@web-ppt/edit-core 0.5.0-beta.1 → 0.5.0-beta.7

package/dist/common-object-slide-types.d.ts

@@ -0,0 +1,34 @@
+import type { SectionId, SlideId } from './identities';
+export interface ElementAltTextOverrides {
+    title?: string;
+    descr?: string;
+}
+export interface ElementAltTextState {
+    readonly title: string;
+    readonly descr: string;
+    readonly sourceTitle: string;
+    readonly sourceDescr: string;
+    readonly directTitle: boolean;
+    readonly directDescr: boolean;
+    readonly direct: boolean;
+}
+export interface SlideSizeState {
+    readonly w: number;
+    readonly h: number;
+    readonly sourceW: number;
+    readonly sourceH: number;
+    readonly direct: boolean;
+}
+export interface SectionRecord {
+    readonly id: SectionId;
+    /** 写回 p14:section@id 的 GUID；与会话身份分开，避免格式身份渗入命令目标。 */
+    readonly presentationId: string;
+    name: string;
+    slideIds: SlideId[];
+}
+export interface SectionState {
+    records: Record<SectionId, SectionRecord>;
+    order: SectionId[];
+    /** 仅显式节命令置为 true；普通增删页仍走保留未知 XML 的增量写回。 */
+    edited: boolean;
+}

package/dist/custom-geometry-path.d.ts

@@ -0,0 +1,3 @@
+import type { CustomGeometry } from '@web-ppt/core';
+/** 将 core 已求值的预设 SVG 路径显式物化为稳定寻址的自由形状模型。 */
+export declare function customGeometryFromSvgPath(d: string, width: number, height: number, open?: boolean): CustomGeometry;

package/dist/custom-geometry.d.ts

@@ -0,0 +1,12 @@
+import type { CustomGeometry } from '@web-ppt/core';
+import type { EditDoc, ElementId } from './types';
+export declare function assertCustomGeometry(value: unknown, label: string): asserts value is CustomGeometry;
+/** 投影读 value、保存写 expression；覆盖边界必须保证二者不会形成两套真相。 */
+export declare function assertCustomGeometryOverride(current: CustomGeometry | null, value: unknown, label: string): asserts value is CustomGeometry;
+export declare function queryElementCustomGeometry(doc: EditDoc, id: ElementId): CustomGeometry | null;
+export declare function moveCustomGeometryPoint(geometry: CustomGeometry, pointId: string, position: {
+    readonly x: number;
+    readonly y: number;
+}): CustomGeometry;
+export declare function setCustomGeometryClosed(geometry: CustomGeometry, pathId: string, closed: boolean): CustomGeometry;
+export declare function setCustomGeometrySegmentType(geometry: CustomGeometry, pathId: string, commandId: string, type: 'line' | 'cubic'): CustomGeometry;

package/dist/data-validation.d.ts

@@ -1,6 +1,6 @@
 import type { TextPosition, TextRange } from './commands/types';
 export declare const own: (object: object, key: PropertyKey) => boolean;
-export declare function assertDataObject(value: unknown, fields: readonly string[], label: string): asserts value is object;
+export declare function assertDataObject(value: unknown, fields: readonly string[] | ReadonlySet<PropertyKey>, label: string): asserts value is object;
 /** JSON 数组必须稠密且只能拥有索引与 length；否则序列化会吞掉空洞、访问器或附加状态。 */
 export declare function assertDataArray(value: unknown, label: string): asserts value is readonly unknown[];
 export declare function assertTextPosition(value: unknown, label: string): asserts value is TextPosition;

package/dist/describe/budget.d.ts

@@ -0,0 +1,3 @@
+import type { DescribeOptions, PresentationDescription } from './types';
+export declare function validateBudget(options: DescribeOptions): void;
+export declare function applyBudget(full: PresentationDescription, options: DescribeOptions): PresentationDescription;

package/dist/describe/index.d.ts

