@lokascript/framework 4.7.0 → 4.8.0

package/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.8.0] - 2026-10-16
+
+### Added
+
+- **`@lokascript/intent` / `@lokascript/framework`: a role's word list, `RoleSpec.words`** (domains
+  rethink Phase 5). Per language, with `'*'` for every language; the core engine (`engine: 'core'`)
+  reads such a slot only from one of its words, compared lower-cased, so a word the grammar does not
+  know is left unread and the input refused, instead of read as the value. It is for a domain's fixed
+  words: behaviorspec's `when clicks zzqx` read actor `clicks`, action `zzqx`, and compiled to a
+  comment. The schema-pattern generator carries the pattern language's list on the role token
+  (`RolePatternToken.words`); a grammar that lists no words generates the same patterns. The classic
+  engine and semantic ignore it.
+- **`@lokascript/framework/testing/gate`: `GateFixture.commands`**, commands the gate writes besides
+  the generated ones, where one role's value depends on another's (behaviorspec's
+  `[given subject:#box value:visible]` beside `[given subject:viewport value:1024x768]`).
+- **`@lokascript/framework`: `UnreadInputError.hint`.** Where the last word a parse read as a value is
+  followed by another bare word, the refusal adds `if "buy milk" is one value, quote it` (todo's
+  `add buy milk to groceries`, whose item is quoted).
+
+### Changed
+
+- **`@lokascript/framework/testing/gate`: leftover input read into a role is `pass`.** An unknown word
+  after a command used to be `silent` wherever the parse accepted it. It is `pass` when the parse is
+  the text's own with the word in one role (an open-text role extended by it, sql's
+  `where active zzqx`, or a role the text left empty, todo's `list zzqx`) and the word reaches the
+  compiled code; `refused` when the input stops compiling; `silent` otherwise (read as something
+  else, or the word goes nowhere). `readsWord` is exported. On the domains (domains 4.1.0, this
+  framework packed): 74 leftover cases accepted → read, 0 worse, 0 parses moved.
+- **`@lokascript/framework`: the stock reader's optional slot does not read a marker the rest of the
+  pattern owes**, through its optional groups, as a required slot already does not read the marker
+  next to it (behaviorspec's `when user types into #search`, whose typed text is optional and has no
+  marker). No domain parse moves.
+
 ## [4.7.0] - 2026-10-16
 
 ### Added
@@ -1821,7 +1854,8 @@ _Synchronized version release. See git history for details._
 - npm access token stored in GitHub Secrets
 - 2FA recommended for npm organization
 
-[Unreleased]: https://github.com/codetalcott/hyperfixi/compare/v4.7.0...HEAD
+[Unreleased]: https://github.com/codetalcott/hyperfixi/compare/v4.8.0...HEAD
+[4.8.0]: https://github.com/codetalcott/hyperfixi/compare/v4.7.0...v4.8.0
 [4.7.0]: https://github.com/codetalcott/hyperfixi/compare/v4.6.0...v4.7.0
 [4.6.0]: https://github.com/codetalcott/hyperfixi/compare/v4.5.0...v4.6.0
 [4.5.0]: https://github.com/codetalcott/hyperfixi/compare/v4.4.0...v4.5.0

package/dist/api/create-dsl.d.ts

