bestax-mcp 0.0.0

package/data/skills.json

@@ -0,0 +1,148 @@
+{
+  "skills": [
+    {
+      "name": "bestax-custom-component",
+      "description": "Build a custom React component in the bestax/Bulma style. In an app using @allxsmith/bestax-bulma — compose existing components, helper props, public hooks (useBulmaClasses, usePrefixedClassNames), and --bulma-* CSS variables. In the bestax monorepo — the full component pipeline (SCSS partial, stories, tests, docs, wiring). Use when creating a component beyond stock Bulma or extending one.",
+      "promptName": "custom-component",
+      "dir": "bestax-custom-component",
+      "references": [
+        { "id": "api", "file": "references/api.md", "bytes": 5379 },
+        {
+          "id": "component-catalog",
+          "file": "references/component-catalog.md",
+          "bytes": 17351
+        },
+        {
+          "id": "library-contributor",
+          "file": "references/library-contributor.md",
+          "bytes": 15257
+        },
+        { "id": "patterns", "file": "references/patterns.md", "bytes": 4601 }
+      ],
+      "examples": [
+        { "id": "stat-card", "file": "examples/stat-card.tsx", "bytes": 3828 }
+      ]
+    },
+    {
+      "name": "bestax-form",
+      "description": "Build forms with @allxsmith/bestax-bulma — Field/Control/Label/Help composition, inputs, selects, checkboxes, radios, switches, and advanced controls (Autocomplete, Slider, Numberinput, Rate, Taginput, File, date/time). There is no form/validation library; this skill shows the components and the validate-it-yourself error pattern. Use when building a form, wiring inputs to state, or showing validation/error state.",
+      "promptName": "form",
+      "dir": "bestax-form",
+      "references": [
+        { "id": "api", "file": "references/api.md", "bytes": 8378 },
+        { "id": "patterns", "file": "references/patterns.md", "bytes": 5566 }
+      ],
+      "examples": []
+    },
+    {
+      "name": "bestax-icons",
+      "description": "Use icons in an app built with @allxsmith/bestax-bulma — the Icon/IconText components and the five supported libraries (Font Awesome, Material Design Icons, Ionicons, Google Material Icons, Material Symbols). Use when adding an icon, choosing or configuring the app-wide icon library, fixing an icon that renders blank, pairing icons with text, or making icons accessible (decorative vs labeled).",
+      "promptName": "icons",
+      "dir": "bestax-icons",
+      "references": [
+        {
+          "id": "icon-libraries",
+          "file": "references/icon-libraries.md",
+          "bytes": 6179
+        }
+      ],
+      "examples": [
+        { "id": "icon-usage", "file": "examples/icon-usage.tsx", "bytes": 2720 }
+      ]
+    },
+    {
+      "name": "bestax-layout-scaffold",
+      "description": "Scaffold a complete, responsive page layout with @allxsmith/bestax-bulma — app shells/dashboards, marketing/landing pages, centered auth/settings pages, and card-grid catalogs. Use when building a full page or overall app layout (not a single component).",
+      "promptName": "layout-scaffold",
+      "dir": "bestax-layout-scaffold",
+      "references": [
+        {
+          "id": "archetypes",
+          "file": "references/archetypes.md",
+          "bytes": 8038
+        },
+        {
+          "id": "layout-components",
+          "file": "references/layout-components.md",
+          "bytes": 14389
+        }
+      ],
+      "examples": [
+        { "id": "app-shell", "file": "examples/app-shell.tsx", "bytes": 2765 },
+        { "id": "card-grid", "file": "examples/card-grid.tsx", "bytes": 2700 },
+        { "id": "centered", "file": "examples/centered.tsx", "bytes": 1443 },
+        {
+          "id": "content-page",
+          "file": "examples/content-page.tsx",
+          "bytes": 2608
+        },
+        { "id": "landing", "file": "examples/landing.tsx", "bytes": 3910 }
+      ]
+    },
+    {
+      "name": "bestax-migrate",
+      "description": "Migrate an existing app from react-bulma-components (v4) to @allxsmith/bestax-bulma on Bulma v1 — run the bestax-migrate codemod, then resolve every TODO(bestax-migrate) comment it leaves using the mapping references. Use when a repo imports react-bulma-components and wants to move to bestax-bulma, when TODO(bestax-migrate) comments are present in a codebase, or when asked to migrate off an unmaintained React Bulma library.",
+      "promptName": "migrate",
+      "dir": "bestax-migrate",
+      "references": [
+        {
+          "id": "component-map",
+          "file": "references/component-map.md",
+          "bytes": 11894
+        },
+        {
+          "id": "css-migration",
+          "file": "references/css-migration.md",
+          "bytes": 5679
+        },
+        { "id": "prop-map", "file": "references/prop-map.md", "bytes": 6363 },
+        {
+          "id": "unmappables",
+          "file": "references/unmappables.md",
+          "bytes": 4866
+        }
+      ],
+      "examples": []
+    },
+    {
+      "name": "bestax-optimize",
+      "description": "Reduce the built CSS size of an app using @allxsmith/bestax-bulma — measure raw and gzip size, then apply the cheapest lever that fits (lighter prebuilt CSS flavor, hand-rolled modular Sass build, import and icon-asset hygiene). Use when the CSS bundle looks too big, a size budget or Lighthouse audit flags stylesheet weight, switching bestax.css to a versions/*.css flavor, or setting up a modular @use Bulma/Sass build.",
+      "promptName": "optimize",
+      "dir": "bestax-optimize",
+      "references": [
+        {
+          "id": "modular-build",
+          "file": "references/modular-build.md",
+          "bytes": 7761
+        }
+      ],
+      "examples": []
+    },
+    {
+      "name": "bestax-theming",
+      "description": "Customize colors, branding, dark mode, and visual tokens of an app built with @allxsmith/bestax-bulma. Use when changing the primary/brand color, recoloring components, overriding Bulma --bulma-* CSS variables, setting fonts/radius/spacing tokens, adding light/dark mode, or configuring the app-wide icon library / class prefix via ConfigProvider.",
+      "promptName": "theming",
+      "dir": "bestax-theming",
+      "references": [
+        {
+          "id": "css-variables",
+          "file": "references/css-variables.md",
+          "bytes": 24452
+        },
+        {
+          "id": "themeable-components",
+          "file": "references/themeable-components.md",
+          "bytes": 20268
+        }
+      ],
+      "examples": [
+        { "id": "dark-mode", "file": "examples/dark-mode.tsx", "bytes": 1148 },
+        {
+          "id": "theme-config",
+          "file": "examples/theme-config.tsx",
+          "bytes": 2089
+        }
+      ]
+    }
+  ]
+}

