@lingfan-engine/shell 0.0.0-stage → 0.1.0

package/src/panel/history.ts

@@ -0,0 +1,70 @@
+/**
+ * 历史面板的数据整形：引擎给出的历史条目 → 可直接渲染的块列表。
+ *
+ * 连续 NVL 条目聚合成一个块——玩家所见本来就是整块累积画面，块级回溯 =
+ * 回到「块尾检查点」（整块可见的时刻，检查点语义的自然延伸）；buffer 收缩
+ * （nvl clear）即分段。回溯粒度不减：逐检查点仍全在历史里，只是呈现聚合。
+ *
+ * 本模块平台无关：不触碰任何框架、DOM 或宿主全局。
+ */
+
+/** 一条历史条目（引擎 `historyView` 的行） */
+export interface HistoryEntry {
+  /** 回溯目标：引擎检查点序号 */
+  index: number;
+  /** 说话人（空串 = 无） */
+  speaker: string;
+  /** 正文（非 NVL 模式下的一行） */
+  text: string;
+  /** 是否 NVL 累积模式下的行 */
+  nvl: boolean;
+  /** NVL 模式下的整块行（回溯目标为块尾） */
+  nvlLines: string[];
+}
+
+/** 呈现块：连续 NVL 聚合后的一行 */
+export interface HistoryBlock {
+  /** 块首条目 index（稳定，避免重建） */
+  key: string;
+  /** 回溯目标 = 块尾检查点 */
+  index: number;
+  speaker: string;
+  /** 该块要显示的正文行 */
+  lines: string[];
+  nvl: boolean;
+}
+
+/** 丢掉说话人与正文都空的行（不构成一次可回溯的呈现） */
+export function filterHistoryEntries(
+  entries: readonly HistoryEntry[],
+): HistoryEntry[] {
+  return entries.filter((h) => h.text !== "" || h.speaker !== "");
+}
+
+/** 把历史条目聚合成呈现块 */
+export function buildHistoryBlocks(
+  entries: readonly HistoryEntry[],
+): HistoryBlock[] {
+  const blocks: HistoryBlock[] = [];
+  for (const entry of entries) {
+    const prev = blocks[blocks.length - 1];
+    // 同段延续：块尾推进为最新检查点；行数变少说明 buffer 已收缩（分段）
+    if (
+      entry.nvl &&
+      prev?.nvl === true &&
+      entry.nvlLines.length >= prev.lines.length
+    ) {
+      prev.index = entry.index;
+      prev.lines = entry.nvlLines;
+      continue;
+    }
+    blocks.push({
+      key: `blk-${entry.index}`,
+      index: entry.index,
+      speaker: entry.speaker,
+      lines: entry.nvl ? [...entry.nvlLines] : [entry.text],
+      nvl: entry.nvl,
+    });
+  }
+  return blocks;
+}

package/src/panel/index.ts

@@ -0,0 +1,10 @@
+/**
+ * 面板数据域：历史与槽位面板的数据整形与装配。
+ *
+ * 面板本身（DOM/组件）属于各平台宿主；这里只做「引擎数据 → 可直接渲染的视图」，
+ * 让每个宿主的模板保持零逻辑。
+ */
+
+export * from "./history.ts";
+export * from "./slotTexts.ts";
+export * from "./slots.ts";

package/src/panel/slotTexts.ts

@@ -0,0 +1,24 @@
+/**
+ * 宿主注入引擎的文案整形：把句子里的槽位名换成面板叫法。
+ *
+ * 引擎缺省模板把槽位 id 原样嵌进句子（`槽位 ${slot}`），而宿主的槽位 id 是
+ * `slot_1` 这种形式，直出就是「槽位 slot_2」——玩家在面板上点的是「槽位 2」，
+ * 失败横幅却报一个他从没见过的 id。这里按 `defaultSlotLabel` 改名，让面板怎么
+ * 称呼、报错里就怎么称呼。
+ *
+ * 只摊开引擎缺省表改这两句，其余句子跟着引擎演进：整表手写会在引擎新增句子时
+ * 静默漏接。整体改写或本地化玩家文案时改的是底表，这套槽位名规则不动。
+ */
+import { type EngineTexts } from "@lingfan-engine/core";
+import { defaultSlotLabel } from "./slots.ts";
+
+/** 槽位名与面板同源的引擎文案表（未改写的句子 = 传入底表的原句） */
+export function withSlotLabels(texts: EngineTexts): EngineTexts {
+  return {
+    ...texts,
+    saveWriteFailed: (slot, error) =>
+      `${defaultSlotLabel(slot)} 写档失败：${error}`,
+    loadReadFailed: (slot, error) =>
+      `${defaultSlotLabel(slot)} 读取或解析失败：${error}`,
+  };
+}

