@printstack/print-studio 0.0.0-stage → 0.1.1

package/core/errors.d.ts

@@ -0,0 +1,20 @@
+export interface DesignerExceptionOptions {
+    /** 根因（可选），保留原始错误与堆栈 */
+    cause?: unknown;
+    /** 机器码（可选），如 'document.invalid'，便于上报聚合与测试断言 */
+    code?: string;
+    /** 开发者向补充信息（作为 message）；缺省时与 userMessage 相同 */
+    detail?: string;
+}
+/** 设计器领域异常：全局兜底按 userMessage 提示使用者，message / cause 留给开发者 */
+export declare class DesignerException extends Error {
+    /** 机器码（可选） */
+    readonly code?: string;
+    /** 面向使用者的文案（全局兜底的 toast 直接展示） */
+    readonly userMessage: string;
+    constructor(userMessage: string, options?: DesignerExceptionOptions);
+}
+/** 类型守卫：全局兜底规则据此识别「需要给用户看文案」的领域异常 */
+export declare function isDesignerException(error: unknown): error is DesignerException;
+/** 把 unknown 错误转成可展示文本（边界降级 UI / 日志共用） */
+export declare function describeError(error: unknown): string;

package/core/events.d.ts

@@ -0,0 +1,311 @@
+import { AlignMode, SpacingDirection } from './align';
+import { DataSource, ElementGroup, ElementNode, FollowBlock, Guide, PageNode, PageTemplate, RepeatGroup } from './types';
+/** 与 store.view.settings 结构一致（结构化兼容，避免 core 反向依赖 designer） */
+export interface DesignerSettings {
+    clickToCreate: boolean;
+    gridSize: number;
+    /** 锁定全部参考线：禁止拖动 / 拖出新建 */
+    guidesLocked: boolean;
+    /** 多页面排列方式：纵向堆叠 / 横向一排 / 网格 */
+    pageLayoutMode: 'grid' | 'horizontal' | 'vertical';
+    previewWithData: boolean;
+    showGrid: boolean;
+    showGuides: boolean;
+    showMargins: boolean;
+    showRulers: boolean;
+    snapToElements: boolean;
+    snapToGrid: boolean;
+    snapToGuides: boolean;
+    snapToMargins: boolean;
+}
+export type DesignerDialogName = 'apply-template' | 'canvas-color' | 'datasource' | 'element' | 'follow' | 'follow-join' | 'follow-manager' | 'guide' | 'page' | 'preview' | 'repeat' | 'repeat-manager' | 'template-library' | null;
+export interface DesignerDialogState {
+    /** repeat 对话框：要编辑的循环区块 id（缺省 = 新建模式） */
+    groupId?: string;
+    /** guide 对话框：要编辑的参考线 id（缺省 = 新建模式） */
+    guideId?: string;
+    name: DesignerDialogName;
+    pageId?: string;
+    returnDialog?: 'follow-manager' | 'repeat-manager';
+}
+export type DesignerToastKind = 'error' | 'info' | 'success';
+export type { AlignMode } from './align';
+/** `action:<name>` 泛化事件的 payload：任意 store action 的调用记录 */
+export interface StoreActionEvent {
+    args: unknown[];
+    /** 带领域的 action 名称，如 'element.add' */
+    name: string;
+    result: unknown;
+}
+/** 无 payload 事件的空对象类型 */
+export type EmptyEvent = Record<string, never>;
+/**
+ * 设计器全局事件目录。命名约定：`<域>:<动作>`。
+ * 子 store 的 action 会自动发 `action:<子域>.<动作>`（见 StoreActionEvent）。
+ */
+export type DesignerEventMap = {
+    'action:failed': {
+        args: unknown[];
+        error: unknown;
+        name: string;
+        result: undefined;
+    };
+    /** 画布（页面外虚无区域）背景色变化：preset 为预设 id（'custom' 表示自定义），color 为最终 CSS 颜色值 */
+    'canvas:background-changed': {
+        color: string;
+        preset: string;
+    };
+    'clipboard:copied': {
+        nodes: ElementNode[];
+    };
+    'clipboard:cut': {
+        nodes: ElementNode[];
+    };
+    'clipboard:pasted': {
+        nodes: ElementNode[];
+    };
+    'command:after': {
+        args: unknown[];
+        id: string;
+    };
+    'command:before': {
+        args: unknown[];
+        id: string;
+    };
+    'command:error': {
+        error: unknown;
+        id: string;
+    };
+    'command:unknown': {
+        id: string;
+    };
+    /** 命令注册表内容变化（注册 / 注销 / 替换），菜单与快捷键索引据此重建 */
+    'commands:changed': EmptyEvent;
+    'context-menu:closed': EmptyEvent;
+    'context-menu:opened': {
+        x: number;
+        y: number;
+    };
+    'datasource:removed': {
+        key: string;
+    };
+    'datasource:upserted': {
+        source: DataSource;
+    };
+    'dialog:closed': EmptyEvent;
+    'dialog:opened': {
+        dialog: DesignerDialogState;
+    };
+    /** 任意文档数据变更（页面 / 元素 / 数据源 / 循环区块，含拖拽中间态） */
+    'document:changed': EmptyEvent;
+    'document:loaded': {
+        skippedTypes?: string[];
+    };
+    'document:new': EmptyEvent;
+    'document:renamed': {
+        name: string;
+    };
+    'drag:end': {
+        moved: boolean;
+        tag: string;
+    };
+    /** tag 标识交互种类：move / resize / rotate / marquee / create / guide */
+    'drag:start': {
+        tag: string;
+    };
+    'editing:changed': {
+        id: null | string;
+    };
+    'element-group:created': {
+        group: ElementGroup;
+    };
+    'element-group:removed': {
+        deleteElements: boolean;
+        id: string;
+    };
+    'element-group:updated': {
+        id: string;
+        patch: Partial<Omit<ElementGroup, 'id' | 'pageId'>>;
+    };
+    'element:added': {
+        node: ElementNode;
+        pageId: string;
+    };
+    'element:aligned': {
+        mode: AlignMode;
+    };
+    'element:distributed': {
+        mode: AlignMode;
+    };
+    'element:duplicated': {
+        sourceIds: string[];
+        sourceNodes: ElementNode[];
+    };
+    'element:flags-changed': {
+        id: string;
+        locked: boolean;
+        visible: boolean;
+    };
+    'element:nudged': {
+        deltaX: number;
+        deltaY: number;
+    };
+    'element:removed': {
+        ids: string[];
+        nodes: ElementNode[];
+    };
+    'element:renamed': {
+        id: string;
+        name: string;
+    };
+    'element:reordered': {
+        nodeId?: string;
+        pageId?: string;
+    };
+    'element:spacingDistributed': {
+        direction: SpacingDirection;
+    };
+    /** transient = 拖拽 / 输入等连续中间态（未入历史） */
+    'element:updated': {
+        node: ElementNode | null;
+        patch: Record<string, unknown>;
+        transient: boolean;
+    };
+    'elements:changed': EmptyEvent;
+    'follow-block:created': {
+        block: FollowBlock;
+    };
+    'follow-block:removed': {
+        id: string;
+    };
+    'follow-block:updated': {
+        id: string;
+        patch: Partial<FollowBlock>;
+    };
+    'guide:added': {
+        guide: Guide;
+        pageId: string;
+    };
+    'guide:cleared': {
+        pageId?: string;
+    };
+    'guide:moved': {
+        guideId: string;
+        pageId: string;
+        position: number;
+    };
+    'guide:removed': {
+        guideId: string;
+        pageId: string;
+    };
+    'history:changed': {
+        canRedo: boolean;
+        canUndo: boolean;
+    };
+    'history:pushed': {
+        canRedo: boolean;
+        canUndo: boolean;
+    };
+    'hover:changed': {
+        id: null | string;
+    };
+    'page:activated': {
+        pageId: string;
+    };
+    'page:added': {
+        pageId: string;
+    };
+    'page:copied': {
+        newPageId: string;
+        sourcePageId: string;
+    };
+    'page:removed': {
+        pageId: string;
+    };
+    'page:updated': {
+        pageId: string;
+        patch: Partial<Pick<PageNode, 'background' | 'height' | 'margins' | 'name' | 'templateId' | 'width'>>;
+    };
+    'plugin:disposed': {
+        name: string;
+    };
+    'plugin:registered': {
+        name: string;
+    };
+    'plugin:state-changed': {
+        name: string;
+        status: string;
+    };
+    'repeat-group:created': {
+        group: RepeatGroup;
+    };
+    'repeat-group:removed': {
+        deleteElements: boolean;
+        id: string;
+    };
+    'repeat-group:updated': {
+        id: string;
+        patch: Partial<Omit<RepeatGroup, 'id' | 'pageId'>>;
+    };
+    'selection:changed': {
+        ids: string[];
+        nodes: ElementNode[];
+    };
+    'settings:changed': {
+        settings: DesignerSettings;
+    };
+    'state:changed': EmptyEvent;
+    'template:added': {
+        template: PageTemplate;
+    };
+    'template:applied': {
+        pageIds: string[];
+        templateId: string;
+    };
+    'template:edit-changed': {
+        templateId: null | string;
+    };
+    'template:removed': {
+        id: string;
+    };
+    'template:updated': {
+        id: string;
+        patch: Partial<Pick<PageTemplate, 'background' | 'baseTemplateId' | 'evenPages' | 'facingPages' | 'name' | 'oddPages'>>;
+    };
+    'toast:shown': {
+        kind: DesignerToastKind;
+        text: string;
+    };
+    'tool:changed': {
+        tool: string;
+    };
+    'zoom:changed': {
+        zoom: number;
+    };
+} & {
+    /** 泛化兜底：任意 store action 自动触发，如 on('action:history.undo', …) */
+    [key: `action:${string}`]: StoreActionEvent;
+};
+type WildcardHandler<Events> = (type: keyof Events, event: Events[keyof Events]) => void;
+/**
+ * mitt 的强类型包装：
+ * - on/once 返回解绑函数（方便插件式生命周期管理）；
+ * - 支持 `'*'` 通配监听所有事件；
+ * - emit 时通配监听器同步收到 (type, payload)。
+ */
+export declare class TypedEventBus<Events extends object> {
+    private emitter;
+    private wildcard;
+    emit<K extends keyof Events>(type: K, event: Events[K]): void;
+    off<K extends keyof Events>(type: K, handler: (event: Events[K]) => void): void;
+    /** 清空全部监听（含通配），用于整体销毁 */
+    offAll(): void;
+    /** 监听事件，返回解绑函数 */
+    on<K extends keyof Events>(type: K, handler: (event: Events[K]) => void): () => void;
+    /** 通配监听所有事件 */
+    on(type: '*', handler: WildcardHandler<Events>): () => void;
+    /** 监听一次后自动解绑，返回解绑函数 */
+    once<K extends keyof Events>(type: K, handler: (event: Events[K]) => void): () => void;
+}
+/** 全局事件总线单例（由 editor context 创建并共享，pointer-drag 等核心模块亦可直接发射） */
+export declare function getEventBus(): TypedEventBus<DesignerEventMap>;