package/dist/data.d.ts

@@ -0,0 +1,131 @@
+/** Bumped by the generator when the shape changes incompatibly. */
+export declare const SUPPORTED_SCHEMA_VERSION = 1;
+export interface PropRow {
+    name: string;
+    type: string;
+    default: string | null;
+    description: string;
+    required: boolean;
+    inherited: boolean;
+    deprecated: boolean;
+    deprecationNote?: string;
+    /** Docs slug defining a value union too large to inline, e.g. Bulma colors. */
+    valuesRef?: string;
+}
+export interface TypeDef {
+    name: string;
+    expansion: string;
+    summary: string;
+}
+export interface Part {
+    /** Dot-path: `Navbar`, `Navbar.Brand`. */
+    path: string;
+    summary: string;
+    /** Set when the sub-component is also exported standalone. */
+    component: string | null;
+    props: PropRow[];
+    extraProps: PropRow[];
+    catchAll: string | null;
+    types: TypeDef[];
+}
+export interface CssVar {
+    css: string;
+    sass: string | null;
+    default: string;
+    /** `component`: declared on the component's own selector. `global`: on :root. */
+    scope: 'component' | 'global';
+}
+export interface Example {
+    title: string;
+    code: string;
+}
+export interface ComponentRecord {
+    name: string;
+    kind: 'component' | 'helper';
+    category: string;
+    slug: string;
+    docsUrl: string;
+    summary: string;
+    import: string;
+    examples: Example[];
+    accessibility: string | null;
+    related: string[];
+    storybook: string | null;
+    parts: Part[];
+    cssVars: CssVar[];
+    sourceFile?: string;
+    rootClass?: string | null;
+    /** Helper pages ship as prose — they have no props interface. */
+    doc?: string;
+}
+export interface CatalogEntry {
+    name: string;
+    kind: 'component' | 'helper';
+    category: string;
+    purpose: string;
+    slug: string;
+    import: string;
+    compound: boolean;
+    propCount: number;
+    exampleCount: number;
+}
+export interface Catalog {
+    schemaVersion: number;
+    generatedFrom: {
+        package: string;
+        version: string;
+    };
+    docsBase: string;
+    categories: {
+        id: string;
+        label: string;
+        components: string[];
+    }[];
+    components: CatalogEntry[];
+    cssVarIndex: Record<string, string>;
+}
+export interface SkillFile {
+    id: string;
+    file: string;
+    bytes: number;
+}
+export interface Skill {
+    name: string;
+    description: string;
+    /** `bestax-theming` -> `theming`, the name an MCP client shows for the prompt. */
+    promptName: string;
+    dir: string;
+    references: SkillFile[];
+    examples: SkillFile[];
+}
+/** `dist/data.js` and `src/data.ts` are both one level under the package root. */
+export declare const DATA_DIR: string;
+/**
+ * The index and the server ship in the same tarball, so a mismatch here is a
+ * broken build rather than a user running something stale. Fail loudly instead
+ * of serving half of every field.
+ */
+export declare function assertSchema(catalog: Catalog): Catalog;
+export declare function loadCatalog(): Promise<Catalog>;
+/**
+ * Resolve a user-supplied name to a real component.
+ *
+ * Tolerant on purpose — a model asks for `navbar`, `<Button>` or
+ * `Navbar.Brand`, and refusing any of those wastes a round trip when the
+ * intent is unambiguous.
+ */
+export declare function resolveName(input: string): Promise<string | null>;
+export declare function loadComponent(name: string): Promise<ComponentRecord>;
+export declare function loadSkills(): Promise<Skill[]>;
+/**
+ * A skill's SKILL.md or one of its reference/example files.
+ *
+ * Bodies are copied into `data/skills/` at build time (see
+ * `scripts/sync-skills.mjs`) rather than committed, so a source checkout that
+ * has not been built has the manifest but no bodies. Say so rather than
+ * surfacing an ENOENT — the fix is `pnpm --filter bestax-mcp build`.
+ */
+export declare function loadSkillFile(dir: string, relative?: string): Promise<string>;
+/** Test seam — the loaders memoise for the life of a stdio session. */
+export declare function resetCaches(): void;
+//# sourceMappingURL=data.d.ts.map

