@gakim-digital/dexter-bridge 0.11.17 → 0.11.20

package/src/framerAgentTools.js

@@ -4,6 +4,7 @@ import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import jsTokens from 'js-tokens';
+import { loadGoogleFontsCatalog, searchGoogleFonts } from './googleFontsFallback.js';
 import {
   canonicalIdMappings,
   evidenceNodeIds,
@@ -81,19 +82,6 @@ const EMPTY_SCHEMA = {
 };
 
 export const FRAMER_AGENT_TOOL_DEFINITIONS = [
-  {
-    name: 'progress_update',
-    description:
-      'Tell the user what you are about to do or are doing now in one or two natural first-person sentences. Name the specific page area, component, or behavior and the concrete change; optionally say what you will check next. Avoid generic updates such as "working on the next step", "thinking", "loading", or "making changes". Call this before the first Framer inspection or edit and at meaningful phase changes.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        message: { type: 'string', minLength: 1, maxLength: 500 },
-      },
-      required: ['message'],
-      additionalProperties: false,
-    },
-  },
   {
     name: 'framer_instructions',
     description:
@@ -124,7 +112,7 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     name: 'framer_read_project',
     description:
-      'Run Framer Agent readProject queries against the connected project. Use this for focused canvas inspection and screenshots.',
+      'Run Framer Agent readProject queries: "screenshot", "font-search", and "implementation-guide-from-index" are the only query types. Read nodes and layout with framer_read instead.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -228,7 +216,7 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     name: 'framer_verify_interactions',
     description:
-      'Confirm planned behaviors against the live project. For each target node, name the Framer property that carries the behavior (for example loopEffect, hoverEffect, appearEffect, link, or onTap) and optionally a literal the value must contain (such as a route or SHOW_OVERLAY). Results: verified (the property is set and matches), contradicted (the property holds a different value), or unknown (the property was not found on the node). Unknown never blocks your work; it is reported as unverified. Checks accumulate across calls, so you can verify targets on several pages.',
+      'Confirm planned behaviors against the live project. For each target node, name the Framer property that carries the behavior (for example loopEffect, hoverEffect, appearEffect, link, or onTap, or a field inside one such as link.href or hoverEffect.opacity) and optionally a literal the value must contain (such as a route or SHOW_OVERLAY). Results: verified (the property is set and matches), contradicted (the property holds a different value), or unknown (the property was not found on the node). Unknown never blocks your work; it is reported as unverified. Checks accumulate across calls, so you can verify targets on several pages.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -288,12 +276,20 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     name: 'framer_apply_changes',
     description:
-      'Apply Framer Agent DSL changes directly to the connected project. Prefer this for page, layout, style, design-token, component, and CMS-on-canvas work.',
+      'Apply Framer Agent DSL changes directly to the connected project. Prefer this for page, layout, style, design-token, component, and CMS-on-canvas work. Pass screenshotNodeIds to get screenshots of those nodes taken after the change in the same result, instead of a separate read.',
     inputSchema: {
       type: 'object',
       properties: {
         changes: { type: 'string', minLength: 1, maxLength: 250_000 },
         pagePath: { type: 'string', maxLength: 500, default: '/' },
+        screenshotNodeIds: {
+          type: 'array',
+          maxItems: MAX_SCREENSHOTS_PER_CALL,
+          uniqueItems: true,
+          items: { type: 'string', minLength: 1, maxLength: 200 },
+          description:
+            'Nodes (or component variants) to screenshot after the change is applied. The screenshots count as visual evidence after this mutation.',
+        },
       },
       required: ['changes'],
       additionalProperties: false,
@@ -360,7 +356,7 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     name: 'framer_read',
     description:
-      'Execute read-only JavaScript with the official Framer Agent connection for capabilities not covered by readProject.',
+      'Execute read-only JavaScript with the official Framer Agent connection. Use it to read nodes and layout, for example with framer.agent.getNode, serialize, or serializeNodes; combine several reads in one script.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -539,12 +535,21 @@ function onDemandGuideCatalog(projectRoot) {
   return catalog;
 }
 
+// Returns a "## " or "### " section up to the next heading of the same or a
+// higher level.
 function markdownSection(markdown, heading) {
   const lines = markdown.split('\n');
-  const start = lines.findIndex((line) => line.trim() === `## ${heading}`);
+  const headingLevel = (line) => /^(#{1,6}) /.exec(line)?.[1].length || 0;
+  const start = lines.findIndex(
+    (line) => headingLevel(line) >= 2
+      && line.trim().replace(/^#+ /, '') === heading,
+  );
   if (start < 0) return '';
+  const level = headingLevel(lines[start]);
   const end = lines.findIndex(
-    (line, index) => index > start && line.startsWith('## '),
+    (line, index) => index > start
+      && headingLevel(line) > 0
+      && headingLevel(line) <= level,
   );
   return lines.slice(start, end < 0 ? undefined : end).join('\n').trim();
 }
@@ -1196,7 +1201,6 @@ export function createFramerAgentToolRuntime({
   let lowLevelWriteCalls = 0;
   let imageSearchCalls = 0;
   let readCalls = 0;
-  let progressCalls = 0;
   let toolCallCount = 0;
   const toolCalls = [];
   let repeatedFailureFingerprint = null;
@@ -1207,6 +1211,7 @@ export function createFramerAgentToolRuntime({
   let lowLevelWriteDisabled = false;
   let lowLevelWriteBlockedCalls = 0;
   let instructionFallbacks = 0;
+  let fontSearchFallbacks = 0;
   let instructionLookupUnavailable = false;
   let branchChange = null;
   let lastInspectionAt = null;
@@ -1556,14 +1561,23 @@ export function createFramerAgentToolRuntime({
     // Every run gets the guidance an edit always needs: principles, command
     // syntax, tool APIs, scope and replica rules, and the edit loop. Topic
     // guides (CMS, components, creation strategy, examples, ...) are listed
-    // in a catalog and read on demand through framer_instructions.
+    // in a catalog and read on demand through framer_instructions. The CLI,
+    // session, and file-map parts of SKILL.md and index.md do not apply to
+    // Dexter's tools, and index.md changes every session, so both are left
+    // out; the guidance stays byte-identical across runs and can be cached.
+    // The project inventory changes with the project and is returned apart.
     const requestedFiles = [
-      { root: skillRoot, path: 'SKILL.md', label: 'SKILL.md' },
-      { root: projectRoot, path: 'index.md', label: 'project/index.md' },
       {
-        root: projectRoot,
-        path: 'project-inventory.md',
-        label: 'project/project-inventory.md',
+        root: skillRoot,
+        path: 'SKILL.md',
+        section: 'Method Selection',
+        label: 'SKILL.md#Method Selection',
+      },
+      {
+        root: skillRoot,
+        path: 'SKILL.md',
+        section: 'Core Usage Principles',
+        label: 'SKILL.md#Core Usage Principles',
       },
       { root: projectRoot, path: 'prompt/overview.md' },
       { root: projectRoot, path: 'prompt/core-principles.md' },
@@ -1609,8 +1623,10 @@ export function createFramerAgentToolRuntime({
       ...files.map((file) => `## ${file.path}\n\n${file.content}`),
       ...(catalogText ? [catalogText] : []),
     ].join('\n\n');
-    const inventory = files.find(
-      (file) => file.path.endsWith('project-inventory.md'),
+    const inventory = readGuidanceFile(
+      projectRoot,
+      'project-inventory.md',
+      MAX_GUIDANCE_FILE_BYTES,
     )?.content || '';
     guidanceMetadata = {
       loaded: Boolean(content),
@@ -1620,10 +1636,13 @@ export function createFramerAgentToolRuntime({
       projectContextHash: inventory
         ? crypto.createHash('sha256').update(inventory).digest('hex')
         : null,
-      files: files.map((file) => file.path),
-      bytes: Buffer.byteLength(content, 'utf8'),
+      files: [
+        ...files.map((file) => file.path),
+        ...(inventory ? ['project/project-inventory.md'] : []),
+      ],
+      bytes: Buffer.byteLength(content + inventory, 'utf8'),
     };
-    return { content, ...guidanceMetadata };
+    return { content, inventory, ...guidanceMetadata };
   };
 
   const configurePromptContext = ({
@@ -1736,7 +1755,74 @@ export function createFramerAgentToolRuntime({
         capture: captured.error,
       });
     }
-    return { images, viaDownload, viaSession, undelivered, failures };
+    screenshotsViaDownload += viaDownload;
+    screenshotsViaSession += viaSession;
+    screenshotsUndelivered += undelivered;
+    screenshotFailures.push(...failures);
+    screenshotFailures.splice(
+      0,
+      Math.max(0, screenshotFailures.length - MAX_SCREENSHOT_FAILURES_REPORTED),
+    );
+    return images;
+  };
+
+  const readProject = (queries, pagePath) => execCode(
+    [
+      `const result = await framer.agent.readProject(${JSON.stringify(queries)}, { pagePath: ${JSON.stringify(pagePath)} });`,
+      'console.log(JSON.stringify(result, null, 2));',
+    ].join('\n'),
+  );
+
+  // Runs readProject screenshot queries and hands the pixels to the model.
+  const readScreenshots = async (queries, pagePath) => {
+    const result = await readProject(queries, pagePath);
+    return deliverScreenshots(queries, parseStructuredOutput(result.stdout));
+  };
+
+  // Framer bills style font searches to the workspace's AI credit and fails
+  // the whole read when they cannot run. Those searches are then answered
+  // from the Google Fonts catalog and the remaining queries are read again.
+  // Returns null when there is nothing to answer, so the original error stands.
+  const readProjectWithFontFallback = async (queries, pagePath) => {
+    try {
+      return await readProject(queries, pagePath);
+    } catch (error) {
+      const styleSearch = (query) =>
+        query.type === 'font-search' && typeof query.query === 'string';
+      if (!queries.some(styleSearch)) throw error;
+      let catalog;
+      try {
+        catalog = await loadGoogleFontsCatalog(fetchImpl);
+      } catch (catalogError) {
+        trace?.warn?.('google_fonts_fallback_unavailable', {
+          message: catalogError?.message,
+        });
+        throw error;
+      }
+      const remaining = queries.filter((query) => !styleSearch(query));
+      const remainingResults = remaining.length
+        ? parseStructuredOutput((await readProject(remaining, pagePath)).stdout)?.results || []
+        : [];
+      fontSearchFallbacks += 1;
+      trace?.warn?.('framer_font_search_fallback', {
+        message: boundedText(String(error?.message || ''), 300),
+      });
+      const reason = boundedText(String(error?.message || 'unavailable'), 160);
+      let next = 0;
+      return {
+        stdout: JSON.stringify({
+          results: queries.map((query) => (styleSearch(query)
+            ? {
+                type: 'font-search',
+                source: 'google-fonts',
+                note: `Framer's style font search failed (${reason}), so these candidates come from the Google Fonts library, which Framer includes. Choose by how the family looks, set fontName to it, and use a listed weight. If you know a Google Fonts family that fits better, confirm it with a font-search by name.`,
+                results: searchGoogleFonts(catalog, query),
+              }
+            : remainingResults[next++] ?? null)),
+        }),
+        stderr: '',
+      };
+    }
   };
 
   const referenceAssetFiles = Array.isArray(assignment?.context?.referenceAssetFiles)
@@ -2105,6 +2191,17 @@ export function createFramerAgentToolRuntime({
     ].join(' ');
   };
 
+  const evidenceRequirement = (check) => {
+    if (check === 'structural') return 'a focused live read';
+    if (check === 'visual') {
+      return 'a screenshot you inspect (screenshotNodeIds on your last framer_apply_changes provides it)';
+    }
+    if (check === 'interactions') {
+      return 'framer_verify_interactions for every declared behavior and target node';
+    }
+    return `a read tagged with verifies:["${check}"]`;
+  };
+
   const verificationRepairPrompt = () => {
     const current = verification();
     if (current.completed || mutationCalls === 0) return null;
@@ -2173,7 +2270,6 @@ export function createFramerAgentToolRuntime({
 
   const reserveToolCall = (name, category) => {
     toolCallCount += 1;
-    if (category === 'progress') progressCalls += 1;
     if (category === 'read') readCalls += 1;
     const call = {
       sequence: toolCallCount,
@@ -2238,25 +2334,6 @@ export function createFramerAgentToolRuntime({
         'The same Framer tool call has failed five times in a row. Change the approach or report the concrete blocker.',
       );
     }
-    if (name === 'progress_update') {
-      const message = String(rawArguments.message || '').trim().slice(0, 500);
-      if (!message) {
-        throw toolError(
-          'FRAMER_AGENT_PROGRESS_INVALID',
-          'A progress message is required.',
-        );
-      }
-      const toolCall = reserveToolCall(name, 'progress');
-      reportActivity({
-        kind: 'status_update',
-        source: 'harness',
-        message,
-      });
-      repeatedFailureFingerprint = null;
-      repeatedFailureCount = 0;
-      toolCall.status = 'succeeded';
-      return { acknowledged: true };
-    }
 
     const startedAt = Date.now();
     const toolCall = reserveToolCall(name, category);
@@ -2275,6 +2352,7 @@ export function createFramerAgentToolRuntime({
     try {
       let result;
       let modelImages = [];
+      let screenshotRequestCount = 0;
       if (name === 'framer_write' && lowLevelWriteDisabled) {
         lowLevelWriteBlockedCalls += 1;
         throw toolError(
@@ -2392,7 +2470,10 @@ export function createFramerAgentToolRuntime({
           ...mergeBehaviorPlans(taskPlan, nextPlan),
         };
         result = {
-          stdout: JSON.stringify({ plan: taskPlanSnapshot() }),
+          stdout: JSON.stringify({
+            plan: taskPlanSnapshot(),
+            beforeFinishing: `After your final change, and before returning, produce: ${requiredChecks().map(evidenceRequirement).join('; ')}.`,
+          }),
           stderr: '',
         };
       } else if (name === 'framer_verify_interactions') {
@@ -2422,7 +2503,15 @@ export function createFramerAgentToolRuntime({
             .map((entry) => [entry.id, entry.node]),
         );
         const results = verifyBehaviorChecks({ checks, nodes });
-        markInspection();
+        // Live link values read here are link evidence too, so the model does
+        // not spend another turn re-reading them under verifies:["links"].
+        const linkChecks = results.filter((check) => /^link(\.|$)/.test(check.property));
+        markInspection({
+          verifies: linkChecks.length > 0
+            && linkChecks.every((check) => check.verdict === 'verified')
+            ? ['links']
+            : [],
+        });
         interactionVerificationCalls += 1;
         interactionVerifiedAt = new Date().toISOString();
         for (const checkResult of results) {
@@ -2451,28 +2540,15 @@ export function createFramerAgentToolRuntime({
           );
         }
         const pagePath = normalizePagePath(rawArguments.pagePath);
-        result = await execCode(
-          [
-            `const result = await framer.agent.readProject(${JSON.stringify(queries)}, { pagePath: ${JSON.stringify(pagePath)} });`,
-            'console.log(JSON.stringify(result, null, 2));',
-          ].join('\n'),
-        );
+        result = await readProjectWithFontFallback(queries, pagePath);
         const requestedScreenshots = screenshotQueries(rawArguments);
-        const delivery = requestedScreenshots.length
+        screenshotRequestCount = requestedScreenshots.length;
+        modelImages = requestedScreenshots.length
           ? await deliverScreenshots(
               requestedScreenshots,
               parseStructuredOutput(result.stdout),
             )
-          : { images: [], viaDownload: 0, viaSession: 0, undelivered: 0, failures: [] };
-        modelImages = delivery.images;
-        screenshotsViaDownload += delivery.viaDownload;
-        screenshotsViaSession += delivery.viaSession;
-        screenshotsUndelivered += delivery.undelivered;
-        screenshotFailures.push(...delivery.failures);
-        screenshotFailures.splice(
-          0,
-          Math.max(0, screenshotFailures.length - MAX_SCREENSHOT_FAILURES_REPORTED),
-        );
+          : [];
         markInspection({
           visual: modelImages.length > 0,
           visualAttempted: requestedScreenshots.length > 0,
@@ -2868,6 +2944,20 @@ export function createFramerAgentToolRuntime({
           ...summarizeFramerChanges(changes),
           renamedIds: canonicalIdMappings(parsedResult),
         });
+        // A screenshot taken here saves the model a whole turn re-reading
+        // its context just to look at the change.
+        const screenshotIds = Array.isArray(rawArguments.screenshotNodeIds)
+          ? uniqueStrings(rawArguments.screenshotNodeIds, MAX_SCREENSHOTS_PER_CALL)
+          : [];
+        if (screenshotIds.length > 0) {
+          const queries = screenshotIds.map((id) => ({ type: 'screenshot', id }));
+          modelImages = await readScreenshots(queries, pagePath);
+          screenshotRequestCount = queries.length;
+          markInspection({
+            visual: modelImages.length > 0,
+            visualAttempted: true,
+          });
+        }
       } else if (name === 'framer_read') {
         result = await execCode(
           validateCode(rawArguments.code, {
@@ -2937,17 +3027,22 @@ export function createFramerAgentToolRuntime({
       if (name === 'framer_read_website') {
         return modelImages.length ? { ...normalized, modelImages } : normalized;
       }
-      if (name !== 'framer_read_project') return normalized;
-      const screenshotCount = screenshotQueries(rawArguments).length;
+      // Naming the evidence still owed after the latest change lets the model
+      // finish it in this session instead of in a resumed repair turn.
+      const evidenceStillDue =
+        taskPlan && mutationCalls > 0 && (category === 'read' || screenshotRequestCount > 0)
+          ? missingVerificationChecks()
+          : [];
       return {
         ...normalized,
         ...(modelImages.length ? { modelImages } : {}),
-        ...(screenshotCount > modelImages.length
+        ...(screenshotRequestCount > modelImages.length
           ? {
               screenshotWarning:
-                `${screenshotCount - modelImages.length} screenshot(s) could not be downloaded for you to view. Treat that visual state as unverified.`,
+                `${screenshotRequestCount - modelImages.length} screenshot(s) could not be downloaded for you to view. Treat that visual state as unverified.`,
             }
           : {}),
+        ...(evidenceStillDue.length > 0 ? { evidenceStillDue } : {}),
       };
     } catch (error) {
       if (
@@ -3125,7 +3220,6 @@ export function createFramerAgentToolRuntime({
           : {}),
       })),
       readCalls,
-      progressCalls,
       toolCallCount,
       toolDurationMs: toolCalls.reduce(
         (total, call) => total + call.durationMs,
@@ -3153,6 +3247,7 @@ export function createFramerAgentToolRuntime({
         lowLevelWriteBlockedCalls,
         instructionFallbacks,
       },
+      fontSearchFallbacks,
       branch: branchChange,
       lastInspectionAt,
       lastMutationAt,

package/src/framerBehaviorContract.js

@@ -110,8 +110,22 @@ function hasContent(value) {
 }
 
 // Finds the property on the node itself. Child nodes are skipped so a
-// descendant cannot satisfy a claim about its parent.
+// descendant cannot satisfy a claim about its parent. A dotted name such as
+// `link.href` or `hoverEffect.opacity`, the way the change language writes
+// it, reads the field inside the property's value.
 function propertyValues(node, property) {
+  const values = keyValues(node, property);
+  const [head, ...path] = property.split('.');
+  if (values.length > 0 || path.length === 0) return values;
+  return keyValues(node, head)
+    .map((value) => path.reduce(
+      (current, key) => (isRecord(current) ? current[key] : undefined),
+      value,
+    ))
+    .filter(hasContent);
+}
+
+function keyValues(node, property) {
   const values = [];
   const visit = (current, depth) => {
     if (depth > MAX_SEARCH_DEPTH || values.length >= 10) return;

package/src/googleFontsFallback.js

@@ -0,0 +1,196 @@
+// Framer's style-based font search ("font-search" with a `query`) is matched
+// by Framer's AI and billed to the workspace's AI credit; when that fails, the
+// run still needs typography candidates. Google Fonts publishes its full
+// catalog (category, weights, italics, variable axes, popularity) without a
+// key, and every Google Fonts family is in Framer's font library, so the
+// bridge answers those searches from it in Framer's own result shape.
+
+const GOOGLE_FONTS_METADATA_URL = 'https://fonts.google.com/metadata/fonts';
+const CATALOG_TTL_MS = 24 * 60 * 60_000;
+const CATALOG_TIMEOUT_MS = 20_000;
+const MAX_RESULTS = 20;
+
+const WEIGHT_DESCRIPTORS = {
+  thin: 100,
+  'extra-light': 200,
+  light: 300,
+  regular: 400,
+  medium: 500,
+  semibold: 600,
+  bold: 700,
+  'extra-bold': 800,
+  black: 900,
+};
+
+// Words in a style query that point at a category.
+const CATEGORY_WORDS = {
+  serif: 'serif',
+  serifs: 'serif',
+  sans: 'sans-serif',
+  'sans-serif': 'sans-serif',
+  grotesque: 'sans-serif',
+  grotesk: 'sans-serif',
+  geometric: 'sans-serif',
+  slab: 'slab',
+  mono: 'monospace',
+  monospace: 'monospace',
+  monospaced: 'monospace',
+  code: 'monospace',
+  script: 'handwriting',
+  handwriting: 'handwriting',
+  handwritten: 'handwriting',
+  calligraphy: 'handwriting',
+  display: 'display',
+  poster: 'display',
+};
+const NARROW_WORDS = new Set(['condensed', 'narrow', 'compressed']);
+
+let cachedCatalog = null;
+let cachedAt = 0;
+let pendingCatalog = null;
+
+export async function loadGoogleFontsCatalog(fetchImpl = fetch) {
+  if (cachedCatalog && Date.now() - cachedAt < CATALOG_TTL_MS) return cachedCatalog;
+  pendingCatalog ||= (async () => {
+    const response = await fetchImpl(GOOGLE_FONTS_METADATA_URL, {
+      signal: AbortSignal.timeout(CATALOG_TIMEOUT_MS),
+    });
+    if (!response.ok) throw new Error(`Google Fonts catalog returned HTTP ${response.status}.`);
+    const text = await response.text();
+    // The feed starts with an anti-JSON-hijacking prefix before the object.
+    const families = JSON.parse(text.slice(text.indexOf('{'))).familyMetadataList;
+    if (!Array.isArray(families) || families.length === 0) {
+      throw new Error('Google Fonts catalog is empty.');
+    }
+    cachedCatalog = families;
+    cachedAt = Date.now();
+    return families;
+  })().finally(() => {
+    pendingCatalog = null;
+  });
+  return pendingCatalog;
+}
+
+function categoryOf(family) {
+  if (family.category === 'Monospace') return 'monospace';
+  if (family.category === 'Handwriting') return 'handwriting';
+  if (family.category === 'Display') return 'display';
+  if (family.category === 'Serif') return 'serif';
+  return 'sans-serif';
+}
+
+function fontFacts(family) {
+  const keys = Object.keys(family.fonts || {});
+  const weights = [...new Set(keys.map((key) => Number.parseInt(key, 10)))]
+    .filter(Number.isFinite)
+    .sort((a, b) => a - b);
+  const styles = [
+    ...(keys.some((key) => !key.endsWith('i')) ? ['normal'] : []),
+    ...(keys.some((key) => key.endsWith('i')) ? ['italic'] : []),
+  ];
+  const axes = (family.axes || []).map((axis) => ({
+    tag: axis.tag,
+    minValue: axis.min,
+    maxValue: axis.max,
+    defaultValue: axis.defaultValue,
+  }));
+  return { weights, styles, axes };
+}
+
+function hasDescriptor(family, facts, descriptor) {
+  const classifications = family.classifications || [];
+  if (descriptor in WEIGHT_DESCRIPTORS) {
+    const weight = WEIGHT_DESCRIPTORS[descriptor];
+    const wght = facts.axes.find((axis) => axis.tag === 'wght');
+    return facts.weights.includes(weight)
+      || Boolean(wght && wght.minValue <= weight && wght.maxValue >= weight);
+  }
+  if (descriptor.startsWith('variation-axis/')) {
+    const tag = descriptor.slice('variation-axis/'.length);
+    return facts.axes.some((axis) => axis.tag === tag);
+  }
+  switch (descriptor) {
+    case 'serif':
+      return family.category === 'Serif' || family.stroke === 'Serif';
+    case 'sans-serif':
+      return family.category === 'Sans Serif' || family.stroke === 'Sans Serif';
+    case 'slab':
+      return family.stroke === 'Slab Serif';
+    case 'monospace':
+      return family.category === 'Monospace' || classifications.includes('Monospace');
+    case 'display':
+      return family.category === 'Display' || classifications.includes('Display');
+    case 'handwriting':
+      return family.category === 'Handwriting' || classifications.includes('Handwriting');
+    case 'normal':
+    case 'italic':
+      return facts.styles.includes(descriptor);
+    default:
+      // Descriptors the catalog cannot judge do not exclude a family.
+      return true;
+  }
+}
+
+function queryScore(family, facts, words) {
+  const nameWords = family.family.toLowerCase().split(/\s+/);
+  let score = 0;
+  for (const word of words) {
+    const category = CATEGORY_WORDS[word];
+    if (category && hasDescriptor(family, facts, category)) score += 2;
+    if (NARROW_WORDS.has(word)) {
+      const width = facts.axes.find((axis) => axis.tag === 'wdth');
+      if (nameWords.some((part) => NARROW_WORDS.has(part)) || (width && width.minValue < 100)) {
+        score += 2;
+      }
+    }
+    if (
+      !category
+      && word.length >= 4
+      && nameWords.some((part) => part.slice(0, 5) === word.slice(0, 5))
+    ) {
+      score += 3;
+    }
+  }
+  return score;
+}
+
+// Ranks catalog families for one font-search query: every `mustHave`
+// descriptor is required, query words raise matching families, and Google
+// Fonts popularity breaks ties. More candidates than `limit` are returned
+// because keyword matching is coarse; the model chooses by how they look.
+export function searchGoogleFonts(catalog, query = {}) {
+  const mustHave = (Array.isArray(query.mustHave) ? query.mustHave : [])
+    .map((descriptor) => String(descriptor).trim().toLowerCase())
+    .filter(Boolean);
+  const words = String(query.query || '')
+    .toLowerCase()
+    .split(/[^a-z0-9-]+/)
+    .filter(Boolean);
+  const limit = Math.min(
+    MAX_RESULTS,
+    Math.max(10, (Number.parseInt(query.limit, 10) || 5) * 2),
+  );
+  return catalog
+    .filter((family) =>
+      typeof family?.family === 'string'
+      && !family.isNoto
+      && !family.isBrandFont
+      && (family.subsets || []).includes('latin'))
+    .map((family) => ({ family, facts: fontFacts(family) }))
+    .filter(({ family, facts }) =>
+      facts.weights.length > 0
+      && mustHave.every((descriptor) => hasDescriptor(family, facts, descriptor)))
+    .map((entry) => ({ ...entry, score: queryScore(entry.family, entry.facts, words) }))
+    .sort((a, b) =>
+      b.score - a.score
+      || (a.family.popularity ?? Infinity) - (b.family.popularity ?? Infinity))
+    .slice(0, limit)
+    .map(({ family, facts }) => ({
+      name: family.family,
+      weights: facts.weights,
+      styles: facts.styles,
+      category: categoryOf(family),
+      variationAxes: facts.axes,
+      reason: 'Google Fonts catalog match',
+    }));
+}