package/core/flow-expand.d.ts

@@ -0,0 +1,13 @@
+import { DataContext, WarningCollector } from './data-context';
+import { PageLayout } from './page-layout';
+import { ElementNode, PageNode, PrintDocument } from './types';
+interface FlowExpandContext {
+    context: DataContext;
+    document: PrintDocument;
+    getPage: (draftIndex: number) => PageLayout;
+    page: PageNode;
+    resolveNode?: (node: ElementNode) => ElementNode;
+    warnings: WarningCollector;
+}
+export { getLayoutBounds } from './follow-layout';
+export declare function expandFlowPage(options: FlowExpandContext): ElementNode[][];

package/core/follow-block.d.ts

@@ -0,0 +1,9 @@
+import { FollowBlock, LayoutTarget, PrintDocument } from './types';
+export declare function layoutTargetKey(target: LayoutTarget): string;
+export declare function resolveLayoutTarget(document: PrintDocument, pageId: string, target: LayoutTarget): undefined | {
+    elementIds: string[];
+    name: string;
+};
+export declare function getFollowBlockIssue(document: PrintDocument, block: FollowBlock): string | undefined;
+export declare function validateFollowBlocks(document: PrintDocument): void;
+export declare function pruneFollowBlocks(document: PrintDocument): void;