@@ -0,0 +1,5 @@
+import type { EditDoc } from '@web-ppt/edit-core';
+import type { DescribeOptions, PresentationDescription } from './types';
+export declare function describePresentation(doc: EditDoc, options?: DescribeOptions): PresentationDescription;
+export { DescribeError } from './types';
+export type { DescribeFailureReason, DescribeOptions, DescriptionElement, DescriptionParagraph, DescriptionPlaceholder, DescriptionReference, DescriptionSlide, PresentationDescription, } from './types';

package/dist/describe/read.d.ts

@@ -0,0 +1,4 @@
+import type { SlideElement } from '@web-ppt/core';
+import type { EditDoc } from '@web-ppt/edit-core';
+import type { PresentationDescription } from './types';
+export declare function readDescription(doc: EditDoc, observe?: (page: number, id: string, element: SlideElement) => void): PresentationDescription;

package/dist/describe/types.d.ts

@@ -0,0 +1,103 @@
+export interface DescriptionReference {
+    readonly id: string;
+    readonly name: string;
+}
+export interface DescriptionPlaceholder {
+    readonly type: string;
+    readonly index: string | null;
+    readonly layout: {
+        readonly id: string;
+        readonly elementId: string;
+    } | null;
+    readonly master: {
+        readonly id: string;
+        readonly elementId: string;
+    } | null;
+}
+export interface DescriptionParagraph {
+    readonly text: string;
+    readonly level: number;
+    readonly bullet: {
+        readonly kind: 'none' | 'text' | 'image';
+        readonly text: string | null;
+        readonly numbering: {
+            readonly type: string;
+            readonly startAt: number;
+        } | null;
+    };
+    readonly cell: {
+        readonly row: number;
+        readonly column: number;
+    } | null;
+}
+export interface DescriptionElement {
+    readonly id: string;
+    readonly kind: 'shape' | 'image' | 'group' | 'table' | 'unsupported';
+    readonly name: string;
+    readonly altText: {
+        readonly title: string;
+        readonly description: string;
+    };
+    /** 根到自身的稳定 ID；先序截断后仍能解析每个已返回元素的祖先。 */
+    readonly path: readonly string[];
+    readonly canvas: {
+        readonly kind: 'slide' | 'layout' | 'master';
+        readonly id: string;
+    };
+    readonly bounds: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly editable: 'full' | 'frame' | 'none';
+    readonly hidden: boolean;
+    readonly locked: boolean;
+    readonly placeholder: DescriptionPlaceholder | null;
+    readonly paragraphs: readonly DescriptionParagraph[];
+}
+export interface DescriptionSlide {
+    readonly id: string;
+    /** 面向使用者的页码，从 1 开始，包含隐藏页。 */
+    readonly number: number;
+    readonly hidden: boolean;
+    readonly layout: DescriptionReference | null;
+    readonly master: DescriptionReference | null;
+    readonly section: DescriptionReference | null;
+    readonly notes: string;
+    readonly elements: readonly DescriptionElement[];
+}
+export interface PresentationDescription {
+    readonly version: 1;
+    readonly source: 'pptx' | 'ppt';
+    readonly width: number;
+    readonly height: number;
+    readonly totalSlides: number;
+    /** 按页面计数，同一个设计对象在不同页面出现时分别计入。 */
+    readonly totalElements: number;
+    readonly slides: readonly DescriptionSlide[];
+    readonly truncation: {
+        readonly reason: 'max-chars' | 'max-tokens' | null;
+        readonly omittedSlides: number;
+        readonly omittedElements: number;
+        /** elementId 为 null 时，截断发生在整页元数据之前。 */
+        readonly next: {
+            readonly slideNumber: number;
+            readonly elementId: string | null;
+        } | null;
+    };
+}
+export interface DescribeOptions {
+    /** JSON.stringify(result) 的 UTF-16 单元数上限，包含截断说明。 */
+    readonly maxChars?: number;
+    readonly maxTokens?: number;
+    /** 使用目标模型的计数规则；设置 maxTokens 时必须提供，返回非负安全整数。 */
+    readonly countTokens?: (json: string) => number;
+}
+export type DescribeFailureReason = 'invalid-budget' | 'token-counter-required' | 'invalid-token-count' | 'token-count-failed' | 'budget-too-small' | 'invalid-document' | 'unaddressable-element' | 'invalid-geometry';
+export declare class DescribeError extends Error {
+    readonly reason: DescribeFailureReason;
+    readonly slideNumber: number | null;
+    readonly elementId: string | null;
+    constructor(reason: DescribeFailureReason, message: string, slideNumber?: number | null, elementId?: string | null);
+}

