@hyperfixi/patterns-reference 3.1.1 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/CHANGELOG.md +186 -1
  2. package/README.md +47 -36
  3. package/data/engine-verification.json +58 -65
  4. package/data/patterns.db +0 -0
  5. package/data/patterns.db.stamp +1 -0
  6. package/dist/api/index.d.mts +2 -2
  7. package/dist/api/index.d.ts +2 -2
  8. package/dist/api/index.js +198 -98
  9. package/dist/api/index.mjs +197 -100
  10. package/dist/{index-6GkHj5yJ.d.mts → index-CoDUfq2P.d.mts} +39 -3
  11. package/dist/{index-6GkHj5yJ.d.ts → index-CoDUfq2P.d.ts} +39 -3
  12. package/dist/index.d.mts +87 -13
  13. package/dist/index.d.ts +87 -13
  14. package/dist/index.js +261 -144
  15. package/dist/index.mjs +258 -146
  16. package/dist/{llm-B5nGz8V1.d.mts → llm-CCCSw-yp.d.ts} +21 -10
  17. package/dist/{llm-rEdJQScF.d.ts → llm-PxnriEZ_.d.mts} +21 -10
  18. package/dist/sync/index.d.mts +1 -1
  19. package/dist/sync/index.d.ts +1 -1
  20. package/dist/sync/index.js +4 -1
  21. package/dist/sync/index.mjs +4 -1
  22. package/package.json +16 -16
  23. package/src/adapters/llm-adapter.ts +64 -42
  24. package/src/api/engine-filter.ts +37 -0
  25. package/src/api/llm.ts +54 -64
  26. package/src/api/patterns.ts +92 -30
  27. package/src/api/roles.ts +6 -4
  28. package/src/api/translations.ts +34 -27
  29. package/src/database/connection.ts +16 -4
  30. package/src/html-snippets.ts +39 -10
  31. package/src/index.ts +12 -2
  32. package/src/registry/patterns-provider.ts +3 -1
  33. package/src/sync/db-stamp.ts +7 -4
  34. package/src/sync/markup-attributes.ts +15 -0
  35. package/src/sync/verify-parses.ts +42 -0
  36. package/src/types/better-sqlite3.d.ts +2 -0
  37. package/src/types/index.ts +44 -2
  38. package/src/sync/span-mask.ts +0 -166
  39. package/src/sync/translation-checks.ts +0 -282
package/dist/index.d.mts CHANGED
@@ -1,7 +1,7 @@
1
- import { C as ConnectionOptions, b as Command, E as Expression, F as Feature, K as Keyword, S as SpecialSymbol, L as LanguageDocsStats, c as LanguageElementType, d as LanguageElement, e as LLMExample, f as PatternsReference } from './index-6GkHj5yJ.mjs';
2
- export { g as ClassifiedPattern, h as ComplexityLevel, D as DiscoveryResult, i as EngineCompat, j as ExpressionOperator, a as Pattern, k as PatternStats, l as SearchOptions, m as SyncOptions, n as SyncResult, T as TestOptions, o as Translation, p as TranslationMethod, V as ValidationOptions, q as ValidationResult, r as VerificationResult, W as WordOrder } from './index-6GkHj5yJ.mjs';
1
+ import { C as ConnectionOptions, b as Command, E as Expression, F as Feature, K as Keyword, S as SpecialSymbol, L as LanguageDocsStats, c as LanguageElementType, d as LanguageElement, e as EngineCompat, f as LLMExample, g as PatternsReference } from './index-CoDUfq2P.mjs';
2
+ export { h as ClassifiedPattern, i as ComplexityLevel, D as DiscoveryResult, j as ExampleOptions, k as ExpressionOperator, a as Pattern, l as PatternStats, m as SearchOptions, n as SyncOptions, o as SyncResult, T as TestOptions, p as Translation, q as TranslationMethod, V as ValidationOptions, r as ValidationResult, s as VerificationResult, W as WordOrder } from './index-CoDUfq2P.mjs';
3
3
  import Database from 'better-sqlite3';
