@svgrid/mcp 2.6.8 → 3.0.0

package/dist/installed.d.ts

@@ -0,0 +1,33 @@
+export type InstalledGrid = {
+    version: string;
+    /** Where it was found, so a surprising answer can be traced. */
+    path: string;
+};
+/**
+ * Walk up from `from` looking for `node_modules/@svgrid/grid/package.json`.
+ *
+ * Nearest-first, and it stops at the first hit: a monorepo can legitimately
+ * hold several copies, and guessing which one the user means would produce
+ * confident nonsense. The nearest one to the working directory is the one a
+ * build would resolve.
+ */
+export declare function findInstalledGrid(from?: string): InstalledGrid | null;
+/** Cached lookup. The filesystem does not change under a running server. */
+export declare function installedGrid(): InstalledGrid | null;
+/** Test seam: forget what was found, so a test can point at another tree. */
+export declare function resetInstalledGrid(next?: InstalledGrid | null): void;
+export type VersionNote = {
+    /** The version this server's corpus and API surface describe. */
+    corpus: string;
+    /** What is actually installed where the server is running, if anything. */
+    installed?: string;
+    /** Present only when they disagree - the part a model must not ignore. */
+    warning?: string;
+};
+/**
+ * How to describe the corpus/installed pairing in a tool result.
+ *
+ * Silent when they match or when nothing is installed. A note that fires
+ * constantly is a note that gets skipped.
+ */
+export declare function versionNote(corpusVersion: string): VersionNote | undefined;

package/dist/installed.js

