@lingfan-engine/editor 0.0.0-stage → 0.1.2

package/src/editing/pointers.ts

@@ -0,0 +1,291 @@
+/**
+ * JSON Pointer（RFC 6901）读取与不可变树编辑：沿路径克隆（结构共享），
+ * 未命中路径 fail-closed 返回 null——编辑器映射器只做纯函数。
+ */
+
+import { describeForm } from "../schema/index.ts";
+import { BUILTIN_OP_SURFACE, type OpSurface } from "../schema/index.ts";
+
+type PathSegment = string | number;
+
+/** 组装 JSON Pointer（段转义 ~ 与 /） */
+export function buildPointer(segments: readonly PathSegment[]): string {
+  if (segments.length === 0) return "";
+  return (
+    "/" +
+    segments
+      .map((segment) =>
+        String(segment).replaceAll("~", "~0").replaceAll("/", "~1"),
+      )
+      .join("/")
+  );
+}
+
+export function parsePointer(pointer: string): PathSegment[] {
+  if (pointer === "" || !pointer.startsWith("/")) return [];
+  return pointer
+    .split("/")
+    .slice(1)
+    .map((segment) => segment.replaceAll("~1", "/").replaceAll("~0", "~"))
+    .map((segment) => (/^\d+$/.test(segment) ? Number(segment) : segment));
+}
+
+/** 读取指针处值；指针非法或路径未命中返回 undefined */
+export function getAtPointer(root: unknown, pointer: string): unknown {
+  let current: unknown = root;
+  for (const segment of parsePointer(pointer)) {
+    if (typeof segment === "number") {
+      if (!Array.isArray(current)) return undefined;
+      current = current[segment];
+      continue;
+    }
+    if (current === null || typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+function shallowClone(
+  node: unknown,
+): Record<string, unknown> | unknown[] | undefined {
+  if (Array.isArray(node)) return node.slice();
+  if (node !== null && typeof node === "object") {
+    return { ...(node as Record<string, unknown>) };
+  }
+  return undefined;
+}
+
+/**
+ * 沿 parentSegments 克隆到目标父节点（结构共享），对父克隆应用 apply。
+ * apply 返回 false = 未命中（fail-closed）；返回 undefined = 路径未命中。
+ */
+function editAt(
+  root: unknown,
+  parentSegments: readonly PathSegment[],
+  key: PathSegment,
+  apply: (parentClone: unknown, key: PathSegment) => boolean,
+): unknown | undefined {
+  if (parentSegments.length === 0) {
+    const parentClone = shallowClone(root);
+    if (parentClone === undefined) return undefined;
+    return apply(parentClone, key) ? parentClone : undefined;
+  }
+  const [head, ...rest] = parentSegments;
+  if (typeof head === "number") {
+    if (!Array.isArray(root) || head < 0 || head >= root.length)
+      return undefined;
+    const child = editAt(root[head], rest, key, apply);
+    if (child === undefined) return undefined;
+    const clone = root.slice();
+    clone[head] = child;
+    return clone;
+  }
+  if (root === null || typeof root !== "object") return undefined;
+  const record = root as Record<string, unknown>;
+  if (!(head in record)) return undefined;
+  const child = editAt(record[head], rest, key, apply);
+  if (child === undefined) return undefined;
+  return { ...record, [head]: child };
+}
+
+function keyOf(
+  parent: unknown,
+  key: PathSegment,
+): { get(): unknown; set(value: unknown): boolean } | null {
+  if (typeof key === "number") {
+    if (!Array.isArray(parent)) return null;
+    return {
+      get: () => parent[key],
+      set: (value) => {
+        if (key < 0 || key > parent.length) return false;
+        parent[key] = value;
+        return true;
+      },
+    };
+  }
+  if (parent === null || typeof parent !== "object") return null;
+  const record = parent as Record<string, unknown>;
+  return {
+    get: () => record[key],
+    set: (value) => {
+      record[key] = value;
+      return true;
+    },
+  };
+}
+
+/** 写入指针处值（不可变；数组索引允许 == length 追加）；路径未命中返回 null */
+export function setAtPointer<T>(
+  root: T,
+  pointer: string,
+  value: unknown,
+): T | null {
+  const segments = parsePointer(pointer);
+  if (segments.length === 0) return null;
+  const key = segments[segments.length - 1]!;
+  const next = editAt(root, segments.slice(0, -1), key, (parent, k) => {
+    const slot = keyOf(parent, k);
+    return slot !== null && slot.set(value);
+  });
+  return next === undefined ? null : (next as T);
+}
+
+/** 移除指针处值（数组按索引删，对象删键）；不可变；未命中返回 null */
+export function removeAtPointer<T>(root: T, pointer: string): T | null {
+  const segments = parsePointer(pointer);
+  if (segments.length === 0) return null;
+  const key = segments[segments.length - 1]!;
+  const next = editAt(root, segments.slice(0, -1), key, (parent, k) => {
+    if (typeof k === "number") {
+      if (!Array.isArray(parent) || k < 0 || k >= parent.length) return false;
+      parent.splice(k, 1);
+      return true;
+    }
+    if (parent === null || typeof parent !== "object") return false;
+    if (!(k in (parent as Record<string, unknown>))) return false;
+    delete (parent as Record<string, unknown>)[k];
+    return true;
+  });
+  return next === undefined ? null : (next as T);
+}
+
+/** 数组插入：pointer 指向数组，index 为插入位；不可变；未命中返回 null */
+export function insertAtPointer<T>(
+  root: T,
+  pointer: string,
+  index: number,
+  value: unknown,
+): T | null {
+  const segments = parsePointer(pointer);
+  if (segments.length === 0) return null;
+  const key = segments[segments.length - 1]!;
+  const next = editAt(root, segments.slice(0, -1), key, (parent, k) => {
+    const slot = keyOf(parent, k);
+    if (slot === null || !Array.isArray(slot.get())) return false;
+    const list = slot.get() as unknown[];
+    if (index < 0 || index > list.length) return false;
+    const copy = list.slice();
+    copy.splice(index, 0, value);
+    return slot.set(copy);
+  });
+  return next === undefined ? null : (next as T);
+}
+
+/** 数组元素移动：elementPointer 指向元素，toIndex 为移除后目标位；不可变；未命中返回 null */
+export function moveAtPointer<T>(
+  root: T,
+  elementPointer: string,
+  toIndex: number,
+): T | null {
+  const segments = parsePointer(elementPointer);
+  if (segments.length === 0) return null;
+  const key = segments[segments.length - 1]!;
+  if (typeof key !== "number") return null;
+  const next = editAt(root, segments.slice(0, -1), key, (parent, k) => {
+    if (!Array.isArray(parent) || typeof k !== "number") return false;
+    if (k < 0 || k >= parent.length) return false;
+    if (toIndex < 0 || toIndex >= parent.length) return false;
+    const [moved] = parent.splice(k, 1);
+    parent.splice(toIndex, 0, moved);
+    return true;
+  });
+  return next === undefined ? null : (next as T);
+}
+
+function isCommandAt(root: unknown, pointer: string): boolean {
+  const node = getAtPointer(root, pointer);
+  return (
+    node !== null &&
+    typeof node === "object" &&
+    !Array.isArray(node) &&
+    typeof (node as Record<string, unknown>).op === "string"
+  );
+}
+
+/**
+ * 归一到**最近的命令祖先指针**：诊断/引用给出的指针是字段级（精确到
+ * 字段），而时间线行选中与属性面板表单都锚在命令指针上——指针不是命令时沿前缀
+ * **从长到短**上溯包含它的命令（嵌套块体逐级上溯）；本身已是命令、或无命令祖先
+ * （列指针 / 根）→ 原样返回（调用方既有语义不变）。
+ */
+export function nearestCommandPointer(story: unknown, pointer: string): string {
+  if (isCommandAt(story, pointer)) return pointer;
+  const segments = parsePointer(pointer);
+  for (let i = segments.length - 1; i >= 2; i -= 1) {
+    const prefix = buildPointer(segments.slice(0, i));
+    if (isCommandAt(story, prefix)) return prefix;
+  }
+  return pointer;
+}
+
+/* ------------------------------------------------------------------ *
+ * 选中态语义
+ * ------------------------------------------------------------------ */
+
+/** 选中态分类；**除 `unknown-op` 外都不是错误**（列 / 元素 / 数组项都是正常选中） */
+export type SelectionKind = "none" | "non-command" | "unknown-op" | "command";
+
+/** 非命令选中的细分（仅供文案取用，不改变 `kind`） */
+export type SelectionNodeKind = "column" | "element" | "item" | "other";
+
+export interface SelectionDescription {
+  kind: SelectionKind;
+  /** `non-command` / `unknown-op` 时有意义 */
+  nodeKind?: SelectionNodeKind;
+  /** `command` / `unknown-op` 时有意义 */
+  opName?: string;
+}
+
+/** 按指针形状细分非命令目标：`/columns/<i>` = 列；`…/elements/<j>` = 元素；`…/commands/<j>` = 组内项 */
+function selectionNodeKind(pointer: string): SelectionNodeKind {
+  const segments = parsePointer(pointer);
+  if (segments[0] !== "columns") return "other";
+  if (segments.length === 2) return "column";
+  if (segments[2] === "elements") return "element";
+  if (segments[2] === "commands") return "item";
+  return "other";
+}
+
+/**
+ * 描述「当前选中了什么」——**四态**，而不是「是命令 / 不是命令」两态。
+ *
+ * **要点**：属性面板**不得**把「选中的是一列」渲染成错误——「所选位置不是命令
+ * （op 缺失）——诊断面板有详情」会与**同一时刻**诊断面板显示的「✓ 无诊断」
+ * 互相矛盾，且把用户的**正常操作**说成故障。真实语义有四种：
+ *
+ * | kind | 触发 | 该说什么 |
+ * |---|---|---|
+ * | `none` | `pointer === null` | 中性引导：选一条命令 |
+ * | `non-command` | 指针落在列 / 元素 / 数组项 | **中性陈述**，**不得出现「错误/缺失/诊断」** |
+ * | `unknown-op` | 落在命令上，但**无表单描述符** | **真问题**（提诊断、可删除） |
+ * | `command` | 正常命令 | 现有表单 |
+ *
+ * 判定顺序：`null` → `none`；节点是对象且 `op` 为字符串 → 有描述符即 `command`，
+ * 否则 `unknown-op`（把操作数也带上，即 `opName`）；其余 → `non-command`。
+ * **指针悬空**（`getAtPointer` 未命中）同样归 `non-command` —— fail-soft：面板给
+ * 中性文案，**不谎报成错误**（悬空多由撤销后的陈旧选中造成，不属 op 缺失）。
+ *
+ * `surface` 与 `describeForm` 同口径（缺省 = 内建 op 面）——**不得**在这里换一套
+ * op 面，否则会与面板表单的判断打架。
+ */
+export function describeSelection(
+  story: unknown,
+  pointer: string | null,
+  surface: OpSurface = BUILTIN_OP_SURFACE,
+): SelectionDescription {
+  if (pointer === null) return { kind: "none" };
+  const nodeKind = selectionNodeKind(pointer);
+  const node = getAtPointer(story, pointer);
+  if (
+    node !== null &&
+    typeof node === "object" &&
+    !Array.isArray(node) &&
+    typeof (node as Record<string, unknown>).op === "string"
+  ) {
+    const opName = (node as Record<string, unknown>).op as string;
+    return describeForm(opName, surface) === undefined
+      ? { kind: "unknown-op", nodeKind, opName }
+      : { kind: "command", nodeKind, opName };
+  }
+  return { kind: "non-command", nodeKind };
+}

package/src/editing/saveNormalization.ts

@@ -0,0 +1,58 @@
+/**
+ * 保存前规范化提示：
+ * 「不再提示」偏好持久化 + 提示文案组装。
+ *
+ * 分层：**检测**归引擎（`detectWriteNormalization`，与 `serializeProject` 同一布局
+ * 知识族）；本模块只管编辑器视图侧的两件事——偏好是**本机视图偏好**（边界：
+ * 不入故事 JSON、任何存储失败全静默，与列分组相同降级策略），文案负责把 finding
+ * 翻成与真实写回行为一一对应的行。
+ */
+import type { WriteNormalizationFinding } from "@lingfan-engine/core";
+import type { KeyValueStorage } from "./columnGrouping.ts";
+
+/** 「不再提示」键（全局一次性偏好，非按工程——规范化行为是引擎布局规则，不随工程变） */
+export const NORMALIZATION_NOTICE_PREF_KEY =
+  "lingfan-editor-skip-normalization-notice";
+
+/** 读偏好：键缺失 / 坏值 / 存储失败一律 `false`（提示默认开启，fail-open 到可见侧） */
+export function readSkipNormalizationNotice(
+  storage: KeyValueStorage | undefined,
+): boolean {
+  try {
+    return storage?.getItem(NORMALIZATION_NOTICE_PREF_KEY) === "1";
+  } catch {
+    return false;
+  }
+}
+
+/** 写偏好：`true` 记 `"1"`、`false` 记 `"0"`（读侧只认 `"1"`）；失败静默 = 仅本次会话有效 */
+export function writeSkipNormalizationNotice(
+  storage: KeyValueStorage | undefined,
+  skip: boolean,
+): void {
+  try {
+    storage?.setItem(NORMALIZATION_NOTICE_PREF_KEY, skip ? "1" : "0");
+  } catch {
+    /* 存储不可用（配额 / 隐私模式）= 偏好仅本次会话有效 */
+  }
+}
+
+/**
+ * finding → 提示行（每行对应一个真实文件级动作；码元序稳定输出）。
+ * 空 finding → 空数组（界面据此不渲染提示）。
+ */
+export function describeNormalization(
+  finding: WriteNormalizationFinding,
+): string[] {
+  const lines: string[] = [];
+  for (const path of finding.toConvert) {
+    const json = `${path.slice(0, -".story".length)}.json`;
+    lines.push(`「${path}」将转换为标准 JSON 列文件「${json}」（内容等价）`);
+  }
+  for (const path of finding.toRemove) {
+    lines.push(
+      `「${path}」将从磁盘移除（内容重组为按列命名的单列文件，或已不被当前故事引用）`,
+    );
+  }
+  return lines;
+}

package/src/editing/session.ts

@@ -0,0 +1,134 @@
+/**
+ * 编辑器会话（视图族共享中枢）：所有视图经同一 session 提交编辑——
+ * 一处改动全视图同步（订阅通知）+ 统一 undo 栈（一次提交 = 一个 undo 单元，
+ * 深度可配置）。故事树不可变：提交即整体换引用，视图零 diff 成本。
+ * 统一 undo：跨视图同步、一次提交一个单元。
+ */
+
+import type { Story } from "@lingfan-engine/core";
+import type { StoryListener, UndoEntry } from "../contracts/index.ts";
+
+const DEFAULT_UNDO_CAPACITY = 100;
+
+export class EditorSession {
+  private current: Story;
+  /** 已保存基线（引用比较：commit 恒换引用、undo 恢复原引用 → 撤销回已保存态即干净） */
+  private saved: Story;
+  private readonly undoStack: UndoEntry[] = [];
+  private readonly redoStack: UndoEntry[] = [];
+  private readonly listeners = new Set<StoryListener>();
+  private readonly capacity: number;
+
+  constructor(story: Story, options: { undoCapacity?: number } = {}) {
+    this.current = story;
+    this.saved = story;
+    this.capacity = Math.max(1, options.undoCapacity ?? DEFAULT_UNDO_CAPACITY);
+  }
+
+  get story(): Story {
+    return this.current;
+  }
+
+  /**
+   * 有未保存更改。引用比较：唯一代价是「内容相同的不同引用」会多亮一次按钮，
+   * **不会漏报**未保存（安全方向正确）；深比较每次渲染全树遍历，不划算。
+   */
+  get dirty(): boolean {
+    return this.current !== this.saved;
+  }
+
+  /**
+   * 保存成功：把基线钉到**实际写出的那个引用**（不是当前引用）——
+   * 保存期间用户又编辑时，`current !== reference` → 仍 dirty，不会误清。
+   */
+  markSaved(reference: Story = this.current): void {
+    if (this.saved === reference) return;
+    this.saved = reference;
+    this.notify();
+  }
+
+  /**
+   * **换基线**（结构刷新，不产生历史）：把当前树与已保存基线**同时**换掉。
+   *
+   * 为何不用 `commit`：那是**用户编辑**的语义（压一个 undo 单元）。工程结构变化
+   * （如新增一列 ⇒ 既有列的切分投影跟着变）需要的是「这些文档本来就干净，
+   * 让它们继续干净」，而不是给每个文档记一条假历史（撤销键会堆满噪声）。
+   *
+   * **有未保存改动时拒绝**（返回 false）：那属于编辑，必须走 `commit`
+   * 才能撤销 —— 静默丢弃作者的改动不可接受。
+   */
+  replaceClean(next: Story): boolean {
+    if (this.dirty) return false;
+    this.current = next;
+    this.saved = next;
+    this.notify();
+    return true;
+  }
+
+  get canUndo(): boolean {
+    return this.undoStack.length > 0;
+  }
+
+  get canRedo(): boolean {
+    return this.redoStack.length > 0;
+  }
+
+  get undoDepth(): number {
+    return this.undoStack.length;
+  }
+
+  get redoDepth(): number {
+    return this.redoStack.length;
+  }
+
+  /**
+   * 提交一次编辑（一个 undo 单元）：同引用提交为 no-op（无变更不产生历史噪声）。
+   * 提交后清空 redo 尾（新分支时间线，与菜单重选开新时间线同思想）。
+   */
+  commit(label: string, next: Story): void {
+    if (next === this.current) return;
+    this.undoStack.push({ label, before: this.current, after: next });
+    if (this.undoStack.length > this.capacity) this.undoStack.shift();
+    this.redoStack.length = 0;
+    this.current = next;
+    this.notify();
+  }
+
+  /** 由编辑函数派生新故事并提交；编辑函数返回 null = 未命中，不产生历史单元 */
+  apply(label: string, edit: (story: Story) => Story | null): boolean {
+    const next = edit(this.current);
+    if (next === null) return false;
+    this.commit(label, next);
+    return true;
+  }
+
+  undo(): boolean {
+    const entry = this.undoStack.pop();
+    if (entry === undefined) return false;
+    this.redoStack.push(entry);
+    this.current = entry.before;
+    this.notify();
+    return true;
+  }
+
+  redo(): boolean {
+    const entry = this.redoStack.pop();
+    if (entry === undefined) return false;
+    this.undoStack.push(entry);
+    this.current = entry.after;
+    this.notify();
+    return true;
+  }
+
+  /** 订阅故事变更（视图同步接缝）；返回退订函数 */
+  subscribe(listener: StoryListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  private notify(): void {
+    for (const listener of this.listeners) listener(this.current);
+  }
+}