package/dist/describe.js

@@ -0,0 +1,192 @@
+import { findPlaceholderByIdentity as D } from "@web-ppt/core";
+import { toSlide as q, sectionOfSlide as F, querySelectionPane as L, effectiveElement as U, elementWorldBounds as H, queryElementAltText as J } from "@web-ppt/edit-core";
+class c extends Error {
+  constructor(n, t, r = null, i = null) {
+    super(t), this.reason = n, this.slideNumber = r, this.elementId = i, this.name = "DescribeError";
+  }
+}
+function Q(e) {
+  if (!e || typeof e != "object" || Array.isArray(e))
+    throw new c("invalid-budget", "describe.options 必须为预算选项对象");
+  for (const n of ["maxChars", "maxTokens"]) {
+    const t = e[n];
+    if (t !== void 0 && (!Number.isSafeInteger(t) || t < 0))
+      throw new c("invalid-budget", `describe.${n} 实际为 ${String(t)}，必须为非负安全整数`);
+  }
+  if (e.maxTokens !== void 0 && typeof e.countTokens != "function")
+    throw new c("token-counter-required", "describe.maxTokens 必须同时提供目标模型的 countTokens(json)");
+}
+function R(e, n) {
+  if (n.maxChars === void 0 && n.maxTokens === void 0) return e;
+  const t = (d) => {
+    const m = JSON.stringify(d);
+    let h = 0;
+    if (n.maxTokens !== void 0)
+      try {
+        h = n.countTokens(m);
+      } catch (f) {
+        throw new c("token-count-failed", `describe.countTokens 执行失败：${f instanceof Error ? f.message : String(f)}`);
+      }
+    if (!Number.isSafeInteger(h) || h < 0)
+      throw new c("invalid-token-count", `describe.countTokens 实际返回 ${String(h)}，必须为非负安全整数`);
+    return n.maxChars !== void 0 && m.length > n.maxChars ? "max-chars" : n.maxTokens !== void 0 && h > n.maxTokens ? "max-tokens" : null;
+  }, r = t(e);
+  if (!r) return e;
+  const i = e.totalElements + e.totalSlides, s = (d) => {
+    const m = [];
+    let h = 0, f = d, x = null;
+    for (const w of e.slides) {
+      if (!f) {
+        x = { slideNumber: w.number, elementId: null };
+        break;
+      }
+      f--;
+      const b = Math.min(f, w.elements.length), E = w.elements.slice(0, b);
+      if (m.push({ ...w, elements: E }), h += b, f -= b, b < w.elements.length) {
+        x = { slideNumber: w.number, elementId: w.elements[b].id };
+        break;
+      }
+    }
+    return {
+      ...e,
+      slides: m,
+      truncation: { reason: r, omittedSlides: e.totalSlides - m.length, omittedElements: e.totalElements - h, next: x }
+    };
+  };
+  let a = s(0);
+  if (t(a)) throw new c("budget-too-small", `describe 的 ${r} 预算不足以容纳最小结果及截断定位`);
+  let u = 0, p = i - 1;
+  for (; u < p; ) {
+    const d = Math.ceil((u + p) / 2), m = s(d);
+    t(m) ? p = d - 1 : (u = d, a = m);
+  }
+  return a;
+}
+function W(e, n) {
+  let t = e.elements[n];
+  const r = /* @__PURE__ */ new Set();
+  for (; t; ) {
+    if (r.has(t.id)) throw new Error(`元素父链成环：${t.id}`);
+    if (r.add(t.id), e.slides[t.parent]) return { kind: "slide", id: t.parent };
+    if (e.layouts[t.parent]) return { kind: "layout", id: t.parent };
+    if (e.masters[t.parent]) return { kind: "master", id: t.parent };
+    t = e.elements[t.parent];
+  }
+  throw new Error(`元素 ${n} 的父链没有画布根`);
+}
+function P(e, n = !1) {
+  const t = (r, i) => ((r == null ? void 0 : r.paragraphs) ?? []).map((s) => {
+    var u;
+    const a = (u = s.editInfo) == null ? void 0 : u.autoNumbering;
+    return {
+      text: s.runs.map((p) => p.text).join(""),
+      level: s.lvl,
+      cell: i,
+      bullet: {
+        kind: s.bulletImage ? "image" : s.bullet !== null ? "text" : "none",
+        text: s.bullet,
+        numbering: a ? { type: a.scheme, startAt: a.startAt } : null
+      }
+    };
+  });
+  return e.kind === "shape" ? t(e.text, null) : e.kind === "group" && n ? e.children.flatMap((r) => P(r, !0)) : e.kind !== "table" ? [] : e.rows.flatMap((r, i) => r.cells.flatMap((s, a) => s.merged ? [] : t(s.text, { row: i, column: a })));
+}
+function z(e, n, t) {
+  const r = e.elements[t].meta.ph;
+  if (!r) return null;
+  const i = e.layouts[e.slides[n].layoutId ?? ""], s = i ? e.masters[i.origin.masterPart] : void 0, a = (m, h) => D(
+    m,
+    (f) => e.elements[f].meta.ph,
+    h
+  ), u = i ? a(i.children, r) : void 0, p = u ? e.elements[u].meta.ph : r, d = s ? a(s.children, p) : void 0;
+  return {
+    type: r.type,
+    index: r.idx ?? null,
+    layout: u ? { id: i.id, elementId: u } : null,
+    master: d ? { id: s.id, elementId: d } : null
+  };
+}
+function G(e, n, t, r) {
+  const i = q(e, n), s = e.slides[n], a = e.layouts[s.layoutId ?? ""], u = a ? e.masters[a.origin.masterPart] : void 0, p = F(e, n), d = p ? e.sections.records[p] : null, m = L(e, n), h = m.filter((l) => l.parentId === null).reverse().map((l) => l.id), f = new Map(m.map((l) => [l.id, l])), x = [...(u == null ? void 0 : u.children) ?? [], ...(a == null ? void 0 : a.children) ?? []], w = [], b = (l, o, $, T, S) => {
+    var M;
+    const g = e.elements[o];
+    if (!g || $.includes(o))
+      throw new c("unaddressable-element", `页面 ${t} 元素 ${o} 缺少有效的无环编辑身份`, t, o);
+    const k = H(e, o);
+    if (!Object.values(k).every(Number.isFinite))
+      throw new c("invalid-geometry", `页面 ${t} 元素 ${o} 的包围盒必须为有限数值`, t, o);
+    const y = J(e, o), v = f.get(o), N = [...$, o], I = T || (v == null ? void 0 : v.hidden) === !0 || g.meta.hiddenByUser === !0, j = S || (v == null ? void 0 : v.locked) === !0 || g.meta.locked === !0 || g.meta.moveLocked === !0, B = l.kind === "group" && (g.meta.editable === "frame" || ((M = l.editInfo) == null ? void 0 : M.editable) === "frame");
+    if (w.push({
+      id: o,
+      kind: l.kind,
+      name: (v == null ? void 0 : v.name) ?? l.name ?? "",
+      altText: { title: y.title, description: y.descr },
+      path: N,
+      canvas: W(e, o),
+      bounds: { x: k.left, y: k.top, width: k.right - k.left, height: k.bottom - k.top },
+      editable: g.meta.editable,
+      hidden: I,
+      locked: j,
+      placeholder: z(e, n, o),
+      paragraphs: P(l, B)
+    }), l.kind === "group" && !B) {
+      const O = g.children ?? [];
+      if (O.length !== l.children.length)
+        throw new c("unaddressable-element", `页面 ${t} 组合 ${o} 的投影后代与编辑记录数量不符`, t, o);
+      l.children.forEach((A, C) => b(A, O[C], N, I, j));
+    }
+  }, E = i.elements.length - h.length;
+  if (E < 0) throw new c("invalid-document", `页面 ${t} 的投影根数量小于编辑根数量`, t);
+  return i.elements.forEach((l, o) => {
+    var T;
+    let $ = h[o - E];
+    if (o < E) {
+      const S = (T = l.editInfo) == null ? void 0 : T.origin, g = x.filter((k) => {
+        if (U(e, k) === l) return !0;
+        const y = e.elements[k].meta.origin;
+        return !!S && (y == null ? void 0 : y.part) === S.part && y.spid === S.spid;
+      });
+      if (g.length !== 1)
+        throw new c("unaddressable-element", `页面 ${t} 设计投影 ${l.name ?? o} 必须对应唯一编辑记录，实际 ${g.length} 个`, t);
+      $ = g[0];
+    }
+    b(l, $, [], !1, !1);
+  }), {
+    id: n,
+    number: t,
+    hidden: i.hidden === !0,
+    layout: a ? { id: a.id, name: a.name } : i.layoutName ? { id: "", name: i.layoutName } : null,
+    master: u ? { id: u.id, name: u.name } : null,
+    section: d ? { id: d.id, name: d.name } : null,
+    notes: i.notes ?? "",
+    elements: w
+  };
+}
+function K(e, n) {
+  if (!e || !e.meta || !Number.isFinite(e.meta.width) || !Number.isFinite(e.meta.height) || e.meta.width <= 0 || e.meta.height <= 0 || !["pptx", "ppt"].includes(e.meta.source))
+    throw new c("invalid-document", "describe 要求尺寸为正有限数值、来源为 pptx/ppt 的 EditDoc");
+  const t = e.slideOrder.map((r, i) => {
+    try {
+      return G(e, r, i + 1, n);
+    } catch (s) {
+      throw s instanceof c ? s : new c("invalid-document", `页面 ${i + 1}（${r}）读取失败：${s instanceof Error ? s.message : String(s)}`, i + 1);
+    }
+  });
+  return {
+    version: 1,
+    source: e.meta.source,
+    width: e.meta.width,
+    height: e.meta.height,
+    totalSlides: t.length,
+    totalElements: t.reduce((r, i) => r + i.elements.length, 0),
+    slides: t,
+    truncation: { reason: null, omittedSlides: 0, omittedElements: 0, next: null }
+  };
+}
+function Y(e, n = {}) {
+  return Q(n), R(K(e), n);
+}
+export {
+  c as DescribeError,
+  Y as describePresentation
+};

