makersclaw 0.2.0 → 0.3.1

package/src/cli.mjs

@@ -3,9 +3,9 @@
 // agent reading a terminal: short lines, what changed, what to run next.
 // --json is the same result as one object, for the platform.
 
-import { resolve } from "node:path";
+import { delimiter, resolve } from "node:path";
 import { CliError, add, diff, init, remove, update } from "./install.mjs";
-import { loadItems, loadTemplate, packageInfo, readmeOf, searchItems, suggest, templateNames } from "./registry.mjs";
+import { loadItems, loadTemplate, packageInfo, readmeOf, searchItems, suggest, templateNames, useExtraBlockRoots } from "./registry.mjs";
 
 const COMMANDS = {
   init: "init",
@@ -139,8 +139,10 @@ function addText(r) {
   return lines.join("\n");
 }
 
+const kind = (item) => (item.tier === "premium" ? "premium" : item.type);
+
 function itemLine(item) {
-  return `  ${item.name.padEnd(18)} ${item.type.padEnd(10)} ${clip(item.description, 72)}`;
+  return `  ${item.name.padEnd(18)} ${kind(item).padEnd(10)} ${clip(item.description, 72)}`;
 }
 
 function searchText(query, matches) {
@@ -155,7 +157,7 @@ function searchText(query, matches) {
 
 function viewText(item, readme) {
   const { version } = packageInfo();
-  const head = `${item.name} · ${item.type} · makersclaw ${version}`;
+  const head = `${item.name} · ${item.type}${item.tier === "premium" ? " · premium" : ""} · makersclaw ${version}`;
   if (readme) return `${head}\n\n${readme.trimEnd()}`;
   const folder = item.type === "part" ? "parts" : "ui";
   return [
@@ -179,7 +181,7 @@ function listText(items) {
     const of = items.filter((i) => i.type === type);
     if (!of.length) continue;
     lines.push("", label);
-    for (const i of of) lines.push(`  ${i.name.padEnd(18)} ${clip(i.description, 80)}`);
+    for (const i of of) lines.push(`  ${i.name.padEnd(18)} ${i.tier === "premium" ? "premium · " : ""}${clip(i.description, 80)}`);
   }
   return lines.join("\n");
 }
@@ -271,6 +273,7 @@ function summary(item) {
   return {
     name: item.name,
     type: item.type,
+    tier: item.tier,
     title: item.title,
     description: item.description,
     useWhen: item.useWhen || undefined,
@@ -281,7 +284,17 @@ function summary(item) {
   };
 }
 
-export function main(argv, { stdout = process.stdout, stderr = process.stderr } = {}) {
+/** The block roots the platform names beside the package's own
+ *  (MAKERSCLAW_BLOCKS_DIR, folders joined like PATH). */
+export function blockRootsFromEnv(env = process.env) {
+  return String(env.MAKERSCLAW_BLOCKS_DIR ?? "")
+    .split(delimiter)
+    .map((d) => d.trim())
+    .filter(Boolean);
+}
+
+export function main(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env } = {}) {
+  useExtraBlockRoots(blockRootsFromEnv(env));
   let opts = { json: argv.includes("--json") };
   try {
     opts = parseArgs(argv);

package/src/install.mjs

@@ -147,6 +147,7 @@ function lay(dir, tpl, before) {
   }
 
   const blocks = {};
+  const blockDeps = {};
   const known = loadBlocks();
   for (const [name, from] of Object.entries(before.manifest?.blocks ?? {})) {
     if (!existsSync(join(dir, BLOCK_DIR, name))) {
@@ -170,6 +171,20 @@ function lay(dir, tpl, before) {
       pins[f.to] = hash;
     }
     blocks[name] = v;
+    Object.assign(blockDeps, block.dependencies);
+  }
+
+  // The blocks' npm packages, at the versions this release pins them to
+  // (block.json `dependencies`): a block's files and its packages move
+  // together, or an update would lay files the installed package cannot run.
+  if (Object.keys(blockDeps).length && existsSync(join(dir, "package.json"))) {
+    const path = join(dir, "package.json");
+    const { out, changes } = mergePackage(readJson(path, {}), { dependencies: blockDeps });
+    if (changes.length) {
+      writeJson(path, out);
+      if (!written.includes("package.json")) written.push("package.json");
+      pkg = [...pkg, ...changes];
+    }
   }
 
   for (const p of Object.keys(before.pins)) {
@@ -446,6 +461,9 @@ export function diff(dir) {
   const pkgPath = join(dir, "package.json");
   const tplPkg = tpl.files.find((f) => f.class === "merged");
   const pkg = existsSync(pkgPath) && tplPkg ? mergePackage(readJson(pkgPath), readJson(tplPkg.from)).changes : [];
+  // …and the installed blocks' npm packages, which update lays with them.
+  const blockDeps = Object.assign({}, ...Object.keys(manifest.blocks ?? {}).map((n) => known.find((b) => b.name === n)?.dependencies ?? {}));
+  if (existsSync(pkgPath) && Object.keys(blockDeps).length) pkg.push(...mergePackage(readJson(pkgPath), { dependencies: blockDeps }).changes);
   return {
     from: manifest.version,
     to: v,

package/src/registry.mjs

@@ -7,6 +7,12 @@
 // app has one until `add` puts it there, so the agent searches for what
 // it needs and installs just that. Everything here ships inside this
 // package, so the version you run is the version you get.
+//
+// One exception: extra block roots. The platform lays its premium blocks
+// (never on npm) into the sandbox and names their folder; the CLI's entry
+// point hands it to useExtraBlockRoots() from MAKERSCLAW_BLOCKS_DIR. Only
+// that entry point does: the shadcn registry builder never calls it, so
+// no environment variable can put a premium block into the npm package.
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
@@ -79,13 +85,40 @@ export function loadTemplate(name) {
   return { name, title: meta.title ?? name, description: meta.description ?? "", root, files, components };
 }
 
+let extraRoots = [];
+
+/** Block folders outside this package (the platform's premium blocks),
+ *  read after the package's own. Same shape as registry/blocks/. */
+export function useExtraBlockRoots(dirs) {
+  extraRoots = (dirs ?? []).filter((d) => d && existsSync(d) && statSync(d).isDirectory());
+}
+
+export function extraBlockRoots() {
+  return [...extraRoots];
+}
+
 export function loadBlocks() {
-  if (!existsSync(BLOCKS)) return [];
-  return readdirSync(BLOCKS)
-    .filter((n) => statSync(join(BLOCKS, n)).isDirectory())
+  const blocks = [];
+  const seen = new Map();
+  for (const root of [BLOCKS, ...extraRoots]) {
+    for (const block of loadBlocksFrom(root, root === BLOCKS ? "free" : "premium")) {
+      if (seen.has(block.name)) {
+        throw new Error(`block ${block.name}: in both ${seen.get(block.name)} and ${root} — a block name is used once`);
+      }
+      seen.set(block.name, root);
+      blocks.push(block);
+    }
+  }
+  return blocks;
+}
+
+function loadBlocksFrom(root, defaultTier) {
+  if (!existsSync(root)) return [];
+  return readdirSync(root)
+    .filter((n) => statSync(join(root, n)).isDirectory())
     .sort()
     .map((folder) => {
-      const dir = join(BLOCKS, folder);
+      const dir = join(root, folder);
       const meta = readJson(join(dir, "block.json"));
       if (!meta) throw new Error(`block ${folder}: no block.json`);
       if (meta.name !== folder || !NAME.test(folder)) throw new Error(`block ${folder}: name must be the folder's, lowercase and dashed`);
@@ -98,6 +131,7 @@ export function loadBlocks() {
       return {
         name: folder,
         type: "block",
+        tier: meta.tier === "premium" || defaultTier === "premium" ? "premium" : "free",
         title: meta.title ?? folder,
         description: meta.description ?? "",
         tags: meta.tags ?? [],

package/src/shadcn.mjs

@@ -40,6 +40,14 @@ const CSS_VARS = {
   theme: {
     "text-2xs": "0.6875rem",
     "text-2xs--line-height": "1rem",
+    // The chart block's series colours. A shadcn theme already defines
+    // --chart-1…5 (light and dark); this only makes sure the utilities
+    // (fill-chart-1, stroke-chart-2…) read them.
+    "color-chart-1": "var(--chart-1)",
+    "color-chart-2": "var(--chart-2)",
+    "color-chart-3": "var(--chart-3)",
+    "color-chart-4": "var(--chart-4)",
+    "color-chart-5": "var(--chart-5)",
   },
   light: {
     success: "oklch(0.627 0.194 149.214)",
@@ -142,7 +150,12 @@ function blockItem(block, base, version) {
 /** Every item, with its files' content, and the index shadcn's `list` and
  *  `search` read (the same items, without content). */
 export function buildRegistry({ base = defaultBase(), version = packageInfo().version } = {}) {
-  const items = [coreItem(), ...loadBlocks().map((b) => blockItem(b, base, version))];
+  // Free blocks only. Extra roots are set by the CLI's entry point, never
+  // here — this refusal is the second lock on premium code reaching npm.
+  const blocks = loadBlocks();
+  const premium = blocks.filter((b) => b.tier === "premium").map((b) => b.name);
+  if (premium.length) throw new Error(`the public registry would carry premium blocks (${premium.join(", ")}) — build it without extra block roots`);
+  const items = [coreItem(), ...blocks.map((b) => blockItem(b, base, version))];
   const index = {
     $schema: INDEX_SCHEMA,
     name: "makersclaw",

package/templates/next/files/README.md

@@ -129,28 +129,162 @@ rarely does. `npm run check` refuses a raw `<select>`, `<dialog>`,
 `<svg>`, `role="tab"`, `popover` or `window.confirm()` outside the kit.
 
 ```jsx
-import { Button, IconButton, Card, Field, Input, Textarea, Select, Switch, Checkbox,
-         Sheet, Confirm, Tabs, TabPanel, Menu, Notice, Badge, Kicker, Empty, Icon, cx }
+import { Button, IconButton, ButtonGroup, ButtonGroupSeparator, Toggle, ToggleGroup,
+         Field, Input, TimeInput, Textarea, Select, Switch, Checkbox, RadioGroup, Radio, Rating,
+         InputGroup, PasswordInput, InputOTP, Slider, Image, FileInput, FileDrop, fileMatches, Combobox, Command, CommandDialog, Calendar, DatePicker, DateInput, DATE_PRESETS,
+         parseDate, isDateString, toDateString, todayString, addDays, addMonths,
+         startOfMonth, endOfMonth, dayOfWeek, formatDate, firstDayOfWeek,
+         Card, Notice, Badge, Kicker, Empty, Item, ItemGroup, Avatar, AvatarGroup,
+         Sheet, Confirm, Tabs, TabPanel, Menu, ContextMenu, Popover, Tooltip, HoverCard,
+         Breadcrumb, Pagination, Collapsible, Accordion, Carousel, ScrollArea,
+         ResizablePanelGroup, ResizablePanel, ResizableHandle,
+         Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption,
+         Spinner, Skeleton, Progress, Separator, Kbd, KbdGroup, AspectRatio,
+         Stat, StatGroup, Delta, StatusDot, Legend, Meter, Distribution, Swatch, Steps,
+         toast, Toaster, Depiction, Icon, ICON_NAMES, usePopoverPosition, panelClass, cx }
   from "../components/ui";           // "./ui" from a component
 import { RecordSwitcher, useFixture, FixtureNotice, isSample } from "../components/parts";
 ```
 
 - `Button` — `variant` primary (one per surface) · secondary · quiet ·
-  danger · link; `size` md (44px) · sm; `icon="plus"`; `href` for a link.
-  `IconButton` for an icon alone (`label` required).
+  danger · link (inline text: no padding or height, wraps and truncates
+  with its sentence; `size="inherit"` takes the sentence's size;
+  `tone="muted"` for a secondary link) · nav (a full-width navigation row, start-aligned, normal
+  weight, filled by `aria-current="page"`); `size` md (44px) · sm;
+  `align` center · start; `icon="plus"`; `href` for a link.
+  `IconButton` for an icon alone (`label` required). `loading` while its
+  action runs: a spinner, the same width, `aria-busy`, disabled.
 - `Field` wraps `Input`, `Textarea`, `Select`, `Switch`, `Checkbox` with
   its label, hint and error. `Select` with empty `options` renders a
-  muted line, never a disabled dropdown.
+  muted line, never a disabled dropdown. `TimeInput` — a time of day
+  ("HH:MM"; `min max step`), the kit's clock in place of the browser's.
+- `Rating` — stars: read-only `value` of `max` (halves drawn, "4.5 out
+  of 5" to a reader), or with `onChange` a radio-group input; `size`, `label`.
+- `InputGroup` — an input with `icon`, `prefix` ("https://"), `suffix`
+  ("USD"), `kbd` and an `action` button (copy, search, show password);
+  one border, focus ring and `invalid` for the whole group; `multiline`
+  is the chat composer (a growing textarea, `minRows` `maxRows`, `tools`
+  and the action in a bar under it, `above` for attached files).
+  `PasswordInput` — the password field with a show/hide toggle
+  (`autoComplete` passes through; "new-password" on sign-up).
+  `Textarea autoGrow` grows with its text the same way. `InputOTP` —
+  a one-time code in boxes (`length` or `groups={[3, 3]}`, `digitsOnly`,
+  `onComplete(code)`, `invalid`; paste and SMS autofill fill every box).
+  `Slider` — a number, or a range with `value={[low, high]}`; `min max
+  step`, `showValue` + `format`. A number someone will type is an Input.
+- `Combobox` — pick one or many from a searchable list (`options` with
+  `icon`, `description`, `group`, `count` at the right; `multiple` →
+  chips; `creatable`; `open` + `onOpenChange` or `defaultOpen`;
+  `onSearch` async; `clearable`; in a `Field` by `id`; a bottom sheet on a
+  phone). `searchable={false}` is the rich Select (icons, descriptions)
+  — a plain list of words stays the native `Select`. `Command` — a
+  searchable list of actions (`items` with `icon`, `shortcut`, `keywords`,
+  `group`, `onSelect`); `CommandDialog hotkey="k"` is the ⌘K palette.
 - `Sheet` — the one overlay, a rail beside the work (`side="end"`), a
-  dialog (`center`) or a bottom sheet; on a narrow window every side
-  becomes a bottom sheet. `Confirm` is the "delete this?" case.
+  navigation drawer (`start`), a dialog (`center`) or a bottom sheet; on a narrow window every side
+  becomes a bottom sheet; `bare` + `label` for a panel that draws its own
+  top (no header, flush body). `Confirm` is the "delete this?" case;
+  `consequences`, `requireText` and `acknowledge` hold it until met.
+- `Image src alt ratio fit rounded` — a picture of a thing (thumbnail,
+  cover): Skeleton while it loads, a glyph when it fails, lazy, `alt`
+  required. Never a raw `<img>`; a face is an `Avatar`.
+- `FileInput onFiles accept multiple` (a Button that opens the picker;
+  only a `label` → an IconButton) and `FileDrop` (a drop zone, `label`
+  `hint` `size` sm · md; a drop is filtered by `accept`, the rest go to
+  `onReject`). Never a raw `<input type="file">`.
 - `Tabs` + `TabPanel` — views of ONE thing (a record's notes | history).
   Never for the app's surfaces; those are the shell's nav.
-- `Menu` — the "…" of a row. Empty `items` render nothing: a menu is
-  earned by having actions.
-- `Card`, `Notice` (tone neutral · info · success · warning · danger),
-  `Badge`, `Kicker` (the small line above a heading), `Empty` (a filter
+- `Menu` — the "…" of a row, a View or Account dropdown. `items` are
+  data: actions (`icon`, `tone`, `shortcut`, `description`), `{ group,
+  items }`, `{ type: "separator" }`, `{ type: "checkbox", checked,
+  onCheckedChange }`, `{ type: "radio", value, onValueChange, options }`
+  (choices keep it open) and submenus `{ label, items }`; `side` +
+  `align`; `size` sm (36px, default) · md (44px trigger). Empty `items` render nothing: a menu is earned by having
+  actions. `ContextMenu` opens the same `items` on a region's right-click,
+  long press or Shift+F10 — a shortcut, never the only door.
+- `Popover` (a panel beside its `trigger`; `side`, `align`, `width`;
+  flips at the window's edge; `open` + `onOpenChange` or uncontrolled),
+  `Tooltip` (a short text `label` on hover or keyboard focus; never on
+  touch, so it only repeats what is visible) and `HoverCard` (a preview
+  of what a link points at; may hold links). `usePopoverPosition` is the
+  placement alone, for a floating part of your own.
+- `DatePicker` (a field that opens a Calendar; `mode` single · range,
+  `presets`, `clearable`, `min max disabled`; in a `Field` with the same
+  `id`), `Calendar` (the grid inline; `mode` single · multiple · range,
+  `numberOfMonths`, `captionLayout` dropdown · none (you show and move a
+  controlled `month`), `showWeekNumbers`, `weekStartsOn`, `marked` with
+  `emphasizeMarked` and `onlyMarked`) and
+  `DateInput` (a typed date with the Calendar a button away). Dates are
+  `"YYYY-MM-DD"` strings in and out — never a Date — and `addDays`,
+  `addMonths`, `formatDate`… do the arithmetic.
+- `RadioGroup` (`options` or `<Radio>` children, each with a
+  `description`; `variant` list · card; `orientation`; in a `Field` with
+  the same `id`), `Toggle` (`pressed` + `onPressedChange`, aria-pressed),
+  `ToggleGroup` (the segmented control; `type` single · multiple) and
+  `ButtonGroup` (buttons, icon buttons and a `Menu` joined into one
+  piece; `ButtonGroupSeparator` between primary or quiet ones).
+- `Avatar name src size shape status` (initials while loading and when
+  the image fails) and `AvatarGroup people max` ("+N" past `max`);
+  `Breadcrumb items={[{ label, href }]}` (last is this page; the middle
+  folds into "…"; the current page takes the rest of the row); `Pagination page pageCount` with `hrefFor(page)` or
+  `onPageChange` (compact on a phone; `pageSize` + `onPageSizeChange`).
+- `Collapsible` (title, meta, `open` + `onOpenChange` or `defaultOpen`;
+  `variant` plain · outline · flush for edge-to-edge rows inside a Card;
+  `chevron` down · right, the disclosure triangle that turns down)
+  and `Accordion` (`items`, `type` single · multiple) — show and hide,
+  never a raw `<details>`. `Item` / `ItemGroup` — the list row (media or
+  icon, title, description, meta, actions; `href` or `onClick` makes the
+  whole row the target; `aria-current`, `onClick`, `target`, `rel` reach
+  that link or button). `Table` + `TableHeader`, `TableBody`, `TableRow`
+  (`selected`), `TableHead` (`sort` + `onSort`; `sortIndex` when several
+  are sorted), `TableCell` (`numeric`)
+  — a table that scrolls inside itself on a phone.
+- `Card` (`padding` md · sm · none — none for a table or rows that run
+  to the border, never `p-0!`; `titleSize` md · lg for a 20px title),
+  `Notice` (tone neutral · info · success · warning · danger),
+  `Badge` (tone neutral · primary · success · warning · danger · info;
+  `variant` label — small caps · soft — the case as written, every tone
+  tinted, primary too · outline — the case as written, a hairline, no
+  fill · code — a version tag or a commit hash in the mono face; `hue`
+  1..5 for a KIND of thing — a platform, a content type — never a state:
+  tone is status, hue is category), `Kicker` (the small line above a heading), `Empty` (a filter
   or search with no matches — not the landing state, that is the fixture).
+- `Spinner` (size sm · md · lg), `Skeleton` (shape line · circle · rect,
+  sized by className), `Progress` (`value` of `max`, no value for
+  indeterminate; tone; `label`) — waiting, never a hand-drawn loader.
+- `Steps steps={[{ label, description, status, meta }]}` (or `current`)
+  — where a staged job has got: `variant` dots · bar (rollout phases);
+  status complete · current · pending · failed · skipped; `orientation`
+  horizontal · vertical; `pulse`; `label` + `valueText`;
+  `hideStepLabels` for bare dots (still pass every label: it is what a
+  reader hears); `onSelect`
+  only when a step opens something. Never a hand-drawn stepper.
+- `Stat label value unit caption tone delta invert size` (sm · md · lg)
+  in a `StatGroup` (the 2–4 summary strip; card · divided · bare);
+  `Delta value suffix invert` (coloured by sign; zero is neutral);
+  `StatusDot tone pulse label`; `Legend items={[{ tone, label, count }]}`;
+  `Meter value max unit target thresholds` (a role=meter; over the limit
+  turns danger; `direction` higher · lower picks the tone against the
+  target; `valueTone`; `targetMark={false}`; tone `muted` for a plain
+  grey share) — numbers and states, never a hand-drawn tile or bar.
+  `Delta hideValue` is the arrow alone; `StatusDot` and Legend items take
+  `hue` (1..5) for a category. `Distribution segments={[{ label, value,
+  tone, hue }]} legend label size` (thin · md) — parts of one whole as
+  one stacked bar, a hue per segment, a tone for sentiment. `Swatch color
+  label size` — a colour that comes from data; the only inline colour.
+- `Separator` (horizontal · vertical; `decorative={false}` for a real
+  one), `Kbd` / `KbdGroup keys={["⌘", "K"]}`, `AspectRatio ratio="video"`
+  (its child fills it), `ScrollArea` (a bounded scroller with themed
+  scrollbars, `fade`, keyboard-focusable while it overflows; `ref` is the
+  scrolling element, for a list that sets its own scrollTop).
+- `toast("Saved")`, `toast.success/.error/.info/.warning(title, {
+  description, action, duration })`, `toast.promise(p, { loading,
+  success, error })` — nothing to mount; `<Toaster position />` only to
+  move the stack. A toast is never the only record of an error.
+- `Carousel label itemsPerView` (scroll-snap; 1 on a phone; dots ·
+  counter; `loop`, `autoplay` only when asked), `ResizablePanelGroup`
+  + `ResizablePanel defaultSize minSize` + `ResizableHandle grip`
+  (`storageKey` remembers; a horizontal group stacks below md).
 - `Icon name="…"` — one sprite, `ICON_NAMES` lists it. Missing one? Add
   the glyph to `components/ui/icon.jsx`; never an `<svg>` in a surface.
 - `RecordSwitcher` — pick a saved record or make a new one. With nothing

package/templates/next/files/app/globals.css

@@ -100,6 +100,41 @@
     border: 0;
     background: transparent;
   }
+
+  /* Status tones when the preset does not pin them (@theme below reads
+     these). The plain fallbacks there are for a dark canvas and read faint
+     on a light one, so a light page gets darker ones: by color-scheme (the
+     preset's), through light-dark(), where the browser has it; by
+     data-theme=light where it does not. Every one reads at 4.5:1 or more
+     as text on the Daylight background and card. */
+  [data-theme=light] {
+    --scheme-success: #15703a;
+    --scheme-warning: #9a4a06;
+    --scheme-info: #1d4ed8;
+    --scheme-destructive: #c01c1c;
+  }
+  @supports (color: light-dark(red, red)) {
+    :root,
+    [data-theme] {
+      --scheme-success: light-dark(#15703a, #4ade80);
+      --scheme-warning: light-dark(#9a4a06, #ffbd38);
+      --scheme-info: light-dark(#1d4ed8, #60a5fa);
+      --scheme-destructive: light-dark(#c01c1c, #fb2c36);
+    }
+  }
+
+  /* Chart series 2-5, derived with relative colour (oklch(from …)), which
+     Chrome before 119 and Safari before 16.4 lack. Set only where it
+     parses; elsewhere @theme falls back to plain colours that still stay
+     apart, rather than to no colour at all. */
+  @supports (color: oklch(from red l c h)) {
+    :root {
+      --chart-derived-2: oklch(from var(--primary, var(--midground-base)) clamp(0.55, l, 0.8) clamp(0.12, c, 0.2) calc(h + 144));
+      --chart-derived-3: oklch(from var(--primary, var(--midground-base)) clamp(0.55, l, 0.8) clamp(0.12, c, 0.2) calc(h + 288));
+      --chart-derived-4: oklch(from var(--primary, var(--midground-base)) clamp(0.55, l, 0.8) clamp(0.12, c, 0.2) calc(h + 72));
+      --chart-derived-5: oklch(from var(--primary, var(--midground-base)) clamp(0.55, l, 0.8) clamp(0.12, c, 0.2) calc(h + 216));
+    }
+  }
 }
 
 /* The boundary where the workspace theme stops: a depiction (README §3c),
@@ -150,16 +185,32 @@
   --color-accent: var(--accent, color-mix(in srgb, var(--midground-base) 12%, var(--background-base)));
   --color-accent-foreground: var(--accent-foreground, var(--midground-base));
 
-  --color-destructive: var(--destructive, #fb2c36);
+  --color-destructive: var(--destructive, var(--scheme-destructive, #fb2c36));
   --color-destructive-foreground: var(--destructive-foreground, #ffffff);
-  --color-success: var(--success, #4ade80);
-  --color-warning: var(--warning, #ffbd38);
-  --color-info: var(--info, #60a5fa);
+  --color-success: var(--success, var(--scheme-success, #4ade80));
+  --color-warning: var(--warning, var(--scheme-warning, #ffbd38));
+  --color-info: var(--info, var(--scheme-info, #60a5fa));
 
   --color-border: var(--border, color-mix(in srgb, var(--midground-base) 15%, transparent));
   --color-input: var(--input, color-mix(in srgb, var(--midground-base) 15%, transparent));
   --color-ring: var(--ring, var(--midground-base));
 
+  /* Chart series (fill-chart-1, stroke-chart-2, bg-chart-3…), for the chart
+     block: several colours that must stay apart in every theme. A preset
+     (or a shadcn theme) may pin --chart-N. Otherwise chart-1 is the primary
+     and the others turn its hue round the wheel, 144° a step so neighbours
+     never sit close, keeping its lightness (the primary already reads on
+     this canvas) with a floor on chroma so a grey or pastel theme still
+     gets colours. Not success/warning/info: those are status, and a theme's
+     primary is often one of them (amber, mint, blue). The turn is worked
+     out in the base layer (--chart-derived-N); the hex after it is for a
+     browser without relative colour. */
+  --color-chart-1: var(--chart-1, var(--primary, var(--midground-base)));
+  --color-chart-2: var(--chart-2, var(--chart-derived-2, #14b8a6));
+  --color-chart-3: var(--chart-3, var(--chart-derived-3, #a78bfa));
+  --color-chart-4: var(--chart-4, var(--chart-derived-4, #f472b6));
+  --color-chart-5: var(--chart-5, var(--chart-derived-5, #38bdf8));
+
   --radius-sm: calc(var(--theme-radius) - 4px);
   --radius-md: calc(var(--theme-radius) - 2px);
   --radius-lg: var(--theme-radius);

package/templates/next/files/check/run.mjs

@@ -48,7 +48,7 @@ const STATIC_ONLY = process.argv.includes("--static");
 // update` lays both folders again.
 // Exact names AND extensions: Next resolves .js before .jsx, so a
 // components/ui/depiction.js beside depiction.jsx would win unseen.
-const KIT = /^components\/(?:ui\/(?:cx|index)\.js|ui\/(?:button|depiction|field|icon|menu|notice|sheet|tabs)\.jsx|parts\/(?:index|sample)\.js|parts\/(?:fixture|record-switcher)\.jsx)$/;
+const KIT = /^components\/(?:ui\/(?:cx|index)\.js|ui\/(?:radio|toggle|button-group|avatar|breadcrumb|pagination|button|collapsible|item|table|depiction|feedback|stat|distribution|swatch|steps|separator|scroll-area|field|icon|menu|context-menu|popover|calendar|date-picker|tooltip|notice|sheet|tabs|slider|input-group|image|file-input|input-otp|command|combobox|rating|toast|carousel|resizable)\.jsx|parts\/(?:index|sample)\.js|parts\/(?:fixture|record-switcher)\.jsx)$/;
 
 // The pins: sha256 of every fixed file, written by `makersclaw init` and
 // `makersclaw add` (check/pins.json). Read first, because a BLOCK is
@@ -209,11 +209,11 @@ const ATTRS = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'{])*`
   const RULES = [
     [/<select\b/, "Select from components/ui, or RecordSwitcher from components/parts", files],
     [/<dialog\b/, "Sheet or Confirm from components/ui", files],
-    [/<details\b/, "Menu or Sheet from components/ui", files],
+    [/<details\b/, "Collapsible or Accordion from components/ui", files],
     [/role=["']tab(?:list)?["']/, "Tabs from components/ui", files],
     [/role=["']menu(?:item)?["']/, "Menu from components/ui", files],
     [/role=["']dialog["']/, "Sheet from components/ui", files],
-    [/\bpopover=/, "Menu from components/ui", files],
+    [/\bpopover=/, "Popover, Tooltip, HoverCard or Menu from components/ui", files],
     [/window\.confirm\(/, "Confirm from components/ui", files],
     [/<svg\b/, "Icon from components/ui (add a glyph there if it is missing)", appFiles],
   ];

package/templates/next/files/components/ui/avatar.jsx

@@ -0,0 +1,141 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { cx } from "./cx";
+import { Icon } from "./icon";
+
+// Avatar — a person's face, or their initials while it loads and when it
+// fails. The initials are always drawn; the image lays over them only
+// once it has loaded, so a slow, missing or broken `src` never shows a
+// hole or the browser's broken-image glyph. No name either: a user icon.
+//
+//   name     "Jane Cooper" → JC; also the accessible name
+//   src      the image; optional
+//   size     xs (24px) · sm (32px) · md (40px) · lg (56px)
+//   shape    round · square (a company, a bot, a workspace)
+//   status   online · away · busy · offline — a dot, named to a reader
+//   label    overrides what a screen reader says
+//
+// AvatarGroup below is the overlapping stack with "+N" after `max`.
+
+const SIZES = {
+  xs: { box: "h-6 w-6 text-2xs", dot: "h-1.5 w-1.5", icon: 12, overlap: "-space-x-1.5" },
+  sm: { box: "h-8 w-8 text-xs", dot: "h-2 w-2", icon: 14, overlap: "-space-x-2" },
+  md: { box: "h-10 w-10 text-sm", dot: "h-2.5 w-2.5", icon: 18, overlap: "-space-x-2.5" },
+  lg: { box: "h-14 w-14 text-lg", dot: "h-3.5 w-3.5", icon: 24, overlap: "-space-x-3" },
+};
+
+const SHAPES = { round: "rounded-full", square: "rounded-md" };
+
+// Colour is the signal: the status tones are the workspace's status tokens.
+const STATUS = {
+  online: { dot: "bg-success", say: "online" },
+  away: { dot: "bg-warning", say: "away" },
+  busy: { dot: "bg-destructive", say: "busy" },
+  offline: { dot: "bg-muted-foreground", say: "offline" },
+};
+
+/** "Jane Cooper" → "JC", "jane@acme.com" → "J", "Priya" → "P". First and
+ *  last word, by code point, so an accented or non-Latin name survives. */
+function initials(name) {
+  const words = String(name ?? "").split("@")[0].trim().split(/[\s._-]+/).filter(Boolean);
+  if (words.length === 0) return "";
+  const first = Array.from(words[0])[0] ?? "";
+  const last = words.length > 1 ? Array.from(words[words.length - 1])[0] ?? "" : "";
+  return (first + last).toUpperCase();
+}
+
+export function Avatar({ name, src, size = "md", shape = "round", status, label, className }) {
+  const s = SIZES[size] ?? SIZES.md;
+  const round = SHAPES[shape] ?? SHAPES.round;
+  const st = STATUS[status];
+  const img = useRef(null);
+  // Both hold the src they are about, so a new src starts fresh unreset.
+  const [loaded, setLoaded] = useState(null);
+  const [failed, setFailed] = useState(null);
+
+  // A server-rendered <img> can load or fail before React is listening.
+  useEffect(() => {
+    const i = img.current;
+    if (!i || !src || !i.complete) return;
+    if (i.naturalWidth > 0) setLoaded(src);
+    else setFailed(src);
+  }, [src]);
+
+  const text = initials(name);
+  const said = label ?? ([name, st?.say].filter(Boolean).join(", ") || undefined);
+  const showImg = src && failed !== src;
+
+  return (
+    <span
+      role={said ? "img" : undefined}
+      aria-label={said}
+      aria-hidden={said ? undefined : true}
+      title={name || undefined}
+      className={cx("relative inline-flex shrink-0 select-none", round, s.box, className)}
+    >
+      <span className={cx("relative flex h-full w-full items-center justify-center overflow-hidden bg-muted font-medium text-muted-foreground", round)}>
+        {/* Hidden, not removed, once the image is in: a transparent PNG must not show letters through it. */}
+        <span aria-hidden="true" className={cx("inline-flex leading-none", loaded === src && showImg && "invisible")}>
+          {text || <Icon name="user" size={s.icon} />}
+        </span>
+        {showImg ? (
+          <img
+            ref={img}
+            src={src}
+            alt=""
+            onLoad={() => setLoaded(src)}
+            onError={() => setFailed(src)}
+            className={cx("absolute inset-0 h-full w-full object-cover", loaded === src ? "opacity-100" : "opacity-0")}
+          />
+        ) : null}
+      </span>
+      {st ? (
+        <span
+          aria-hidden="true"
+          className={cx(
+            "absolute rounded-full ring-2 ring-background",
+            shape === "square" ? "-bottom-0.5 -right-0.5" : "bottom-0 right-0",
+            s.dot,
+            st.dot,
+          )}
+        />
+      ) : null}
+    </span>
+  );
+}
+
+/** Faces overlapping, the first `max` of `people`, then "+N" naming the
+ *  rest on hover and to a reader. No status dots: the next face covers
+ *  them. Empty `people` renders nothing.
+ *
+ *    people   [{ name, src? }]
+ *    max      how many faces before "+N" (default 4)
+ */
+export function AvatarGroup({ people, max = 4, size = "sm", shape = "round", label, className }) {
+  const list = (people ?? []).filter(Boolean);
+  if (list.length === 0) return null;
+  const s = SIZES[size] ?? SIZES.sm;
+  const round = SHAPES[shape] ?? SHAPES.round;
+  const shown = list.slice(0, Math.max(1, max));
+  const rest = list.slice(shown.length);
+  const restNames = rest.map((p) => p.name).filter(Boolean).join(", ");
+
+  return (
+    <div role="group" aria-label={label ?? `${list.length} people`} className={cx("flex items-center", s.overlap, className)}>
+      {shown.map((p, i) => (
+        <Avatar key={i} name={p.name} src={p.src} size={size} shape={shape} className="ring-2 ring-background" />
+      ))}
+      {rest.length > 0 ? (
+        <span
+          role="img"
+          aria-label={`and ${rest.length} more${restNames ? `: ${restNames}` : ""}`}
+          title={restNames || undefined}
+          className={cx("relative inline-flex shrink-0 items-center justify-center bg-muted font-medium text-muted-foreground ring-2 ring-background", round, s.box)}
+        >
+          <span data-nums aria-hidden="true" className="leading-none">+{rest.length}</span>
+        </span>
+      ) : null}
+    </div>
+  );
+}