package/core/follow-layout.d.ts

@@ -0,0 +1,8 @@
+import { Rect } from './geometry';
+import { ElementLayoutPatch, ElementNode, PrintDocument } from './types';
+export declare function getLayoutBounds(nodes: ElementNode[]): null | Rect;
+export declare function computeFollowLayout(document: PrintDocument): ElementLayoutPatch[];
+export declare function computeFollowGapUpdates(document: PrintDocument, movedElementIds: readonly string[], reshapedElementIds?: readonly string[]): {
+    gap: number;
+    id: string;
+}[];

package/core/geometry.d.ts

@@ -0,0 +1,110 @@
+import { ElementNode } from './types';
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Rect {
+    height: number;
+    width: number;
+    x: number;
+    y: number;
+}
+export declare const HANDLE_IDS: readonly ["nw", "n", "ne", "e", "se", "s", "sw", "w"];
+export type HandleId = (typeof HANDLE_IDS)[number];
+/** 每个缩放手柄在元素局部坐标系（u = 元素右方向, v = 元素下方向）中的方向分量 */
+export declare const HANDLE_DIRS: Record<HandleId, {
+    u: number;
+    v: number;
+}>;
+export declare function rectsIntersect(a: Rect, b: Rect): boolean;
+export declare function rectContainsPoint(rect: Rect, point: Point): boolean;
+/** 角度归一化到 [-180, 180)，消除连续拖拽累积出的 735° 之类的脏值 */
+export declare function normalizeDegrees(deg: number): number;
+/** 旋转后元素在页面坐标系中的轴对齐包围盒（AABB） */
+export declare function rotatedAabb(rect: Rect, rotationDeg: number): Rect;
+export declare function unionRects(rects: Rect[]): null | Rect;
+/**
+ * 拖拽缩放手柄时计算元素新矩形。
+ *
+ * 关键点：元素绕自身中心旋转，锚点（与被拖手柄相对的边/角）在页面坐标系
+ * 中保持不动。算法先把手柄位移从页面坐标系旋转变换到元素局部坐标系
+ * （u/v 轴），得到新宽高，再由固定锚点反推新中心，最后换回页面坐标系。
+ */
+export declare function resizeRectByHandle(start: Rect, rotationDeg: number, handle: HandleId, mouse: Point, startMouse: Point, options?: {
+    aspectRatio?: number;
+    keepRatio?: boolean;
+    minHeight?: number;
+    minSize?: number;
+    minWidth?: number;
+}): Rect;
+/** 多选整体缩放：把节点矩形关于锚点做线性缩放 */
+export declare function scaleRectAboutAnchor(rect: Rect, anchor: Point, sx: number, sy: number): Rect;
+/** 计算从元素顶部中心向上的旋转手柄锚点（页面坐标系） */
+export declare function rotateHandleAnchor(rect: Rect, rotationDeg: number, offsetMm: number): Point;
+export declare function clampRectToSize(rect: Rect, maxWidth: number, maxHeight: number): Rect;
+/** 点集的轴对齐包围盒（空点集返回 1×1 的零位矩形，避免调用方判空） */
+export declare function pointsAabb(points: Point[]): Rect;
+export declare function translatePoints(points: Point[], dx: number, dy: number): Point[];
+/** 把点集关于锚点做线性缩放（多选整体缩放 / 定界框数值缩放共用） */
+export declare function scalePointsAboutAnchor(points: Point[], anchor: Point, sx: number, sy: number): Point[];
+/** 点绕中心旋转（deg，顺时针为正） */
+export declare function rotatePointAround(point: Point, center: Point, rotationDeg: number): Point;
+/** 点集绕自身包围盒中心整体旋转（deg，顺时针为正），点数不足时不旋转 */
+export declare function rotatePointsAroundAabbCenter(points: Point[], deltaDeg: number): Point[];
+/**
+ * 点集方向角：首末点连线的方向角（deg，-180 ~ 180，屏幕坐标系 y 向下，
+ * 与节点 rotation 同一约定——rotation 每转过 1° 方向角也增加 1°）。
+ */
+export declare function pointsDirectionDeg(points: Point[]): number;
+/** 点集首末点的直线距离（线条的「长度」：属性面板宽度字段对线条展示 / 编辑该值） */
+export declare function pointsSpanLength(points: Point[]): number;
+/** 末点网格微调：使首末点方向角最接近 targetDeg（角度录入精确化） */
+export declare function snapSegmentAngle(first: Point, last: Point, targetDeg: number, keep?: (candidate: Point) => boolean): Point;
+/** 末点网格微调：使首末点距离最接近 targetLength（长度录入精确化） */
+export declare function snapSegmentLength(first: Point, last: Point, targetLength: number, keep?: (candidate: Point) => boolean): Point;
+/**
+ * 数值录入：保持首点与方向不变，把末点放到目标长度处。
+ * 属性面板「长度」字段编辑线条用：方向取当前显示角度（两位小数）作不变量，
+ * 避免上次端点舍入的残差滚进下次方向角造成累积漂移；吸附时优先保持
+ * 显示角度不变，使改长度不联动角度。
+ */
+export declare function segmentEndpointAtLength(first: Point, last: Point, lengthMm: number): Point;
+/**
+ * 数值录入：保持首点与长度不变，把末点转到目标方向角。
+ * 属性面板「旋转」字段编辑线条用：长度取当前显示长度（两位小数）作不变量，
+ * 吸附时优先保持显示长度不变，使改角度不联动长度，吸附策略同上。
+ */
+export declare function segmentEndpointAtAngle(first: Point, last: Point, angleDeg: number): Point;
+/**
+ * 角度约束：把 moved 约束到相对 anchor 的 stepDeg 倍数方向上（Shift 画 45° 直线）。
+ * 半径取两点的原始距离，方向按象限吸附到最近的约束角。
+ */
+export declare function constrainPointToAngle(anchor: Point, moved: Point, stepDeg?: number): Point;
+/**
+ * 轴对齐意图吸附：moved 落在 anchor 的水平/竖直容差带内时精确取齐，
+ * 消除手抖造成的毫米级倾斜（点驱动元素拖拽创建用）。
+ * 水平判定优先：线条以横向绘制为主，纵偏移在容差内即视为水平意图。
+ */
+export declare function alignPointToAxis(anchor: Point, moved: Point, toleranceMm: number): Point;
+/** 点到线段的最短距离 */
+export declare function distancePointToSegment(point: Point, a: Point, b: Point): number;
+/** 线段与轴对齐矩形是否相交（端点在矩形内也算相交） */
+export declare function segmentIntersectsRect(a: Point, b: Point, rect: Rect): boolean;
+/** 折线（依次连接的顶点序列）与轴对齐矩形是否相交；少于 2 点时退化为端点包含 */
+export declare function pathIntersectsRect(points: Point[], rect: Rect): boolean;
+/** 参与几何计算的节点字段：允许传入实时节点或交互开始时的几何快照 */
+export type NodeGeometry = Pick<ElementNode, 'height' | 'points' | 'rotation' | 'width' | 'x' | 'y'>;
+/** 节点几何快照：交互拖拽期间以此为基准计算补丁，避免读到被逐帧修改的响应式节点 */
+export declare function nodeGeometrySnapshot(node: NodeGeometry): NodeGeometry;
+/** 判断节点是否为点驱动（以实际数据为准，能力定义只决定交互形态），收窄 points 为必填 */
+export declare function isPointNode<T extends {
+    points?: Point[];
+}>(node: T): node is T & {
+    points: Point[];
+};
+/** 由新点集生成完整补丁：points 与包围盒、rotation 一起同步 */
+export declare function pointsNodePatch(node: NodeGeometry, points: Point[]): Partial<ElementNode>;
+/** 平移节点：点驱动元素连带平移点集 */
+export declare function translateNodePatch(node: NodeGeometry, dx: number, dy: number): Partial<ElementNode>;
+/** 关于锚点缩放节点：点驱动元素缩放点集，普通元素缩放定界框 */
+export declare function scaleNodePatch(node: NodeGeometry, anchor: Point, sx: number, sy: number, minSize?: number): Partial<ElementNode>;