@@ -0,0 +1,87 @@
+/**
+ * Which version of SvGrid the person asking actually has installed.
+ *
+ * This is the thing a proxy-shaped MCP server cannot do. Telerik and Syncfusion
+ * answer every question from a backend that serves one global "latest" - their
+ * server has no idea what is in your `node_modules`, so a model can be told
+ * about an API you do not have, confidently and with a citation.
+ *
+ * We ship the corpus, so we can do better: read the consumer's installed grid
+ * and say plainly when it disagrees with what this corpus describes. A warning
+ * that the answer may not apply is worth far more than a confident wrong one.
+ *
+ * Absent is the normal case, not an error - the server is often run from a
+ * directory that has no SvGrid in it at all (a fresh project, a chat with no
+ * workspace). Say nothing then rather than inventing a mismatch.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, parse } from 'node:path';
+let cached;
+/**
+ * Walk up from `from` looking for `node_modules/@svgrid/grid/package.json`.
+ *
+ * Nearest-first, and it stops at the first hit: a monorepo can legitimately
+ * hold several copies, and guessing which one the user means would produce
+ * confident nonsense. The nearest one to the working directory is the one a
+ * build would resolve.
+ */
+export function findInstalledGrid(from = process.cwd()) {
+    let dir = from;
+    const { root } = parse(dir);
+    for (;;) {
+        const manifest = join(dir, 'node_modules', '@svgrid', 'grid', 'package.json');
+        if (existsSync(manifest)) {
+            try {
+                const version = JSON.parse(readFileSync(manifest, 'utf8')).version;
+                if (typeof version === 'string' && version)
+                    return { version, path: manifest };
+            }
+            catch {
+                // An unreadable manifest is the same as not finding one: this is a
+                // courtesy check, and it must never be the reason a tool call fails.
+            }
+            return null;
+        }
+        if (dir === root)
+            return null;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Cached lookup. The filesystem does not change under a running server. */
+export function installedGrid() {
+    if (cached === undefined)
+        cached = findInstalledGrid();
+    return cached;
+}
+/** Test seam: forget what was found, so a test can point at another tree. */
+export function resetInstalledGrid(next) {
+    cached = next;
+}
+/**
+ * How to describe the corpus/installed pairing in a tool result.
+ *
+ * Silent when they match or when nothing is installed. A note that fires
+ * constantly is a note that gets skipped.
+ */
+export function versionNote(corpusVersion) {
+    const found = installedGrid();
+    // Nothing installed means nothing to add: the check result already carries
+    // `checkedAgainst` and says the version in its summary, so a bare
+    // `{ corpus }` would be the same fact a third time. A field that is usually
+    // redundant is a field that gets skipped when it finally matters.
+    if (!found)
+        return undefined;
+    if (found.version === corpusVersion) {
+        return { corpus: corpusVersion, installed: found.version };
+    }
+    return {
+        corpus: corpusVersion,
+        installed: found.version,
+        warning: `This server describes @svgrid/grid@${corpusVersion}, but ${found.version} is installed ` +
+            `here. Treat anything version-specific as unverified for your version, and say so rather ` +
+            `than asserting it.`,
+    };
+}

package/dist/preview.d.ts

@@ -0,0 +1,88 @@
+/** MCP Apps constants, inlined rather than depending on the extension SDK server-side. */
+export declare const UI_MIME_TYPE = "text/html;profile=mcp-app";
+export declare const UI_RESOURCE_URI = "ui://svgrid/preview.html";
+/**
+ * The published versions the preview loads from the CDN.
+ *
+ * Pinned, not `@latest`: a preview that silently follows a future major would
+ * start failing in a way nobody is watching for. `tools/mcp-tools.test.ts` checks these
+ * against the workspace so they cannot quietly rot either.
+ */
+export declare const PREVIEW_GRID_WC_VERSION = "2.7.0";
+export declare function previewResource(): {
+    uri: string;
+    name: string;
+    title: string;
+    description: string;
+    mimeType: string;
+    _meta: {
+        'ui/csp': {
+            resourceDomains: string[];
+        };
+        'ui/prefersBorder': boolean;
+    };
+};
+export declare function readPreviewResource(uri: string): {
+    contents: {
+        uri: string;
+        mimeType: string;
+        text: string;
+    }[];
+} | undefined;
+export declare const PREVIEW_TOOL: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            columns: {
+                type: string;
+                description: string;
+            };
+            data: {
+                type: string;
+                description: string;
+            };
+            demo: {
+                type: string;
+                description: string;
+            };
+            title: {
+                type: string;
+                description: string;
+            };
+            sortable: {
+                type: string;
+                description: string;
+            };
+            filterable: {
+                type: string;
+                description: string;
+            };
+            pageable: {
+                type: string;
+                description: string;
+            };
+            groupBy: {
+                type: string;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    _meta: {
+        "ui/resourceUri": string;
+    };
+};
+type ToolResult = {
+    isError?: boolean;
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    structuredContent?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+};
+export declare function handlePreview(args: Record<string, unknown>): ToolResult;
+export {};

package/dist/preview.js

@@ -0,0 +1,211 @@
+/**
+ * A live, interactive grid rendered inside the conversation.
+ *
+ * Every other tool here hands the model TEXT and asks a person to imagine the
+ * result. This renders the real grid - sortable, filterable, scrollable - in
+ * the client, using MCP Apps, the official UI extension: a tool points at a
+ * `ui://` resource through `_meta`, the client loads that HTML in a sandboxed
+ * iframe, and the tool's `structuredContent` arrives over a postMessage bridge.
+ *
+ * It is the same custom element a real page would use, from the published
+ * package on a CDN - not a screenshot, not a mock table. What you see is what
+ * `<sv-grid>` does with those columns.
+ *
+ * Progressive enhancement is the rule the extension is built around: clients
+ * without MCP Apps ignore the `_meta` and still get the text summary, which is
+ * why the text half has to stand on its own rather than say "see the preview".
+ */
+import { examples } from './data.js';
+/** MCP Apps constants, inlined rather than depending on the extension SDK server-side. */
+export const UI_MIME_TYPE = 'text/html;profile=mcp-app';
+export const UI_RESOURCE_URI = 'ui://svgrid/preview.html';
+const UI_RESOURCE_META_KEY = 'ui/resourceUri';
+/**
+ * The published versions the preview loads from the CDN.
+ *
+ * Pinned, not `@latest`: a preview that silently follows a future major would
+ * start failing in a way nobody is watching for. `tools/mcp-tools.test.ts` checks these
+ * against the workspace so they cannot quietly rot either.
+ */
+export const PREVIEW_GRID_WC_VERSION = '2.7.0';
+const EXT_APPS_VERSION = '1.7.5';
+const CDN = 'https://cdn.jsdelivr.net/npm';
+/**
+ * The UI itself.
+ *
+ * Deliberately small and dependency-light: two module imports, one element, no
+ * framework. The iframe is sandboxed and the client enforces the CSP declared
+ * beside this resource, so anything else would just be blocked.
+ */
+const PREVIEW_HTML = `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>SvGrid preview</title>
+    <style>
+      html, body { margin: 0; height: 100%; font: 13px system-ui, sans-serif; }
+      #root { display: flex; flex-direction: column; height: 100%; min-height: 0; }
+      #note { padding: 8px 12px; color: #64748b; }
+      #host { flex: 1; min-width: 0; min-height: 0; }
+      sv-grid { display: block; height: 100%; }
+    </style>
+  </head>
+  <body>
+    <div id="root">
+      <div id="note">Loading the grid…</div>
+      <div id="host"></div>
+    </div>
+    <script type="module">
+      import { App } from '${CDN}/@modelcontextprotocol/ext-apps@${EXT_APPS_VERSION}/dist/src/app-with-deps.js'
+      import '${CDN}/@svgrid/grid-wc@${PREVIEW_GRID_WC_VERSION}/dist/sv-grid-element.js'
+
+      const note = document.getElementById('note')
+      const host = document.getElementById('host')
+
+      function render(payload) {
+        const { columns, data, title, ...rest } = payload ?? {}
+        if (!Array.isArray(columns) || !Array.isArray(data)) {
+          note.textContent = 'No grid data arrived from the tool.'
+          return
+        }
+        host.replaceChildren()
+        const el = document.createElement('sv-grid')
+        el.data = data
+        el.columns = columns
+        // Whatever else the tool passed - sortable, filterable, pageable,
+        // groupBy - goes straight through as a property, exactly as a host page
+        // would set it. Arrays and objects cannot cross as attributes, which is
+        // the whole reason the element takes properties.
+        for (const [key, value] of Object.entries(rest)) {
+          if (value !== undefined) el[key] = value
+        }
+        host.appendChild(el)
+        note.textContent = title
+          ? title + ' - ' + data.length + ' rows'
+          : data.length + ' rows, ' + columns.length + ' columns'
+      }
+
+      try {
+        const app = new App()
+        app.ontoolresult = (params) => render(params?.structuredContent)
+        await app.connect()
+      } catch (err) {
+        note.textContent = 'Preview bridge unavailable: ' + (err && err.message ? err.message : err)
+      }
+    </script>
+  </body>
+</html>
+`;
+export function previewResource() {
+    return {
+        uri: UI_RESOURCE_URI,
+        name: 'SvGrid preview',
+        title: 'SvGrid preview',
+        description: 'A live, interactive SvGrid rendered from the data a tool returns.',
+        mimeType: UI_MIME_TYPE,
+        _meta: {
+            // The iframe is offline-hostile by default; these are the only two
+            // origins it needs, and they are the ones the HTML imports from.
+            'ui/csp': { resourceDomains: [CDN.replace('https://', '').split('/')[0]] },
+            'ui/prefersBorder': true,
+        },
+    };
+}
+export function readPreviewResource(uri) {
+    if (uri !== UI_RESOURCE_URI)
+        return undefined;
+    return { contents: [{ uri, mimeType: UI_MIME_TYPE, text: PREVIEW_HTML }] };
+}
+export const PREVIEW_TOOL = {
+    name: 'svgrid_preview',
+    title: 'Preview a grid',
+    description: 'Render a REAL, interactive SvGrid in the conversation - sortable, filterable, scrollable - from columns and rows you pass, or from a demo id. Use it to show the user what a grid will look like before they build it, and after svgrid_check_code to demonstrate the result. In clients without UI support it returns a text summary instead, so it is always safe to call.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            columns: {
+                type: 'array',
+                description: 'Column definitions, e.g. [{ "field": "name", "header": "Name", "width": 160 }]. Required unless `demo` is set.',
+            },
+            data: {
+                type: 'array',
+                description: 'Rows to display. Required unless `demo` is set. Keep it under a few hundred for a preview.',
+            },
+            demo: {
+                type: 'string',
+                description: 'Preview a shipped demo instead, by id (e.g. "11-stock-market"). Its source is returned as text; find ids with svgrid_search.',
+            },
+            title: { type: 'string', description: 'Caption shown above the grid.' },
+            sortable: { type: 'boolean', description: 'Sortable headers. Default true.' },
+            filterable: { type: 'boolean', description: 'Filtering. Default true.' },
+            pageable: { type: 'boolean', description: 'Pagination footer.' },
+            groupBy: { type: 'array', description: 'Group by these column ids.' },
+        },
+        required: [],
+    },
+    _meta: { [UI_RESOURCE_META_KEY]: UI_RESOURCE_URI },
+};
+const fail = (message) => ({
+    isError: true,
+    content: [{ type: 'text', text: message }],
+});
+export function handlePreview(args) {
+    const demoId = typeof args.demo === 'string' ? args.demo.trim() : '';
+    if (demoId) {
+        const demo = examples.find((e) => e.id === demoId);
+        if (!demo) {
+            return fail(`No demo with id "${demoId}". Use svgrid_search to find one.`);
+        }
+        // A demo is a Svelte component, not data: there is nothing to hand the
+        // element. Return the source and say so, rather than rendering an empty
+        // grid and letting it look like the demo is broken.
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `// ${demo.path}\n// ${demo.title} - ${demo.blurb}\n` +
+                        `//\n// Demos are Svelte components, so this is the source rather than a live\n` +
+                        `// render. To preview a grid interactively, pass \`columns\` and \`data\`.\n\n` +
+                        demo.source,
+                },
+            ],
+        };
+    }
+    const columns = args.columns;
+    const data = args.data;
+    if (!Array.isArray(columns) || !columns.length) {
+        return fail('columns is required: an array of column definitions, or pass `demo` for a shipped example.');
+    }
+    if (!Array.isArray(data)) {
+        return fail('data is required: an array of rows.');
+    }
+    // A preview is a picture, not a dataset. `structuredContent` crosses into the
+    // conversation, so an unbounded `data` would put the caller's whole table in
+    // the context window - 200 rows is already ~2,900 tokens. Cap it and say so,
+    // rather than quietly rendering a truncated grid that looks complete.
+    const MAX_ROWS = 100;
+    const shown = data.slice(0, MAX_ROWS);
+    const truncated = data.length > shown.length;
+    const payload = { columns, data: shown };
+    for (const key of ['title', 'sortable', 'filterable', 'pageable', 'groupBy']) {
+        if (args[key] !== undefined)
+            payload[key] = args[key];
+    }
+    // The text half has to stand alone: a client without UI support shows only
+    // this, and "see the preview above" would be nonsense there.
+    const headers = columns
+        .map((c) => c.header ?? c.field ?? '?')
+        .join(', ');
+    const summary = `SvGrid preview: ${shown.length} row${shown.length === 1 ? '' : 's'} x ${columns.length} column${columns.length === 1 ? '' : 's'}` +
+        (typeof args.title === 'string' && args.title ? ` - ${args.title}` : '') +
+        `\nColumns: ${headers}` +
+        (truncated ? `\nShowing the first ${MAX_ROWS} of ${data.length} rows - a preview is a picture, not the dataset.` : '') +
+        `\n\nIn a client with MCP Apps support this renders as a live, interactive grid.`;
+    return {
+        content: [{ type: 'text', text: summary }],
+        // What the UI reads. Kept separate from the text so the model is not made
+        // to re-read the whole dataset it just sent.
+        structuredContent: payload,
+        _meta: { [UI_RESOURCE_META_KEY]: UI_RESOURCE_URI },
+    };
+}

