/** * 视图局部的屏幕空间浮层索引。保存位置、目标代次与焦点/输入法状态,独立于业务文档和撤销历史。 * 同 ID 浮层重新注册时获得新 token,旧组件迟到清理不能删掉新浮层。 */ import type {Target} from '../canvas-core/types.ts'; import type {Rect} from '../canvas-core/geometry.ts'; import {createPaintIndex} from './paint-index.ts'; import {fault} from '../canvas-core/values.ts'; /** bounds 使用屏幕空间;target 仍是真实元素 ID+代次,viewId 限定所属交互视图。 */ export type OverlayEntry={readonly id:string;readonly viewId:string;readonly placement:string;readonly target:Target;readonly bounds:Rect;readonly focused:boolean;readonly composing:boolean}; /** Ephemeral screen-space placements. A lease prevents late cleanup from removing a replacement. */ /** 为一个有效 viewId 创建租约表、冻结快照和可重建 paint 网格。 */ export function createOverlayIndex(viewId:string){ if(typeof viewId!=='string'||!viewId)throw fault('view_session_required');let serial=0,snapshot:readonly OverlayEntry[]=Object.freeze([]);const entries=new Map(),listeners=new Set<()=>void>(),index=createPaintIndex(); /** 从当前条目重建快照和空间索引后通知;这里只同步位置事实,不决定浮层 DOM 的挂载。 */ function publish(){snapshot=Object.freeze([...entries.values()].map(row=>row.entry));index.sync(snapshot.map(entry=>({id:entry.id,bounds:entry.bounds})));for(const listener of [...listeners])listener();} /** 复制并冻结目标/矩形,验证身份和位置;复用 paint 索引校验矩形,拒绝不合法的外部边界。 */ function capture(id:string,value:Omit):OverlayEntry{if(typeof id!=='string'||!id||typeof value.placement!=='string'||!value.placement||typeof value.target.id!=='string'||!value.target.id||!Number.isSafeInteger(value.target.incarnation)||value.target.incarnation<1)throw fault('invalid_overlay');const entry=Object.freeze({...value,id,viewId,target:Object.freeze({...value.target}),bounds:Object.freeze({...value.bounds})});const check=createPaintIndex();check.sync([{id,bounds:entry.bounds}]);return entry;} // 订阅只关注本视图位置变化,调用方需用返回函数解除监听;getSnapshot 返回稳定的最近发布值。 return Object.freeze({viewId,getSnapshot:()=>snapshot,subscribe(listener:()=>void){listeners.add(listener);return()=>{listeners.delete(listener);};}, /** 注册或替换一个浮层,返回只能操作本 token 的 update/release。 * update 先完整校验,新旧序列化值相同时不发布;过期租约的更新/释放均无效果。 */ register(id:string,value:Omit){const token=++serial,entry=capture(id,value);entries.set(id,{token,entry});publish();return Object.freeze({update(value:Omit){if(entries.get(id)?.token!==token)return;const entry=capture(id,value),old=entries.get(id)!.entry;if(JSON.stringify(old)===JSON.stringify(entry))return;entries.set(id,{token,entry});publish();},release(){if(entries.get(id)?.token!==token)return;entries.delete(id);publish();}});}, /** 正常浮层按视口交集筛选;已聚焦或输入法组合中的浮层保留,但目标必须仍有效。 */ visible(bounds:Rect,current:(target:Target)=>boolean){const ids=index.query(bounds);return snapshot.filter(entry=>current(entry.target)&&(entry.focused||entry.composing||ids.has(entry.id)));}, /** 清空所有当前浮层并发布空快照;不关闭监听服务,后续仍可注册新租约。 */ clear(){entries.clear();publish();}, }); } /** 由工厂推导接口,调用方无权直接操作内部 token/Map。 */ export type OverlayIndex=ReturnType;