package/core/index.d.ts

@@ -0,0 +1,5 @@
+export { createElement, createPage, createTemplate, deserializeDocument, DOCUMENT_VERSION, } from './document-model';
+export { defineElement, ElementRegistry, elementRegistry, } from './element-registry';
+export type { ElementDefinition, ElementOverflowContext, ElementOverflowResult, } from './element-registry';
+export { DesignerException } from './errors';
+export * from './types';

package/core/inspector.d.ts

@@ -0,0 +1,27 @@
+import { ElementRegistry } from './element-registry';
+import { ElementNode, InspectorBinding, InspectorField, InspectorSection, PrintDocument } from './types';
+export declare function getContextInspectorSections(sections: InspectorSection[], document: PrintDocument, node: ElementNode, registry: ElementRegistry): InspectorSection[];
+export declare function getPanelInspectorSections(sections: InspectorSection[], node: ElementNode): InspectorSection[];
+export declare function getBatchInspectorSections(sections: InspectorSection[], node: ElementNode): InspectorSection[];
+export declare function getVisibleInspectorSections(sections: InspectorSection[], node: ElementNode, options?: {
+    includeAdvanced?: boolean;
+}): InspectorSection[];
+export declare function readInspectorValue(node: ElementNode, field: InspectorField): unknown;
+export declare function getPropsPath(props: Record<string, unknown>, key: string): unknown;
+/**
+ * 点路径写入：返回以首段键为根的更新补丁（供 updateProps 浅合并使用），
+ * 中间层级不存在时自动补齐对象框架。
+ */
+export declare function writePropsPatch(props: Record<string, unknown>, key: string, value: unknown): Record<string, unknown>;
+/**
+ * 文本类字段声明了可追加的表达式绑定时，使用变量文本输入：
+ * 变量以原子节点内嵌于文本，替代整体「绑定」按钮。
+ */
+export declare function usesVariableText(field: InspectorField): boolean;
+export declare const expressionBinding: Required<Pick<InspectorBinding, 'isBound' | 'read' | 'readPaths' | 'write'>>;
+/**
+ * 属性绑定策略：读写 node.bindings 中的路径。
+ * bindingKey 缺省取 field.key；当绑定目标与字段 key 不一致时显式指定
+ * （如表格「列定义」字段绑定的实际是 bindings.rows）。
+ */
+export declare function propertyBinding(mode: 'collection' | 'field', bindingKey?: string): InspectorBinding;

