131 lines
11 KiB
TypeScript
131 lines
11 KiB
TypeScript
/**
|
||
* 图片元信息异步到达后，把默认尺寸修正合回原创建历史的纯规划器。
|
||
* 同时修正后续历史的 before，使 undo/redo 保持可回放；不会改写已经冻结的请求 body。
|
||
* 持久授权、Root 版本检查和发布由 coordinator/editor 完成。
|
||
*/
|
||
import type { Change, CreationSizeEffect, Document, ElementRecord, Geometry, HistoryState, Id, Registry, Target } from './types.ts';
|
||
import { applyChanges, invert, validateDocument } from './document.ts';
|
||
import { closeNumber, unitScale } from './units.ts';
|
||
import { equal, fault, freeze, readMap, validJson } from './values.ts';
|
||
|
||
/** 校验恢复图像中的尺寸 effect；未知协议与格式非法分别拒绝，不能猜旧效果含义。 */
|
||
export function validateCreationSizeEffect(value: unknown): asserts value is CreationSizeEffect {
|
||
const effect = value as CreationSizeEffect | undefined;
|
||
if (!effect || effect.version !== 1 || effect.kind !== 'creation-size') throw fault('history_effect_interpreter_unavailable');
|
||
if (!validJson(effect) || typeof effect.entryId !== 'string' || !effect.entryId || typeof effect.target?.id !== 'string' || !effect.target.id
|
||
|| !Number.isSafeInteger(effect.target.incarnation) || effect.target.incarnation < 1
|
||
|| !effect.size || ![effect.size.width, effect.size.height].every(value => typeof value === 'number' && Number.isFinite(value) && value > 0)) throw fault('invalid_creation_size_effect');
|
||
}
|
||
|
||
/** A pure proposal, not a publication API. The coordinator must still validate a
|
||
* durable sizing grant and record a recoverable history effect before adopting it.
|
||
* Already-issued operation bodies are deliberately outside this function.
|
||
*/
|
||
/** 仅原创建仍在 undo、目标仍活且未被用户缩放时，准备默认尺寸与历史修正。
|
||
* 返回候选 document/history/changes，不发布状态；输入须来自已捕获的不可变文档与历史。
|
||
* 这里按 geometry.resize 能力判定，不限定 componentId 必须是 image；图片授权条件由外层 grant 决定。 */
|
||
export function planCreationSize(document: Document, history: HistoryState, registry: Registry,
|
||
entryId: Id, target: Target, size: { readonly width: number; readonly height: number }) {
|
||
/** 统一将失败绑定到目标 ID，便于调用方解释为何不能再自动调整。 */
|
||
const fail = (code: string): never => { throw fault(code, [target.id]); };
|
||
if (![size.width, size.height].every(value => Number.isFinite(value) && value > 0)) fail('invalid_creation_size');
|
||
// 创建项必须仍在已应用 undo 时间线上；已撤销到 redo、被淘汰或目标换代的尺寸结果不能采用。
|
||
const index = history.undo.indexOf(entryId), entry = history.entries.get(entryId);
|
||
const current = document.elements.get(target.id);
|
||
if (index < 0 || !entry || current?.incarnation !== target.incarnation || current.structure !== 'node') fail('creation_size_target_changed');
|
||
// 必须在指定 entry 中找到唯一一次同 incarnation 的节点创建，不能猜其它创建记录。
|
||
const creations = entry!.changes.filter(change => change.kind === 'element' && change.id === target.id && !change.before && change.after?.incarnation === target.incarnation);
|
||
if (creations.length !== 1 || creations[0].kind !== 'element' || creations[0].after?.structure !== 'node') fail('creation_size_entry_mismatch');
|
||
const created = creations[0].after as ElementRecord & { structure: 'node' };
|
||
if (registry.resolve(current!) !== 'known' || !registry.supports(current!, 'geometry.resize')) fail('unsupported_capability');
|
||
// 以创建时的视觉尺寸为基准；目标换 owner 后 unitScale 可变，但视觉基线仍可比较。
|
||
const units = unitScale(created.data.presentation);
|
||
const baseline = { width: created.geometry.width / units, height: created.geometry.height / units };
|
||
const ratio = { width: size.width / baseline.width, height: size.height / baseline.height };
|
||
/** 调用处已按 target.id 取记录，这里再限制 incarnation 与 node 结构；不单独比较元素 ID。 */
|
||
const matches = (element: ElementRecord | undefined) => element?.incarnation === target.incarnation && element.structure === 'node';
|
||
/** 比较宽高除 unitScale 后的视觉值，移动/换 owner 不等同于用户主动缩放。 */
|
||
const unchanged = (element: ElementRecord | undefined) => matches(element) && element!.structure === 'node'
|
||
&& closeNumber(element!.geometry.width / unitScale(element!.data.presentation), baseline.width)
|
||
&& closeNumber(element!.geometry.height / unitScale(element!.data.presentation), baseline.height);
|
||
if (!unchanged(current)) fail('creation_size_user_resized');
|
||
/** 保留位置和旋转，只将需要继承默认修正的宽高按当前 ratio 缩放。 */
|
||
const scaled = (geometry: Geometry): Geometry => freeze({ ...geometry, width: geometry.width * ratio.width, height: geometry.height * ratio.height });
|
||
// Rewind on private roots. applyChanges intentionally preserves historical
|
||
// incarnations here; this is inspection, not a user-visible delete/restore.
|
||
let original = document;
|
||
// 从创建项起回退全部已应用项，得到创建前私有基线；此处用 applyChanges 而非 planHistoryChanges，
|
||
// 因而允许检查途中存在历史代次/墓碑组合，不把它们作为最终文档发布。
|
||
const applied = history.undo.slice(index);
|
||
for (const id of [...applied].reverse()) original = applyChanges(original, invert(history.entries.get(id)!.changes));
|
||
// original 追踪旧时间线，amended 追踪修正后的时间线；inheriting 只在匹配创建之后开启。
|
||
let amended = original, inheriting = false;
|
||
const entries = new Map(history.entries);
|
||
// 先按 undo 的正向顺序重建已应用项，再倒序遍历 redo 栈还原未来重做时间线。
|
||
const timeline = [...applied, ...[...history.redo].reverse()];
|
||
for (let cursor = 0; cursor < timeline.length; cursor++) {
|
||
const id = timeline[cursor], source = entries.get(id)!;
|
||
const end = applyChanges(original, source.changes), isApplied = cursor < applied.length;
|
||
if (isApplied && !unchanged(end.elements.get(target.id))) fail('creation_size_user_resized');
|
||
// A future resize preserves each dimension explicitly changed by the user.
|
||
// Its before value and unchanged dimensions may inherit the default correction.
|
||
const futureResize = !isApplied && inheriting && matches(end.elements.get(target.id)) && !unchanged(end.elements.get(target.id));
|
||
let resizeConsumed = false;
|
||
/** redo 中按宽/高分别判断：被用户改过的维度将 ratio 置 1，保留其 after；
|
||
* before 重取修正时间线，未被用户改变的另一维仍可继承默认比例。每项最多消费一次。 */
|
||
const preserveFutureResize = () => {
|
||
if (!futureResize || resizeConsumed) return;
|
||
const value = end.elements.get(target.id) as ElementRecord & { structure: 'node' };
|
||
if (!closeNumber(value.geometry.width / unitScale(value.data.presentation), baseline.width)) ratio.width = 1;
|
||
if (!closeNumber(value.geometry.height / unitScale(value.data.presentation), baseline.height)) ratio.height = 1;
|
||
resizeConsumed = true;
|
||
};
|
||
const changes: Change[] = [];
|
||
// 目标整记录/geometry 变化从 amended 重取 before；其它变化保留原条件，继续用 applyChanges 校验。
|
||
for (const change of source.changes) {
|
||
let next = change;
|
||
// 整记录变化也要重取真实 before；其它对象/字段沿用原变化，保证整条时间线仍按原次序检查。
|
||
if (change.kind === 'element' && change.id === target.id) {
|
||
const before = amended.elements.get(target.id) ?? null;
|
||
const birth = id === entryId && change === creations[0];
|
||
// 从创建点开始继承；遇到删除或其它 incarnation 时停止，不能跨生命周期改尺寸。
|
||
if (birth) inheriting = true;
|
||
else preserveFutureResize();
|
||
const after = change.after && inheriting && change.after.incarnation === target.incarnation && change.after.structure === 'node'
|
||
? freeze({ ...change.after, geometry: scaled(change.after.geometry) }) : change.after;
|
||
next = freeze({ ...change, before, after });
|
||
if (!change.after || change.after.incarnation !== target.incarnation) inheriting = false;
|
||
} else if (change.kind === 'field' && change.target.id === target.id && change.target.incarnation === target.incarnation && change.field === 'geometry') {
|
||
const before = amended.elements.get(target.id);
|
||
if (before?.structure !== 'node') fail('creation_size_target_changed');
|
||
preserveFutureResize();
|
||
next = freeze({ ...change, before: (before as ElementRecord & { structure: 'node' }).geometry, after: inheriting ? scaled(change.after as Geometry) : change.after });
|
||
}
|
||
amended = applyChanges(amended, [next]);
|
||
changes.push(next);
|
||
}
|
||
// 整项完成后再推进旧时间线；只有变化内容确实不同才替换 entries 中这一项，operationIds/标签保持。
|
||
original = end;
|
||
if (!equal(changes, source.changes)) entries.set(id, freeze({ ...source, changes }));
|
||
}
|
||
// Publishable proposal changes only the currently live geometry. Replaying
|
||
// redo above was validation; it must never become the working document.
|
||
// 上方 replay redo 只为校验/修正历史；当前工作文档仅修改当前活元素，不提前重做未来项。
|
||
const after = freeze({ ...(current as ElementRecord & { structure: 'node' }).geometry,
|
||
width: (current as ElementRecord & { structure: 'node' }).geometry.width * size.width / baseline.width,
|
||
height: (current as ElementRecord & { structure: 'node' }).geometry.height * size.height / baseline.height });
|
||
const changes: readonly Change[] = equal(after, (current as ElementRecord & { structure: 'node' }).geometry) ? [] : freeze([
|
||
{ kind: 'field', target, field: 'geometry', before: (current as ElementRecord & { structure: 'node' }).geometry, after },
|
||
]);
|
||
const nextDocument = applyChanges(document, changes);
|
||
validateDocument(nextDocument, registry);
|
||
// 调用已安装 resize handler，把其生成变化应用后的目标记录与直接候选比较；不一致就拒绝。
|
||
// 这能执行组件实际实现的限制，不凭 capability 名称宣称所有组件都有 min/max/aspect 政策。
|
||
const handler = registry.handlers.get(current!.componentId)?.get('geometry.resize');
|
||
const proposed = handler!({ element: current!, input: freeze({ patch: { width: after.width, height: after.height } }) });
|
||
for (const change of proposed) if (change.target.id !== target.id || change.target.incarnation !== target.incarnation || change.field !== 'geometry') fail('invalid_handler_change');
|
||
if (!equal(applyChanges(document, proposed).elements.get(target.id), nextDocument.elements.get(target.id))) fail('creation_size_constraint');
|
||
// 仅返回当前几何 changes，历史 entries 是整条修正时间线；两栈顺序沿用，不把上方 redo 检查变成实际重做。
|
||
return Object.freeze({ document: nextDocument, changes, history: Object.freeze({ undo: history.undo, redo: history.redo, entries: readMap(entries) }) });
|
||
}
|