@usableapp/cardds 0.7.72 → 0.7.74

package/lib/catalog.mjs

@@ -5,7 +5,8 @@ import { existsSync, readFileSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { checkSource } from '../lint/rules.mjs';
+import { checkSource, tagAt, CONTROL_NAMES } from '../lint/rules.mjs';
+import { SHAPES, KINDS, shapeOf, interactOf } from './role.mjs';
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), '..');
 const CSS = 'node_modules/@usableapp/cardds/dist/cardds.css';
@@ -21,8 +22,13 @@ export function load({ root } = {}) {
   return JSON.parse(readFileSync(file, 'utf8'));
 }
 
-/** the names only — the first call of nearly every session, so it stays small */
-export const list = (cat) => cat.components.map(({ name, group }) => ({ name, group }));
+export { SHAPES, KINDS };
+
+// `represents` is the concept (person · group · time…) or, for a control that stands for no one thing, the KIND of data it carries (words · number · picture · signal); `—` is none, so []
+const representsOf = ({ represents }) => represents.filter((v) => v !== '—');
+
+/** the names only — the first call of nearly every session, so it stays small. `group` is the src folder; `represents`, `shape` and `interact` say what it is for */
+export const list = (cat) => cat.components.map(({ name, group, role }) => ({ name, group, represents: representsOf(role), shape: shapeOf(role), interact: interactOf(role) }));
 
 const sentence = (text) => {
   const flat = text.replace(/\s+/g, ' ').trim();
@@ -62,6 +68,7 @@ export function get(cat, name, { html = false, all = false } = {}) {
     name: c.name,
     group: c.group,
     description: c.description,
+    ...(c.role && { role: c.role }),
     element: c.element,
     props: c.props.map((p) => ({ ...p, ...(isSlot(p.type) && { slot: true }) })),
     variations: [...own, ...elsewhere.filter((s) => shown.includes(s))].map(show),
@@ -75,29 +82,80 @@ const tokens = (query) => [...new Set(words(String(query)).filter((t) => t.lengt
 const stem = (t) => (t.length > 3 && t.endsWith('s') ? t.slice(0, -1) : t);
 const hits = (text, token) => words(text).some((w) => w.startsWith(token) || w.startsWith(stem(token)));
 
-/** short ranked answer to "what is there for this?": screens already drawn first, then components, then what they are used with.
- *  A query that matches nothing (another language, say) returns every screen's id with `fallback: true` — ask again in English, or pick the nearest. */
-export function find(cat, query) {
+const TOP = 8; // answers per kind; the components that match every axis are never cut
+
+/** the closed vocabulary of the axes `find` takes, `represents` read from the catalog's own roles (docs/roles.md does not ship). `group` = either group shape */
+export const vocabulary = (cat) => ({
+  represents: [...new Set(cat.components.flatMap((c) => representsOf(c.role)))].sort(),
+  shape: ['one', 'group-brief', 'group-detail', 'group'],
+  interact: KINDS,
+});
+const roleOf = (c) => ({ represents: representsOf(c.role), shape: shapeOf(c.role), interact: interactOf(c.role) });
+
+/** the axes a caller gave, checked against the vocabulary: `{ error }`, or only the ones in force (an empty list is no axis) */
+function wanted(cat, { represents, shape, interact } = {}) {
+  const many = (v) => (v === undefined ? [] : [v].flat());
+  const vocab = vocabulary(cat);
+  const kinds = interact === false ? false : many(interact);
+  const unknown = (axis, given, allowed) => given.filter((v) => !allowed.includes(v)).map((v) => `${axis} "${v}" (one of: ${allowed.join(' · ')})`);
+  const errors = [...unknown('represents', many(represents), vocab.represents), ...unknown('shape', many(shape), vocab.shape), ...unknown('interact', kinds || [], vocab.interact)];
+  if (errors.length) return { error: `no such value — ${errors.join('; ')}` };
+  return { want: { ...(many(represents).length && { represents: many(represents) }), ...(shape && { shape }), ...((kinds === false || kinds.length) && { interact: kinds }) } };
+}
+/** a role matches when it matches EVERY axis in force: holds every `represents` asked, is the shape, has every kind of interaction asked (`false` = only shows) */
+const matches = (role, want) => !!role
+  && (!want.represents || want.represents.every((v) => role.represents.includes(v)))
+  && (!want.shape || (want.shape === 'group' ? role.shape.startsWith('group') : role.shape === want.shape))
+  && (want.interact === undefined || (want.interact === false ? role.interact === false : want.interact.every((k) => role.interact && role.interact.includes(k))));
+
+/** a screen is a composition, its axes spread over its parts: for each axis SOME used component answers it (represents: holds any value asked, the looser reading
+ *  — a part that holds every one is the stronger match, which `matches` finds; shape: has it; interact: has every kind asked, or for `none` every part only shows) */
+const matchesUnion = (roles, want) => roles.length > 0
+  && (!want.represents || roles.some((r) => want.represents.some((v) => r.represents.includes(v))))
+  && (!want.shape || roles.some((r) => matches(r, { shape: want.shape })))
+  && (want.interact === undefined || (want.interact === false ? roles.every((r) => r.interact === false) : roles.some((r) => matches(r, { interact: want.interact }))));
+
+/** short ranked answer to "what is there for this?". `axes` ({ represents?, shape?, interact? } — what it represents, how many, what the member can do with it) are
+ *  asked first: whatever matches every one of them (a component, or a screen where one component does, then a screen whose parts do between them) ranks above whatever matches only words;
+ *  with axes and no words they are the whole answer. Among screens that tie on words, the one whose description says the axes comes first, then the one where a single component matches them all.
+ *  Then the words: screens already drawn, then components, then what they are used with.
+ *  A query that matches nothing (another language, say) returns `fallback: true`, a hint and how many screens are drawn — not their ids:
+ *  they did not help to choose; ask again in English or by the axes, or `scaffold` with no id lists them. */
+export function find(cat, query, axes = {}) {
+  const asked = wanted(cat, axes);
+  if (asked.error) return asked;
+  const active = Object.keys(asked.want).length > 0;
+  const roles = new Map(cat.components.map((c) => [c.name, roleOf(c)]));
   const toks = tokens(query);
-  const rank = (items, fields) => items
-    .map((item) => {
+  const axisWords = [...(asked.want.represents ?? []), ...(asked.want.interact || [])]; // the axis values as words: a screen's own description may say them
+  const rank = (items, fields, level, said = () => 0) => {
+    const scored = items.map((item) => {
       let matched = 0, score = 0;
       for (const t of toks) {
         const w = fields(item).filter(([text]) => hits(text, t)).reduce((sum, [, weight]) => sum + weight, 0);
         if (w) { matched++; score += w; }
       }
-      return { item, matched, score };
-    })
-    .filter((r) => r.matched)
-    .sort((a, b) => b.matched - a.matched || b.score - a.score);
-  const screenOf = (s) => ({ kind: 'screen', id: s.id, summary: sentence(s.description) });
+      return { item, matched, score, level: active ? level(item) : 0, said: active ? said(item) : 0 };
+    });
+    const byWords = (a, b) => b.matched - a.matched || b.score - a.score;
+    const byAxes = (a, b) => b.said - a.said || b.level - a.level; // among equal words: the screen that says the axes itself, then one component over several
+    return { axis: scored.filter((r) => r.level).sort((a, b) => byWords(a, b) || byAxes(a, b)), rest: scored.filter((r) => r.matched && !r.level).sort(byWords) };
+  };
+  const tier = ({ axis, rest }, cap) => [axis.slice(0, cap), rest.slice(0, Math.max(0, cap - axis.length))];
+  const screenOf = ({ item: s }) => ({ kind: 'screen', id: s.id, summary: sentence(s.description) });
+  const componentOf = ({ item: c }) => ({ kind: 'component', name: c.name, summary: sentence(c.description), role: roles.get(c.name) });
   const screens = cat.stories.filter((s) => s.screen);
-  const ranked = [
-    ...rank(screens, (s) => [[s.id, 5], [s.description, 3], [s.uses.join(' '), 1]]).slice(0, 8).map((r) => screenOf(r.item)),
-    ...rank(cat.components, (c) => [[c.name, 6], [c.description, 2], [c.props.map((p) => p.name).join(' '), 1]]).slice(0, 8)
-      .map((r) => ({ kind: 'component', name: r.item.name, summary: sentence(r.item.description) })),
-  ];
-  if (!ranked.length) return { query, fallback: true, hint: 'the names and descriptions are English: ask again in English words', results: screens.map((s) => ({ kind: 'screen', id: s.id })) };
+  const level = (s) => { // 2: one component of the screen matches every axis; 1: its parts do between them
+    const parts = s.uses.map((u) => roles.get(u)).filter(Boolean);
+    return !matchesUnion(parts, asked.want) ? 0 : parts.some((r) => matches(r, asked.want)) ? 2 : 1; // `none` is about the whole screen: one show-only part is not enough
+  };
+  const said = (s) => axisWords.filter((v) => hits(s.description, v)).length;
+  const [screenAxis, screenRest] = tier(rank(screens, (s) => [[s.id, 5], [s.description, 3], [s.uses.join(' '), 1]], level, said), TOP);
+  const components = rank(cat.components, (c) => [[c.name, 6], [c.description, 2], [c.props.map((p) => p.name).join(' '), 1]], (c) => Number(matches(roles.get(c.name), asked.want)));
+  const [componentAxis, componentRest] = tier(components, Math.max(TOP, components.axis.length));
+  const ranked = [...screenAxis.map(screenOf), ...componentAxis.map(componentOf), ...screenRest.map(screenOf), ...componentRest.map(componentOf)];
+  if (!ranked.length && active && !toks.length) return { query, results: [], hint: 'no component or screen has that role: drop an axis, or add English words' };
+  if (!ranked.length) return { query, fallback: true, hint: 'the names and descriptions are English: ask again in English words, or by the axes (represents · shape · interact); `scaffold` with no id lists the screens', screens: screens.length };
 
   const matched = new Set(ranked.filter((r) => r.kind === 'component').map((r) => r.name));
   const together = new Map();
@@ -106,14 +164,38 @@ export function find(cat, query) {
   return { query, results: ranked, usedTogether };
 }
 
-/** no id: the screens already drawn. With one: a file to start from — `tsx` (the code) or `html` (the look, static) */
+// the parts that put themselves where they belong by JS at runtime — over the content, open, at the edge: the static html shows them in the wrong place
+const PLACED_BY_JS = ['Sheet', 'SheetStack', 'SheetSteps', 'SheetStage', 'Step', 'Modal', 'Menu', 'Dropdown', 'Snackbar', 'FloatBar'];
+
+/** a story names cardds's own controls by hand where the gallery's page is not in the story's language (`backLabel="กลับ"` on an
+ *  lang="en" page). In an app that is noise — and a session copies what it is handed (two prototypes did, 2026-10-08): the starting file
+ *  leaves those props, and the note above them, out. The tags are read by the name the import gives them (`Home as HomeScreen`). */
+function ownWords(tsx, imports) {
+  let out = tsx;
+  for (const [name, props] of Object.entries(CONTROL_NAMES)) {
+    const tags = [name, ...[...imports.matchAll(new RegExp(`\\b${name}\\s+as\\s+(\\w+)`, 'g'))].map((m) => m[1])];
+    for (const tag of tags) {
+      for (let at = out.indexOf(`<${tag}`); at >= 0; at = out.indexOf(`<${tag}`, at + 1)) {
+        if (/[\w.]/.test(out[at + tag.length + 1] ?? '')) continue;
+        const was = tagAt(out, at);
+        const now = props.reduce((t, prop) => t.replace(new RegExp(`(\\n[ \\t]*|[ \\t]+)${prop}\\s*=\\s*(?:"[^"]*"|'[^']*'|\\{\\s*(?:"[^"]*"|'[^']*')\\s*\\})`, 'g'), ''), was);
+        if (now !== was) out = out.slice(0, at) + now + out.slice(at + was.length);
+      }
+    }
+  }
+  return out.replace(/^[ \t]*(?:\/\/|\/\*|\{\/\*)[^\n]*cardds-ignore-next-line[^\n]*\n/gm, '');
+}
+
+/** no id: the screens already drawn. With one: a file to start from — `tsx` (the code, a string) or `html` (the look, static: `{ html, warning? }`, the warning when the picture lies) */
 export function scaffold(cat, id, { format = 'tsx', css = CSS } = {}) {
   if (!id) return cat.stories.filter((s) => s.screen).map((s) => ({ id: s.id, summary: sentence(s.description) }));
   const s = cat.stories.find((x) => x.id.toLowerCase() === String(id).toLowerCase());
   if (!s) return { error: `no story "${id}"`, closest: closest(cat.stories.map((x) => x.id), String(id)) };
   if (format === 'html') {
     if (!s.html) return { error: `${s.id} has no rendered html: ${s.htmlError ?? 'it did not render'}` };
-    return `<!doctype html>
+    const placed = [...new Set(s.uses.filter((u) => PLACED_BY_JS.includes(u)))];
+    const warning = placed.length ? `${placed.join(', ')} ${placed.length > 1 ? 'are' : 'is'} placed by JS at runtime, so this static picture is NOT the layout (a sheet over the content, a menu not open): use format tsx to see it live` : undefined;
+    return { html: `<!doctype html>${warning ? `\n<!-- ${warning} -->` : ''}
 <html lang="en">
 <head>
 <meta charset="utf-8">
@@ -126,14 +208,14 @@ export function scaffold(cat, id, { format = 'tsx', css = CSS } = {}) {
 ${s.html}
 </body>
 </html>
-`;
+`, ...(warning && { warning }) };
   }
   const glue = [...s.imports.matchAll(/import (.+?) from '\.\/_[^']*';/g)]
     .flatMap((m) => m[1].replace(/[{}]/g, '').split(',').map((n) => n.trim().replace(/^type /, '').split(/ as /).pop()).filter(Boolean));
   const taken = /\bScreen\b/.test(s.imports) || /^(?:function|const|class|type|interface) Screen\b/m.test(s.tsx);
   const as = taken ? 'MyScreen' : 'Screen';
   const note = glue.length ? `// story glue from ./_*, not part of the package — replace or drop: ${glue.join(', ')}\n` : '';
-  return `${note}${s.imports}\n\n${s.tsx.replace(new RegExp(`^function ${s.name}\\b`, 'm'), `export default function ${as}`)}\n`;
+  return `${note}${s.imports}\n\n${ownWords(s.tsx, s.imports).replace(new RegExp(`^function ${s.name}\\b`, 'm'), `export default function ${as}`)}\n`;
 }
 
 /** the rules of lint/rules.mjs over a piece of code */

package/lib/guide.mjs

@@ -0,0 +1,16 @@
+// lib/guide.mjs — the few rules of using cardds that no checker can see, for an AI session: ONE text, two doors —
+// `npx cardds guide` (bin/cardds.mjs) prints it, the MCP server (lib/mcp.mjs) hands it over as its `instructions` at start.
+// Short on purpose: an MCP client may truncate server instructions, so the trigger and the order come first. A component's own rules are
+// not here — they are in its JSDoc (get_component) and in lint/rules.mjs (check).
+export const GUIDE = `cardds — BEFORE drawing any phone-width / mobile screen in a project with @usableapp/cardds, or that Lh asks to build "with cardds": load these tools (ToolSearch "cardds" if they are deferred) and call find_components. This holds when the request only says prototype, poc, mock-up, sketch, "show me a design", หน้า, หน้าจอ, ขึ้นหน้า, ขอดู prototype — a screen, card, bottom sheet, sheet stack, form step, sticky note / post-it, chat of notes, stamp, postcard, home. Never hand-write HTML, CSS or emoji for what it has.
+ORDER: find → scaffold or get → write → check. First question: has cardds drawn this screen already? find BOTH ways: by the axes (represents · shape · interact) and by the English noun of the task ("sticky", "stamp", "chat").
+TOOLS: find_components · scaffold_screen · get_component · list_components · check_source. No MCP: npx cardds find|scaffold|get|list|check (all take --json).
+What no checker sees:
+1. cardds is a framework you take from outside. Never edit, commit to or release cardds from a consumer project, never node_modules. What cannot be set from outside is a framework gap: STOP and tell the user exactly what you needed.
+2. Adjust from outside only, widest first: theme.css bases → knobs (--<component>-<what>) → props/slots. The theme's values are the user's call; never pick them.
+3. Every component is controlled like an input (state/open/value + its on…, or default…) and none knows another: the app owns the state and wires them.
+4. Import components, never copy their markup or classes: a component is the look AND the behaviour.
+5. Mobile only, big targets; never adapt it to desktop.
+A prototype in HTML (scaffold --html) is a still picture to look at, never a screen; when it warns, run the tsx. check is for tsx only.
+Everything else (a component's own rules) is in get_component and enforced by check.
+`;

package/lib/mcp.mjs

@@ -5,6 +5,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import * as catalog from './catalog.mjs';
+import { GUIDE } from './guide.mjs';
 
 const { version } = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
 const str = (description) => ({ type: 'string', description });
@@ -13,7 +14,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 +26,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 +63,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;
@@ -67,9 +84,9 @@ export function serve({ root, input = process.stdin, output = process.stdout } =
   function handle(msg) {
     const { id, method, params } = msg;
     switch (method) {
-      case 'initialize': return reply(id, { protocolVersion: params?.protocolVersion ?? '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'cardds', version } });
+      case 'initialize': return reply(id, { protocolVersion: params?.protocolVersion ?? '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'cardds', version }, instructions: GUIDE }); // the guide: what no checker sees, handed over before the first question
       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/lint/eslint.mjs

@@ -18,8 +18,8 @@ const rule = (level, description) => ({
     };
   },
 });
-const check = rule('error', 'cardds used through its components: no hand-written cardds class; the bar is the Screen\'s bottom');
-const advice = rule('warn', 'cardds behaviour kept: a Sheet that can move and slides out; no bar in front of a sheet');
+const check = rule('error', 'cardds used through its components: no hand-written cardds class, no native <select>; the bar is the Screen\'s bottom');
+const advice = rule('warn', 'cardds behaviour kept: a Sheet that can move and slides out; no bar in front of a sheet; the cursor, the control names and the look are cardds\'s and the theme\'s, not the element\'s');
 
 const plugin = { meta: { name: '@usableapp/cardds/eslint' }, rules: { check, advice } };
 plugin.configs = {

package/lint/rules.mjs

@@ -9,6 +9,12 @@ import { fileURLToPath } from 'node:url';
 
 const CSS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'css');
 
+/** the props whose default is cardds's own word (src/words.ts), per component — a `label` that is a control's required accessible name (IconBtn, Fab, Pin…) is not here */
+export const CONTROL_NAMES = {
+  Sheet: ['handle'], CallSheet: ['handle'], StackSheet: ['backLabel'], Home: ['backLabel'], Walkthrough: ['backLabel', 'nextLabel'],
+  Calendar: ['prevLabel', 'nextLabel'], SheetStep: ['skipLabel'], PostLetter: ['backLabel', 'pictureLabel', 'playLabel', 'pauseLabel', 'toLabel'],
+};
+
 const lineOf = (text, idx) => text.slice(0, idx).split('\n').length;
 
 /** every class cardds's CSS styles — read from the package's own css/, so the list is never copied by hand */
@@ -29,7 +35,7 @@ export function carddsClasses(dir = CSS_DIR) {
 }
 
 /** the whole of a JSX opening tag from `<Name` — attributes may hold `=>` and nested braces, so a `[^>]*` regex is not enough */
-function tagAt(text, start) {
+export function tagAt(text, start) {
   let depth = 0, quote = null;
   for (let i = start + 1; i < text.length; i++) {
     const c = text[i];
@@ -83,6 +89,23 @@ function classWords(text, at) {
   return words;
 }
 
+/** a style object's or attribute's `key: value` entries from its body (`at` = where the body starts in the text): split on the commas / semicolons that are not inside a string, bracket or call */
+function* styleEntries(body, at, sep) {
+  let depth = 0, quote = null, from = 0;
+  for (let i = 0; i <= body.length; i++) {
+    const c = body[i];
+    if (quote) { if (c === quote && body[i - 1] !== '\\') quote = null; continue; }
+    if (c === '"' || c === "'" || c === '`') quote = c;
+    else if (c === '(' || c === '[' || c === '{') depth++;
+    else if (c === ')' || c === ']' || c === '}') depth--;
+    else if ((c === sep && depth === 0) || i === body.length) {
+      const m = body.slice(from, i).match(/^\s*(?:'([^']+)'|"([^"]+)"|([\w$-]+))\s*:\s*([\s\S]*)$/);
+      if (m) yield { key: m[1] ?? m[2] ?? m[3], value: m[4], at: at + from + m[0].length - m[4].length };
+      from = i + 1;
+    }
+  }
+}
+
 /**
  * @param {string} text  a source file
  * @param {string} file  its name, for the findings
@@ -91,7 +114,12 @@ function classWords(text, at) {
 export function checkSource(source, file, { classes = carddsClasses() } = {}) {
   const findings = [];
   const lines = source.split('\n');
-  const text = source.replace(/\/\*[\s\S]*?\*\/|(?<![:'"`\\])\/\/[^\n]*/g, (c) => c.replace(/[^\n]/g, ' ')); // comments out, lines kept
+  let text = source.replace(/\/\*[\s\S]*?\*\/|(?<![:'"`\\])\/\/[^\n]*/g, (c) => c.replace(/[^\n]/g, ' ')); // comments out, lines kept
+  // a component imported under another name (`Home as HomeScreen`) is still that component: its tags read by the name the rules know. Lines kept
+  // (seen 2026-10-08: a prototype's `<HomeScreen backLabel="กลับ">` passed control-name-repeat)
+  for (const imp of text.matchAll(/import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*['"][^'"]*cardds[^'"]*['"]/g)) {
+    for (const [, name, alias] of imp[1].matchAll(/\b([A-Z]\w*)\s+as\s+([A-Z]\w*)/g)) text = text.replace(new RegExp(`(</?)${alias}\\b`, 'g'), `$1${name}`);
+  }
   const add = (rule, level, idx, message) => {
     const line = lineOf(text, idx);
     if (!/cardds-ignore-next-line/.test(lines[line - 2] ?? '')) findings.push({ rule, level, file, line, message }); // `// cardds-ignore-next-line` — a deliberate case (a story that shows the wrong way)
@@ -131,5 +159,49 @@ export function checkSource(source, file, { classes = carddsClasses() } = {}) {
     if (/<Sheet\b/.test(screen) && /<ActionBar\b/.test(screen)) add('screen.bar-with-sheet', 'warn', m.index, 'a Sheet and an ActionBar on one Screen — a screen with a sheet finishes on the sheet\'s CardFoot, no bar.');
   }
 
+  // 4 · focus: cardds places the cursor when these parts come up — an `autoFocus` or a `.focus(` beside them fights it
+  if (/<(?:Sheet|SheetStep|SheetSteps|SheetStack|StackSheet|Home|Modal|CallSheet)\b/.test(text)) {
+    const msg = (what) => `${what} in a file that uses a Sheet, SheetStep, SheetStack or Modal: cardds already places the cursor when one comes up (the field marked data-autofocus, else the first field, else the heading) — remove it. To choose the field put data-autofocus on it; focus about something else (the field a server error points at) is the app's: then // cardds-ignore-next-line with the reason.`;
+    for (const m of text.matchAll(/(?<![\w)\]])<[A-Za-z][\w.]*/g)) {
+      const hit = tagAt(text, m.index).match(/\sautoFocus\b(?!\s*:)/);
+      if (hit) add('focus-by-hand', 'warn', m.index + hit.index + 1, msg('autoFocus'));
+    }
+    for (const m of text.matchAll(/\.focus\s*\(/g)) add('focus-by-hand', 'warn', m.index, msg('.focus()'));
+  }
+
+  // 5 · control names: cardds names its controls in the page's language — a literal that only repeats them is noise (and English-only)
+  for (const [name, props] of Object.entries(CONTROL_NAMES)) {
+    for (const m of text.matchAll(new RegExp(`<${name}\\b`, 'g'))) {
+      const tag = tagAt(text, m.index);
+      for (const prop of props) {
+        const hit = tag.match(new RegExp(`\\s${prop}\\s*=\\s*(?:"[^"]*"|'[^']*'|\\{\\s*(?:"[^"]*"|'[^']*'|\`[^\`$]*\`)\\s*\\})`));
+        if (hit) add('control-name-repeat', 'warn', m.index + hit.index + 1, `${prop}="…" on <${name}>: cardds names this control itself, in the page's language (<html lang>) — drop it unless the words differ from cardds's. Another language is setWords(lang, {…}) once at app start, not a string on each component.`);
+      }
+    }
+  }
+
+  // 6 · a native <select> opens the platform's picker: not cardds's look, not its words — Dropdown is the one component for it
+  for (const m of text.matchAll(/<select\b/g)) add('native-select', 'error', m.index, '<select> is the platform\'s own picker: it draws outside cardds\'s look and takes none of its knobs — use <Dropdown> (one component, value controlled, the pill named by the chosen item).');
+
+  // 7 · a raw colour or px length in a style prop: the look is the theme's (theme.css · a knob · a prop); a custom property (`'--x': …`) IS a knob, so its value is the app's to set
+  if (/\.[jt]sx$/.test(file)) {
+    const raw = (value) => {
+      const v = value.replace(/var\((?:[^()]|\([^()]*\))*\)/g, '');
+      return /#[0-9a-fA-F]{3,8}\b|\b(?:rgba?|hsla?)\(/.test(v) ? 'raw colour' : /(?<![\w.])\d*\.?\d+px\b/.test(v) ? 'raw px length' : null;
+    };
+    const report = (e) => {
+      const what = !e.key.startsWith('--') && raw(e.value);
+      if (what) add('raw-value', 'warn', e.at, `${what} in style (${e.key}): the look is set in the project's theme.css, by a knob (--<component>-<what>) or by a prop — not on the element. A hairline is var(--border-w), even 1px.`);
+    };
+    for (const m of text.matchAll(/\bstyle\s*=\s*\{\{/g)) {
+      const open = m.index + m[0].length - 2, expr = braceAt(text, open);
+      if (expr.endsWith('}}')) for (const e of styleEntries(expr.slice(2, -2), open + 2, ',')) report(e);
+    }
+    for (const m of text.matchAll(/\bstyle\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+      const body = m[1] ?? m[2];
+      for (const e of styleEntries(body, m.index + m[0].indexOf(body), ';')) report(e);
+    }
+  }
+
   return findings.sort((a, b) => a.line - b.line);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usableapp/cardds",
-  "version": "0.7.72",
+  "version": "0.7.74",
   "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.",