package/core/layout-references.d.ts

@@ -0,0 +1,8 @@
+import { ElementGroup, FollowBlock, PrintDocument, RepeatGroup } from './types';
+export interface LayoutReferences {
+    elementGroups: ElementGroup[];
+    followBlocks: FollowBlock[];
+    repeatGroups: RepeatGroup[];
+}
+export declare function captureLayoutReferences(document: PrintDocument, elementIds: string[]): LayoutReferences;
+export declare function copyLayoutReferences(document: PrintDocument, references: LayoutReferences, elementIds: Map<string, string>, pageId: string, createId: (prefix: string) => string): void;

package/core/overflow-expand.d.ts

@@ -0,0 +1,7 @@
+import { DataContext, WarningCollector } from './data-context';
+import { ElementNode, PageNode, PrintDocument } from './types';
+export declare function preparePageOverflow(document: PrintDocument, page: PageNode, context: DataContext, warnings: WarningCollector): {
+    continuations: PageNode[];
+    page: PageNode;
+    resolveNode: (node: ElementNode) => ElementNode;
+};

package/core/page-extensions.d.ts

@@ -0,0 +1,26 @@
+import { ElementRegistry } from './element-registry';
+import { ElementNode, PageTemplate, PrintDocument } from './types';
+/** 从文档关系推导承载元素的角色，不依赖当前设计器编辑状态。 */
+export declare function getPageExtensionContext(document: PrintDocument, node: ElementNode, registry: ElementRegistry): {
+    capability: {
+        rebind: (node: ElementNode, purpose: string, templateId: string, elementId: string) => void;
+        reconcile?: (document: PrintDocument, node: ElementNode) => void;
+        references: (node: ElementNode) => {
+            elementId: string;
+            purpose: string;
+            templateId: string;
+        }[];
+        resolveTarget?: (source: ElementNode, target: ElementNode, purpose: string) => ElementNode;
+        targetInspectorFields?: (purpose: string) => import('./types').InspectorField[];
+    };
+    purpose: string;
+    source: ElementNode;
+} | undefined;
+export declare function resolvePageExtensionNode(document: PrintDocument, node: ElementNode, registry: ElementRegistry): ElementNode;
+export declare function reconcilePageExtensions(document: PrintDocument, node: ElementNode, registry: ElementRegistry): void;
+export declare function assertRequiredElementMutation(document: PrintDocument, node: ElementNode, patch?: Partial<ElementNode>): void;
+export declare function validateTemplateDependencies(template: PageTemplate): void;
+/** 复制内部资源并重新绑定引用，避免副本与原元素共享可编辑资源。也迁移旧版引用。 */
+export declare function copyPageExtensions(document: PrintDocument, source: ElementNode, target: ElementNode, registry: ElementRegistry, resources?: PrintDocument): void;
+export declare function prunePageExtensions(document: PrintDocument, registry?: ElementRegistry): void;
+export declare function assertPageExtensionReferences(document: PrintDocument, node: ElementNode, registry: ElementRegistry): void;