package/dist/design-dependencies.d.ts

@@ -0,0 +1,8 @@
+import type { EditDoc, SlideId } from './types';
+export declare function slidesForTheme(doc: EditDoc, themeId: string): ReadonlySet<SlideId>;
+export declare function slidesForLayout(doc: EditDoc, layoutId: string): ReadonlySet<SlideId>;
+export declare function slidesForMaster(doc: EditDoc, masterId: string): ReadonlySet<SlideId>;
+/** 页面树与换版式命令在模型落地前后各调用一次，热路径无需重扫全部页面。 */
+export declare function beforeSlideDesignChange(doc: EditDoc, slideId: SlideId): void;
+export declare function afterSlideDesignChange(doc: EditDoc, slideId: SlideId): void;
+export declare function releaseDesignDependencies(doc: EditDoc): void;

package/dist/design-projection-package.d.ts

@@ -0,0 +1,10 @@
+import { type OpcPackage } from '@web-ppt/core';
+import type { EditDoc } from './types';
+/** 母版元素的来源只含主题与母版属性；元素覆盖必须留到 effectiveElement 统一应用一次。 */
+export declare function masterSourceProjectionPackage(doc: EditDoc): OpcPackage | null;
+/**
+ * 母版元素覆盖物化到页面/版式重解析专用 OPC 视图；来源查询改走上面的属性视图，
+ * 因而页面能看到完整设计改动，母版元素自身又不会重复叠加同一份覆盖。
+ */
+export declare function designProjectionPackage(doc: EditDoc): OpcPackage | null;
+export declare function releaseDesignProjectionPackage(doc: EditDoc): void;