package/dist/data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../src/data.ts"],"names":[],"mappings":"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"}

package/dist/data.js

@@ -0,0 +1,111 @@
+/**
+ * Loaders for the generated index in `data/`.
+ *
+ * Everything here is lazy and cached. A stdio server is spawned fresh by every
+ * client, so startup cost is paid on every session: the catalog (~76 KB) is the
+ * only file read eagerly, and a component's own file is pulled the first time a
+ * tool asks for it.
+ *
+ * Nothing in this module is written by hand — regenerate with `pnpm gen:mcp`.
+ */
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Bumped by the generator when the shape changes incompatibly. */
+export const SUPPORTED_SCHEMA_VERSION = 1;
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** `dist/data.js` and `src/data.ts` are both one level under the package root. */
+export const DATA_DIR = join(HERE, '..', 'data');
+const readJson = async (path) => JSON.parse(await readFile(path, 'utf8'));
+/**
+ * The index and the server ship in the same tarball, so a mismatch here is a
+ * broken build rather than a user running something stale. Fail loudly instead
+ * of serving half of every field.
+ */
+export function assertSchema(catalog) {
+    if (catalog.schemaVersion !== SUPPORTED_SCHEMA_VERSION) {
+        throw new Error(`bestax-mcp: data/catalog.json is schema version ${catalog.schemaVersion}, ` +
+            `but this server understands ${SUPPORTED_SCHEMA_VERSION}. Reinstall bestax-mcp.`);
+    }
+    return catalog;
+}
+let catalogPromise = null;
+export function loadCatalog() {
+    catalogPromise ??= readJson(join(DATA_DIR, 'catalog.json')).then(assertSchema);
+    return catalogPromise;
+}
+const componentCache = new Map();
+/**
+ * Resolve a user-supplied name to a real component.
+ *
+ * Tolerant on purpose — a model asks for `navbar`, `<Button>` or
+ * `Navbar.Brand`, and refusing any of those wastes a round trip when the
+ * intent is unambiguous.
+ */
+export async function resolveName(input) {
+    const catalog = await loadCatalog();
+    const cleaned = input.trim().replace(/^<|\/?>$/g, '');
+    const root = cleaned.split('.')[0];
+    const exact = catalog.components.find(c => c.name === root);
+    if (exact)
+        return exact.name;
+    const lower = root.toLowerCase();
+    const ci = catalog.components.find(c => c.name.toLowerCase() === lower);
+    return ci ? ci.name : null;
+}
+export function loadComponent(name) {
+    let cached = componentCache.get(name);
+    if (!cached) {
+        cached = readJson(join(DATA_DIR, 'components', `${name}.json`));
+        componentCache.set(name, cached);
+    }
+    return cached;
+}
+let skillsPromise = null;
+/**
+ * Skill bodies, memoised like every other loader in this file. `inlineStyleRule()` slices a
+ * section out of bestax-layout-scaffold on every `get_helper_props` call and `nearMissRule()`
+ * does the same on every unfiltered `list_components`; without this each of those re-read a
+ * 15 KB file from disk. The bodies are immutable for the life of a stdio session.
+ */
+const skillFileCache = new Map();
+export function loadSkills() {
+    skillsPromise ??= readJson(join(DATA_DIR, 'skills.json')).then(d => d.skills);
+    return skillsPromise;
+}
+/**
+ * A skill's SKILL.md or one of its reference/example files.
+ *
+ * Bodies are copied into `data/skills/` at build time (see
+ * `scripts/sync-skills.mjs`) rather than committed, so a source checkout that
+ * has not been built has the manifest but no bodies. Say so rather than
+ * surfacing an ENOENT — the fix is `pnpm --filter bestax-mcp build`.
+ */
+export async function loadSkillFile(dir, relative = 'SKILL.md') {
+    // Defence in depth: `relative` reaches these loaders from tool arguments, and
+    // the manifest is the only thing allowed to name a file.
+    if (relative.includes('..') || relative.startsWith('/')) {
+        throw new Error(`bestax-mcp: refusing to read "${relative}"`);
+    }
+    const cacheKey = `${dir}/${relative}`;
+    const hit = skillFileCache.get(cacheKey);
+    if (hit)
+        return hit;
+    const path = join(DATA_DIR, 'skills', dir, relative);
+    if (!existsSync(path)) {
+        throw new Error(`bestax-mcp: ${dir}/${relative} is not in this build. Skill bodies are ` +
+            `synced by \`pnpm --filter bestax-mcp build\`; a published tarball ` +
+            `always carries them.`);
+    }
+    const read = readFile(path, 'utf8');
+    skillFileCache.set(cacheKey, read);
+    return read;
+}
+/** Test seam — the loaders memoise for the life of a stdio session. */
+export function resetCaches() {
+    catalogPromise = null;
+    skillsPromise = null;
+    componentCache.clear();
+    skillFileCache.clear();
+}