package/core/page-layout.d.ts

@@ -0,0 +1,6 @@
+import { Rect } from './geometry';
+import { PageMargins, PageNode } from './types';
+export type PageLayout = Pick<PageNode, 'height' | 'margins' | 'width'>;
+export declare function resolvePageLayout(page: PageLayout): PageLayout;
+export declare function resolvePageMargins(margins?: PageMargins): PageMargins;
+export declare function getPageContentRect(page: PageLayout): Rect;

package/core/parser-version.d.ts

@@ -0,0 +1,2 @@
+export declare const INITIAL_PARSER_VERSION = "1.0.0";
+export declare function resolveParserVersion(value: unknown): string;

package/core/pointer-drag.d.ts

@@ -0,0 +1,33 @@
+import { DesignerEventMap, TypedEventBus } from './events';
+import { Point } from './geometry';
+export declare function registerDragScope(root: Element, events: TypedEventBus<DesignerEventMap>): () => void;
+export interface DragSession {
+    /** 原始 PointerEvent */
+    event: PointerEvent;
+    /** 最近一次 move 事件的位置 */
+    lastPoint: Point;
+    /** 本次拖拽起始的页面坐标（由调用方换算好传入） */
+    startPoint: Point;
+}
+export interface PointerDragOptions {
+    cancelOnBlur?: boolean;
+    onCancel?: (session: DragSession, moved: boolean) => void;
+    onEnd?: (session: DragSession, moved: boolean) => void;
+    onMove?: (session: DragSession) => void;
+    pointerId: number;
+    /** 指针按下时的屏幕坐标，仅用于阈值判定；缺省时退回用 startPoint（毫米）比较 */
+    startClient?: Point;
+    /** 位置变化阈值（CSS px）：小于该值不触发 onMove，用于区分"点击"与"拖动" */
+    startPoint: Point;
+    /** 交互标识（move / resize / rotate / marquee / create / guide），随 drag 事件广播 */
+    tag?: string;
+    /** 触发拖拽的元素，将对其进行 setPointerCapture */
+    target: Element;
+    threshold?: number;
+}
+export interface PointerDragHandle {
+    (): void;
+    cancel(): void;
+}
+/** 返回幂等结束函数，供调用方在卸载或替换会话时释放监听。 */
+export declare function startPointerDrag(options: PointerDragOptions): PointerDragHandle;