package/src/panel/slots.ts

@@ -0,0 +1,115 @@
+/**
+ * 槽位面板的数据装配：把存档端口的清单与逐槽快照整理成可直接渲染的视图。
+ *
+ * 面板只负责「呈现槽位」：写读与校验由引擎命令面承担（`engine.save` /
+ * `engine.load`），此处读取存档端口仅为取标题与缩略图；个别槽读取失败只丢这两项，
+ * 不影响整张面板列出槽位，真实读档失败由引擎 fail-closed 上报。
+ *
+ * 本模块平台无关：不触碰任何框架、DOM 或宿主全局。
+ */
+import type { SaveDataV1, SavePort } from "@lingfan-engine/core";
+
+/** 面板用途：存或读 */
+export type SlotPanelMode = "save" | "load";
+
+/** 一个槽位的呈现数据 */
+export interface SlotView {
+  /** 槽位 id（引擎命令参数） */
+  id: string;
+  /** 槽位显示名（与提示条文案同源，见 {@link defaultSlotLabel}） */
+  label: string;
+  /** 无存档（存档模式仍可点选=覆盖写入；读档模式不可点选，见 {@link canChooseSlot}） */
+  empty: boolean;
+  /** 存档时间戳（无存档时不呈现） */
+  timestamp?: number;
+  /** 存档标题（快照里没有则缺省） */
+  title?: string;
+  /** 缩略图 data URL（快照里没有则缺省） */
+  screenshot?: string;
+}
+
+/** 槽位装配需要的外部事实 */
+export interface SlotPanelOptions {
+  /** 存档端口（清单与逐槽读取） */
+  savePort: SavePort;
+  /** 本工程的槽位 id 序列（顺序即呈现顺序） */
+  slotIds: readonly string[];
+  /** 槽位显示名：把槽位 id 变成面板上给玩家看的一行字；缺省 = 去掉 `slot_` 前缀后加「槽位 」 */
+  labelFor?(id: string): string;
+}
+
+/**
+ * 从快照原文里取出标题与缩略图。
+ *
+ * 单点收敛解析与容错：读到的内容可能不是本版本的存档（或已损坏），
+ * 解析失败与字段类型不符都按「没有」处理，不中断面板装配。
+ */
+export function parseSlotMeta(raw: string): {
+  title?: string;
+  screenshot?: string;
+} {
+  try {
+    const parsed = JSON.parse(raw) as Partial<SaveDataV1>;
+    return {
+      title: typeof parsed.title === "string" ? parsed.title : undefined,
+      screenshot:
+        typeof parsed.screenshot === "string" ? parsed.screenshot : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** 装配槽位视图列表 */
+export async function loadSlotViews(
+  options: SlotPanelOptions,
+): Promise<SlotView[]> {
+  const labelFor = options.labelFor ?? defaultSlotLabel;
+  const summaries = await options.savePort.list().catch(() => []);
+  const byId = new Map(summaries.map((s) => [s.slot, s]));
+  const views: SlotView[] = [];
+  for (const id of options.slotIds) {
+    const summary = byId.get(id);
+    let meta: { title?: string; screenshot?: string } = {};
+    if (summary !== undefined) {
+      // 这次读只用来取标题与缩略图，端口拒读（存档策略拒绝旧档、记录损坏等）不该
+      // 让整张面板列不出槽位：那种槽位照列，只是没有标题与缩略图。
+      meta = await options.savePort.read(id).then(parseSlotMeta, () => ({}));
+    }
+    views.push({
+      id,
+      label: labelFor(id),
+      empty: summary === undefined,
+      timestamp: summary?.timestamp,
+      title: meta.title,
+      screenshot: meta.screenshot,
+    });
+  }
+  return views;
+}
+
+/**
+ * 槽位显示名的缺省规则：`slot_1` → `槽位 1`，其余 id 原样透传。
+ *
+ * 导出是为了让槽位名的规则全仓只有一处：面板的 `labelFor` 与提示条的
+ * `labelFor` 都缺省到它。宿主自定义槽位命名时应把同一个函数传给两处，
+ * 好让同一次操作在面板与提示条上叫法一致。
+ */
+export function defaultSlotLabel(id: string): string {
+  return id.startsWith("slot_") ? `槽位 ${id.slice(5)}` : id;
+}
+
+/**
+ * 槽位是否可点选。
+ *
+ * 读档模式下的空槽点下去必然失败（引擎读不到存档即 fail-closed），玩家只会收到
+ * 一条报错。空槽在读档模式置灰，在存档模式下可点——那是一次覆盖写入。
+ * `mode` 为 null（面板未打开）时一律不可点。
+ */
+export function canChooseSlot(
+  view: SlotView,
+  mode: SlotPanelMode | null,
+): boolean {
+  if (mode === "save") return true;
+  return mode === "load" && !view.empty;
+}

package/src/stage/index.ts

@@ -0,0 +1,21 @@
+/** 舞台适配域：纯计算，视口尺寸由宿主提供。 */
+
+export { computeStageLayout, stageTransform } from "./layout.ts";
+export {
+  DEFAULT_STAGE_FIT,
+  DEFAULT_STAGE_HEIGHT,
+  DEFAULT_STAGE_WIDTH,
+  resolveStagePreset,
+  STAGE_BASELINES,
+  STAGE_PRESETS,
+  type StageBaseline,
+  type StagePreset,
+} from "./presets.ts";
+export type {
+  StageAlign,
+  StageConfig,
+  StageFit,
+  StageLayout,
+  StageScalePolicy,
+  StageViewport,
+} from "./types.ts";

package/src/stage/layout.ts

@@ -0,0 +1,149 @@
+/**
+ * 舞台适配计算：把「视口尺寸 + 设计基准 + 适配策略」算成一组可直接套用的变换。
+ *
+ * 作者按设计基准像素书写元素与控件坐标，演出前由这里算出缩放与偏移，宿主把结果套到
+ * 舞台容器上。本模块只做纯计算：不读平台全局、不碰 DOM。视口尺寸由宿主提供——浏览器
+ * 宿主读窗口，小程序宿主读系统信息，桌面宿主读窗口内可用区域。
+ *
+ * 尺寸不可用（视口或基准非正、非有限）时退化为原始尺寸左上角摆放：调用方拿到的仍是
+ * 一组可安全套用的数字，而不是 NaN。夹取（`minScale`/`maxScale`）按轴生效，等比策略
+ * 下两轴同值，所以夹取不会破坏等比。
+ */
+import { resolveStagePreset } from "./presets.ts";
+import {
+  type StageAlign,
+  type StageConfig,
+  type StageLayout,
+  type StageScalePolicy,
+  type StageViewport,
+} from "./types.ts";
+
+/** 非正或非有限一律按 0 处理：比值算不出来时统一落到退化分支 */
+function positiveOrZero(value: number): number {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/** 两轴缩放倍率：`fill` 与固定数字是仅有的两支可能不等比 */
+function scaleFactors(
+  policy: StageScalePolicy,
+  viewport: StageViewport,
+  width: number,
+  height: number,
+): { readonly x: number; readonly y: number } {
+  const byWidth = viewport.width / width;
+  const byHeight = viewport.height / height;
+  if (typeof policy === "number") {
+    const fixed = Number.isFinite(policy) && policy > 0 ? policy : 1;
+    return { x: fixed, y: fixed };
+  }
+  if (policy === "fill") return { x: byWidth, y: byHeight };
+  if (policy === "width") return { x: byWidth, y: byWidth };
+  if (policy === "height") return { x: byHeight, y: byHeight };
+  if (policy === "max") {
+    const longest = Math.max(byWidth, byHeight);
+    return { x: longest, y: longest };
+  }
+  const shortest = Math.min(byWidth, byHeight);
+  return { x: shortest, y: shortest };
+}
+
+/** 夹取到配置范围：未配置或不合法的一侧不设限 */
+function clampScale(
+  value: number,
+  min: number | undefined,
+  max: number | undefined,
+): number {
+  let scale = value;
+  if (typeof min === "number" && Number.isFinite(min) && scale < min) {
+    scale = min;
+  }
+  if (typeof max === "number" && Number.isFinite(max) && scale > max) {
+    scale = max;
+  }
+  return scale;
+}
+
+/** 留边方向上的摆放偏移：多出的空间按锚点分给两侧，裁切时偏移为负 */
+function alignOffset(
+  viewportEdge: number,
+  scaledEdge: number,
+  align: StageAlign,
+): number {
+  if (align === "start") return 0;
+  if (align === "end") return viewportEdge - scaledEdge;
+  return (viewportEdge - scaledEdge) / 2;
+}
+
+/** 非有限一律按 0：变换串会直接进 CSS，NaN 会让整条声明被静默丢弃 */
+function finite(value: number): number {
+  return Number.isFinite(value) ? value : 0;
+}
+
+/** 小数截到六位：变换串进 CSS 与快照判据都要求稳定文本 */
+function round6(value: number): number {
+  return Math.round(finite(value) * 1e6) / 1e6;
+}
+
+/**
+ * 把布局结果写成 CSS 变换串：先平移再缩放，原点取舞台容器左上角。
+ *
+ * 宿主把这一串原样写进舞台容器的 `transform`（并配 `transform-origin: top left`），
+ * 于是「作者坐标 → 屏幕坐标」的换算全仓只有 `computeStageLayout` 与本函数这一条路径，
+ * 浏览器宿主与小程序宿主不会各写一份变换顺序（顺序错了就变成先缩后移，偏移量会跟着被缩放）。
+ */
+export function stageTransform(layout: StageLayout): string {
+  const x = round6(layout.offsetX);
+  const y = round6(layout.offsetY);
+  const sx = round6(layout.scaleX);
+  const sy = round6(layout.scaleY);
+  return `translate(${x}px, ${y}px) scale(${sx}, ${sy})`;
+}
+
+/** 算一次适配：策略与对齐都是「配置显式值优先，缺省取预设」 */
+export function computeStageLayout(
+  viewport: StageViewport,
+  config: StageConfig,
+): StageLayout {
+  const viewWidth = positiveOrZero(viewport.width);
+  const viewHeight = positiveOrZero(viewport.height);
+  const width = positiveOrZero(config.width);
+  const height = positiveOrZero(config.height);
+  const preset = resolveStagePreset(config.fit);
+  const policy = config.scaleBy ?? preset.scaleBy;
+  if (viewWidth === 0 || viewHeight === 0 || width === 0 || height === 0) {
+    return {
+      policy,
+      scaleX: 1,
+      scaleY: 1,
+      width,
+      height,
+      scaledWidth: width,
+      scaledHeight: height,
+      offsetX: 0,
+      offsetY: 0,
+    };
+  }
+  const factors = scaleFactors(
+    policy,
+    { width: viewWidth, height: viewHeight },
+    width,
+    height,
+  );
+  const scaleX = clampScale(factors.x, config.minScale, config.maxScale);
+  const scaleY = clampScale(factors.y, config.minScale, config.maxScale);
+  const scaledWidth = width * scaleX;
+  const scaledHeight = height * scaleY;
+  const alignX = config.alignX ?? preset.alignX;
+  const alignY = config.alignY ?? preset.alignY;
+  return {
+    policy,
+    scaleX,
+    scaleY,
+    width,
+    height,
+    scaledWidth,
+    scaledHeight,
+    offsetX: alignOffset(viewWidth, scaledWidth, alignX),
+    offsetY: alignOffset(viewHeight, scaledHeight, alignY),
+  };
+}

package/src/stage/presets.ts

@@ -0,0 +1,134 @@
+/**
+ * 舞台适配的预设表：基准尺寸与内置策略。
+ *
+ * 内置策略不是独立实现，而是「缩放策略 + 对齐锚点」的命名组合：`contain` 短边铺满 +
+ * 居中，`cover` 长边铺满 + 居中，`fill` 两轴各自拉满，`none` 固定 1 倍。作者需要特殊
+ * 行为时直接写 `scaleBy`/`alignX`/`alignY`，与预设走同一条计算路径，所以预设与自定义
+ * 之间不存在两套代码。
+ */
+import { DEFAULT_STAGE_CONFIG } from "@lingfan-engine/core";
+import {
+  type StageAlign,
+  type StageFit,
+  type StageScalePolicy,
+} from "./types.ts";
+
+/** 基准尺寸预设：编辑器与宿主的下拉项，作者另填任意尺寸同样可用 */
+export interface StageBaseline {
+  readonly id: string;
+  readonly label: string;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** 内置策略展开后的参数 */
+export interface StagePreset {
+  readonly fit: StageFit;
+  readonly label: string;
+  readonly scaleBy: StageScalePolicy;
+  readonly alignX: StageAlign;
+  readonly alignY: StageAlign;
+}
+
+/**
+ * 缺省基准宽：取自引擎内建舞台配置（横屏 16:9，与视频、存档缩略图同比例）。
+ * 基准的**唯一事实源**在契约层；这里只把它摆成预设下拉要用的名字，避免两处各写一个 1280。
+ */
+export const DEFAULT_STAGE_WIDTH = DEFAULT_STAGE_CONFIG.width;
+/** 缺省基准高 */
+export const DEFAULT_STAGE_HEIGHT = DEFAULT_STAGE_CONFIG.height;
+
+/** 基准尺寸预设（横竖屏各四档：720p / 1080p / 2K / 4K，覆盖常见发布形态） */
+export const STAGE_BASELINES: readonly StageBaseline[] = [
+  {
+    id: "landscape-1280x720",
+    label: "横屏 1280 × 720",
+    width: 1280,
+    height: 720,
+  },
+  {
+    id: "landscape-1920x1080",
+    label: "横屏 1920 × 1080",
+    width: 1920,
+    height: 1080,
+  },
+  {
+    id: "landscape-2560x1440",
+    label: "横屏 2K 2560 × 1440",
+    width: 2560,
+    height: 1440,
+  },
+  {
+    id: "landscape-3840x2160",
+    label: "横屏 4K 3840 × 2160",
+    width: 3840,
+    height: 2160,
+  },
+  {
+    id: "portrait-750x1334",
+    label: "竖屏 750 × 1334",
+    width: 750,
+    height: 1334,
+  },
+  {
+    id: "portrait-1080x1920",
+    label: "竖屏 1080 × 1920",
+    width: 1080,
+    height: 1920,
+  },
+  {
+    id: "portrait-1440x2560",
+    label: "竖屏 2K 1440 × 2560",
+    width: 1440,
+    height: 2560,
+  },
+  {
+    id: "portrait-2160x3840",
+    label: "竖屏 4K 2160 × 3840",
+    width: 2160,
+    height: 3840,
+  },
+];
+
+/** 缺省策略（同样取契约层的内建值；工程未声明 `fit` 时落到这里） */
+export const DEFAULT_STAGE_FIT: StageFit =
+  DEFAULT_STAGE_CONFIG.fit ?? "contain";
+
+/** 内置策略表 */
+export const STAGE_PRESETS: Readonly<Record<StageFit, StagePreset>> = {
+  contain: {
+    fit: "contain",
+    label: "完整显示（留边）",
+    scaleBy: "min",
+    alignX: "center",
+    alignY: "center",
+  },
+  cover: {
+    fit: "cover",
+    label: "铺满裁切",
+    scaleBy: "max",
+    alignX: "center",
+    alignY: "center",
+  },
+  fill: {
+    fit: "fill",
+    label: "拉伸铺满",
+    scaleBy: "fill",
+    alignX: "center",
+    alignY: "center",
+  },
+  none: {
+    fit: "none",
+    label: "原始尺寸",
+    scaleBy: 1,
+    alignX: "center",
+    alignY: "center",
+  },
+};
+
+/** 取内置策略：名字不在表内时回退缺省（配置来自外部，运行期不假定合法） */
+export function resolveStagePreset(fit: StageFit | undefined): StagePreset {
+  const fallback = STAGE_PRESETS[DEFAULT_STAGE_FIT];
+  if (fit === undefined) return fallback;
+  return STAGE_PRESETS[fit] ?? fallback;
+}

package/src/stage/types.ts

@@ -0,0 +1,40 @@
+/**
+ * 舞台适配的公共类型：视口、设计基准与适配策略。
+ *
+ * 配置契约（`StageConfig` 与三个策略别名）**声明在引擎**（`project.json shell.stage` 是工程
+ * 事实，与 `shell.saves` 同属契约层，解析也在引擎），此处按原路径转出，消费方无需改 import。
+ * 本域只留「算出来的东西」：视口与布局结果。类型单独成文件，是让策略表与计算实现都只依赖
+ * 类型，实现文件之间不成环。
+ */
+
+import type { StageScalePolicy } from "@lingfan-engine/core";
+
+export type {
+  StageAlign,
+  StageConfig,
+  StageFit,
+  StageScalePolicy,
+} from "@lingfan-engine/core";
+
+/** 视口尺寸（宿主提供的逻辑像素尺寸） */
+export interface StageViewport {
+  readonly width: number;
+  readonly height: number;
+}
+
+/** 计算结果：宿主把它套成舞台容器的缩放与定位 */
+export interface StageLayout {
+  /** 实际生效的缩放策略 */
+  readonly policy: StageScalePolicy;
+  readonly scaleX: number;
+  readonly scaleY: number;
+  /** 设计基准宽高（作者坐标系） */
+  readonly width: number;
+  readonly height: number;
+  /** 缩放后的实际占位尺寸 */
+  readonly scaledWidth: number;
+  readonly scaledHeight: number;
+  /** 舞台内容左上角相对视口左上角的偏移（逻辑像素） */
+  readonly offsetX: number;
+  readonly offsetY: number;
+}

package/src/state/index.ts

@@ -0,0 +1,10 @@
+/**
+ * 叙事视图状态域出口：形状见 `./types`，装配见 `./narrativeState`。
+ */
+export { createNarrativeState } from "./narrativeState";
+export type {
+  MenuChoice,
+  NarrativeState,
+  NarrativeStateOptions,
+  StateCells,
+} from "./types";