package/dist/format.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Rendering for tool responses.
+ *
+ * Responses are markdown, not JSON. The consumer is a language model, and a
+ * prop table it can read costs fewer tokens than the same data as nested
+ * objects with repeated keys — and it does not tempt the model into echoing
+ * JSON structure back into the code it writes.
+ *
+ * The other rule here is that nothing is dumped in full when a summary will do.
+ * `get_component` returns a component's props; the 24 usage examples are a
+ * separate call, because most questions do not need them.
+ */
+import type { CatalogEntry, ComponentRecord, CssVar, Example, Part, Skill } from './data.js';
+export declare function table(headers: string[], rows: string[][]): string;
+export declare function renderPart(part: Part, { heading }?: {
+    heading?: boolean | undefined;
+}): string;
+export declare function renderComponent(record: ComponentRecord, include: string[]): string;
+export declare function renderExamples(examples: Example[]): string;
+export declare function renderCssVars(vars: CssVar[]): string;
+export declare function renderCatalog(entries: CatalogEntry[]): string;
+export declare function renderSkills(skills: Skill[]): string;
+/** Wrap a body as an MCP text result, appending the version note when there is one. */
+export declare function textResult(body: string, note: string | null): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function errorResult(message: string): {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EACf,MAAM,EACN,OAAO,EACP,IAAI,EAEJ,KAAK,EACN,MAAM,WAAW,CAAC;AAUnB,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,CAOjE;AAsBD,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,OAAc,EAAE;;CAAK,GAAG,MAAM,CAiCtE;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,MAAM,EAAE,GAChB,MAAM,CAsDR;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAI1D;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAmBpD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAkB7D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAgBpD;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;;;;;EAM3D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM;;;;;;EAK1C"}

package/dist/format.js

@@ -0,0 +1,178 @@
+/** Escape a cell for a markdown table — the parser splits on pipes first. */
+const cell = (text) => String(text ?? '')
+    .replace(/\\/g, '\\\\')
+    .replace(/\|/g, '\\|')
+    .replace(/\r?\n/g, ' ')
+    .trim();
+export function table(headers, rows) {
+    if (!rows.length)
+        return '';
+    return [
+        `| ${headers.join(' | ')} |`,
+        `| ${headers.map(() => '---').join(' | ')} |`,
+        ...rows.map(r => `| ${r.map(cell).join(' | ')} |`),
+    ].join('\n');
+}
+function propRows(props) {
+    return props.map(p => {
+        const notes = [
+            p.deprecated
+                ? `**Deprecated.**${p.deprecationNote ? ` ${p.deprecationNote}` : ''}`
+                : '',
+            p.description,
+            // The valid-value unions are too large to inline in a cell; name the page
+            // that lists them so the model can ask for it rather than guess.
+            p.valuesRef ? `(values: ${p.valuesRef})` : '',
+        ].filter(Boolean);
+        return [
+            `\`${p.name}\``,
+            `\`${p.type}\``,
+            p.default ? `\`${p.default}\`` : '—',
+            notes.join(' '),
+        ];
+    });
+}
+export function renderPart(part, { heading = true } = {}) {
+    const out = [];
+    if (heading)
+        out.push(`### ${part.path}`);
+    if (part.summary)
+        out.push(part.summary);
+    if (part.component) {
+        out.push(`Also exported standalone as \`${part.component}\` — call \`get_props\` with that name for its full table.`);
+    }
+    const rows = [...propRows(part.props), ...propRows(part.extraProps)];
+    if (part.catchAll) {
+        rows.push(['`...`', part.catchAll, '—', 'See `get_helper_props`.']);
+    }
+    if (rows.length) {
+        out.push(table(['Prop', 'Type', 'Default', 'Notes'], rows));
+    }
+    else if (!part.component) {
+        out.push('No props of its own beyond the standard HTML attributes.');
+    }
+    if (part.types.length) {
+        out.push([
+            '**Types:**',
+            '',
+            ...part.types.map(t => `- \`${t.name}\`: \`${t.expansion}\`${t.summary ? ` — ${t.summary}` : ''}`),
+        ].join('\n'));
+    }
+    return out.join('\n\n');
+}
+export function renderComponent(record, include) {
+    const out = [`# ${record.name}`];
+    if (record.summary)
+        out.push(record.summary);
+    out.push(`\`\`\`tsx\n${record.import}\n\`\`\``);
+    if (record.kind === 'helper') {
+        // Helper pages are reference prose with signature blocks, not tables — and for
+        // useBulmaClasses that prose is 51,054 characters. It used to be pushed unconditionally,
+        // outside any `include` check, so the DEFAULT call returned all of it and no argument
+        // could ask for less. Now it is opt-in, and the default is a pointer at the tool that
+        // exists to serve exactly this and can narrow it by group.
+        if (include.includes('reference') && record.doc) {
+            out.push(record.doc);
+        }
+        else {
+            out.push(`This is a helper, not a component — its reference is large and grouped. ` +
+                `Call \`get_helper_props()\` for every prop with its accepted values, or ` +
+                `\`get_helper_props({ group })\` for one area with examples. ` +
+                `Pass \`include: ["reference"]\` here for the full prose.`);
+        }
+    }
+    else if (include.includes('props')) {
+        const [root, ...subs] = record.parts;
+        if (root)
+            out.push(renderPart(root, { heading: false }));
+        if (subs.length) {
+            out.push(`**Subcomponents:** ${subs.map(s => `\`${s.path}\``).join(', ')}. ` +
+                `Call \`get_props\` with a dot-path for any of them.`);
+        }
+    }
+    if (include.includes('examples') && record.examples.length) {
+        out.push('## Examples', renderExamples(record.examples.slice(0, 5)));
+        if (record.examples.length > 5) {
+            out.push(`_${record.examples.length - 5} more — call \`get_examples\` for the rest._`);
+        }
+    }
+    if (include.includes('cssVars') && record.cssVars.length) {
+        out.push('## CSS Variables', renderCssVars(record.cssVars));
+    }
+    if (include.includes('accessibility') && record.accessibility) {
+        out.push('## Accessibility', record.accessibility);
+    }
+    if (include.includes('related') && record.related.length) {
+        out.push(`**Related:** ${record.related.map(r => `\`${r}\``).join(', ')}.`);
+    }
+    const links = [`Docs: ${record.docsUrl}`];
+    if (record.storybook)
+        links.push(`Storybook: ${record.storybook}`);
+    out.push(links.join(' · '));
+    return out.join('\n\n');
+}
+export function renderExamples(examples) {
+    return examples
+        .map(e => `### ${e.title}\n\n\`\`\`tsx\n${e.code}\n\`\`\``)
+        .join('\n\n');
+}
+export function renderCssVars(vars) {
+    const body = table(['CSS Variable', 'Sass Variable', 'Default'], vars.map(v => [
+        `\`${v.css}\``,
+        v.sass ? `\`${v.sass}\`` : '—',
+        `\`${v.default}\``,
+    ]));
+    // Where Bulma declares the default decides where an override has to go, and
+    // getting that wrong is the single most common theming failure.
+    const scopes = new Set(vars.map(v => v.scope));
+    const note = scopes.has('component')
+        ? "Variables scoped `component` are declared on the component's own element — " +
+            'override them there or via `className`; a value set on an ancestor is only ' +
+            'inherited and loses to the component-level declaration.'
+        : 'These are declared globally, so overriding them on `:root` (or with the ' +
+            '`Theme` component) retheme every instance.';
+    return `${body}\n\n${note}`;
+}
+export function renderCatalog(entries) {
+    const byCategory = new Map();
+    for (const e of entries) {
+        const list = byCategory.get(e.category) ?? [];
+        list.push(e);
+        byCategory.set(e.category, list);
+    }
+    return [...byCategory]
+        .map(([category, list]) => [
+        `## ${category}`,
+        ...list.map(e => `- **${e.name}**${e.compound ? ' (compound)' : ''} — ${e.purpose}`),
+    ].join('\n'))
+        .join('\n\n');
+}
+export function renderSkills(skills) {
+    return skills
+        .map(s => [
+        `## ${s.name}`,
+        s.description,
+        s.references.length
+            ? `References: ${s.references.map(r => `\`${r.id}\``).join(', ')} — ` +
+                `call \`get_skill\` with \`reference\` to read one.`
+            : null,
+        `MCP prompt: \`${s.promptName}\`.`,
+    ]
+        .filter(Boolean)
+        .join('\n\n'))
+        .join('\n\n');
+}
+/** Wrap a body as an MCP text result, appending the version note when there is one. */
+export function textResult(body, note) {
+    return {
+        content: [
+            { type: 'text', text: note ? `${body}\n\n${note}` : body },
+        ],
+    };
+}
+export function errorResult(message) {
+    return {
+        isError: true,
+        content: [{ type: 'text', text: message }],
+    };
+}