package/core/render/barcode.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 条形码渲染原语：基于 JsBarcode，提供 SVG（HTML 用，矢量打印质量更好）
+ * 与 Canvas（PDF 用）两种输出，并做"包含缩放"处理以适配元素框。
+ * 两种输出使用相同的原始参数，保证视觉一致。
+ */
+export interface BarcodeOptions {
+    background: string;
+    displayValue: boolean;
+    /** 字号（pt） */
+    fontSize: number;
+    format: string;
+    lineColor: string;
+    /** 静默区边距（mm） */
+    margin: number;
+}
+export interface BarcodeRenderResult {
+    height: number;
+    /** SVG 标记，width/height 属性为原始渲染尺寸（CSS px） */
+    svg: string;
+    /** 内容宽高（CSS px） */
+    width: number;
+}
+/** 渲染失败（值与格式不匹配等）返回 null，调用方显示占位提示 */
+export declare function renderBarcodeSvg(value: string, options: BarcodeOptions): BarcodeRenderResult | null;
+/** 渲染到 canvas（同步），scale 为物理像素放大倍数，提高打印清晰度 */
+export declare function renderBarcodeCanvas(value: string, options: BarcodeOptions, targetWidthPx: number, targetHeightPx: number, scale?: number): HTMLCanvasElement | null;