package/dist/prompts.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Slash-command style starters, exposed as MCP prompts.
+ *
+ * These are the tasks people actually arrive with, and a prompt is how a client
+ * surfaces one before the user has thought of a tool call. Each is written to
+ * make the model USE this server rather than recall SvGrid from training data,
+ * which is where the wrong-API answers come from - and every one of them ends
+ * at `svgrid_check_code`, because a grid that does not compile is the failure
+ * mode this whole server exists to prevent.
+ */
+export type Prompt = {
+    name: string;
+    title: string;
+    description: string;
+    arguments: {
+        name: string;
+        description: string;
+        required: boolean;
+    }[];
+};
+export declare const PROMPTS: Prompt[];
+export declare function getPrompt(name: string, args: Record<string, unknown>): {
+    messages: {
+        role: "user";
+        content: {
+            type: "text";
+            text: string;
+        };
+    }[];
+    description: string;
+} | undefined;

package/dist/prompts.js

@@ -0,0 +1,65 @@
+export const PROMPTS = [
+    {
+        name: 'build_grid',
+        title: 'Build a SvGrid',
+        description: 'Scaffold a SvGrid for a described dataset, grounded in the real API and verified before you see it.',
+        arguments: [
+            { name: 'description', description: 'The data and behaviour you want, in plain language.', required: true },
+        ],
+    },
+    {
+        name: 'explain_api',
+        title: 'Explain a SvGrid API',
+        description: 'Explain a prop, column option or method using the shipped docs rather than recall.',
+        arguments: [{ name: 'symbol', description: 'A prop, column option or method name.', required: true }],
+    },
+    {
+        name: 'review_grid_code',
+        title: 'Review SvGrid code',
+        description: 'Check existing SvGrid code against the real API surface and report what is wrong.',
+        arguments: [{ name: 'source', description: 'The component source to review.', required: true }],
+    },
+];
+const messages = (body) => ({
+    messages: [{ role: 'user', content: { type: 'text', text: body } }],
+});
+export function getPrompt(name, args) {
+    const arg = (key) => String(args[key] ?? '').trim();
+    if (name === 'build_grid') {
+        return {
+            description: 'Build a verified SvGrid',
+            ...messages(`Build a SvGrid for: ${arg('description')}\n\n` +
+                'Work in this order, and do not skip a step:\n' +
+                '1. Call `svgrid_search` for the features this needs. Do not rely on memory of ' +
+                'SvGrid\'s API - it changes, and a wrong prop name fails silently.\n' +
+                '2. Call `svgrid_get` on the closest demo id and follow its structure.\n' +
+                '3. Write the component.\n' +
+                '4. Call `svgrid_check_code` on what you wrote. Use the `fixed` source it ' +
+                'returns rather than re-deriving the edits, and repeat until it is clean - ' +
+                'BEFORE showing me the code.\n' +
+                '5. Call `svgrid_preview` with the same columns and a few rows, so I can see ' +
+                'and touch the grid rather than just read it.'),
+        };
+    }
+    if (name === 'explain_api') {
+        return {
+            description: 'Explain a SvGrid API from the shipped docs',
+            ...messages(`Explain the SvGrid API \`${arg('symbol')}\`.\n\n` +
+                'Call `svgrid_search` with it first and answer only from what comes back. If it ' +
+                'is not in the results, say so plainly rather than guessing - a plausible ' +
+                'invented prop is worse than "not found".'),
+        };
+    }
+    if (name === 'review_grid_code') {
+        return {
+            description: 'Review SvGrid code against the real API',
+            ...messages('Review this SvGrid code:\n\n```svelte\n' +
+                arg('source') +
+                '\n```\n\n' +
+                'Call `svgrid_check_code` on it first. Explain each finding and how to fix it, ' +
+                'and if it returned a `fixed` source, show me that rather than describing the ' +
+                'edits. Use `svgrid_search` to back up any claim about what an API does.'),
+        };
+    }
+    return undefined;
+}

