@usableapp/cardds 0.7.72 → 0.7.73

package/lib/mcp.mjs

@@ -13,7 +13,7 @@ const bool = (description) => ({ type: 'boolean', description });
 const TOOLS = [
   {
     name: 'list_components',
-    description: 'The names of every cardds component and the group it belongs to, nothing else. Call this once, first, in a session that will build a UI with cardds, to learn what exists; then get_component for the ones you use.',
+    description: 'The names of every cardds component and what each is FOR, nothing else. represents is what it stands for (person, group, time…) or, for a control that stands for no one thing, the KIND of data it carries (words, number, picture, signal); the word in parentheses after a name in the text is its represents. Every component shows information; shape says how much: "one" (one thing), "group-brief" (a group read at a glance or in a line), "group-detail" (a group read in detail), "—" (a helper function or structure, not something drawn). interact says whether the member can do something with it: false (it only shows or holds), or the kinds, any of pick, act, write, navigate — alone when shape is one (a Btn acts), as a group when shape is a group (a Segment picks among several). Two kinds mean it does both. group is the src folder, not what it is for. Call this once, first, in a session that will build a UI with cardds, to learn what exists; then get_component for the ones you use.',
     inputSchema: { type: 'object', properties: {} },
     run: (cat) => catalog.list(cat),
   },
@@ -25,15 +25,26 @@ const TOOLS = [
   },
   {
     name: 'find_components',
-    description: 'Search by words ("stamp", "otp pin", "bottom sheet") when you do not know the component name. Answers short: the screens cardds has already drawn first, then components, then the components most often used together with them. Call it at the start of a task, before composing a screen from parts: if a screen like it exists, scaffold_screen gives its code. Ask in ENGLISH words — the names and descriptions are English; translate the request first. A query that matches nothing returns the id of every screen (fallback: true).',
-    inputSchema: { type: 'object', properties: { query: str('English words describing the screen or the part') }, required: ['query'] },
-    run: (cat, a) => catalog.find(cat, a.query),
+    description: (cat) => `Find what to build with when you do not know the component name. Ask BOTH ways and read both answers: by the AXES (translated from the request) AND by the English noun of the task ("stamp", "otp", "postcard") — the screen already drawn is often found by the noun. The axes are a closed vocabulary, so ask by them in any language: represents (what it stands for, or for a control the KIND of data it carries${cat ? `: ${catalog.vocabulary(cat).represents.join(' · ')}` : ' — the word in parentheses after a name in list_components'}), shape (one · group-brief · group-detail · group = either group shape), interact (the kinds the member can do with it: ${catalog.KINDS.join(' · ')}, or "none" = it only shows). "Show all the members" is represents [person] + shape group; adding interact [pick] narrows it to the ones the member chooses from. Whatever matches every axis you give comes first, each with its role so you see why; with axes and no words they are the whole answer. Words ("stamp", "otp pin", "bottom sheet") rank what matches only by words, in ENGLISH — the names and descriptions are English, translate first. Answers short: the screens cardds has already drawn (a screen is a composition: it counts when its parts answer the axes between them, one component per axis, and one that answers them all ranks higher), then components, then the components most often used together with them. Call it at the start of a task, before composing a screen from parts: if a screen like it exists, scaffold_screen gives its code. A query that matches nothing returns fallback: true, a hint and the number of screens drawn, not their ids: ask again in English words or by the axes, or call scaffold_screen with no id to list them.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        represents: { type: 'array', items: { type: 'string' }, description: 'what it stands for, e.g. ["person"]; a component must hold every value you give' },
+        shape: { type: 'string', enum: ['one', 'group-brief', 'group-detail', 'group'], description: 'how many it shows and how much reading; group = group-brief or group-detail' },
+        interact: { anyOf: [{ type: 'array', items: { type: 'string' }, description: 'kinds, e.g. ["pick"]; the component must have every one' }, { type: 'string', enum: ['none'], description: 'only shows, nothing to do with it' }] },
+        query: str('English words describing the screen or the part; optional when axes are given'),
+      },
+    },
+    run: (cat, a) => catalog.find(cat, a.query ?? '', { represents: a.represents, shape: a.shape, interact: a.interact === 'none' ? false : a.interact }),
   },
   {
     name: 'scaffold_screen',
-    description: 'Start from a screen cardds has already drawn. With no id: the list of such screens, one line each. With an id (from find_components): a complete file to start from — format tsx (default) is the React code with its imports, edit its content for the task; format html is a static document (the look only, no behaviour) that links cardds.css, for a prototype without React. A tsx file may name story glue (from ./_story) that is not in the package: replace or drop it.',
+    description: 'Start from a screen cardds has already drawn. With no id: the list of such screens, one line each. With an id (from find_components): a complete file to start from — format tsx (default) is the React code with its imports, edit its content for the task; format html is a static document (the look only, no behaviour) that links cardds.css, for a prototype without React — when the screen has a sheet, menu, step or the like, the file begins with a comment saying the static picture is not the layout. A tsx file may name story glue (from ./_story) that is not in the package: replace or drop it.',
     inputSchema: { type: 'object', properties: { id: str('a screen id such as StampScreens/MakeStamp; omit to list the screens'), format: { type: 'string', enum: ['tsx', 'html'], description: 'tsx (default) or html' }, css: str('html only: the href of cardds.css from where the file will sit; default node_modules/@usableapp/cardds/dist/cardds.css') } },
-    run: (cat, a) => catalog.scaffold(cat, a.id, { format: a.format, css: a.css }),
+    run: (cat, a) => {
+      const r = catalog.scaffold(cat, a.id, { format: a.format, css: a.css });
+      return typeof r.html === 'string' ? `${r.warning ? `<!-- ${r.warning} -->\n` : ''}${r.html}` : r; // the warning first, where a caller reading the top of the file cannot miss it
+    },
   },
   {
     name: 'check_source',
@@ -51,6 +62,11 @@ export function serve({ root, input = process.stdin, output = process.stdout } =
   let cat;
   const text = (r) => typeof r === 'string' ? r : JSON.stringify(r);
 
+  // the catalog, or nothing: listing the tools must not fail because it cannot be loaded (a call says why)
+  function loaded() {
+    try { return (cat ??= catalog.load({ root })); } catch { return undefined; }
+  }
+
   function call(params) {
     const tool = TOOLS.find((t) => t.name === params?.name);
     if (!tool) return null;
@@ -69,7 +85,7 @@ export function serve({ root, input = process.stdin, output = process.stdout } =
     switch (method) {
       case 'initialize': return reply(id, { protocolVersion: params?.protocolVersion ?? '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'cardds', version } });
       case 'ping': return reply(id, {});
-      case 'tools/list': return reply(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+      case 'tools/list': return reply(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description: typeof description === 'function' ? description(loaded()) : description, inputSchema })) });
       case 'tools/call': { const r = call(params); return r ? reply(id, r) : fail(id, -32602, `unknown tool: ${params?.name}`); }
       default: return fail(id, -32601, `method not found: ${method}`);
     }

package/lib/role.mjs

@@ -0,0 +1,30 @@
+// lib/role.mjs — the role table (docs/roles.md) read, and what a role says a component is FOR. Pure, no fs: the catalog (node), scripts/roles.mjs
+// and the gallery's nav (browser) all read the table through these.
+const AXES = ['represents', 'count', 'density', 'job'];
+const values = (cell) => cell.trim().split(' · ').map((v) => v.trim()).filter(Boolean);
+
+/** the text of docs/roles.md → `vocabulary` (each axis's closed values) and `rows` (one per component). Hand-written; the vocabulary is the
+ *  table's own definition lines, so a value outside it is the test's to catch, not this reader's. */
+export function parseRoles(doc) {
+  const vocabulary = Object.fromEntries([...doc.matchAll(/^- `([a-z]+)`: (.+)$/gm)].filter((m) => AXES.includes(m[1])).map((m) => [m[1], values(m[2])]));
+  const rows = [...doc.matchAll(/^\| (?!component )([A-Za-z]\w*) \| ([a-z]+) \|(.*)\|$/gm)].map((m) => {
+    const [represents, count, density, job, stands, note] = m[3].split('|').map((c) => c.trim());
+    return {
+      component: m[1],
+      group: m[2],
+      represents: values(represents), count: values(count), density: values(density), job: values(job),
+      standsInFor: stands ? stands.split(';').map((s) => s.trim().match(/^(\w+)(?: \((.*)\))?$/)).map((x) => ({ name: x[1], condition: x[2] ?? '' })) : [],
+      note: note.replace(/^\?\s*/, ''),
+      unsure: note.startsWith('?'),
+    };
+  });
+  return { vocabulary, rows };
+}
+
+// What a component is FOR, read from its role: every component shows information; what differs is how much it shows
+// (`one` thing, a group in brief, a group in detail) and whether the member can do something with it (and what: pick, act, write, navigate).
+export const SHAPES = ['one', 'group-brief', 'group-detail', '—'];
+export const KINDS = ['pick', 'act', 'write', 'navigate'];
+export const shapeOf = ({ count: [count], density: [density] }) =>
+  count === 'one' ? 'one' : count === 'few' || count === 'many' ? (density === 'detail' || density === 'full' ? 'group-detail' : 'group-brief') : '—'; // a holder with no density of its own claims no detail
+export const interactOf = ({ job }) => job.some((j) => KINDS.includes(j)) ? job.filter((j) => KINDS.includes(j)) : false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.7.72",
+  "version": "0.7.73",
   "license": "UNLICENSED",
   "type": "module",
   "description": "card-first mobile design system, React-first: the components in src/ are thin wrappers over the CSS contract (css/*.css stays the only truth); gallery/ shows every story live (npm run dev), tests/ measures the geometry.",