@usableapp/cardds 0.7.73 → 0.7.74

package/dist/choice/Calendar.d.ts

@@ -16,9 +16,9 @@ export interface CalendarProps extends Omit<ComponentProps<'div'>, 'title' | 'on
     onPrev?: () => void;
     /** the next-month button was tapped: the app turns the month, as with `onPrev` */
     onNext?: () => void;
-    /** the previous button's accessible name (default "Previous", by `<html lang>`) */
+    /** the previous button's accessible name — cardds names it in the page's language (`<html lang>`); pass it only for different words */
     prevLabel?: string;
-    /** the next button's accessible name (default "Next", by `<html lang>`) */
+    /** the next button's accessible name — cardds names it in the page's language (`<html lang>`); pass it only for different words */
     nextLabel?: string;
     /** softly marked days */
     marks?: number[];

package/dist/post/PostLetter.d.ts

@@ -32,15 +32,15 @@ export interface PostLetterProps extends ComponentProps<'div'> {
     sign?: ReactNode;
     /** one line under the card: the trip it made */
     journey?: ReactNode;
-    /** the tab's words while the picture is in front (default: cardds's own, by `<html lang>`) */
+    /** the tab's words while the picture is in front — cardds names it in the page's language (`<html lang>`); pass it only for different words */
     backLabel?: string;
-    /** the tab's words while the back is in front */
+    /** the tab's words while the back is in front — named by cardds like `backLabel`; pass it only for different words */
     pictureLabel?: string;
-    /** the play control's name while the note is paused (default "Play", by `<html lang>`) */
+    /** the play control's name while the note is paused — named by cardds in the page's language (`<html lang>`); pass it only for different words */
     playLabel?: string;
-    /** the play control's name while the note plays (default "Pause", by `<html lang>`) */
+    /** the play control's name while the note plays — named by cardds like `playLabel`; pass it only for different words */
     pauseLabel?: string;
-    /** the small word before the name (default "To", by `<html lang>`) */
+    /** the small word before the name — named by cardds in the page's language (`<html lang>`); pass it only for different words */
     toLabel?: ReactNode;
 }
 /**

package/dist/sheets/Drawer.d.ts

@@ -15,7 +15,7 @@ export interface ModalProps extends ComponentProps<'article'> {
  * out below while the lift moves up.
  * A COMPONENT, not a wiring: it does not know its buttons. They are plain `IconBtn`s / `Btn`s with the app's `onClick` — the app
  * records the answer and sets `open={false}`; the modal's one behaviour is how it leaves. `onDismiss` asks to leave unanswered (a tap on
- * the scrim, Esc).
+ * the scrim, Esc). When it has arrived, cardds puts the cursor in the field marked `data-autofocus`, else the first field, else the question — write no focus code.
  */
 export declare function Modal({ open, onClosed, onDismiss, className, ...rest }: ModalProps): import("react").JSX.Element;
 export interface LiftProps extends ComponentProps<'div'> {

package/dist/sheets/Drawer.js

@@ -8,7 +8,7 @@ import { cx } from '../cx.js';
  * out below while the lift moves up.
  * A COMPONENT, not a wiring: it does not know its buttons. They are plain `IconBtn`s / `Btn`s with the app's `onClick` — the app
  * records the answer and sets `open={false}`; the modal's one behaviour is how it leaves. `onDismiss` asks to leave unanswered (a tap on
- * the scrim, Esc).
+ * the scrim, Esc). When it has arrived, cardds puts the cursor in the field marked `data-autofocus`, else the first field, else the question — write no focus code.
  */
 export function Modal({ open = true, onClosed, onDismiss, className, ...rest }) {
     const ref = useRef(null);

package/dist/sheets/Sheet.d.ts

@@ -19,7 +19,7 @@ export interface SheetProps extends Omit<ComponentProps<'article'>, 'onChange'>
     onSettled?: (state: SheetState) => void;
     /** the states a drag snaps to and a reveal may climb through — "peek half full", or an array (default all four) */
     states?: string | readonly Resting[];
-    /** the grab handle; `false` for a sheet with no handle, a string sets its accessible name */
+    /** the grab handle; `false` for a sheet with no handle. cardds names it in the page's language (`<html lang>`) — a string is for different words only */
     handle?: boolean | string;
     /** the grab mark. `line` (default) or `dots`: both sit in the card's top padding, the same distance from the edge, so the title does not move */
     mark?: 'line' | 'dots';
@@ -50,5 +50,6 @@ export interface SheetProps extends Omit<ComponentProps<'article'>, 'onChange'>
  * fixed habit of every sheet. A sheet asked up in the same box meanwhile waits for it: "one left, another came", never two sheets
  * crossing and never one continuous move, whatever the app's wiring (both states set in one render, or the next raised from the
  * first's `onSettled`) — the app adds no timer.
+ * The CURSOR is cardds's too: once it has come up it waits in the field marked `data-autofocus`, else the first field, else the heading — write no `autoFocus` or `.focus()` for it.
  */
 export declare function Sheet({ state, defaultState, onStateChange, onSettled, states, handle, mark, refreshing, tone, paper, className, children, onFocus, ...rest }: SheetProps): import("react").JSX.Element;

package/dist/sheets/Sheet.js

@@ -37,6 +37,7 @@ function markLong(node, long) {
  * fixed habit of every sheet. A sheet asked up in the same box meanwhile waits for it: "one left, another came", never two sheets
  * crossing and never one continuous move, whatever the app's wiring (both states set in one render, or the next raised from the
  * first's `onSettled`) — the app adds no timer.
+ * The CURSOR is cardds's too: once it has come up it waits in the field marked `data-autofocus`, else the first field, else the heading — write no `autoFocus` or `.focus()` for it.
  */
 export function Sheet({ state, defaultState = 'half', onStateChange, onSettled, states, handle = true, mark = 'line', refreshing, tone, paper, className, children, onFocus, ...rest }) {
     const [current, request] = useControlled(state, defaultState, onStateChange);

package/dist/sheets/SheetStack.d.ts

@@ -38,5 +38,6 @@ export interface SheetStackProps extends ComponentProps<'div'> {
  * the phone's back button can open and close a section. WHAT the sheet does with that, and with `refreshing`, lives on the card (`stack`):
  * the place classes, the grip, the pull. The stack only says which index. Sheets are rigid — the open one slides up, the ones after it leave
  * below, the ones before tuck under nearest-first; closing reverses in two beats. Only `translate` (stack.css); never a size.
+ * The CURSOR is cardds's: a sheet that opens takes it in the field marked `data-autofocus`, else the first field, else the heading — write no `autoFocus` or `.focus()` for it.
  */
 export declare function SheetStack({ mode, open, defaultOpen, onOpenChange, onRefresh, refreshing, mark, fanned, closed, rise, base, className, children, onClickCapture, onPointerDownCapture, ref: passed, ...rest }: SheetStackProps): import("react").JSX.Element;

package/dist/sheets/SheetStack.js

@@ -55,6 +55,7 @@ function stamp(child, place) {
  * the phone's back button can open and close a section. WHAT the sheet does with that, and with `refreshing`, lives on the card (`stack`):
  * the place classes, the grip, the pull. The stack only says which index. Sheets are rigid — the open one slides up, the ones after it leave
  * below, the ones before tuck under nearest-first; closing reverses in two beats. Only `translate` (stack.css); never a size.
+ * The CURSOR is cardds's: a sheet that opens takes it in the field marked `data-autofocus`, else the first field, else the heading — write no `autoFocus` or `.focus()` for it.
  */
 export function SheetStack({ mode = 'tap', open, defaultOpen = null, onOpenChange, onRefresh, refreshing = null, mark = 'dots', fanned, closed, rise = 'under', base, className, children, onClickCapture, onPointerDownCapture, ref: passed, ...rest }) {
     const [current, request] = useControlled(open, defaultOpen, onOpenChange);

package/dist/sheets/SheetSteps.d.ts

@@ -40,7 +40,7 @@ export interface SheetStepProps extends Omit<ComponentProps<'li'>, 'title'> {
     summary?: ReactNode;
     /** the member may pass this step without doing it: a small link at its end moves on (reason `skip`) */
     skippable?: boolean;
-    /** the skip link's words (default "Skip") */
+    /** the skip link's words — cardds names it in the page's language (`<html lang>`); pass it only for different words */
     skipLabel?: ReactNode;
     /** what went wrong, in words — one line UNDER the step's button (an alert icon, `--signal-error`, read out at once): the number
      *  is not a phone number, no signal, the code could not be sent, the two PINs differ. The step stays where it is; to send the
@@ -50,5 +50,5 @@ export interface SheetStepProps extends Omit<ComponentProps<'li'>, 'title'> {
      *  step's buttons take no taps meanwhile. The app moves `at` when the answer is good, or sets `error`. */
     busy?: ReactNode;
 }
-/** SheetStep — one step of a SheetSteps: its title, then what the member does (a Field, a Pin, a Toggle, the step's own Btn). */
+/** SheetStep — one step of a SheetSteps: its title, then what the member does (a Field, a Pin, a Toggle, the step's own Btn). When it opens, cardds puts the cursor in the field marked `data-autofocus`, else the first field, else the title — write no focus code. */
 export declare function SheetStep({ title, summary, skippable, skipLabel, error, busy, className, children, ...rest }: SheetStepProps): import("react").JSX.Element;

package/dist/sheets/SheetSteps.js

@@ -201,7 +201,7 @@ function useStepChecks(off, park) {
     };
     return { note, group, press };
 }
-/** SheetStep — one step of a SheetSteps: its title, then what the member does (a Field, a Pin, a Toggle, the step's own Btn). */
+/** SheetStep — one step of a SheetSteps: its title, then what the member does (a Field, a Pin, a Toggle, the step's own Btn). When it opens, cardds puts the cursor in the field marked `data-autofocus`, else the first field, else the title — write no focus code. */
 export function SheetStep({ title, summary, skippable, skipLabel = word('skip'), error, busy, className, children, ...rest }) {
     const ctx = useContext(StepCtx);
     if (!ctx)

package/dist/sheets/StackSheet.d.ts

@@ -29,7 +29,7 @@ export interface StackSheetProps extends Omit<ComponentProps<'article'>, 'title'
     onTabChange?: (tab: string) => void;
     /** the SHEET FOOT: the CTA at the sheet's bottom (one row) */
     foot?: ReactNode;
-    /** the back button's label (shown once the sheet is open) */
+    /** the back button's label (shown once the sheet is open) — cardds names it in the page's language (`<html lang>`); pass it only for different words */
     backLabel?: string;
     /** where the back button stands: `none` (default — hidden for now, Lh 2026-09-29: not used in real work yet; a tap on the open sheet's title folds it) ·
      *  `end` (after the tabs, chevron DOWN: the sheet folds down) · `start` (before the title, chevron left) */
@@ -42,6 +42,6 @@ export interface StackSheetProps extends Omit<ComponentProps<'article'>, 'title'
  * SHEET BODY (the children; scrolls) · SHEET FOOT (`foot`, the CTA) at the bottom. Its tabs are icon buttons. The chosen one is filled
  * only while this sheet is open — a closed home shows every icon plain; the disc fades in with the rise and out with the fold.
  * A count shows as a small circle over its icon. The body is the app's: render the page of the chosen tab (and nothing while the sheet
- * is closed — see `Home`). A direct child of `SheetStack`.
+ * is closed — see `Home`). A direct child of `SheetStack`. Once open, cardds puts the cursor in the field marked `data-autofocus`, else the first field, else the heading — write no focus code.
  */
 export declare function StackSheet({ title, tone, paper, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel, backAt, stack, className, children, ...rest }: StackSheetProps): import("react").JSX.Element;

package/dist/sheets/StackSheet.js

@@ -17,7 +17,7 @@ import { word } from '../words.js';
  * SHEET BODY (the children; scrolls) · SHEET FOOT (`foot`, the CTA) at the bottom. Its tabs are icon buttons. The chosen one is filled
  * only while this sheet is open — a closed home shows every icon plain; the disc fades in with the rise and out with the fold.
  * A count shows as a small circle over its icon. The body is the app's: render the page of the chosen tab (and nothing while the sheet
- * is closed — see `Home`). A direct child of `SheetStack`.
+ * is closed — see `Home`). A direct child of `SheetStack`. Once open, cardds puts the cursor in the field marked `data-autofocus`, else the first field, else the heading — write no focus code.
  */
 export function StackSheet({ title, tone, paper, icon, tabs, tab: tabProp, defaultTab, onTabChange, foot, backLabel = word('back'), backAt = 'none', stack, className, children, ...rest }) {
     const [tab, pick] = useControlled(tabProp, defaultTab ?? tabs?.[0]?.id, onTabChange);

package/dist/templates/CallSheet.d.ts

@@ -10,7 +10,7 @@ export interface CallSheetSheet {
     foot?: ReactNode;
     /** a small link UNDER that button (a `Link sm`, e.g. details for developers) */
     footLink?: ReactNode;
-    /** this sheet's handle — its accessible name (a string), or `false` for none; overrides the CallSheet's `handle` */
+    /** this sheet's handle: `false` for none, a string only for words different from cardds's own (named in the page's language, `<html lang>`); overrides the CallSheet's `handle` */
     handle?: SheetProps['handle'];
 }
 /** one way in: its button and the sheet it calls */
@@ -45,7 +45,7 @@ export interface CallSheetProps extends Omit<ComponentProps<typeof Screen>, 'chi
     onOpenChange?: (open: boolean, way: number | null) => void;
     /** the sheets' resting states once up (default "peek full") */
     states?: string;
-    /** every sheet's handle: its accessible name in the app's language (a string — default "Resize"), or `false` for none. A sheet's own `handle` wins */
+    /** every sheet's handle: `false` for none; cardds names it in the page's language (`<html lang>`), so pass a string only for different words. A sheet's own `handle` wins */
     handle?: SheetProps['handle'];
     /** layers over the screen */
     children?: ReactNode;

package/dist/templates/Home.d.ts

@@ -46,7 +46,7 @@ export interface HomeProps extends Omit<ComponentProps<typeof Screen>, 'children
     base?: ReactNode;
     /** keep a sheet's body mounted after it closes (it opens again at once, scrolled where it was); default: dropped */
     keep?: boolean;
-    /** the open sheet's back button label */
+    /** the open sheet's back button label — cardds names it in the page's language (`<html lang>`); pass it only for different words */
     backLabel?: string;
     /** the open sheet's back button — see `StackSheet backAt` (default `none`: hidden for now) */
     backAt?: StackSheetProps['backAt'];

package/dist/templates/Walkthrough.d.ts

@@ -32,9 +32,9 @@ export interface WalkthroughProps extends Omit<ComponentProps<typeof Screen>, 'c
     ctaLink?: ReactNode;
     /** layers over the screen: the app's `SheetStage dim` + `Modal` that a link or button opens (the app wires it) */
     children?: ReactNode;
-    /** the pager's back button name (default "Back", by `<html lang>`) */
+    /** the pager's back button name — cardds names it in the page's language (`<html lang>`); pass it only for different words */
     backLabel?: string;
-    /** the pager's next button name (default "Next", by `<html lang>`) */
+    /** the pager's next button name — cardds names it in the page's language (`<html lang>`); pass it only for different words */
     nextLabel?: string;
 }
 /**

package/lib/catalog.mjs

@@ -5,7 +5,7 @@ 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)), '..');
@@ -167,6 +167,25 @@ export function find(cat, query, axes = {}) {
 // 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) }));
@@ -196,7 +215,7 @@ ${s.html}
   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 });
@@ -83,7 +84,7 @@ 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: 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}`); }

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.73",
+  "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.",