@hyperfixi/patterns-reference 3.1.1 → 3.2.0

package/dist/api/index.mjs

@@ -1,9 +1,85 @@
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { canParse } from '@lokascript/semantic';
 import Database from 'better-sqlite3';
 import { statSync } from 'fs';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var init_esm_shims = __esm({
+  "../../node_modules/tsup/assets/esm_shims.js"() {
+  }
+});
+
+// src/sync/markup-attributes.ts
+function findHyperscriptAttributes(markup) {
+  const spans = [];
+  ATTRIBUTE.lastIndex = 0;
+  let match;
+  while ((match = ATTRIBUTE.exec(markup)) !== null) {
+    const body = match[2] ?? match[3];
+    const start = match.index + match[0].length - body.length - 1;
+    spans.push({ start, end: start + body.length, body });
+  }
+  return spans;
+}
+function isMarkupRow(code) {
+  return /^\s*<[a-zA-Z!]/.test(code);
+}
+function hyperscriptBodies(code) {
+  if (!isMarkupRow(code)) return [code];
+  const bodies = findHyperscriptAttributes(code).map((span) => span.body);
+  for (const match of code.matchAll(HX_LIVE_ATTRIBUTE)) bodies.push(match[2] ?? match[3] ?? "");
+  return bodies.filter((body) => body.trim().length > 0);
+}
+var ATTRIBUTE, HX_LIVE_ATTRIBUTE;
+var init_markup_attributes = __esm({
+  "src/sync/markup-attributes.ts"() {
+    init_esm_shims();
+    ATTRIBUTE = /(^|[\s"'])_\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+    HX_LIVE_ATTRIBUTE = /(^|[\s"'])hx-live\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+  }
+});
+
+// src/sync/verify-parses.ts
+var verify_parses_exports = {};
+__export(verify_parses_exports, {
+  verifyParses: () => verifyParses
+});
+function verifyParses(code, language, translatable = true) {
+  const bodies = hyperscriptBodies(code);
+  if (bodies.length === 0) return false;
+  const parseLanguage = translatable ? language : "en";
+  return bodies.every((body) => {
+    try {
+      return canParse(body, parseLanguage);
+    } catch {
+      return false;
+    }
+  });
+}
+var init_verify_parses = __esm({
+  "src/sync/verify-parses.ts"() {
+    init_esm_shims();
+    init_markup_attributes();
+  }
+});
+
+// src/api/index.ts
+init_esm_shims();
+
+// src/api/patterns.ts
+init_esm_shims();
 
 // src/database/connection.ts
+init_esm_shims();
 var __filename$1 = fileURLToPath(import.meta.url);
 var __dirname$1 = dirname(__filename$1);
 var DEFAULT_DB_PATH = process.env.LSP_DB_PATH || process.env.HYPERSCRIPT_LSP_DB || join(__dirname$1, "../data/patterns.db");
@@ -11,10 +87,11 @@ var dbInstance = null;
 var currentDbPath = null;
 var openFileId = null;
 var lastIdentityCheckAt = 0;
+var openReadonly = false;
 var IDENTITY_TTL_MS = 1e3;
-function fileIdentity(path) {
+function fileIdentity(path2) {
   try {
-    const s = statSync(path);
+    const s = statSync(path2);
     return `${s.dev}:${s.ino}:${s.size}:${s.mtimeMs}`;
   } catch {
     return null;
@@ -22,7 +99,9 @@ function fileIdentity(path) {
 }
 function getDatabase(options = {}) {
   const dbPath = options.dbPath ?? DEFAULT_DB_PATH;
-  if (dbInstance !== null && currentDbPath === dbPath) {
+  const readonly = options.readonly ?? false;
+  const canServe = !openReadonly || readonly;
+  if (dbInstance !== null && currentDbPath === dbPath && canServe) {
     const now = Date.now();
     if (now - lastIdentityCheckAt < IDENTITY_TTL_MS) {
       return dbInstance;
@@ -38,9 +117,8 @@ function getDatabase(options = {}) {
   if (dbInstance !== null) {
     dbInstance.close();
   }
-  dbInstance = new Database(dbPath, {
-    readonly: options.readonly ?? false
-  });
+  dbInstance = new Database(dbPath, { readonly });
+  openReadonly = readonly;
   dbInstance.pragma("foreign_keys = ON");
   currentDbPath = dbPath;
   openFileId = fileIdentity(dbPath);
@@ -48,12 +126,26 @@ function getDatabase(options = {}) {
   return dbInstance;
 }
 
+// src/api/patterns.ts
+init_markup_attributes();
+
+// src/api/engine-filter.ts
+init_esm_shims();
+function runsOn(column, engine) {
+  if (engine === null) return { sql: `${column} IS NULL`, params: [] };
+  if (engine === "both") return { sql: `${column} = 'both'`, params: [] };
+  return { sql: `${column} IN ('both', ?)`, params: [engine] };
+}
+function exampleCondition(column, engine) {
+  return engine === void 0 ? { sql: `${column} IS NOT NULL`, params: [] } : runsOn(column, engine);
+}
+
 // src/api/patterns.ts
 async function getPatternById(id, options) {
   const db = getDatabase({ ...options, readonly: true });
   const row = db.prepare(
     `
-    SELECT id, title, raw_code, description, feature, engine, created_at
+    SELECT id, title, raw_code, description, feature, engine, translatable, created_at
     FROM code_examples
     WHERE id = ?
   `
@@ -64,7 +156,7 @@ async function getPatternsByCategory(category, options) {
   const db = getDatabase({ ...options, readonly: true });
   const rows = db.prepare(
     `
-    SELECT id, title, raw_code, description, feature, engine, created_at
+    SELECT id, title, raw_code, description, feature, engine, translatable, created_at
     FROM code_examples
     WHERE feature = ?
     ORDER BY title
@@ -76,7 +168,7 @@ async function getPatternsByCommand(command, options) {
   const db = getDatabase({ ...options, readonly: true });
   const rows = db.prepare(
     `
-    SELECT id, title, raw_code, description, feature, engine, created_at
+    SELECT id, title, raw_code, description, feature, engine, translatable, created_at
     FROM code_examples
     WHERE raw_code LIKE ?
     ORDER BY title
@@ -84,32 +176,45 @@ async function getPatternsByCommand(command, options) {
   ).all(`%${command}%`);
   return rows.filter((row) => new RegExp(`\\b${command}\\b`, "i").test(row.raw_code)).map(mapRowToPattern);
 }
-async function searchPatterns(query, searchOptions = {}, connOptions) {
-  const db = getDatabase({ ...connOptions, readonly: true });
-  const { limit = 50, offset = 0 } = searchOptions;
+function engineFilter(searchOptions) {
+  return searchOptions.engine === void 0 ? { sql: "1 = 1", params: [] } : runsOn("engine", searchOptions.engine);
+}
+function usableIn(db, language) {
   const rows = db.prepare(
-    `
-    SELECT id, title, raw_code, description, feature, engine, created_at
-    FROM code_examples
-    WHERE title LIKE ? OR raw_code LIKE ? OR description LIKE ?
-    ORDER BY title
-    LIMIT ? OFFSET ?
-  `
-  ).all(`%${query}%`, `%${query}%`, `%${query}%`, limit, offset);
-  return rows.map(mapRowToPattern);
+    "SELECT code_example_id AS id FROM pattern_translations WHERE language = ? AND verified_parses = 1"
+  ).all(language);
+  const verified = new Set(rows.map((row) => row.id));
+  return (pattern) => verified.has(pattern.id) || hyperscriptBodies(pattern.rawCode).length === 0;
 }
-async function getAllPatterns(searchOptions = {}, connOptions) {
+function queryPatterns(searchOptions, defaultLimit, connOptions, match = { sql: "1 = 1", params: [] }) {
   const db = getDatabase({ ...connOptions, readonly: true });
-  const { limit = 1e3, offset = 0 } = searchOptions;
+  const { limit = defaultLimit, offset = 0, category, difficulty, language } = searchOptions;
+  const runs = engineFilter(searchOptions);
+  const inCategory = category === void 0 ? { sql: "1 = 1", params: [] } : { sql: "feature = ?", params: [category] };
   const rows = db.prepare(
     `
-    SELECT id, title, raw_code, description, feature, engine, created_at
+    SELECT id, title, raw_code, description, feature, engine, translatable, created_at
     FROM code_examples
+    WHERE (${match.sql}) AND ${runs.sql} AND ${inCategory.sql}
     ORDER BY title
-    LIMIT ? OFFSET ?
   `
-  ).all(limit, offset);
-  return rows.map(mapRowToPattern);
+  ).all(...match.params, ...runs.params, ...inCategory.params);
+  const inLanguage = language === void 0 ? null : usableIn(db, language);
+  return rows.map(mapRowToPattern).filter((pattern) => difficulty === void 0 || pattern.difficulty === difficulty).filter((pattern) => inLanguage === null || inLanguage(pattern)).slice(offset, offset + limit);
+}
+async function searchPatterns(query, searchOptions = {}, connOptions) {
+  const like = `%${query}%`;
+  const inTranslation = searchOptions.language === void 0 ? { sql: "", params: [] } : {
+    sql: " OR id IN (SELECT code_example_id FROM pattern_translations WHERE language = ? AND hyperscript LIKE ?)",
+    params: [searchOptions.language, like]
+  };
+  return queryPatterns(searchOptions, 50, connOptions, {
+    sql: `title LIKE ? OR raw_code LIKE ? OR description LIKE ?${inTranslation.sql}`,
+    params: [like, like, like, ...inTranslation.params]
+  });
+}
+async function getAllPatterns(searchOptions = {}, connOptions) {
+  return queryPatterns(searchOptions, 1e3, connOptions);
 }
 async function getPatternStats(connOptions) {
   const db = getDatabase({ ...connOptions, readonly: true });
@@ -164,6 +269,7 @@ function mapRowToPattern(row) {
     tags: extractTags(row.raw_code),
     difficulty: inferDifficulty(row.raw_code),
     engine: row.engine || null,
+    translatable: row.translatable !== 0,
     createdAt: new Date(row.created_at)
   };
 }
@@ -188,6 +294,7 @@ function inferDifficulty(code) {
 }
 
 // src/api/translations.ts
+init_esm_shims();
 async function getTranslation(patternId, language, options) {
   const db = getDatabase({ ...options, readonly: true });
   const row = db.prepare(
@@ -249,32 +356,35 @@ async function verifyTranslation(translation, options) {
   let parseSuccess = false;
   let errorMessage = null;
   let confidence = translation.confidence;
+  const db = getDatabase(options);
+  const example = db.prepare("SELECT translatable FROM code_examples WHERE id = ?").get(translation.codeExampleId);
   try {
-    const { canParse, parse } = await import('@lokascript/semantic');
-    if (canParse(translation.hyperscript, translation.language)) {
-      parse(translation.hyperscript, translation.language);
-      parseSuccess = true;
-    } else {
-      errorMessage = "canParse returned false";
-    }
+    const { verifyParses: verifyParses2 } = await Promise.resolve().then(() => (init_verify_parses(), verify_parses_exports));
+    parseSuccess = verifyParses2(
+      translation.hyperscript,
+      translation.language,
+      example?.translatable !== 0
+    );
+    if (!parseSuccess) errorMessage = "the semantic parser rejected it (or it has no hyperscript)";
   } catch (e) {
     errorMessage = e.message;
   }
-  const db = getDatabase(options);
-  db.prepare(
+  db.transaction(() => {
+    db.prepare(
+      `
+      UPDATE pattern_translations
+      SET verified_parses = ?, updated_at = datetime('now')
+      WHERE id = ?
     `
-    UPDATE pattern_translations
-    SET verified_parses = ?, updated_at = datetime('now')
-    WHERE id = ?
-  `
-  ).run(parseSuccess ? 1 : 0, translation.id);
-  db.prepare(
+    ).run(parseSuccess ? 1 : 0, translation.id);
+    db.prepare(
+      `
+      INSERT INTO pattern_tests
+        (code_example_id, language, test_type, success, error_message, test_date)
+      VALUES (?, ?, 'parse', ?, ?, datetime('now'))
     `
-    INSERT INTO pattern_tests
-      (code_example_id, language, test_date, parse_success, error_message)
-    VALUES (?, ?, datetime('now'), ?, ?)
-  `
-  ).run(translation.codeExampleId, translation.language, parseSuccess ? 1 : 0, errorMessage);
+    ).run(translation.codeExampleId, translation.language, parseSuccess ? 1 : 0, errorMessage);
+  })();
   return {
     translation,
     parseSuccess,
@@ -344,74 +454,70 @@ function getWordOrder(language) {
 }
 
 // src/api/llm.ts
+init_esm_shims();
+var EXAMPLES_FROM = `
+  SELECT le.*, ce.engine AS engine
+  FROM llm_examples le
+  JOIN code_examples ce ON ce.id = le.code_example_id`;
 async function getLLMExamples(prompt, language = "en", limit = 5, options) {
   const db = getDatabase({ ...options, readonly: true });
+  const runs = exampleCondition("ce.engine", options?.engine);
   const keywords = extractKeywords(prompt);
   if (keywords.length === 0) {
     const rows2 = db.prepare(
-      `
-      SELECT * FROM llm_examples
-      WHERE language = ?
-      ORDER BY quality_score DESC, usage_count DESC
+      `${EXAMPLES_FROM}
+      WHERE le.language = ? AND ${runs.sql}
+      ORDER BY le.quality_score DESC, le.usage_count DESC
       LIMIT ?
     `
-    ).all(language, limit);
-    trackUsage(
-      db,
-      rows2.map((r) => r.id)
-    );
+    ).all(language, ...runs.params, limit);
     return rows2.map(mapRowToLLMExample);
   }
-  const likeClauses = keywords.map(() => "(prompt LIKE ? OR completion LIKE ?)").join(" OR ");
+  const likeClauses = keywords.map(() => "(le.prompt LIKE ? OR le.completion LIKE ?)").join(" OR ");
   const params = keywords.flatMap((k) => [`%${k}%`, `%${k}%`]);
   const rows = db.prepare(
-    `
-    SELECT * FROM llm_examples
-    WHERE language = ? AND (${likeClauses})
-    ORDER BY quality_score DESC
+    `${EXAMPLES_FROM}
+    WHERE le.language = ? AND ${runs.sql} AND (${likeClauses})
+    ORDER BY le.quality_score DESC
     LIMIT ?
   `
-  ).all(language, ...params, limit);
-  trackUsage(
-    db,
-    rows.map((r) => r.id)
-  );
+  ).all(language, ...runs.params, ...params, limit);
   return rows.map(mapRowToLLMExample);
 }
 async function getExamplesByCommand(command, language = "en", limit = 5, options) {
   const db = getDatabase({ ...options, readonly: true });
+  const runs = exampleCondition("ce.engine", options?.engine);
   const rows = db.prepare(
-    `
-    SELECT * FROM llm_examples
-    WHERE language = ? AND completion LIKE ?
-    ORDER BY quality_score DESC
+    `${EXAMPLES_FROM}
+    WHERE le.language = ? AND ${runs.sql} AND le.completion LIKE ?
+    ORDER BY le.quality_score DESC
     LIMIT ?
   `
-  ).all(language, `%${command}%`, limit);
+  ).all(language, ...runs.params, `%${command}%`, limit);
   return rows.map(mapRowToLLMExample);
 }
 async function getHighQualityExamples(language = "en", minQuality = 0.8, limit = 10, options) {
   const db = getDatabase({ ...options, readonly: true });
+  const runs = exampleCondition("ce.engine", options?.engine);
   const rows = db.prepare(
-    `
-    SELECT * FROM llm_examples
-    WHERE language = ? AND quality_score >= ?
-    ORDER BY quality_score DESC, usage_count DESC
+    `${EXAMPLES_FROM}
+    WHERE le.language = ? AND ${runs.sql} AND le.quality_score >= ?
+    ORDER BY le.quality_score DESC, le.usage_count DESC
     LIMIT ?
   `
-  ).all(language, minQuality, limit);
+  ).all(language, ...runs.params, minQuality, limit);
   return rows.map(mapRowToLLMExample);
 }
 async function getMostUsedExamples(language = "en", limit = 10, options) {
   const db = getDatabase({ ...options, readonly: true });
+  const runs = exampleCondition("ce.engine", options?.engine);
   const rows = db.prepare(
-    `
-    SELECT * FROM llm_examples
-    WHERE language = ?
-    ORDER BY usage_count DESC, quality_score DESC
+    `${EXAMPLES_FROM}
+    WHERE le.language = ? AND ${runs.sql}
+    ORDER BY le.usage_count DESC, le.quality_score DESC
     LIMIT ?
   `
-  ).all(language, limit);
+  ).all(language, ...runs.params, limit);
   return rows.map(mapRowToLLMExample);
 }
 async function buildFewShotContext(prompt, language = "en", numExamples = 3, options) {
@@ -509,18 +615,6 @@ function extractKeywords(prompt) {
   ]);
   return prompt.toLowerCase().split(/\W+/).filter((word) => word.length > 2 && !stopWords.has(word));
 }
-function trackUsage(db, ids) {
-  if (ids.length === 0) return;
-  try {
-    const stmt = db.prepare(`
-      UPDATE llm_examples SET usage_count = usage_count + 1 WHERE id = ?
-    `);
-    for (const id of ids) {
-      stmt.run(id);
-    }
-  } catch {
-  }
-}
 function mapRowToLLMExample(row) {
   return {
     id: row.id,
@@ -530,11 +624,13 @@ function mapRowToLLMExample(row) {
     completion: row.completion,
     qualityScore: row.quality_score,
     usageCount: row.usage_count,
-    createdAt: new Date(row.created_at)
+    createdAt: new Date(row.created_at),
+    engine: row.engine ?? null
   };
 }
 
 // src/api/roles.ts
+init_esm_shims();
 async function getPatternRoles(patternId, options) {
   const db = getDatabase({ ...options, readonly: true });
   const rows = db.prepare(
@@ -551,7 +647,7 @@ async function getPatternsByRole(role, options) {
   const db = getDatabase({ ...options, readonly: true });
   const rows = db.prepare(
     `
-    SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.created_at
+    SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.translatable, ce.created_at
     FROM code_examples ce
     INNER JOIN pattern_roles pr ON ce.id = pr.code_example_id
     WHERE pr.role = ?
@@ -567,7 +663,7 @@ async function getPatternsByRoles(roles, matchMode = "any", options) {
     const placeholders = roles.map(() => "?").join(", ");
     const rows = db.prepare(
       `
-      SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.created_at
+      SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.translatable, ce.created_at
       FROM code_examples ce
       INNER JOIN pattern_roles pr ON ce.id = pr.code_example_id
       WHERE pr.role IN (${placeholders})
@@ -579,7 +675,7 @@ async function getPatternsByRoles(roles, matchMode = "any", options) {
     const placeholders = roles.map(() => "?").join(", ");
     const rows = db.prepare(
       `
-      SELECT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.created_at
+      SELECT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.translatable, ce.created_at
       FROM code_examples ce
       WHERE (
         SELECT COUNT(DISTINCT pr.role)
@@ -596,7 +692,7 @@ async function getPatternsByRoleValue(role, value, options) {
   const db = getDatabase({ ...options, readonly: true });
   const rows = db.prepare(
     `
-    SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.created_at
+    SELECT DISTINCT ce.id, ce.title, ce.raw_code, ce.description, ce.feature, ce.engine, ce.translatable, ce.created_at
     FROM code_examples ce
     INNER JOIN pattern_roles pr ON ce.id = pr.code_example_id
     WHERE pr.role = ? AND pr.role_value LIKE ?
@@ -729,6 +825,7 @@ function mapRowToPattern2(row) {
     tags: extractTags2(row.raw_code),
     difficulty: inferDifficulty2(row.raw_code),
     engine: row.engine || null,
+    translatable: row.translatable !== 0,
     createdAt: new Date(row.created_at)
   };
 }

package/dist/{index-6GkHj5yJ.d.mts → index-CoDUfq2P.d.mts}

@@ -24,6 +24,12 @@ interface Pattern {
     tags: string[];
     difficulty: 'beginner' | 'intermediate' | 'advanced';
     engine: EngineCompat | null;
+    /**
+     * Whether the corpus writer translates this row. `false` rows are copied
+     * verbatim into every language (markup whose attribute names are resolved by
+     * vocab modules, or markup with no hyperscript at all).
+     */
+    translatable: boolean;
     createdAt: Date;
 }
 /**
@@ -48,7 +54,8 @@ type WordOrder = 'SVO' | 'SOV' | 'VSO' | 'V2';
  * - `grammar-transform-no-reference`: `best` only — the i18n row because semantic
  *   cannot parse the ENGLISH source (a parser-coverage gap, not a render loss).
  * - `keyword-substitute`: word-for-word fallback for a language with no grammar profile.
- * - `original`: the English row; `non-translatable-identity`: markup rows copied verbatim.
+ * - `original`: the English row; `non-translatable-identity`: a non-translatable row copied
+ *   verbatim (the markup rows, and intercept-cache-strategies).
  */
 type TranslationMethod = 'semantic-render' | 'grammar-transform' | 'grammar-transform-no-reference' | 'keyword-substitute' | 'original' | 'non-translatable-identity' | 'auto-generated' | 'hand-crafted' | 'verified';
 /**
@@ -89,8 +96,24 @@ interface LLMExample {
     prompt: string;
     completion: string;
     qualityScore: number;
+    /** @deprecated 0 unless something calls trackExampleUsage() (see getMostUsedExamples). */
     usageCount: number;
     createdAt: Date;
+    /**
+     * The engine(s) verified to run this example's pattern
+     * (`code_examples.engine`). Never null in results: an example no engine
+     * runs is not served.
+     */
+    engine: EngineCompat | null;
+}
+/**
+ * Options for the LLM-example getters. `engine` narrows to examples whose
+ * pattern runs on that engine — 'hyperscript' = both + upstream-only,
+ * 'lokascript' = both + hyperfixi-only, 'both' = both. With or without it,
+ * an example whose pattern NO engine runs is never returned.
+ */
+interface ExampleOptions extends ConnectionOptions {
+    engine?: EngineCompat;
 }
 
 /**
@@ -109,10 +132,22 @@ interface PatternRole {
     roleType: RoleType | null;
     required: boolean;
 }
+/** Honoured by searchPatterns and getAllPatterns; the page is taken after every filter. */
 interface SearchOptions {
+    /**
+     * Patterns usable in this language: a translation there that parses
+     * (`verified_parses`), or no hyperscript at all to translate. searchPatterns
+     * also matches its query against that translation.
+     */
     language?: string;
+    /** The pattern's category (`Pattern.category`). */
     category?: string;
+    /** As inferred from the code (`Pattern.difficulty`). */
     difficulty?: 'beginner' | 'intermediate' | 'advanced';
+    /**
+     * Patterns that run on this engine ('hyperscript' / 'lokascript' include
+     * 'both'); `null` = the patterns no engine runs; omitted = no filter.
+     */
     engine?: EngineCompat | null;
     limit?: number;
     offset?: number;
@@ -302,9 +337,10 @@ interface PatternsReference {
     getTranslation(patternId: string, language: string): Promise<Translation | null>;
     getAllTranslations(patternId: string): Promise<Translation[]>;
     verifyTranslation(translation: Translation): Promise<VerificationResult>;
-    getLLMExamples(prompt: string, language?: string, limit?: number): Promise<LLMExample[]>;
+    /** Never returns an example no engine runs; `engine` narrows further (see ExampleOptions). */
+    getLLMExamples(prompt: string, language?: string, limit?: number, engine?: EngineCompat): Promise<LLMExample[]>;
     getStats(): Promise<PatternStats>;
     close(): void;
 }
 
-export type { ConnectionOptions as C, DiscoveryResult as D, Expression as E, Feature as F, Keyword as K, LanguageDocsStats as L, PatternRole as P, RoleType as R, SpecialSymbol as S, TestOptions as T, ValidationOptions as V, WordOrder as W, Pattern as a, Command as b, LanguageElementType as c, LanguageElement as d, LLMExample as e, PatternsReference as f, ClassifiedPattern as g, ComplexityLevel as h, EngineCompat as i, ExpressionOperator as j, PatternStats as k, SearchOptions as l, SyncOptions as m, SyncResult as n, Translation as o, TranslationMethod as p, ValidationResult as q, VerificationResult as r };
+export type { ConnectionOptions as C, DiscoveryResult as D, Expression as E, Feature as F, Keyword as K, LanguageDocsStats as L, PatternRole as P, RoleType as R, SpecialSymbol as S, TestOptions as T, ValidationOptions as V, WordOrder as W, Pattern as a, Command as b, LanguageElementType as c, LanguageElement as d, EngineCompat as e, LLMExample as f, PatternsReference as g, ClassifiedPattern as h, ComplexityLevel as i, ExampleOptions as j, ExpressionOperator as k, PatternStats as l, SearchOptions as m, SyncOptions as n, SyncResult as o, Translation as p, TranslationMethod as q, ValidationResult as r, VerificationResult as s };

package/dist/{index-6GkHj5yJ.d.ts → index-CoDUfq2P.d.ts}

@@ -24,6 +24,12 @@ interface Pattern {
     tags: string[];
     difficulty: 'beginner' | 'intermediate' | 'advanced';
     engine: EngineCompat | null;
+    /**
+     * Whether the corpus writer translates this row. `false` rows are copied
+     * verbatim into every language (markup whose attribute names are resolved by
+     * vocab modules, or markup with no hyperscript at all).
+     */
+    translatable: boolean;
     createdAt: Date;
 }
 /**
@@ -48,7 +54,8 @@ type WordOrder = 'SVO' | 'SOV' | 'VSO' | 'V2';
  * - `grammar-transform-no-reference`: `best` only — the i18n row because semantic
  *   cannot parse the ENGLISH source (a parser-coverage gap, not a render loss).
  * - `keyword-substitute`: word-for-word fallback for a language with no grammar profile.
- * - `original`: the English row; `non-translatable-identity`: markup rows copied verbatim.
+ * - `original`: the English row; `non-translatable-identity`: a non-translatable row copied
+ *   verbatim (the markup rows, and intercept-cache-strategies).
  */
 type TranslationMethod = 'semantic-render' | 'grammar-transform' | 'grammar-transform-no-reference' | 'keyword-substitute' | 'original' | 'non-translatable-identity' | 'auto-generated' | 'hand-crafted' | 'verified';
 /**
@@ -89,8 +96,24 @@ interface LLMExample {
     prompt: string;
     completion: string;
     qualityScore: number;
+    /** @deprecated 0 unless something calls trackExampleUsage() (see getMostUsedExamples). */
     usageCount: number;
     createdAt: Date;
+    /**
+     * The engine(s) verified to run this example's pattern
+     * (`code_examples.engine`). Never null in results: an example no engine
+     * runs is not served.
+     */
+    engine: EngineCompat | null;
+}
+/**
+ * Options for the LLM-example getters. `engine` narrows to examples whose
+ * pattern runs on that engine — 'hyperscript' = both + upstream-only,
+ * 'lokascript' = both + hyperfixi-only, 'both' = both. With or without it,
+ * an example whose pattern NO engine runs is never returned.
+ */
+interface ExampleOptions extends ConnectionOptions {
+    engine?: EngineCompat;
 }
 
 /**
@@ -109,10 +132,22 @@ interface PatternRole {
     roleType: RoleType | null;
     required: boolean;
 }
+/** Honoured by searchPatterns and getAllPatterns; the page is taken after every filter. */
 interface SearchOptions {
+    /**
+     * Patterns usable in this language: a translation there that parses
+     * (`verified_parses`), or no hyperscript at all to translate. searchPatterns
+     * also matches its query against that translation.
+     */
     language?: string;
+    /** The pattern's category (`Pattern.category`). */
     category?: string;
+    /** As inferred from the code (`Pattern.difficulty`). */
     difficulty?: 'beginner' | 'intermediate' | 'advanced';
+    /**
+     * Patterns that run on this engine ('hyperscript' / 'lokascript' include
+     * 'both'); `null` = the patterns no engine runs; omitted = no filter.
+     */
     engine?: EngineCompat | null;
     limit?: number;
     offset?: number;
@@ -302,9 +337,10 @@ interface PatternsReference {
     getTranslation(patternId: string, language: string): Promise<Translation | null>;
     getAllTranslations(patternId: string): Promise<Translation[]>;
     verifyTranslation(translation: Translation): Promise<VerificationResult>;
-    getLLMExamples(prompt: string, language?: string, limit?: number): Promise<LLMExample[]>;
+    /** Never returns an example no engine runs; `engine` narrows further (see ExampleOptions). */
+    getLLMExamples(prompt: string, language?: string, limit?: number, engine?: EngineCompat): Promise<LLMExample[]>;
     getStats(): Promise<PatternStats>;
     close(): void;
 }
 
-export type { ConnectionOptions as C, DiscoveryResult as D, Expression as E, Feature as F, Keyword as K, LanguageDocsStats as L, PatternRole as P, RoleType as R, SpecialSymbol as S, TestOptions as T, ValidationOptions as V, WordOrder as W, Pattern as a, Command as b, LanguageElementType as c, LanguageElement as d, LLMExample as e, PatternsReference as f, ClassifiedPattern as g, ComplexityLevel as h, EngineCompat as i, ExpressionOperator as j, PatternStats as k, SearchOptions as l, SyncOptions as m, SyncResult as n, Translation as o, TranslationMethod as p, ValidationResult as q, VerificationResult as r };
+export type { ConnectionOptions as C, DiscoveryResult as D, Expression as E, Feature as F, Keyword as K, LanguageDocsStats as L, PatternRole as P, RoleType as R, SpecialSymbol as S, TestOptions as T, ValidationOptions as V, WordOrder as W, Pattern as a, Command as b, LanguageElementType as c, LanguageElement as d, EngineCompat as e, LLMExample as f, PatternsReference as g, ClassifiedPattern as h, ComplexityLevel as i, ExampleOptions as j, ExpressionOperator as k, PatternStats as l, SearchOptions as m, SyncOptions as n, SyncResult as o, Translation as p, TranslationMethod as q, ValidationResult as r, VerificationResult as s };