4
- export { a as addLLMExample, b as buildFewShotContext, g as getAllPatterns, c as getAllTranslations, w as getBehaviorPatterns, d as getExamplesByCommand, e as getHighConfidenceTranslations, f as getHighQualityExamples, h as getLLMExamples, i as getLLMStats, j as getMostUsedExamples, k as getPatternById, l as getPatternStats, m as getPatternsByCategory, n as getPatternsByCommand, o as getTranslation, p as getTranslationStats, q as getTranslationsByLanguage, r as getVerifiedTranslations, s as getWordOrder, t as searchPatterns, u as updateQualityScore, v as verifyTranslation } from './llm-B5nGz8V1.mjs';
4
+ export { a as addLLMExample, b as buildFewShotContext, g as getAllPatterns, c as getAllTranslations, w as getBehaviorPatterns, d as getExamplesByCommand, e as getHighConfidenceTranslations, f as getHighQualityExamples, h as getLLMExamples, i as getLLMStats, j as getMostUsedExamples, k as getPatternById, l as getPatternStats, m as getPatternsByCategory, n as getPatternsByCommand, o as getTranslation, p as getTranslationStats, q as getTranslationsByLanguage, r as getVerifiedTranslations, s as getWordOrder, t as searchPatterns, u as updateQualityScore, v as verifyTranslation } from './llm-PxnriEZ_.mjs';
5
5
  export { DbStampStatus, checkDbStamp, computeDbInputHash, dbStampPath, discoverPatterns, seedLLMExamples, syncTranslations, validateAllTranslations, writeDbStamp } from './sync/index.mjs';
6
6
  import '@lokascript/semantic';
7
7
 
@@ -176,6 +176,8 @@ interface LLMExampleRecord {
176
176
  completion: string;
177
177
  language: string;
178
178
  qualityScore: number;
179
+ /** The engine(s) verified to run the example's pattern (never null here). */
180
+ engine: EngineCompat | null;
179
181
  }
180
182
  /**
181
183
  * Check if the database is available for sync operations.
@@ -190,18 +192,24 @@ declare function isDatabaseAvailable(): boolean;
190
192
  * @param prompt - The user's request/prompt
191
193
  * @param language - Target language code (default: 'en')
192
194
  * @param limit - Maximum number of examples to return (default: 5)
195
+ * @param engine - Only examples whose pattern runs on this engine. Examples no
196
+ * engine runs are never returned, with or without it.
193
197
  */
194
- declare function findRelevantExamples(prompt: string, language?: string, limit?: number): LLMExampleRecord[];
198
+ declare function findRelevantExamples(prompt: string, language?: string, limit?: number, engine?: EngineCompat): LLMExampleRecord[];
195
199
  /**
196
200
  * Find examples by command type (sync interface).
197
201
  */
198
- declare function findExamplesByCommand(command: string, language?: string, limit?: number): LLMExampleRecord[];
202
+ declare function findExamplesByCommand(command: string, language?: string, limit?: number, engine?: EngineCompat): LLMExampleRecord[];
199
203
  /**
200
204
  * Build few-shot context (sync interface).
201
205
  */
202
- declare function buildFewShotContextSync(prompt: string, language?: string, numExamples?: number): string;
206
+ declare function buildFewShotContextSync(prompt: string, language?: string, numExamples?: number, engine?: EngineCompat): string;
203
207
  /**
204
208
  * Track example usage (sync interface).
209
+ *
210
+ * @deprecated The counts go into the installed package's own database file,
211
+ * which every install and every `populate` replaces, and only
212
+ * getMostUsedExamples (deprecated with it) reads them. Nothing calls this.
205
213
  */
206
214
  declare function trackExampleUsage(ids: number[]): void;