package/dist/helper-props.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Shaping the helper-prop reference so asking one question does not cost the whole page.
+ *
+ * `get_helper_props` was 54,886 characters — 49% of everything a cold-start builder read in
+ * a measured session, on the tool this server's own `instructions` tell every client to call
+ * before writing styling. Its `group` argument was supposed to prevent that and did not: the
+ * filter substring-matched whole section BODIES, and three sections (`Supported Props`,
+ * `Viewport-Specific Properties`, `Full TypeScript Definition`) name every helper keyword, so
+ * `group: "text"` matched 21 of 41 sections — 87% of the page.
+ *
+ * Matching headings instead is not the fix either; it is a regression. `spacing` and
+ * `typography` — two of the three groups the tool's own description advertises — match no
+ * heading at all and would answer nothing.
+ *
+ * So the groups are curated, and each one carries its own slice of the prop table. The
+ * governing rule is that **no call ever loses a prop name**: the default lists all 46 with
+ * their accepted values, because a builder has to be able to look up a valid value in one
+ * call. What moves behind `group` is the prose and the live examples, which are re-fetchable
+ * and which nothing breaks without.
+ */
+/**
+ * Markdown tables in the generated index are column-padded for human reading. That padding
+ * is 32% of this document — 16,352 characters, of which `Supported Props` alone contributes
+ * 12,455. Stripping it is free: no model reads alignment, and the cell contents are
+ * untouched.
+ */
+export declare function reflowTables(md: string): string;
+export interface HelperGroup {
+    /** Section headings, matched exactly against the `##`/`###` line. */
+    headings: string[];
+    /** Prop names whose rows are sliced out of the Supported Props table. */
+    props: string[];
+    /** Words a builder is likely to use for this group instead of its name. */
+    aliases: string[];
+}
+/**
+ * Every prop in the table belongs to exactly one group — checked by a test, because a prop
+ * that falls through the map is a prop a `group` call can never surface.
+ */
+export declare const HELPER_GROUPS: Record<string, HelperGroup>;
+export declare const GROUP_NAMES: string[];
+/** A builder's word → a group name, or null when nothing sensible matches. */
+export declare function resolveGroup(input: string): string | null;
+/** The `## Supported Props` table, reflowed, header rows plus the rows for `props`. */
+export declare function propTable(doc: string, props?: string[]): string;
+/**
+ * The no-argument answer: every prop and every accepted value, and nothing else.
+ *
+ * Deliberately excluded, and why each is safe to drop: `Full TypeScript Definition` (5,143)
+ * is a lossless restatement of the table above it; `Composable Mini-Hooks` (4,792) is
+ * material for writing a component, which is `bestax-custom-component`'s job; the twenty-odd
+ * live example blocks are reachable through `group`.
+ */
+export declare function renderHelperDefault(doc: string): string;
+/** One group: its example sections, then just its rows of the prop table. */
+export declare function renderHelperGroup(doc: string, name: string): string;
+//# sourceMappingURL=helper-props.d.ts.map