@pisell/materials 1.8.41 → 1.8.42

package/es/components/pisellFloorMapLayout/hooks/useFloorMapTransformMetrics.js

@@ -1,17 +1,20 @@
 import { _objectSpread2 } from "../../../_virtual/_@oxc-project_runtime@0.122.0/helpers/objectSpread2.js";
-import { getContentSize, getPixelBoundingBox } from "../utils/layoutMeasurements.js";
+import { getPixelBoundingBox } from "../utils/layoutMeasurements.js";
+import { computeFloorMapContentStage } from "../utils/floorMapCanvasStage.js";
+import { readPersistedViewport, readPersistedViewportLock, writePersistedViewport, writePersistedViewportLock } from "./floorMapViewportPersistence.js";
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 //#region src/components/pisellFloorMapLayout/hooks/useFloorMapTransformMetrics.ts
 /**
 * 视口 / 地图区尺寸、内容区宽高与偏移、缩放与全屏、fitBounds、拖拽图元后恢复 transform
 */
-/** 平面图包围盒单侧默认外扩（像素）；过大会导致首屏大量空白 */
-const DEFAULT_BOUNDING_PADDING = 56;
-/** 视口内与首屏对齐时，图元束左上与容器边缘的留白 */
-const VIEWPORT_TOP_LEFT_MARGIN = 16;
+/**
+* react-zoom-pan-pinch：`setTransform` 未显式传 `animationTime` 时默认约 200ms 缓动；
+* 兜底清除「全览激活保持」略大于该值，避免极少数帧未到容差时限位不解除。
+*/
+const FIT_BOUNDS_PROGRAMMATIC_TWEEN_GUARD_MS = 400;
 function useFloorMapTransformMetrics(params) {
-	const { items, cellSize, itemGap, effectiveItemUnit, isFloorMapView, mode, zoom, transformRef, contentOffsetRef, boundingPadding: boundingPaddingProp, frameResetKey } = params;
-	const padSingle = boundingPaddingProp !== null && boundingPaddingProp !== void 0 ? boundingPaddingProp : DEFAULT_BOUNDING_PADDING;
+	const { items, cellSize, itemGap, effectiveItemUnit, isFloorMapView, mode, zoom, transformRef, contentOffsetRef, boundingPadding: boundingPaddingProp, frameResetKey, viewportPersistKey } = params;
+	const padSingle = boundingPaddingProp !== null && boundingPaddingProp !== void 0 ? boundingPaddingProp : 56;
 	const containerRef = useRef(null);
 	const mapAreaRef = useRef(null);
 	const [viewportSize, setViewportSize] = useState({
@@ -72,37 +75,76 @@ function useFloorMapTransformMetrics(params) {
 	]);
 	const [scale, setScale] = useState(zoomConfig.initialScale);
 	const [isFullscreen, setIsFullscreen] = useState(false);
+	/**
+	* 「适配视口」激活态：当前 transform 与最近一次 fitBounds 计算出的目标 transform 在容差内一致时为 true。
+	* 由 fitBounds 写入快照、notifyTransformed 比较；用户主动拖动/缩放后立即失活。
+	*/
+	const lastFitSnapshotRef = useRef(null);
+	const [isAtFitBounds, setIsAtFitBounds] = useState(false);
+	/**
+	* 程序化 fitBounds 使用库默认缓动时，`onTransformed` 中间帧与快照不等会关掉「全览」激活态。
+	* 缓动持有期内不按中间帧降级，仅在到达快照（容差内）或兜底超时后再按真实 transform 对齐。
+	*/
+	const fitBoundsTweenHoldRef = useRef(false);
+	const fitBoundsTweenHoldClearTimerRef = useRef(null);
+	const clearFitBoundsTweenHold = useCallback(() => {
+		if (fitBoundsTweenHoldClearTimerRef.current != null) {
+			clearTimeout(fitBoundsTweenHoldClearTimerRef.current);
+			fitBoundsTweenHoldClearTimerRef.current = null;
+		}
+		fitBoundsTweenHoldRef.current = false;
+	}, []);
+	/**
+	* 视口锁定态：有 viewportPersistKey 时按 key 读写到 localStorage；无 key 时仅组件内存态（不写本地）。
+	* - 切 / 挂载时：有 key 则读持久化初值；无 key 则默认未锁定；
+	* - 用户切换时：有 key 则写回 localStorage；
+	* - 锁定后 fitBounds / 程序化 zoom 入口与 PisellFloorMapLayout 透传到 TransformWrapper 的
+	*   panning/wheel/pinch.disabled 共同把所有视角写入路径关闭。
+	* 切 canvas（key 变化）时跟随新 key 重新初始化，互不影响。
+	*/
+	const [viewportLocked, setViewportLockedState] = useState(() => viewportPersistKey ? readPersistedViewportLock(viewportPersistKey) : false);
+	const viewportLockedRef = useRef(viewportLocked);
+	viewportLockedRef.current = viewportLocked;
+	useEffect(() => {
+		if (!viewportPersistKey) {
+			setViewportLockedState(false);
+			return;
+		}
+		setViewportLockedState(readPersistedViewportLock(viewportPersistKey));
+	}, [viewportPersistKey]);
+	const setViewportLocked = useCallback((next) => {
+		setViewportLockedState(next);
+		const key = viewportPersistKey;
+		if (!key) return;
+		writePersistedViewportLock(key, next);
+	}, [viewportPersistKey]);
+	const toggleViewportLocked = useCallback(() => {
+		setViewportLocked(!viewportLockedRef.current);
+	}, [setViewportLocked]);
 	const { contentWidth, contentHeight, contentOffsetX, contentOffsetY, alignPadSingle } = useMemo(() => {
-		const fromItems = getContentSize(items, cellSize, itemGap, effectiveItemUnit);
-		const pad = padSingle * 2;
-		const zeroOffset = {
-			contentOffsetX: 0,
-			contentOffsetY: 0
+		const stage = computeFloorMapContentStage({
+			items,
+			cellSize,
+			itemGap,
+			itemUnit: effectiveItemUnit,
+			boundingPadding: padSingle,
+			preferPixelBoundingBox: isFloorMapView
+		});
+		let result = {
+			contentWidth: stage.contentWidth,
+			contentHeight: stage.contentHeight,
+			contentOffsetX: stage.contentOffsetX,
+			contentOffsetY: stage.contentOffsetY,
+			alignPadSingle: stage.alignPadSingle
 		};
-		const box = isFloorMapView && effectiveItemUnit === "pixel" && items.length > 0 ? getPixelBoundingBox(items, cellSize) : null;
-		let padded;
-		let alignPad = null;
-		if (box) {
-			padded = {
-				contentWidth: box.maxRight - box.minLeft + pad,
-				contentHeight: box.maxBottom - box.minTop + pad,
-				contentOffsetX: padSingle - box.minLeft,
-				contentOffsetY: padSingle - box.minTop
-			};
-			alignPad = padSingle;
-		} else padded = _objectSpread2({
-			contentWidth: fromItems.contentWidth + pad,
-			contentHeight: fromItems.contentHeight + pad
-		}, zeroOffset);
-		let result = _objectSpread2(_objectSpread2({}, padded), {}, { alignPadSingle: alignPad });
 		/** 像素平面图：阅读态与编辑态均将内容区至少撑满视口，便于大空白处平移 */
 		if (!isFloorMapView || effectiveItemUnit !== "pixel") return result;
 		const vw = mapAreaSize.width > 0 ? mapAreaSize.width : viewportSize.width;
 		const vh = mapAreaSize.height > 0 ? mapAreaSize.height : viewportSize.height;
 		if (vw <= 0 || vh <= 0) return result;
 		result = _objectSpread2(_objectSpread2({}, result), {}, {
-			contentWidth: Math.max(padded.contentWidth, vw),
-			contentHeight: Math.max(padded.contentHeight, vh)
+			contentWidth: Math.max(stage.contentWidth, vw),
+			contentHeight: Math.max(stage.contentHeight, vh)
 		});
 		return result;
 	}, [
@@ -118,8 +160,8 @@ function useFloorMapTransformMetrics(params) {
 		padSingle
 	]);
 	const padForAlign = alignPadSingle !== null && alignPadSingle !== void 0 ? alignPadSingle : 0;
-	const initialPositionX = VIEWPORT_TOP_LEFT_MARGIN - padForAlign * zoomConfig.initialScale;
-	const initialPositionY = VIEWPORT_TOP_LEFT_MARGIN - padForAlign * zoomConfig.initialScale;
+	const initialPositionX = 16 - padForAlign * zoomConfig.initialScale;
+	const initialPositionY = 16 - padForAlign * zoomConfig.initialScale;
 	contentOffsetRef.current = {
 		x: contentOffsetX,
 		y: contentOffsetY
@@ -171,69 +213,128 @@ function useFloorMapTransformMetrics(params) {
 		transformRef,
 		autoFitOnMount
 	]);
+	/**
+	* 伪全屏：用 `position: fixed; inset: 0` 撑满视口，不调用浏览器 Fullscreen API。
+	* 与「资源墙大屏」一致的体验：避免浏览器全屏带来的右键菜单受限、第三方弹层被全屏元素隔绝等。
+	*
+	* 对应 className 与 body overflow 锁定见 PisellFloorMapLayout.less 中
+	* `.pisell-floor-map-layout--pseudo-fullscreen` 与 `body.pisell-floor-map-layout-fullscreen-host`。
+	*
+	* 注意：不再监听 ESC 退出全屏。平面图编辑态全屏与编辑模式强绑定（PisellFloorMapLayout 中 effect），
+	* 若 ESC 直接 setIsFullscreen(false) 会立刻被同步 effect 拉回 true，徒增闪烁。
+	* 退出全屏 = 退出编辑，由顶栏退出按钮承担。
+	*/
 	useEffect(() => {
-		const el = containerRef.current;
-		if (!el) return;
-		const onFullscreenChange = () => setIsFullscreen(document.fullscreenElement === el);
-		document.addEventListener("fullscreenchange", onFullscreenChange);
-		return () => document.removeEventListener("fullscreenchange", onFullscreenChange);
+		if (!isFullscreen) return;
+		if (typeof document === "undefined") return;
+		const bodyCls = "pisell-floor-map-layout-fullscreen-host";
+		document.body.classList.add(bodyCls);
+		return () => {
+			document.body.classList.remove(bodyCls);
+		};
+	}, [isFullscreen]);
+	/** 卸载兜底：组件被卸载时不要把 body 锁住的样式残留 */
+	useEffect(() => {
+		return () => {
+			if (typeof document === "undefined") return;
+			document.body.classList.remove("pisell-floor-map-layout-fullscreen-host");
+		};
 	}, []);
 	const toggleFullscreen = useCallback(() => {
-		const el = containerRef.current;
-		if (!el) return;
-		if (document.fullscreenElement) {
-			var _document$exitFullscr, _document;
-			(_document$exitFullscr = (_document = document).exitFullscreen) === null || _document$exitFullscr === void 0 || _document$exitFullscr.call(_document);
-		} else {
-			var _el$requestFullscreen;
-			(_el$requestFullscreen = el.requestFullscreen) === null || _el$requestFullscreen === void 0 || _el$requestFullscreen.call(el);
-		}
+		setIsFullscreen((prev) => !prev);
 	}, []);
+	/**
+	* 仅保留 fitBoundsRef 给手动 fitBounds 按钮用。
+	*
+	* 历史上这里有个 useEffect：进入伪全屏时自动 fitBounds 适配新视口。
+	* 但现在「编辑态自动全屏 + 视口持久化」的组合下，这会把用户上次保存的视角
+	* 覆盖成 fit 结果，导致每次进编辑都被强制全览，违背用户意图。
+	* 视口尺寸变化由 ResizeObserver 自然处理，transform 不变即「保留用户视角」。
+	*/
+	const fitBoundsRef = useRef(null);
 	/** @returns 是否已调用 setTransform（用于首屏 autoFit：避免空跑仍标记 done） */
 	const fitBounds = useCallback(() => {
-		var _zoom$max3;
+		/**
+		* 锁定态：拦截所有 fitBounds 触发路径（按钮 / autoFit useLayoutEffect / ref API），
+		* 让画布严格停留在用户锁定时的视角。返回 true 让 autoFit 调用方将 done 置位，
+		* 避免被无限重试占用 rAF。
+		*/
+		if (viewportLockedRef.current) return true;
 		const ctx = transformRef.current;
 		const container = containerRef.current;
 		if (!ctx || !container) return false;
 		const wrapper = container.querySelector(".react-transform-wrapper");
 		if (!wrapper) return false;
 		const wrapperRect = wrapper.getBoundingClientRect();
-		if (wrapperRect.width <= 0 || wrapperRect.height <= 0) return false;
+		const wEl = wrapper;
+		/**
+		* 祖先链上若有 transform: scale / zoom，getBoundingClientRect 为「视觉」尺寸，
+		* clientWidth/Height 为布局盒尺寸。react-zoom-pan-pinch 的平移/缩放工作在布局坐标系，
+		* 若全览仅用 rect 算 avail 与 position，会与库内部不一致（日志：visual/layout≈0.864）。
+		*/
+		const layoutW = wEl.clientWidth > 0 ? wEl.clientWidth : wrapperRect.width;
+		const layoutH = wEl.clientHeight > 0 ? wEl.clientHeight : wrapperRect.height;
+		if (layoutW <= 0 || layoutH <= 0) return false;
+		/** 程序化 setTransform 默认带缓动：写入快照后立即保持「全览激活」，缓动结束前不因中间帧关掉 */
+		const applyProgrammaticFit = (fx, fy, fScale) => {
+			clearFitBoundsTweenHold();
+			lastFitSnapshotRef.current = {
+				x: fx,
+				y: fy,
+				scale: fScale
+			};
+			setIsAtFitBounds(true);
+			fitBoundsTweenHoldRef.current = true;
+			fitBoundsTweenHoldClearTimerRef.current = setTimeout(() => {
+				fitBoundsTweenHoldClearTimerRef.current = null;
+				fitBoundsTweenHoldRef.current = false;
+				const cur = lastTransformRef.current;
+				const s = lastFitSnapshotRef.current;
+				if (!s) return;
+				setIsAtFitBounds(Math.abs(s.x - cur.x) < .5 && Math.abs(s.y - cur.y) < .5 && Math.abs(s.scale - cur.scale) < .005);
+			}, FIT_BOUNDS_PROGRAMMATIC_TWEEN_GUARD_MS);
+			ctx.setTransform(fx, fy, fScale);
+		};
 		/**
 		* 平面图像素模式：按「图元轴对齐包围盒」缩放并居中，不按整块 content（含编辑态撑满视口的空白）适配。
 		* 画布 DOM 尺寸与网格空白不变，仅改变视口 transform；视口边可贴边（edgePx=0）。
 		*/
 		const pixelBox = isFloorMapView && effectiveItemUnit === "pixel" && items.length > 0 ? getPixelBoundingBox(items, cellSize) : null;
+		/**
+		* 把按容器算出来的 raw fit 缩放夹到 `[zoom.min, zoom.max]`：
+		* - 上限保留原行为，避免 1×1 内容被放到比 max 还大；
+		* - **下限新增**：全览态下多画布拼合后 raw 经常 < minScale（如 40%），
+		*   原先直接落到 raw 会让 TransformWrapper 处于「比配置最小缩放更小」的
+		*   状态，用户再用鼠标 / +/- 一动就跳回 minScale，体验很怪。
+		*   夹到 minScale 后会自动按真实 minScale 居中，超出部分由用户平移浏览。
+		*/
+		const clampFitScale = (raw) => {
+			var _zoom$min2, _zoom$max2;
+			return Math.max((_zoom$min2 = zoom.min) !== null && _zoom$min2 !== void 0 ? _zoom$min2 : .5, Math.min(raw, (_zoom$max2 = zoom.max) !== null && _zoom$max2 !== void 0 ? _zoom$max2 : 2));
+		};
 		if (pixelBox) {
-			var _zoom$max2;
 			const bw = Math.max(1, pixelBox.maxRight - pixelBox.minLeft);
 			const bh = Math.max(1, pixelBox.maxBottom - pixelBox.minTop);
 			const edgePx = 0;
-			const availW = Math.max(1, wrapperRect.width - 2 * edgePx);
-			const availH = Math.max(1, wrapperRect.height - 2 * edgePx);
-			const raw = Math.min(availW / bw, availH / bh);
-			const nextScale = Math.min(raw, (_zoom$max2 = zoom.max) !== null && _zoom$max2 !== void 0 ? _zoom$max2 : 2);
+			const availW = Math.max(1, layoutW - 2 * edgePx);
+			const availH = Math.max(1, layoutH - 2 * edgePx);
+			const nextScale = clampFitScale(Math.min(availW / bw, availH / bh));
 			const ap = alignPadSingle !== null && alignPadSingle !== void 0 ? alignPadSingle : padSingle;
 			const bboxCx = ap + bw / 2;
 			const bboxCy = ap + bh / 2;
-			const x = wrapperRect.width / 2 - bboxCx * nextScale;
-			const y = wrapperRect.height / 2 - bboxCy * nextScale;
-			ctx.setTransform(x, y, nextScale);
+			applyProgrammaticFit(layoutW / 2 - bboxCx * nextScale, layoutH / 2 - bboxCy * nextScale, nextScale);
 			return true;
 		}
 		if (contentWidth <= 0 || contentHeight <= 0) return false;
-		/** 非平面图或无图元：仍按整块 content 适配 */
-		const raw = Math.min(wrapperRect.width / contentWidth, wrapperRect.height / contentHeight);
-		const nextScale = Math.min(raw, (_zoom$max3 = zoom.max) !== null && _zoom$max3 !== void 0 ? _zoom$max3 : 2);
+		const nextScale = clampFitScale(Math.min(layoutW / contentWidth, layoutH / contentHeight));
 		const padA = alignPadSingle !== null && alignPadSingle !== void 0 ? alignPadSingle : 0;
-		const x = VIEWPORT_TOP_LEFT_MARGIN - padA * nextScale;
-		const y = VIEWPORT_TOP_LEFT_MARGIN - padA * nextScale;
-		ctx.setTransform(x, y, nextScale);
+		applyProgrammaticFit(16 - padA * nextScale, 16 - padA * nextScale, nextScale);
 		return true;
 	}, [
+		clearFitBoundsTweenHold,
 		contentWidth,
 		contentHeight,
-		zoom.max,
+		zoom,
 		transformRef,
 		alignPadSingle,
 		isFloorMapView,
@@ -242,6 +343,8 @@ function useFloorMapTransformMetrics(params) {
 		cellSize,
 		padSingle
 	]);
+	/** 让"进入伪全屏后自动 fit"的 effect 能拿到最新的 fitBounds 实现 */
+	fitBoundsRef.current = fitBounds;
 	/**
 	* autoFitOnMount：每个画布在「有图元且 content 尺寸已按包围盒算好」后执行一次 fitBounds。
 	* 避免首帧 items 仍为空时用占位尺寸 fit 完并标记 done，导致异步图元加载后不再适配。
@@ -252,6 +355,13 @@ function useFloorMapTransformMetrics(params) {
 	});
 	const prevItemsCountForAutoFitRef = useRef(null);
 	/**
+	* 记录「本 frame 的 transform 已由视口缓存接管」：
+	* 命中 localStorage 恢复或 restore effect 完成后写入当前 frame。
+	* 只要等于当前 frame，autoFit 所有分支（包括 items 从 0→N 的 reset done）一律放弃，
+	* 防止 items 异步加载后 autoFit 覆盖恢复值 → onTransformed 又把 fit 结果回写到 localStorage。
+	*/
+	const cachedRestoredFrameRef = useRef("");
+	/**
 	* 首屏 auto fit：时序上易出现「Transform 未挂载 / wrapper 尺寸为 0 / 内容区尚未提交」，
 	* 用 layoutEffect + 双 rAF 贴近浏览器布局完成时刻；仅 fitBounds 真正 setTransform 后才记 done；
 	* viewportSize 纳入依赖以便父级 flex 迟到的尺寸更新后重试（超次不伪造 done）。
@@ -265,10 +375,24 @@ function useFloorMapTransformMetrics(params) {
 				done: false
 			};
 			prevItemsCountForAutoFitRef.current = null;
+			/**
+			* 命中视口缓存：跳过本帧 autoFit，让恢复 effect 用缓存 transform 接管。
+			* 避免「先 autoFit 一次再被恢复覆盖」造成的视觉闪烁。
+			* 同步打上「缓存接管」标记，防止下面的「items 0→N reset done」再度启用 autoFit
+			* 覆盖恢复值并把 fit 结果通过 onTransformed 回写 localStorage。
+			*/
+			if (viewportPersistKey && readPersistedViewport(viewportPersistKey)) {
+				autoFitOnceRef.current.done = true;
+				cachedRestoredFrameRef.current = frame;
+			} else if (cachedRestoredFrameRef.current !== frame) cachedRestoredFrameRef.current = "";
 		}
 		const itemCount = items.length;
 		const prevN = prevItemsCountForAutoFitRef.current;
-		if (prevN !== null && prevN === 0 && itemCount > 0) autoFitOnceRef.current.done = false;
+		/**
+		* 已由缓存接管本 frame 的 transform：items 异步加载完成后绝不重新启用 autoFit，
+		* 否则会把用户上次拖拽的位置覆盖成适配视口，且被 onTransformed 回写 localStorage。
+		*/
+		if (prevN !== null && prevN === 0 && itemCount > 0 && cachedRestoredFrameRef.current !== frame) autoFitOnceRef.current.done = false;
 		prevItemsCountForAutoFitRef.current = itemCount;
 		if (autoFitOnceRef.current.done) return;
 		if (effectiveItemUnit === "pixel" && itemCount === 0) return;
@@ -326,7 +450,8 @@ function useFloorMapTransformMetrics(params) {
 		mapAreaSize.width,
 		mapAreaSize.height,
 		fitBounds,
-		transformRef
+		transformRef,
+		viewportPersistKey
 	]);
 	const lastTransformRef = useRef({
 		x: 0,
@@ -349,6 +474,208 @@ function useFloorMapTransformMetrics(params) {
 		});
 		return () => cancelAnimationFrame(raf);
 	}, [isInteractingWithElement, transformRef]);
+	/**
+	* 视口持久化：写入节流 + 切 canvas 时清掉 pending；
+	* persistKeyRef 保证 debounce 触发时仍然写到「触发时刻」对应的 key（避免 key 变化后被错位写入）。
+	*/
+	const persistKeyRef = useRef(viewportPersistKey);
+	persistKeyRef.current = viewportPersistKey;
+	const persistTimerRef = useRef(null);
+	const flushPersistRef = useRef(null);
+	const schedulePersistViewport = useCallback((snapshot) => {
+		const key = persistKeyRef.current;
+		if (!key) return;
+		if (persistTimerRef.current != null) {
+			clearTimeout(persistTimerRef.current);
+			persistTimerRef.current = null;
+		}
+		const targetKey = key;
+		const doWrite = () => {
+			persistTimerRef.current = null;
+			flushPersistRef.current = null;
+			writePersistedViewport(targetKey, snapshot);
+		};
+		flushPersistRef.current = doWrite;
+		persistTimerRef.current = setTimeout(doWrite, 300);
+	}, []);
+	/**
+	* 由 onTransformed 回调统一上报当前 transform：
+	*   - 写 lastTransformRef（替代父组件直接赋值）
+	*   - 与最近一次 fitBounds 快照比较，更新激活态
+	*
+	* ❗注意：故意不在这里写 localStorage。
+	* react-zoom-pan-pinch 在挂载、`setTransform`、`fitBounds`、`resetTransform` 等程序化路径
+	* 也会触发 onTransformed（含挂载初始值 {x:16, y:16, scale:1}），若在此持久化，
+	* wrapper 重挂载时会用这份"初始值"覆盖 localStorage 里用户上次保存的视角。
+	* 持久化改由 onPanningStop / onPinchingStop / onZoomStop / onWheelStop 触发，
+	* 那些事件只在「用户真的拖完/缩放完」时才发生。
+	*/
+	const notifyTransformed = useCallback((x, y, nextScale) => {
+		lastTransformRef.current = {
+			x,
+			y,
+			scale: nextScale
+		};
+		const snap = lastFitSnapshotRef.current;
+		if (snap) {
+			const same = Math.abs(snap.x - x) < .5 && Math.abs(snap.y - y) < .5 && Math.abs(snap.scale - nextScale) < .005;
+			if (fitBoundsTweenHoldRef.current) {
+				if (same) {
+					clearFitBoundsTweenHold();
+					setIsAtFitBounds(true);
+				}
+				/** 缓动中间帧：保持已设的「全览激活」，不因尚未对齐快照而关掉 */
+				return;
+			}
+			setIsAtFitBounds((prev) => prev === same ? prev : same);
+		} else setIsAtFitBounds((prev) => prev ? false : prev);
+	}, [clearFitBoundsTweenHold]);
+	/**
+	* 用户交互结束时（pan / zoom / pinch / wheel stop）调用：
+	* 以 lastTransformRef 当前值为快照写 localStorage（debounce 兜底高频 stop）。
+	* 程序化的 setTransform / fitBounds / 挂载初始化都不会调这里，避免污染缓存。
+	*/
+	const persistCurrentViewport = useCallback(() => {
+		const snapshot = lastTransformRef.current;
+		schedulePersistViewport({
+			x: snapshot.x,
+			y: snapshot.y,
+			scale: snapshot.scale
+		});
+	}, [schedulePersistViewport]);
+	/** 让 restore 路径读到最新 frameResetKey，避免 closure 过期 */
+	const frameResetKeyRef = useRef(frameResetKey);
+	frameResetKeyRef.current = frameResetKey;
+	const viewportPersistKeyRef = useRef(viewportPersistKey);
+	viewportPersistKeyRef.current = viewportPersistKey;
+	/**
+	* 把缓存视角立即贴到画布上的统一入口（restore effect 与 attachTransformContext 共用）。
+	*
+	* 关键点：
+	* 1. setTransform 的 animationTime 必须传 0：
+	*    - react-zoom-pan-pinch 默认 200ms 缓动；
+	*    - 首屏若 namespace 异步、autoFit 抢先 setTransform(fit) 并仍在缓动中，
+	*      restore 这次 setTransform 会被库认为是「动画过程中无意义的同向 set」吃掉
+	*      或与原动画合成，最终视觉停在 fit 处；
+	*    - 传 0 等价于"立即落点"，强制覆盖任何在飞动画。
+	* 2. 命中后立刻把 cachedRestoredFrameRef / autoFit done / initialAlign done 都打上，
+	*    防止后续 effect 反向覆盖缓存值。
+	*/
+	const applyPersistedViewport = useCallback((cached) => {
+		clearFitBoundsTweenHold();
+		const ctx = transformRef.current;
+		if (!ctx) return false;
+		ctx.setTransform(cached.x, cached.y, cached.scale, 0);
+		lastTransformRef.current = _objectSpread2({}, cached);
+		lastFitSnapshotRef.current = null;
+		setIsAtFitBounds(false);
+		autoFitOnceRef.current.done = true;
+		initialAlignRef.current.done = true;
+		const currentFrame = frameResetKeyRef.current;
+		if (currentFrame !== void 0) cachedRestoredFrameRef.current = String(currentFrame);
+		return true;
+	}, [clearFitBoundsTweenHold, transformRef]);
+	/**
+	* 切换 viewportPersistKey 或 frameResetKey 时（含挂载、wrapper 重挂载）：
+	* 尝试从 localStorage 读取上次视角并恢复。命中缓存 → 阻止本帧 autoFitOnMount /
+	* 首次左上对齐覆盖。未命中保持原行为。
+	*
+	* ❗frameResetKey 必须在依赖里：
+	* `transformWrapperKey` 在远端配置（boundingPadding / defaultScale）回包后会变，
+	* 触发 TransformWrapper 卸载重挂载并以 `initialPositionX/Y/Scale` (≈16,16,1) 渲染。
+	* 仅依赖 viewportPersistKey 时此处不会重跑，画布会停在初始 transform，
+	* 用户上次保存的视角虽然在 localStorage 里却没"贴回"画布。
+	*/
+	useEffect(() => {
+		if (!viewportPersistKey) return;
+		const cached = readPersistedViewport(viewportPersistKey);
+		if (!cached) return;
+		let cancelled = false;
+		let raf1 = 0;
+		let raf2 = 0;
+		let attempts = 0;
+		const MAX_ATTEMPTS = 60;
+		const tick = () => {
+			if (cancelled) return;
+			if (!applyPersistedViewport(cached)) {
+				if (attempts++ < MAX_ATTEMPTS) raf1 = requestAnimationFrame(tick);
+			}
+		};
+		/** 双 rAF：等 TransformWrapper 的 ctx 就绪后再写 */
+		raf1 = requestAnimationFrame(() => {
+			raf2 = requestAnimationFrame(tick);
+		});
+		return () => {
+			cancelled = true;
+			cancelAnimationFrame(raf1);
+			cancelAnimationFrame(raf2);
+		};
+	}, [
+		viewportPersistKey,
+		frameResetKey,
+		applyPersistedViewport
+	]);
+	/**
+	* PisellFloorMapLayout 在 TransformWrapper children render 中调用：
+	*   {(ctx) => { attachTransformContext(ctx); return <>...</> }}
+	*
+	* 用途：wrapper 首次挂载 / 重挂载时，立刻 schedule 一次 restore，
+	* 避免依赖 useEffect、namespace 异步、autoFit 抢先 setTransform 之间的复杂时序。
+	*
+	* ⚠️ 不要用「ctx 引用是否变化」做去重：
+	*   react-zoom-pan-pinch 在每次内部状态更新（缩放 / 平移过程中的 onTransformed）
+	*   都会让父组件重 render，children render 函数会再次被调用，部分版本下 ctx 是新对象引用。
+	*   一旦把它判成「新 ctx」再次 schedule restore，就会把用户刚做的缩放/平移
+	*   又覆盖回缓存，表现成「拖动可以，缩放回弹/缩放不动」。
+	*
+	* 改用 cachedRestoredFrameRef 做幂等：每个 frame（= TransformWrapper 的 key）
+	* 在生命周期内只 restore 一次。frame 真变化（wrapper 卸载重挂载）时，autoFit
+	* useLayoutEffect 的 reset 分支会清掉 / 重置该 ref，attach 自然能再次触发。
+	*/
+	const attachTransformContext = useCallback((ctx) => {
+		transformRef.current = ctx;
+		const key = viewportPersistKeyRef.current;
+		const currentFrame = frameResetKeyRef.current;
+		if (!key || currentFrame === void 0) return;
+		const frameStr = String(currentFrame);
+		/** 该 frame 已经 restore 过（attach 触发或 autoFit reset 分支命中均会标记） */
+		if (cachedRestoredFrameRef.current === frameStr) return;
+		const cached = readPersistedViewport(key);
+		if (!cached) return;
+		/**
+		* 立刻占座：避免本帧后续如果触发 attach 重入 / restore useEffect 同步跑
+		* 出现两条 setTransform 路径并发。applyPersistedViewport 内部还会再设一次
+		* （等于幂等）。
+		*/
+		cachedRestoredFrameRef.current = frameStr;
+		/**
+		* 双 rAF 等 wrapper 内部 useEffect / 初始 onTransformed 走完，
+		* 否则可能被库的 init 回调把 transform 又重置回 initial。
+		*/
+		requestAnimationFrame(() => {
+			requestAnimationFrame(() => {
+				/** 等待期间 frame 又变了（快速切画布）则交给新 frame 的 attach 处理 */
+				if (frameResetKeyRef.current !== currentFrame) return;
+				applyPersistedViewport(cached);
+			});
+		});
+	}, [transformRef, applyPersistedViewport]);
+	/** 卸载 / key 变化时把待写的视口立刻 flush，避免快速来回切丢失最后一次操作 */
+	useEffect(() => {
+		return () => {
+			var _flushPersistRef$curr;
+			if (persistTimerRef.current != null) {
+				clearTimeout(persistTimerRef.current);
+				persistTimerRef.current = null;
+			}
+			(_flushPersistRef$curr = flushPersistRef.current) === null || _flushPersistRef$curr === void 0 || _flushPersistRef$curr.call(flushPersistRef);
+			flushPersistRef.current = null;
+			if (fitBoundsTweenHoldClearTimerRef.current != null) {
+				clearTimeout(fitBoundsTweenHoldClearTimerRef.current);
+				fitBoundsTweenHoldClearTimerRef.current = null;
+			}
+		};
+	}, [viewportPersistKey]);
 	return {
 		containerRef,
 		mapAreaRef,
@@ -366,9 +693,16 @@ function useFloorMapTransformMetrics(params) {
 		isFullscreen,
 		toggleFullscreen,
 		fitBounds,
+		isAtFitBounds,
+		notifyTransformed,
+		persistCurrentViewport,
+		attachTransformContext,
 		lastTransformRef,
 		isInteractingWithElement,
-		setIsInteractingWithElement
+		setIsInteractingWithElement,
+		viewportLocked,
+		setViewportLocked,
+		toggleViewportLocked
 	};
 }
 //#endregion

package/es/components/pisellFloorMapLayout/index.d.ts

@@ -1,7 +1,9 @@
-import { DataSourceFormColumn, FLOOR_MAP_IMAGE_ELEMENT_KIND, FLOOR_MAP_STAGE_ELEMENT_KIND, FloorMapBackgroundType, FloorMapCanvas, FloorMapCanvasNameI18n, FloorMapCanvasUiConfig, FloorMapControlsConfig, FloorMapDataSourceRecordFormContent, FloorMapDataSources, FloorMapEdge, FloorMapElementDataBindingPolicy, FloorMapElementDefaultPresentation, FloorMapElementKindCategory, FloorMapElementKindConfig, FloorMapFullscreenMode, FloorMapGridLayoutConfig, FloorMapItemBase, FloorMapItemShape, FloorMapItemUnit, FloorMapLayerConfig, FloorMapLayoutContextValue, FloorMapLayoutMode, FloorMapMergedItem, FloorMapPanBoundary, FloorMapPanConfig, FloorMapRecordFormRenderContext, FloorMapRenderOptions, FloorMapSceneElement, FloorMapSceneElementDataBinding, FloorMapTextSlot, FloorMapViewConfig, FloorMapViewportOverlayRenderArgs, FloorMapZoomConfig, PisellFloorMapLayoutProps, PisellFloorMapLayoutRef } from "./types.js";
+import { DataSourceFormColumn, FLOOR_MAP_BUILTIN_SHAPE_ELEMENT_KIND, FLOOR_MAP_IMAGE_ELEMENT_KIND, FLOOR_MAP_STAGE_ELEMENT_KIND, FloorMapBackgroundType, FloorMapCanvas, FloorMapCanvasNameI18n, FloorMapCanvasUiConfig, FloorMapControlsConfig, FloorMapDataSourceRecordFormContent, FloorMapDataSources, FloorMapEdge, FloorMapElementDataBindingPolicy, FloorMapElementDefaultPresentation, FloorMapElementKindCategory, FloorMapElementKindConfig, FloorMapFullscreenMode, FloorMapGridLayoutConfig, FloorMapItemBase, FloorMapItemShape, FloorMapItemUnit, FloorMapLayerConfig, FloorMapLayoutContextValue, FloorMapLayoutMode, FloorMapMergedItem, FloorMapPanBoundary, FloorMapPanConfig, FloorMapRecordFormRenderContext, FloorMapRenderOptions, FloorMapSceneElement, FloorMapSceneElementDataBinding, FloorMapTextSlot, FloorMapViewConfig, FloorMapViewportOverlayRenderArgs, FloorMapZoomConfig, PisellFloorMapLayoutProps, PisellFloorMapLayoutRef } from "./types.js";
 import { PisellFloorMapLayout } from "./PisellFloorMapLayout.js";
 import { renderFloorMapFallbackPlaceholder } from "./utils/floorMapFallbackRender.js";
-import { isFloorMapImageElementKind } from "./utils/floorMapElementKindUtils.js";
+import { isFloorMapBuiltinShapeElementKind, isFloorMapImageElementKind } from "./utils/floorMapElementKindUtils.js";
+import { FLOOR_MAP_BUILTIN_SHAPES, FloorMapBuiltinShapeDef, FloorMapBuiltinShapeRenderProps, getFloorMapBuiltinShapeDef } from "./utils/floorMapBuiltinShapes.js";
+import { NAME_AS_TITLE_EXT_KEY, buildNameAsTitleExtensionsPatch, isElementNameAsTitleEnabled, resolveSceneElementDisplayTitle } from "./utils/floorMapElementNameAsTitle.js";
 import { FloorMapBindingPlaceholderReason, FloorMapDataSourceRow, findFloorMapRowByDataBinding, getFloorMapBindingPlaceholderReason } from "./utils/floorMapDataBindingUtils.js";
 import { CreateShopFloorPlanClientOptions, EnsureShopFloorPlanByCodeOptions, PostShopFloorPlanBody, PutShopFloorPlanBody, SHOP_FLOOR_PLAN_DUPLICATE_CODE, ShopFloorPlanByCodeRequestOptions, ShopFloorPlanDetail, ShopFloorPlanHttpAdapter, ShopFloorPlanLayoutItem } from "./shopFloorPlan/shopFloorPlanTypes.js";
 import { createShopFloorPlanClient } from "./shopFloorPlan/shopFloorPlanClient.js";
@@ -12,4 +14,5 @@ import { WrapFloorMapOnSaveWithRemotePersistParams, wrapFloorMapOnSaveWithRemote
 import { EMPTY_FLOOR_MAP_LAYOUT_CONTEXT, FloorMapLayoutProvider, FloorMapLayoutProviderProps, useFloorMapLayoutContext } from "./context/FloorMapLayoutContext.js";
 import { mergeFloorMapLayoutPropsFromContext } from "./context/mergeFloorMapLayoutContext.js";
 import { FloorMapImageElement } from "./components/FloorMapImageElement.js";
+import { FloorMapBuiltinShapeElement } from "./components/FloorMapBuiltinShapeElement.js";
 import { FigmaTableCardItem, FigmaTableStatus, getFigmaTableCardFromMerged, getRenderItemByKindRoundTable, getRenderItemByKindTable, renderFigmaStyleRoundTableCard, renderFigmaStyleTableCard } from "./components/FigmaTableCard.js";