207
215
  /**
@@ -238,11 +246,12 @@ declare function createLLMAdapter(options?: ConnectionOptions): {
238
246
  trackExampleUsage: typeof trackExampleUsage;
239
247
  getLLMExampleStats: typeof getLLMExampleStats;
240
248
  isDatabaseAvailable: typeof isDatabaseAvailable;
241
- getLLMExamples: (prompt: string, language?: string, limit?: number) => Promise<LLMExample[]>;
242
- getExamplesByCommand: (command: string, language?: string, limit?: number) => Promise<LLMExample[]>;
243
- getHighQualityExamples: (language?: string, minQuality?: number, limit?: number) => Promise<LLMExample[]>;
244
- getMostUsedExamples: (language?: string, limit?: number) => Promise<LLMExample[]>;
245
- buildFewShotContext: (prompt: string, language?: string, numExamples?: number) => Promise<string>;
249
+ getLLMExamples: (prompt: string, language?: string, limit?: number, engine?: EngineCompat) => Promise<LLMExample[]>;
250
+ getExamplesByCommand: (command: string, language?: string, limit?: number, engine?: EngineCompat) => Promise<LLMExample[]>;
251
+ getHighQualityExamples: (language?: string, minQuality?: number, limit?: number, engine?: EngineCompat) => Promise<LLMExample[]>;
252
+ /** @deprecated See getMostUsedExamples. */
253
+ getMostUsedExamples: (language?: string, limit?: number, engine?: EngineCompat) => Promise<LLMExample[]>;
254
+ buildFewShotContext: (prompt: string, language?: string, numExamples?: number, engine?: EngineCompat) => Promise<string>;
246
255
  getLLMStats: () => Promise<{
247
256
  total: number;
248
257
  byLanguage: Record<string, number>;
@@ -456,6 +465,8 @@ interface MinimalElement {
456
465
  tagName: string;
457
466
  attributes: ArrayLike<MinimalAttr>;
458
467
  textContent: string | null;
468
+ /** Read only on `<template>`, whose content `querySelectorAll` cannot reach. */
469
+ innerHTML?: string;
459
470
  getAttribute(name: string): string | null;
460
471
  }
461
472
  interface MinimalContainer extends MinimalElement {
@@ -466,7 +477,11 @@ interface MinimalDocument {
466
477
  createElement(tagName: string): MinimalContainer;
467
478
  }
468
479
  interface MarkupSnippets {
469
- /** Every hyperscript source found, in document order. */
480
+ /**
481
+ * Every hyperscript source found, in document order — including the `_`
482
+ * attributes inside component template bodies, which run once the
483
+ * component renders.
484
+ */
470
485
  snippets: string[];
471
486
  /**
472
487
  * The markup uses at least one attribute upstream `_hyperscript` has no
@@ -474,6 +489,12 @@ interface MarkupSnippets {
474
489
  * how its snippets parse.
475
490
  */
476
491
  hyperfixiOnly: boolean;
492
+ /**
493
+ * Custom-element names the markup defines as template components. A
494
+ * component's behavior is its RENDER, which no parse of its snippets can
495
+ * check, so a verifier should instantiate each one.
496
+ */
497
+ componentTags: string[];
477
498
  }
478
499
  /**
479
500
  * Pull every hyperscript source out of `markup`.
@@ -484,12 +505,65 @@ interface MarkupSnippets {
484
505
  * `sse-swap` event names, `ws-connect` URLs) are not hyperscript and carry no
485
506
  * snippet to verify, but they do set `hyperfixiOnly`.
486
507
  *
508
+ * Template components — `<script type="text/hyperscript-template"
509
+ * component="x">` (upstream's form, which upstream's official `component`
510
+ * extension implements and @hyperfixi/components also accepts) and
511
+ * `<template component="x">` — are NOT hyperfixi-only. Their bodies are markup
512
+ * the DOM walk cannot reach (script text; template content), so each is
513
+ * extracted recursively and its `_` sources join `snippets`.
514
+ *
487
515
  * `doc` is any DOM `Document` — a jsdom window's, or the ambient one in a
488
516
  * browser/jsdom test environment. Markup that fails to parse yields no
489
517
  * snippets rather than throwing.
490
518
  */
491
519
  declare function extractHyperscriptFromMarkup(doc: MinimalDocument, markup: string): MarkupSnippets;
492
520
 
521
+ /**
522
+ * Locate and replace the hyperscript bodies inside an HTML-markup corpus row.
523
+ *
524
+ * WHY A REGEX, HERE, DELIBERATELY
525
+ * -------------------------------
526
+ * `html-snippets.ts` warns against regex-scanning HTML — correctly, for its job
527
+ * (walking whole `.html` FILES, where a `<pre>` showing escaped source matches a
528
+ * live attribute). This module has the opposite job: it takes one known-markup
529
+ * corpus row and must splice a translated body back in **without disturbing a
530
+ * single other byte** — indentation, quote style, attribute order, inner text.
531
+ * A DOM round-trip (jsdom `innerHTML`) reserializes all of that, so it is the
532
+ * wrong tool: the corpus stores these rows verbatim and they are compared
533
+ * verbatim. Offsets + splice keeps everything outside the attribute value
534
+ * untouched by construction.
535
+ *
536
+ * Scope: the `_` attribute, double- or single-quoted, which is what the corpus's
537
+ * markup rows carry. A value may contain the OTHER quote character — hyperscript
538
+ * string literals inside a double-quoted attribute are single-quoted, which is
539
+ * how `_="set ^user to {name: 'Demo'}"` is written — so the value class excludes
540
+ * only its own delimiter. (`hx-live` bodies are hyperscript too, but every corpus row
541
+ * using one is flagged non-translatable — its attribute NAMES are resolved
542
+ * per-language by vocab modules, so translating only the body would be half a
543
+ * job.) An attribute whose value contains its own quote character cannot occur
544
+ * in well-formed HTML and is not handled.
545
+ */
546
+ /** One `_="…"` attribute value found in a markup row. */
547
+ interface AttributeSpan {
548
+ /** Offset of the first character of the VALUE (inside the quotes). */
549
+ readonly start: number;
550
+ /** Offset one past the last character of the value. */
551
+ readonly end: number;
552
+ /** The raw attribute value — the hyperscript body. */
553
+ readonly body: string;
554
+ }
555
+ /** Every `_="…"` body in `markup`, in source order. */
556
+ declare function findHyperscriptAttributes(markup: string): AttributeSpan[];
557
+ /**
558
+ * Whether a corpus row is HTML markup rather than hyperscript text.
559
+ *
560
+ * Mirrors testing-framework's `isHtmlMarkupPattern` (top-level hyperscript never
561
+ * begins with `<`; a leading selector literal like `<button/>` is an expression,
562
+ * never a statement start). Kept as its own copy rather than a dependency: this
563
+ * package is upstream of the testing framework in the build order.
564
+ */
565
+ declare function isMarkupRow(code: string): boolean;
566
+
493
567
  /**
494
568
  * @hyperfixi/patterns-reference
495
569
  *
@@ -533,4 +607,4 @@ declare function createPatternsReference(options?: ConnectionOptions): PatternsR
533
607
  */
534
608
  declare const VERSION = "0.1.0";
535
609
 
536
- export { type BehaviorRuntime, Command, ConnectionOptions, DatabasePatternsProvider, Expression, Feature, type IntegrationResult, Keyword, LLMExample, type LLMExampleRecord, LanguageDocsStats, LanguageElement, LanguageElementType, type LoadBehaviorsOptions, type LoadBehaviorsResult, type MarkupSnippets, type PatternEntry, PatternsReference, type PatternsSource, type SemanticIntegrationOptions, SpecialSymbol, VERSION, buildFewShotContextSync, closeDatabase, createLLMAdapter, createPatternsProvider, createPatternsReference, extractHyperscriptFromMarkup, findExamplesByCommand, findRelevantExamples, getAllCommands, getAllExpressions, getAllFeatures, getAllKeywords, getAllSpecialSymbols, getBridgeProvider, getCommandByName, getCurrentDbPath, getDatabase, getDefaultDbPath, getDefaultProvider, getExpressionByName, getExpressionsByCategory, getFeatureByName, getKeywordByName, getLLMExampleStats, getLanguageDocsStats, getSpecialSymbolByName, getSupportedLanguages, initializeSemanticIntegration, isConnected, isDatabaseAvailable, isSemanticIntegrationInitialized, loadBehaviors, queryPatterns, queryPatternsForCommand, resetConnection, resetDefaultProvider, searchCommands, searchLanguageElements, trackExampleUsage, uninitializeSemanticIntegration };
610
+ export { type AttributeSpan, type BehaviorRuntime, Command, ConnectionOptions, DatabasePatternsProvider, EngineCompat, Expression, Feature, type IntegrationResult, Keyword, LLMExample, type LLMExampleRecord, LanguageDocsStats, LanguageElement, LanguageElementType, type LoadBehaviorsOptions, type LoadBehaviorsResult, type MarkupSnippets, type PatternEntry, PatternsReference, type PatternsSource, type SemanticIntegrationOptions, SpecialSymbol, VERSION, buildFewShotContextSync, closeDatabase, createLLMAdapter, createPatternsProvider, createPatternsReference, extractHyperscriptFromMarkup, findExamplesByCommand, findHyperscriptAttributes, findRelevantExamples, getAllCommands, getAllExpressions, getAllFeatures, getAllKeywords, getAllSpecialSymbols, getBridgeProvider, getCommandByName, getCurrentDbPath, getDatabase, getDefaultDbPath, getDefaultProvider, getExpressionByName, getExpressionsByCategory, getFeatureByName, getKeywordByName, getLLMExampleStats, getLanguageDocsStats, getSpecialSymbolByName, getSupportedLanguages, initializeSemanticIntegration, isConnected, isDatabaseAvailable, isMarkupRow, isSemanticIntegrationInitialized, loadBehaviors, queryPatterns, queryPatternsForCommand, resetConnection, resetDefaultProvider, searchCommands, searchLanguageElements, trackExampleUsage, uninitializeSemanticIntegration };
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
- import { C as ConnectionOptions, b as Command, E as Expression, F as Feature, K as Keyword, S as SpecialSymbol, L as LanguageDocsStats, c as LanguageElementType, d as LanguageElement, e as LLMExample, f as PatternsReference } from './index-6GkHj5yJ.js';
2
- export { g as ClassifiedPattern, h as ComplexityLevel, D as DiscoveryResult, i as EngineCompat, j as ExpressionOperator, a as Pattern, k as PatternStats, l as SearchOptions, m as SyncOptions, n as SyncResult, T as TestOptions, o as Translation, p as TranslationMethod, V as ValidationOptions, q as ValidationResult, r as VerificationResult, W as WordOrder } from './index-6GkHj5yJ.js';
1
+ import { C as ConnectionOptions, b as Command, E as Expression, F as Feature, K as Keyword, S as SpecialSymbol, L as LanguageDocsStats, c as LanguageElementType, d as LanguageElement, e as EngineCompat, f as LLMExample, g as PatternsReference } from './index-CoDUfq2P.js';
2
+ export { h as ClassifiedPattern, i as ComplexityLevel, D as DiscoveryResult, j as ExampleOptions, k as ExpressionOperator, a as Pattern, l as PatternStats, m as SearchOptions, n as SyncOptions, o as SyncResult, T as TestOptions, p as Translation, q as TranslationMethod, V as ValidationOptions, r as ValidationResult, s as VerificationResult, W as WordOrder } from './index-CoDUfq2P.js';
3
3
  import Database from 'better-sqlite3';
4
- export { a as addLLMExample, b as buildFewShotContext, g as getAllPatterns, c as getAllTranslations, w as getBehaviorPatterns, d as getExamplesByCommand, e as getHighConfidenceTranslations, f as getHighQualityExamples, h as getLLMExamples, i as getLLMStats, j as getMostUsedExamples, k as getPatternById, l as getPatternStats, m as getPatternsByCategory, n as getPatternsByCommand, o as getTranslation, p as getTranslationStats, q as getTranslationsByLanguage, r as getVerifiedTranslations, s as getWordOrder, t as searchPatterns, u as updateQualityScore, v as verifyTranslation } from './llm-rEdJQScF.js';
4
+ export { a as addLLMExample, b as buildFewShotContext, g as getAllPatterns, c as getAllTranslations, w as getBehaviorPatterns, d as getExamplesByCommand, e as getHighConfidenceTranslations, f as getHighQualityExamples, h as getLLMExamples, i as getLLMStats, j as getMostUsedExamples, k as getPatternById, l as getPatternStats, m as getPatternsByCategory, n as getPatternsByCommand, o as getTranslation, p as getTranslationStats, q as getTranslationsByLanguage, r as getVerifiedTranslations, s as getWordOrder, t as searchPatterns, u as updateQualityScore, v as verifyTranslation } from './llm-CCCSw-yp.js';
5
5
  export { DbStampStatus, checkDbStamp, computeDbInputHash, dbStampPath, discoverPatterns, seedLLMExamples, syncTranslations, validateAllTranslations, writeDbStamp } from './sync/index.js';
6
6
  import '@lokascript/semantic';
7
7
 
@@ -176,6 +176,8 @@ interface LLMExampleRecord {
176
176
  completion: string;
177
177
  language: string;
178
178
  qualityScore: number;
179
+ /** The engine(s) verified to run the example's pattern (never null here). */
180
+ engine: EngineCompat | null;
179
181
  }
180
182
  /**
181
183
  * Check if the database is available for sync operations.
@@ -190,18 +192,24 @@ declare function isDatabaseAvailable(): boolean;
190
192
  * @param prompt - The user's request/prompt
191
193
  * @param language - Target language code (default: 'en')
192
194
  * @param limit - Maximum number of examples to return (default: 5)
195
+ * @param engine - Only examples whose pattern runs on this engine. Examples no
196
+ * engine runs are never returned, with or without it.
193
197
  */
194
- declare function findRelevantExamples(prompt: string, language?: string, limit?: number): LLMExampleRecord[];
198
+ declare function findRelevantExamples(prompt: string, language?: string, limit?: number, engine?: EngineCompat): LLMExampleRecord[];
195
199
  /**
196
200
  * Find examples by command type (sync interface).
197
201
  */
198
- declare function findExamplesByCommand(command: string, language?: string, limit?: number): LLMExampleRecord[];
202
+ declare function findExamplesByCommand(command: string, language?: string, limit?: number, engine?: EngineCompat): LLMExampleRecord[];
199
203
  /**
200
204
  * Build few-shot context (sync interface).
201
205
  */
202
- declare function buildFewShotContextSync(prompt: string, language?: string, numExamples?: number): string;
206
+ declare function buildFewShotContextSync(prompt: string, language?: string, numExamples?: number, engine?: EngineCompat): string;
203
207
  /**
204
208
  * Track example usage (sync interface).
209
+ *
210
+ * @deprecated The counts go into the installed package's own database file,
211
+ * which every install and every `populate` replaces, and only
212
+ * getMostUsedExamples (deprecated with it) reads them. Nothing calls this.
205
213
  */
206
214
  declare function trackExampleUsage(ids: number[]): void;
207
215
  /**
@@ -238,11 +246,12 @@ declare function createLLMAdapter(options?: ConnectionOptions): {
238
246
  trackExampleUsage: typeof trackExampleUsage;
239
247
  getLLMExampleStats: typeof getLLMExampleStats;
240
248
  isDatabaseAvailable: typeof isDatabaseAvailable;
241
- getLLMExamples: (prompt: string, language?: string, limit?: number) => Promise<LLMExample[]>;
242
- getExamplesByCommand: (command: string, language?: string, limit?: number) => Promise<LLMExample[]>;
243
- getHighQualityExamples: (language?: string, minQuality?: number, limit?: number) => Promise<LLMExample[]>;
244
- getMostUsedExamples: (language?: string, limit?: number) => Promise<LLMExample[]>;
245
- buildFewShotContext: (prompt: string, language?: string, numExamples?: number) => Promise<string>;
249
+ getLLMExamples: (prompt: string, language?: string, limit?: number, engine?: EngineCompat) => Promise<LLMExample[]>;
250
+ getExamplesByCommand: (command: string, language?: string, limit?: number, engine?: EngineCompat) => Promise<LLMExample[]>;
251
+ getHighQualityExamples: (language?: string, minQuality?: number, limit?: number, engine?: EngineCompat) => Promise<LLMExample[]>;
252
+ /** @deprecated See getMostUsedExamples. */
253
+ getMostUsedExamples: (language?: string, limit?: number, engine?: EngineCompat) => Promise<LLMExample[]>;
254
+ buildFewShotContext: (prompt: string, language?: string, numExamples?: number, engine?: EngineCompat) => Promise<string>;
246
255
  getLLMStats: () => Promise<{
247
256
  total: number;
248
257
  byLanguage: Record<string, number>;
@@ -456,6 +465,8 @@ interface MinimalElement {
456
465
  tagName: string;
457
466
  attributes: ArrayLike<MinimalAttr>;
458
467
  textContent: string | null;
468
+ /** Read only on `<template>`, whose content `querySelectorAll` cannot reach. */
469
+ innerHTML?: string;
459
470
  getAttribute(name: string): string | null;
460
471
  }
461
472
  interface MinimalContainer extends MinimalElement {
@@ -466,7 +477,11 @@ interface MinimalDocument {
466
477
  createElement(tagName: string): MinimalContainer;
467
478
  }
468
479
  interface MarkupSnippets {
469
- /** Every hyperscript source found, in document order. */
480
+ /**
481
+ * Every hyperscript source found, in document order — including the `_`
482
+ * attributes inside component template bodies, which run once the
483
+ * component renders.
484
+ */
470
485
  snippets: string[];
471
486
  /**
472
487
  * The markup uses at least one attribute upstream `_hyperscript` has no
@@ -474,6 +489,12 @@ interface MarkupSnippets {
474
489
  * how its snippets parse.
475
490
  */
476
491
  hyperfixiOnly: boolean;
492
+ /**
493
+ * Custom-element names the markup defines as template components. A
494
+ * component's behavior is its RENDER, which no parse of its snippets can
495
+ * check, so a verifier should instantiate each one.
496
+ */
497
+ componentTags: string[];
477
498
  }
478
499
  /**
479
500
  * Pull every hyperscript source out of `markup`.
@@ -484,12 +505,65 @@ interface MarkupSnippets {
484
505
  * `sse-swap` event names, `ws-connect` URLs) are not hyperscript and carry no
485
506
  * snippet to verify, but they do set `hyperfixiOnly`.
486
507
  *
508
+ * Template components — `<script type="text/hyperscript-template"
509
+ * component="x">` (upstream's form, which upstream's official `component`
510
+ * extension implements and @hyperfixi/components also accepts) and
511
+ * `<template component="x">` — are NOT hyperfixi-only. Their bodies are markup
512
+ * the DOM walk cannot reach (script text; template content), so each is
513
+ * extracted recursively and its `_` sources join `snippets`.
514
+ *
487
515
  * `doc` is any DOM `Document` — a jsdom window's, or the ambient one in a
488
516
  * browser/jsdom test environment. Markup that fails to parse yields no
489
517
  * snippets rather than throwing.
490
518
  */
491
519
  declare function extractHyperscriptFromMarkup(doc: MinimalDocument, markup: string): MarkupSnippets;
492
520
 
521
+ /**
522
+ * Locate and replace the hyperscript bodies inside an HTML-markup corpus row.
523
+ *
524
+ * WHY A REGEX, HERE, DELIBERATELY
525
+ * -------------------------------
526
+ * `html-snippets.ts` warns against regex-scanning HTML — correctly, for its job
527
+ * (walking whole `.html` FILES, where a `<pre>` showing escaped source matches a
528
+ * live attribute). This module has the opposite job: it takes one known-markup
529
+ * corpus row and must splice a translated body back in **without disturbing a
530
+ * single other byte** — indentation, quote style, attribute order, inner text.
531
+ * A DOM round-trip (jsdom `innerHTML`) reserializes all of that, so it is the
532
+ * wrong tool: the corpus stores these rows verbatim and they are compared
533
+ * verbatim. Offsets + splice keeps everything outside the attribute value
534
+ * untouched by construction.
535
+ *
536
+ * Scope: the `_` attribute, double- or single-quoted, which is what the corpus's
537
+ * markup rows carry. A value may contain the OTHER quote character — hyperscript
538
+ * string literals inside a double-quoted attribute are single-quoted, which is
539
+ * how `_="set ^user to {name: 'Demo'}"` is written — so the value class excludes
540
+ * only its own delimiter. (`hx-live` bodies are hyperscript too, but every corpus row
541
+ * using one is flagged non-translatable — its attribute NAMES are resolved
542
+ * per-language by vocab modules, so translating only the body would be half a
543
+ * job.) An attribute whose value contains its own quote character cannot occur
544
+ * in well-formed HTML and is not handled.
545
+ */
546
+ /** One `_="…"` attribute value found in a markup row. */
547
+ interface AttributeSpan {
548
+ /** Offset of the first character of the VALUE (inside the quotes). */
549
+ readonly start: number;
550
+ /** Offset one past the last character of the value. */
551
+ readonly end: number;
552
+ /** The raw attribute value — the hyperscript body. */
553
+ readonly body: string;
554
+ }
555
+ /** Every `_="…"` body in `markup`, in source order. */
556
+ declare function findHyperscriptAttributes(markup: string): AttributeSpan[];
557
+ /**
558
+ * Whether a corpus row is HTML markup rather than hyperscript text.
559
+ *
560
+ * Mirrors testing-framework's `isHtmlMarkupPattern` (top-level hyperscript never
561
+ * begins with `<`; a leading selector literal like `<button/>` is an expression,
562
+ * never a statement start). Kept as its own copy rather than a dependency: this
563
+ * package is upstream of the testing framework in the build order.
564
+ */
565
+ declare function isMarkupRow(code: string): boolean;
566
+
493
567
  /**
494
568
  * @hyperfixi/patterns-reference
495
569
  *
@@ -533,4 +607,4 @@ declare function createPatternsReference(options?: ConnectionOptions): PatternsR
533
607
  */
534
608
  declare const VERSION = "0.1.0";
535
609
 
536
- export { type BehaviorRuntime, Command, ConnectionOptions, DatabasePatternsProvider, Expression, Feature, type IntegrationResult, Keyword, LLMExample, type LLMExampleRecord, LanguageDocsStats, LanguageElement, LanguageElementType, type LoadBehaviorsOptions, type LoadBehaviorsResult, type MarkupSnippets, type PatternEntry, PatternsReference, type PatternsSource, type SemanticIntegrationOptions, SpecialSymbol, VERSION, buildFewShotContextSync, closeDatabase, createLLMAdapter, createPatternsProvider, createPatternsReference, extractHyperscriptFromMarkup, findExamplesByCommand, findRelevantExamples, getAllCommands, getAllExpressions, getAllFeatures, getAllKeywords, getAllSpecialSymbols, getBridgeProvider, getCommandByName, getCurrentDbPath, getDatabase, getDefaultDbPath, getDefaultProvider, getExpressionByName, getExpressionsByCategory, getFeatureByName, getKeywordByName, getLLMExampleStats, getLanguageDocsStats, getSpecialSymbolByName, getSupportedLanguages, initializeSemanticIntegration, isConnected, isDatabaseAvailable, isSemanticIntegrationInitialized, loadBehaviors, queryPatterns, queryPatternsForCommand, resetConnection, resetDefaultProvider, searchCommands, searchLanguageElements, trackExampleUsage, uninitializeSemanticIntegration };
610
+ export { type AttributeSpan, type BehaviorRuntime, Command, ConnectionOptions, DatabasePatternsProvider, EngineCompat, Expression, Feature, type IntegrationResult, Keyword, LLMExample, type LLMExampleRecord, LanguageDocsStats, LanguageElement, LanguageElementType, type LoadBehaviorsOptions, type LoadBehaviorsResult, type MarkupSnippets, type PatternEntry, PatternsReference, type PatternsSource, type SemanticIntegrationOptions, SpecialSymbol, VERSION, buildFewShotContextSync, closeDatabase, createLLMAdapter, createPatternsProvider, createPatternsReference, extractHyperscriptFromMarkup, findExamplesByCommand, findHyperscriptAttributes, findRelevantExamples, getAllCommands, getAllExpressions, getAllFeatures, getAllKeywords, getAllSpecialSymbols, getBridgeProvider, getCommandByName, getCurrentDbPath, getDatabase, getDefaultDbPath, getDefaultProvider, getExpressionByName, getExpressionsByCategory, getFeatureByName, getKeywordByName, getLLMExampleStats, getLanguageDocsStats, getSpecialSymbolByName, getSupportedLanguages, initializeSemanticIntegration, isConnected, isDatabaseAvailable, isMarkupRow, isSemanticIntegrationInitialized, loadBehaviors, queryPatterns, queryPatternsForCommand, resetConnection, resetDefaultProvider, searchCommands, searchLanguageElements, trackExampleUsage, uninitializeSemanticIntegration };