@lingfan-engine/core 0.1.4 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingfan-engine/core",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "module",
   "description": "灵泛叙事引擎核心：框架无关的叙事语义（格式/执行/回溯/作用域/存档编排）",
   "license": "Apache-2.0",

package/src/contracts/runtime/reader.ts

@@ -38,6 +38,17 @@ export interface MenuChoice {
   target: string;
 }
 
+/**
+ * 输入候选：显示文本与要填进变量的值成对（数组顺序即呈现顺序）。
+ *
+ * 与 `MenuChoice` 分开定义：候选是「替玩家填一个值」，不是「跳到另一列」，
+ * 字段名不同是刻意的——把两者混用会在多语言环境下把译文写进变量。
+ */
+export interface InputCandidate {
+  text: string;
+  value: string;
+}
+
 /**
  * 类型化读口：按用途分组读状态。
  *
@@ -53,6 +64,8 @@ export interface StateReader {
   videoCommand(): VideoCommand | null;
   /** 菜单选项（文本与目标列成对；两键分属不同状态条目，任一畸形都按空处理） */
   menuChoices(): MenuChoice[];
+  /** 输入候选（显示文本与要填的值成对；缺省或形状不合 = 空数组，界面只渲染输入框） */
+  inputCandidates(): InputCandidate[];
   /** 当前说话人（缺省空串） */
   dialogSpeaker(): string;
   /** 当前正文（缺省空串） */

package/src/contracts/runtime/state-keys.ts