@@ -178,15 +178,18 @@ export interface CompileResult {
 /**
  * Thrown by `parse` (and so `compile`, `validate`, `translate`) when the input reads as a command
  * only by leaving some of it unread: `select name from users banana` is not `select name from users`.
- * `reading` is what the longest such match read, `unread` the text after it.
+ * `reading` is what the longest such match read, `unread` the text after it. `hint`, when there is
+ * one, says how the input might read: where a bare word read as a value is followed by another, the
+ * two may be one value written without quotes (todo `add buy milk to groceries`).
  */
 export declare class UnreadInputError extends Error {
     readonly input: string;
     readonly language: string;
     readonly reading: SemanticNode;
     readonly unread: string;
+    readonly hint?: string | undefined;
     readonly code = "unread-input";
-    constructor(input: string, language: string, reading: SemanticNode, unread: string);
+    constructor(input: string, language: string, reading: SemanticNode, unread: string, hint?: string | undefined);
 }
 /** Options for `translate`. */
 export interface TranslateOptions {

package/dist/api/create-dsl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-dsl.d.ts","sourceRoot":"","sources":["../../src/api/create-dsl.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"create-dsl.d.ts","sourceRoot":"","sources":["../../src/api/create-dsl.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,YAAY,EAEZ,iBAAiB,EACjB,eAAe,EAIhB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG/C,OAAO,EAAmB,KAAK,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAClG,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAMnF,OAAO,EAAsB,KAAK,eAAe,IAAI,cAAc,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EACL,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,cAAc,EAGpB,MAAM,eAAe,CAAC;AAKvB;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,8CAA8C;IAC9C,QAAQ,CAAC,cAAc,EAAE,yBAAyB,CAAC;IACnD;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAAC;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;IAChE;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,yBAAyB,CAAC,aAAa,CAAC,CAAC;CACjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,eAAe;IAC9B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAEnE,sFAAsF;IACtF,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC;IAEjC,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,MAAM,CAAC;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAE3C,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IAI9C,gFAAgF;IAChF,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IAEjC,yFAAyF;IACzF,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAE3C,sEAAsE;IACtE,QAAQ,CAAC,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IAE5C,qDAAqD;IACrD,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAEnC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IAIjD,0DAA0D;IAC1D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAEpC,mDAAmD;IACnD,QAAQ,CAAC,cAAc,CAAC,EAAE,eAAe,EAAE,CAAC;IAE5C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,gGAAgG;IAChG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,gGAAgG;IAChG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;CACH;AAED;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAIvC,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,OAAO,EAAE,YAAY;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;IAPxB,QAAQ,CAAC,IAAI,kBAAkB;gBAGpB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,YAAA;CAQzB;AAED,+BAA+B;AAC/B,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CACrC;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IAI/C,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,QAAQ,CAAC,MAAM,EAAE,YAAY;IAC7B,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM;IARtB,QAAQ,CAAC,IAAI,oCAAoC;gBAGtC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,YAAY,GAAG,IAAI,EAC5B,GAAG,EAAE,MAAM;CAKvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAE9B,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC;IACrD,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,YAAY,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAGjG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAG5D,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CAAC;IAGxD;;;;OAIG;IACH,SAAS,CACP,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,MAAM,CAAC;IAEV;;;;;;;OAOG;IACH,MAAM,CAAC,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAG7D,qBAAqB,IAAI,MAAM,EAAE,CAAC;CACnC;AA0hBD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,eAAe,CAsBxE"}

package/dist/api/index.js

@@ -1547,6 +1547,11 @@ function readGreedy(tokens, stopMarkers) {
   }
   return values.length > 0 ? { type: "expression", raw: values.join(" ") } : null;
 }
+function isListedWord(token, words) {
+  if (!token) return false;
+  const forms = [token.value, token.normalized].filter((f) => typeof f === "string");
+  return forms.some((form) => words.some((word) => word.toLowerCase() === form.toLowerCase()));
+}
 var StockValueReader = class {
   constructor(view, profiles = {}) {
     this.view = view;
@@ -1579,6 +1584,11 @@ var StockValueReader = class {
       const token = tokens.peek();
       if (token && this.view.wouldMatch(next, token)) return false;
     }
+    if (slot.words && !isListedWord(tokens.peek(), slot.words)) return slot.optional ?? false;
+    if (slot.optional && !slot.greedy) {
+      const token = tokens.peek();
+      if (token && isStopMarker(token, greedyStopMarkers(this.view.patternRest()))) return true;
+    }
     if (slot.greedy) {
       const value = readGreedy(tokens, greedyStopMarkers(this.view.patternRest()));
       if (value) {
@@ -1968,11 +1978,13 @@ function generateVerbFirstPattern(schema, profile, config = defaultConfig2) {
   const verbToken = keyword.alternatives ? { type: "literal", value: keyword.primary, alternatives: keyword.alternatives } : { type: "literal", value: keyword.primary };
   const roleTokens = requiredRoles.flatMap((r) => {
     const prefix = r.valuePrefixLiteral?.[profile.code];
+    const words = wordsFor(r, profile.code);
     const roleToken = {
       type: "role",
       role: r.role,
       optional: false,
-      expectedTypes: r.expectedTypes
+      expectedTypes: r.expectedTypes,
+      ...words ? { words } : {}
     };
     return prefix ? [{ type: "literal", value: prefix }, roleToken] : [roleToken];
   });
@@ -2142,11 +2154,17 @@ function buildRoleTokens(grammar, schema, profile) {
   }
   return tokens;
 }
+function wordsFor(roleSpec, language) {
+  if (!roleSpec.words) return void 0;
+  const words = [...roleSpec.words["*"] ?? [], ...roleSpec.words[language] ?? []];
+  return words.length > 0 ? words : void 0;
+}
 function buildRoleToken(roleSpec, profile) {
   const tokens = [];
   const overrideMarker = roleSpec.markerOverride?.[profile.code];
   const defaultMarker = profile.roleMarkers[roleSpec.role];
   const suppressMarker = roleSpec.renderOverride?.[profile.code] === "";
+  const words = wordsFor(roleSpec, profile.code);
   const roleValueToken = {
     type: "role",
     role: roleSpec.role,
@@ -2158,7 +2176,9 @@ function buildRoleToken(roleSpec, profile) {
     ...roleSpec.valueShape !== void 0 ? { valueShape: roleSpec.valueShape } : {},
     // A greedy role reads up to the next marker the pattern owes (a domain's
     // SQL condition); its value reader does the reading.
-    ...roleSpec.greedy ? { greedy: true } : {}
+    ...roleSpec.greedy ? { greedy: true } : {},
+    // A role with a word list reads only one of its words.
+    ...words ? { words } : {}
   };
   const prefixLiteral = roleSpec.valuePrefixLiteral?.[profile.code];
   const pushPrefixed = () => {
@@ -2683,12 +2703,15 @@ function readingDifference(source, back) {
 
 // src/api/create-dsl.ts
 var UnreadInputError = class extends Error {
-  constructor(input, language, reading, unread) {
-    super(`"${input}" (${language}) reads as ${reading.action} only by leaving "${unread}" unread`);
+  constructor(input, language, reading, unread, hint) {
+    super(
+      `"${input}" (${language}) reads as ${reading.action} only by leaving "${unread}" unread` + (hint ? `; ${hint}` : "")
+    );
     this.input = input;
     this.language = language;
     this.reading = reading;
     this.unread = unread;
+    this.hint = hint;
     this.code = "unread-input";
     this.name = "UnreadInputError";
   }
@@ -2807,15 +2830,32 @@ var MultilingualDSLImpl = class {
     }
     if (longestPartial) {
       const unread = tokens.tokens.slice(longestPartial.consumedTokens).map((t) => t.value).join(" ");
+      const hint = this.quoteHint(longestPartial, tokens.tokens);
       throw new UnreadInputError(
         input,
         language,
         this.nodeOf(longestPartial, input, language),
-        unread
+        unread,
+        ...hint ? [hint] : []
       );
     }
     throw new Error(`No pattern matched for input: ${input}`);
   }
+  /**
+   * `if "buy milk" is one value, quote it`, where the last token a match read is a bare word it took
+   * as a role's value (a role with no word list) and the first it left is a bare word too.
+   */
+  quoteHint(match, tokens) {
+    const last = tokens[match.consumedTokens - 1];
+    const next = tokens[match.consumedTokens];
+    if (last?.kind !== "identifier" || next?.kind !== "identifier") return void 0;
+    const schema = this.schemaLookup.getSchema(match.pattern.command);
+    const role = [...match.captured].find(
+      ([, v]) => v.raw === last.value
+    )?.[0];
+    if (!role || schema?.roles.find((r) => r.role === role)?.words) return void 0;
+    return `if "${last.value} ${next.value}" is one value, quote it`;
+  }
   nodeOf(match, input, language) {
     return {
       kind: "command",