package/core/render/canvas.d.ts

@@ -0,0 +1,3 @@
+export type RenderCanvas = HTMLCanvasElement | OffscreenCanvas;
+export declare function createRenderCanvas(width?: number, height?: number): RenderCanvas;
+export declare function getRenderContext(canvas: RenderCanvas): CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;

package/core/render/color.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 颜色工具：属性中统一存储 hex 字符串（#rrggbb），渲染时按需转换。
+ */
+export interface Rgb {
+    b: number;
+    g: number;
+    r: number;
+}
+export interface Rgba extends Rgb {
+    alpha: number;
+}
+/** 解析 #rgb / #rrggbb，无效返回 null（代表"无色/透明"） */
+export declare function parseHexColor(value: unknown): null | Rgb;
+export declare function parseCssColor(value: unknown): null | Rgba;
+export declare function resolvePdfColor(value: unknown): null | string;
+/** "transparent" / 空串 / 无效值统一视为无色 */
+export declare function isNoColor(value: unknown): boolean;
+export declare function rgbToCss(rgb: Rgb): string;
+export declare function resolvePageBackground(value: string | undefined): string;

package/core/render/dash.d.ts

@@ -0,0 +1,4 @@
+import { DashStyle } from '../types';
+export declare const DASH_PATTERNS: Record<DashStyle, number[]>;
+export declare function dashArrayFor(style: unknown): number[];
+export declare function dashArrayToCss(pattern: number[]): string;