@@ -36,6 +36,14 @@ export const SYS = {
   menuTargets: "__menu_targets",
   menuSelected: "__menu_selected",
   inputPrompt: "__input_prompt",
+  /**
+   * 输入等待的**候选快捷值**（`input options=[…]` 写入）：`{ text, value }[]`。
+   *
+   * 语义：玩家既可以点候选（把该项 `value` 直接当输入值提交），也可以自己打字。
+   * 与 `menuOptions` 分开存，因为两者字段不同（候选是「替玩家填值」不是「跳列」），
+   * 混用一个键会让读口无法判断该按哪种形状解析。缺省 = 无候选。
+   */
+  inputOptions: "__input_options",
   rollbackActive: "__rollback_active",
   /** I18N 当前语言（setLanguage 命令写入，空串 = 默认语言/原文直出） */
   currentLanguage: "__current_language",

package/src/data/format/validate/dialog.ts

@@ -6,6 +6,37 @@ import { requireNonEmptyString } from "../guards.ts";
 import { validateInstanceZ } from "./shape.ts";
 import { isPlainObject } from "../../../shared/index.ts";
 
+/**
+ * `input.options` 的候选快捷值：`{ text, value }[]`，每项两字段都必填非空。
+ *
+ * 形态选 `text` + `value` 而非 `string[]` 或 menu 的 `{text, target}`：
+ * - `text` 进翻译表（多语言只译显示文本），`value` 原样写进 `store`——若用 `string[]`，
+ *   译文会被写进变量，多语言环境下故事逻辑跟着语言漂移；
+ * - 与 `menu` 的 `{text, target}` 区分开：input 的候选是「替玩家填一个值」，
+ *   不是「跳到另一列」，两者语义不同，不共用字段名以免误用。
+ *
+ * 缺省（字段不存在）= 无候选，只有输入框；空数组与 menu 不同**不算错**（等于没写）。
+ */
+function validateInputOptions(
+  options: unknown,
+  at: string,
+  issues: string[],
+): void {
+  if (options === undefined) return;
+  if (!Array.isArray(options)) {
+    issues.push(`${at} 必须为数组`);
+    return;
+  }
+  for (const [i, option] of options.entries()) {
+    if (!isPlainObject(option)) {
+      issues.push(`${at}[${i}] 必须为对象`);
+      continue;
+    }
+    requireNonEmptyString(option.text, `${at}[${i}].text`, issues);
+    requireNonEmptyString(option.value, `${at}[${i}].value`, issues);
+  }
+}
+
 /**
  * 校验本族 op 的负载（7 个 op：`say` `assert` `guard` `notify` `wait` `pause` `input`）。
  *
@@ -59,9 +90,7 @@ export function validateDialogCommand(
     case "input":
       requireNonEmptyString(cmd.prompt, `${at}.prompt`, issues);
       requireNonEmptyString(cmd.store, `${at}.store`, issues);
-      if (cmd.options !== undefined) {
-        issues.push(`${at}.options 选项式输入暂未实现（fail-closed）`);
-      }
+      validateInputOptions(cmd.options, `${at}.options`, issues);
       validateInstanceZ(cmd, at, issues); // input 的实例 z（choices 层）
       break;
   }

package/src/data/text/generate/command/dialog.ts

@@ -1,5 +1,9 @@
 /** dialog 族的文本投影。 */
-import { quoteForText, instanceZText } from "../../literals.ts";
+import {
+  quoteForText,
+  instanceZText,
+  generateInputOptions,
+} from "../../literals.ts";
 import type { StoryCommand } from "../../../../contracts/index.ts";
 import type { GenerateContext } from "../context.ts";
 
@@ -51,11 +55,19 @@ export function generateDialogCommand(
     case "pause":
       out.push(`${pad}pause ${cmd.seconds}`);
       return;
-    case "input":
+    case "input": {
+      // 候选数组内部含空格与引号，必须整体投影成一行内联字面量（解析侧同法整体摘取）
+      const candidates = cmd.options as
+        Array<{ text: string; value: string }> | undefined;
+      const optionsText =
+        Array.isArray(candidates) && candidates.length > 0
+          ? ` options=${generateInputOptions(candidates)}`
+          : "";
       out.push(
-        `${pad}input ${quoteForText(cmd.prompt as string)} store=${quoteForText(cmd.store as string)}${instanceZText(cmd)}`,
+        `${pad}input ${quoteForText(cmd.prompt as string)} store=${quoteForText(cmd.store as string)}${optionsText}${instanceZText(cmd)}`,
       );
       return;
+    }
     case "nvl": {
       const mode = (cmd.mode as string | undefined) ?? "enter";
       out.push(

package/src/data/text/literals.ts

@@ -110,6 +110,146 @@ export function extractKeyedDictLiteral(
   };
 }
 
+/**
+ * 提取 `key=[…]` 形式的数组字面量（方括号计数，引号内的括号不算）。
+ *
+ * 与 `extractKeyedDictLiteral` 同法，只是括号类型不同；`key` 只认**字符串外**且前面是空白
+ * 或行首的那一处（避免提示语里恰好出现 `options=` 被误当参数）。
+ * 返回字面量与剥离后的余文；找不到或不闭合返回 `null`。
+ */
+export function extractKeyedArrayLiteral(
+  source: string,
+  key: string,
+): { literal: string; remainder: string } | null {
+  const at = findKeyOutsideString(source, key);
+  if (at < 0) return null;
+  const bracketAt = source.indexOf("[", at + key.length + 1);
+  if (bracketAt < 0) return null;
+  let depth = 0;
+  let end = -1;
+  let inString = false;
+  for (let i = bracketAt; i < source.length; i += 1) {
+    const ch = source[i]!;
+    if (inString) {
+      if (ch === "\\") {
+        i += 1;
+        continue;
+      }
+      if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+    if (ch === "[") depth += 1;
+    else if (ch === "]") {
+      depth -= 1;
+      if (depth === 0) {
+        end = i;
+        break;
+      }
+    }
+  }
+  if (end < 0) return null;
+  return {
+    literal: source.slice(bracketAt, end + 1),
+    remainder: `${source.slice(0, at)} ${source.slice(end + 1)}`,
+  };
+}
+
+/** 找 `key=` 在字符串外、且位于行首或空白之后的位置；找不到返回 -1 */
+function findKeyOutsideString(source: string, key: string): number {
+  let inString = false;
+  for (let i = 0; i < source.length; i += 1) {
+    const ch = source[i]!;
+    if (inString) {
+      if (ch === "\\") {
+        i += 1;
+        continue;
+      }
+      if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+    if (
+      source.startsWith(`${key}=`, i) &&
+      (i === 0 || /\s/.test(source[i - 1]!))
+    ) {
+      return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * `[{"text": …, "value": …}, …]` 数组字面量 → 输入候选表。
+ *
+ * 与 `generateInputOptions` 严格互逆（往返字节级一致）；字段不是字符串的项原样保留为
+ * `undefined` 之外的空串，交由校验层报错——解析器不替作者猜。
+ */
+export function parseInputOptionsLiteral(
+  raw: string,
+): Array<{ text: string; value: string }> {
+  const inner = raw.trim().replace(/^\[/, "").replace(/\]$/, "");
+  const parts: string[] = [];
+  let cur = "";
+  let inString = false;
+  let depth = 0;
+  for (let i = 0; i < inner.length; i += 1) {
+    const ch = inner[i]!;
+    if (inString) {
+      cur += ch;
+      if (ch === "\\") {
+        cur += inner[i + 1] ?? "";
+        i += 1;
+        continue;
+      }
+      if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      cur += ch;
+      continue;
+    }
+    if (ch === "{") depth += 1;
+    if (ch === "}") depth -= 1;
+    if (ch === "," && depth === 0) {
+      if (cur.trim() !== "") parts.push(cur);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  if (cur.trim() !== "") parts.push(cur);
+  return parts.map((part) => {
+    const dict = parseDictLiteral(part);
+    return {
+      text: typeof dict.text === "string" ? dict.text : "",
+      value: typeof dict.value === "string" ? dict.value : "",
+    };
+  });
+}
+
+/**
+ * 输入候选表的文本投影：`[{"text": "…", "value": "…"}, …]`。
+ *
+ * 与 `parseInputOptionsLiteral` 严格互逆；每项经 `generateDictLiteral`（键序 text → value，
+ * 插入序确定，故同一份数据两次投影字节相同）。
+ */
+export function generateInputOptions(
+  options: readonly { text: string; value: string }[],
+): string {
+  const items = options.map((item) =>
+    generateDictLiteral({ text: item.text, value: item.value }),
+  );
+  return `[${items.join(", ")}]`;
+}
+
 /** {"f":v} 字典字面量 → 对象（字段值走 parseValueLiteral 语义） */
 export function parseDictLiteral(raw: string): Record<string, unknown> {
   const inner = raw.trim().replace(/^\{/, "").replace(/\}$/, "");

package/src/data/text/parse/statement/dialog.ts

@@ -1,6 +1,10 @@
 /** dialog 族的读向解析。 */
 import { parseSay } from "../say.ts";
 import { unquote } from "../../lexer.ts";
+import {
+  extractKeyedArrayLiteral,
+  parseInputOptionsLiteral,
+} from "../../literals.ts";
 import type { StoryCommand } from "../../../../contracts/index.ts";
 import type { StatementContext } from "../state.ts";
 
@@ -89,6 +93,21 @@ export function parseDialogStatement(c: StatementContext): StoryCommand | null {
         prompt: unquote(prompt),
         store: unquote(storeEq.slice(6)),
       };
+      // 候选快捷值：`input "提示" store="k" options=[{"text": "…", "value": "…"}]`
+      // 从整行里摘（不能只搜 token——数组内部有空格，会被切词拆散）
+      const optionsLiteral = extractKeyedArrayLiteral(rest, "options");
+      if (optionsLiteral !== null) {
+        const candidates = parseInputOptionsLiteral(optionsLiteral.literal);
+        // 缺字段的项在字面量层会落成空串；这里补一条带定位的 issue，
+        // 不让它悄悄变成「点了候选写入空值」（与 JSON 侧的 requireNonEmptyString 同口径）
+        const broken = candidates.findIndex(
+          (item) => item.text === "" || item.value === "",
+        );
+        if (broken >= 0) {
+          return fail(`input 候选 options[${broken}] 需要 text 与 value`);
+        }
+        cmd.options = candidates;
+      }
       const zEq = tokens.find(
         (t) => t.startsWith("z=") || t.startsWith("z-index="),
       );

package/src/runtime/ops/interaction.ts

@@ -26,7 +26,13 @@ const INTERACTION_FIELDS = new Set([
   "z", // 实例级 z（与 minigame 同层：外部系统整屏接管）
 ]);
 
-/** input（prompt + store）→ 进入 input 等待；options 选项式输入延后（解析层拒绝） */
+/**
+ * input（prompt + store，可选 options 候选）→ 进入 input 等待。
+ *
+ * 候选值 `{ text, value }[]`：`text` 走翻译表（显示），`value` 原样进状态（玩家点选后
+ * 由命令面按普通输入提交）。没有候选时也写一个空数组，**不能跳过**——否则上一次输入
+ * 留下的候选会被这一轮读到（状态是跨命令持久的）。
+ */
 export function execInput(
   ctx: OpContext,
   frame: Frame,
@@ -41,6 +47,13 @@ export function execInput(
     SYS.inputPrompt,
     typeof cmd.prompt === "string" ? ctx.translate(cmd.prompt) : "",
   );
+  const candidates = Array.isArray(cmd.options)
+    ? (cmd.options as Array<{ text: string; value: string }>).map((o) => ({
+        text: ctx.translate(o.text),
+        value: o.value,
+      }))
+    : [];
+  ctx.setSystem(SYS.inputOptions, candidates);
   ctx.inputStore = cmd.store as string;
   ctx.setInstanceZ(SYS.choicesZ, cmd.z); // 输入形态的实例 z（choices 层）
   ctx.setSystem(SYS.waiting, "input");

package/src/runtime/state/reader.ts

@@ -14,6 +14,7 @@ import {
   type AudioChannel,
   type AudioChannelState,
   type ElementInstance,
+  type InputCandidate,
   type LayerId,
   type LayerZOverrides,
   type MenuChoice,
@@ -159,6 +160,20 @@ export function createStateReader(source: StateSource): StateReader {
       }));
     },
 
+    inputCandidates(): InputCandidate[] {
+      // 候选是单条目里的对象数组：畸形项整项丢弃（不猜字段），全部丢弃即等于「无候选」
+      const raw = get(SYS.inputOptions);
+      if (!Array.isArray(raw)) return [];
+      const out: InputCandidate[] = [];
+      for (const item of raw) {
+        if (item === null || typeof item !== "object") continue;
+        const { text, value } = item as { text?: unknown; value?: unknown };
+        if (typeof text !== "string" || typeof value !== "string") continue;
+        out.push({ text, value });
+      }
+      return out;
+    },
+
     dialogSpeaker(): string {
       return textOf(get(SYS.currentDialogSpeaker));
     },