package/dist/resources.d.ts

@@ -0,0 +1,19 @@
+export type Resource = {
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType: string;
+};
+export declare function listResources(cursor?: string): {
+    resources: Resource[];
+    nextCursor?: string;
+};
+export type ResourceContents = {
+    contents: {
+        uri: string;
+        mimeType: string;
+        text: string;
+    }[];
+};
+export declare function readResource(uri: string): ResourceContents | undefined;

package/dist/resources.js

@@ -0,0 +1,84 @@
+/**
+ * The docs and demo corpus as MCP resources.
+ *
+ * A resource is content the CLIENT can pull in and attach - the user picks it,
+ * rather than the model having to think of a tool call. That is the right shape
+ * for a fixed corpus of 408 pages and 375 demos, and it is the half of MCP this
+ * server never implemented: it advertised `{"tools":{}}` and answered
+ * `resources/list` with "Method not found".
+ *
+ * Listed lazily and by reference. `resources/list` returns names and URIs only,
+ * never content, so the listing stays cheap however large the corpus grows -
+ * the same reason the tools cap their listings.
+ */
+import { docs, examples } from './data.js';
+import { previewResource } from './preview.js';
+/** `svgrid://doc/help/columns/x` and `svgrid://example/11-stock-market`. */
+function allResources() {
+    return [
+        // The preview UI belongs in the list, not bolted on beside it: prepending
+        // it to page one made that page 101 items, one over the page size, which is
+        // exactly the kind of off-by-one a paginating client trips on.
+        previewResource(),
+        ...docs.map((d) => ({
+            uri: `svgrid://doc/${d.slug}`,
+            name: d.slug,
+            title: d.title,
+            description: `${d.section} - SvGrid documentation`,
+            mimeType: 'text/markdown',
+        })),
+        ...examples.map((e) => ({
+            uri: `svgrid://example/${e.id}`,
+            name: e.id,
+            title: e.title,
+            description: `${e.category} - runnable SvGrid demo`,
+            mimeType: 'text/x-svelte',
+        })),
+    ];
+}
+/**
+ * One page of resources.
+ *
+ * 783 resources in a single response is 147,604 chars - about 36,900 tokens,
+ * which is worse than the 36-tool listing this redesign set out to fix, and it
+ * lands in the client the moment anything enumerates resources. The protocol
+ * has cursor pagination for exactly this; the first version here did not use
+ * it, which is the sort of thing you only notice by measuring the payload.
+ *
+ * The cursor is just the offset. It is opaque to the client by contract, so
+ * there is no need for it to be anything cleverer, but it IS validated - a
+ * malformed cursor restarts from the beginning rather than throwing.
+ */
+const PAGE_SIZE = 100;
+export function listResources(cursor) {
+    const all = allResources();
+    const start = Number.isSafeInteger(Number(cursor)) && Number(cursor) > 0 ? Number(cursor) : 0;
+    const page = all.slice(start, start + PAGE_SIZE);
+    const next = start + PAGE_SIZE;
+    return next < all.length ? { resources: page, nextCursor: String(next) } : { resources: page };
+}
+export function readResource(uri) {
+    const doc = /^svgrid:\/\/doc\/(.+)$/.exec(uri);
+    if (doc) {
+        const match = docs.find((d) => d.slug === doc[1]);
+        if (!match)
+            return undefined;
+        return { contents: [{ uri, mimeType: 'text/markdown', text: match.markdown }] };
+    }
+    const example = /^svgrid:\/\/example\/(.+)$/.exec(uri);
+    if (example) {
+        const match = examples.find((e) => e.id === example[1]);
+        if (!match)
+            return undefined;
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: 'text/x-svelte',
+                    text: `// ${match.path}\n// ${match.title} - ${match.blurb}\n\n${match.source}`,
+                },
+            ],
+        };
+    }
+    return undefined;
+}