package/dist/design-target.d.ts

@@ -0,0 +1,10 @@
+import type { EditDoc, DesignTarget, ElementId, SlideId } from './types';
+export type CanvasTarget = {
+    readonly kind: 'slide';
+    readonly id: SlideId;
+} | DesignTarget;
+export declare function assertDesignTarget(doc: EditDoc, target: DesignTarget): void;
+export declare function canvasTargetOfElement(doc: EditDoc, id: ElementId): CanvasTarget;
+export declare function canvasChildren(doc: EditDoc, target: CanvasTarget): ElementId[];
+export declare function isCanvasRoot(doc: EditDoc, id: string): boolean;
+export declare function sameCanvas(left: CanvasTarget, right: CanvasTarget): boolean;

package/dist/design.d.ts

@@ -0,0 +1,3 @@
+import type { Slide } from '@web-ppt/core';
+import type { DesignTarget, EditDoc } from './types';
+export declare function toDesignCanvas(doc: EditDoc, target: DesignTarget): Slide;

package/dist/document-extensions.d.ts

@@ -0,0 +1,9 @@
+import type { EditDoc } from './types';
+import type { DocumentExtensionPatch } from './commands/types';
+/** 会话与保存入口只校验存储协议；未加载扩展的领域数据仍须能冷恢复。 */
+export declare function assertDocumentExtensions(value: unknown): void;
+export declare function isDocumentExtensionPatch(patch: {
+    path: readonly unknown[];
+}): patch is DocumentExtensionPatch;
+export declare function validateDocumentExtensionPatch(doc: EditDoc, patch: DocumentExtensionPatch, index: number): void;
+export declare function applyDocumentExtensionPatch(doc: EditDoc, patch: DocumentExtensionPatch): void;

package/dist/document.d.ts

@@ -1,4 +1,4 @@
-import type { Presentation, SlideElement } from '@web-ppt/core';
+import { type Presentation, type SlideElement } from '@web-ppt/core';
 import type { CreateDocOptions, EditDoc, EditableKind, ElementId, ElementMeta, SlideId } from './types';
 export declare function elementMetaOf(el: SlideElement, inherited: EditableKind, source: Presentation['source'], writablePart: string | null): ElementMeta;
 export declare function createDoc(pres: Presentation, opts?: CreateDocOptions): EditDoc;

package/dist/dynamic-projection.d.ts

@@ -0,0 +1,6 @@
+import type { SlideElement } from '@web-ppt/core';
+import type { EditDoc, SlideId } from './types';
+/** 稳定模型元素的组后代会分别投影，因此这里只处理当前节点。 */
+export declare const projectElementSlideFields: (doc: EditDoc, slideId: SlideId, element: SlideElement) => SlideElement;
+/** 版式虚拟节点没有 ElementRecord，动态字段必须在值树内递归求值。 */
+export declare const projectVirtualSlideFields: (doc: EditDoc, slideId: SlideId, element: SlideElement) => SlideElement;