package/dist/search.d.ts

@@ -21,6 +21,17 @@ export type DocHit = {
 };
 export declare function occurrences(haystack: string, needle: string): number;
 /** Split a query into distinct lowercase terms, dropping one-character noise. */
+/**
+ * Words too common to identify anything, dropped before matching.
+ *
+ * People phrase queries as questions - "how do I sort a column" - and every
+ * one of those filler words matched something. In the API search it was worse
+ * than noise: a single `a` matched 210 of 240 names, so the results came back
+ * led by `SvGridBoard` and `createSvGrid` for a query about pinning.
+ */
+export declare const STOP_WORDS: Set<string>;
+/** Terms worth matching on: longer than one character, and not filler. */
+export declare function meaningfulTerms(query: string): string[];
 export declare function queryTokens(query: string): string[];
 /** A window of text around the first needle that appears, for search results. */
 export declare function excerptAround(markdown: string, needles: string[]): string;

package/dist/search.js

@@ -18,8 +18,36 @@ export function occurrences(haystack, needle) {
     return n;
 }
 /** Split a query into distinct lowercase terms, dropping one-character noise. */
+/**
+ * Words too common to identify anything, dropped before matching.
+ *
+ * People phrase queries as questions - "how do I sort a column" - and every
+ * one of those filler words matched something. In the API search it was worse
+ * than noise: a single `a` matched 210 of 240 names, so the results came back
+ * led by `SvGridBoard` and `createSvGrid` for a query about pinning.
+ */
+export const STOP_WORDS = new Set([
+    'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'can', 'do', 'does', 'for', 'from', 'how',
+    'i', 'in', 'is', 'it', 'my', 'of', 'on', 'or', 'the', 'to', 'use', 'want', 'what', 'when',
+    'where', 'which', 'with', 'you',
+]);
+/** Terms worth matching on: longer than one character, and not filler. */
+export function meaningfulTerms(query) {
+    return [
+        ...new Set(query
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter((t) => t.length > 2 && !STOP_WORDS.has(t))),
+    ];
+}
 export function queryTokens(query) {
     const tokens = [...new Set(query.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 1))];
+    // Drop filler only when something specific survives - "do" is filler in "how
+    // do I sort", but a query that is ALL filler still has to match on something
+    // rather than silently matching everything.
+    const specific = tokens.filter((t) => !STOP_WORDS.has(t));
+    if (specific.length)
+        return specific;
     return tokens.length ? tokens : [query.toLowerCase().trim()];
 }
 /** A window of text around the first needle that appears, for search results. */