@arronqzy/react-view 1.0.20 → 1.0.21

package/dist/styles.css

@@ -616,6 +616,10 @@ video {
   inset: 0px;
 }
 
+.inset-1\.5 {
+  inset: 0.375rem;
+}
+
 .inset-2 {
   inset: 0.5rem;
 }
@@ -645,6 +649,10 @@ video {
   left: 0.125rem;
 }
 
+.left-1 {
+  left: 0.25rem;
+}
+
 .left-1\/2 {
   left: 50%;
 }
@@ -653,6 +661,10 @@ video {
   left: 0.5rem;
 }
 
+.left-6 {
+  left: 1.5rem;
+}
+
 .left-\[var\(--rv-ruler-size\)\] {
   left: var(--rv-ruler-size);
 }
@@ -677,10 +689,18 @@ video {
   top: 0.125rem;
 }
 
+.top-1 {
+  top: 0.25rem;
+}
+
 .top-2 {
   top: 0.5rem;
 }
 
+.top-4 {
+  top: 1rem;
+}
+
 .top-\[calc\(100\%\+6px\)\] {
   top: calc(100% + 6px);
 }
@@ -1513,6 +1533,10 @@ video {
   border-radius: 1rem;
 }
 
+.rounded-\[2px\] {
+  border-radius: 2px;
+}
+
 .rounded-full {
   border-radius: 9999px;
 }
@@ -1533,6 +1557,15 @@ video {
   border-radius: 0.75rem;
 }
 
+.rounded-l {
+  border-top-left-radius: 0.25rem;
+  border-bottom-left-radius: 0.25rem;
+}
+
+.rounded-tl {
+  border-top-left-radius: 0.25rem;
+}
+
 .border {
   border-width: 1px;
 }
@@ -1890,10 +1923,22 @@ video {
   background-color: hsl(var(--primary) / 0.15);
 }
 
+.bg-primary\/30 {
+  background-color: hsl(var(--primary) / 0.3);
+}
+
 .bg-primary\/35 {
   background-color: hsl(var(--primary) / 0.35);
 }
 
+.bg-primary\/40 {
+  background-color: hsl(var(--primary) / 0.4);
+}
+
+.bg-primary\/45 {
+  background-color: hsl(var(--primary) / 0.45);
+}
+
 .bg-primary\/5 {
   background-color: hsl(var(--primary) / 0.05);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arronqzy/react-view",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "files": [
     "src",
     "dist",
@@ -30,14 +30,14 @@
     "@codemirror/lang-json": "^6.0.1",
     "@codemirror/theme-one-dark": "^6.1.2",
     "@codemirror/view": "^6.36.2",
-    "@arronqzy/i18n": "0.1.7",
-    "@arronqzy/blueprint-dsl": "1.0.9",
     "@arronqzy/ui": "1.0.6",
+    "@arronqzy/blueprint-dsl": "1.0.10",
+    "@arronqzy/i18n": "0.1.8",
+    "@arronqzy/react-blueprint": "1.0.12",
     "@arronqzy/rx-store": "1.0.5",
-    "@arronqzy/react-blueprint": "1.0.11",
-    "@arronqzy/view-scene3d": "0.1.2",
+    "@arronqzy/webllm-assistant": "0.1.10",
     "@arronqzy/view-table": "0.1.5",
-    "@arronqzy/webllm-assistant": "0.1.9"
+    "@arronqzy/view-scene3d": "0.1.2"
   },
   "devDependencies": {
     "@types/react": "^19.0.1",

package/src/panel/ReactViewPanel.tsx

@@ -755,6 +755,7 @@ function ReactViewPanelInner({
           | "lifecyclePhase"
           | "fetchConfig"
           | "jsonConfig"
+          | "storageConfig"
           | "logicConfig"
           | "clockConfig"
           | "eventConfig"
@@ -1602,7 +1603,7 @@ function ReactViewPanelInner({
       if (targetLayer.isMapping) return null;
       const hasBlockingRef = allElements.some((el) => {
         if (el.layerId === layerId) return false;
-        if (el.materialType !== "reference") return false;
+        if (el.materialType !== "reference" && el.materialType !== "viewport") return false;
         if (el.refLayerId !== layerId) return false;
         return (el.refCopyMode ?? "shallow") !== "deep";
       });
@@ -1875,6 +1876,13 @@ function ReactViewPanelInner({
           node.dataset.origWidth = String(parseFloat(node.style.width) || node.offsetWidth || 0);
           node.dataset.origHeight = String(parseFloat(node.style.height) || node.offsetHeight || 0);
         }
+        function applyBoxScale(node, sx, sy) {
+          rememberBox(node);
+          node.style.left = (Number(node.dataset.origLeft) * sx) + "px";
+          node.style.top = (Number(node.dataset.origTop) * sy) + "px";
+          node.style.width = (Number(node.dataset.origWidth) * sx) + "px";
+          node.style.height = (Number(node.dataset.origHeight) * sy) + "px";
+        }
         function fitScene() {
           if (!scene) return;
           var vw = window.innerWidth || 1;
@@ -1885,29 +1893,23 @@ function ReactViewPanelInner({
           var scaleY = vh / sh;
           if (root) root.style.overflow = "hidden";
           var nodes = scene.querySelectorAll("[data-element-id]");
+          var sx = outputScale ? 1 : scaleX;
+          var sy = outputScale ? 1 : scaleY;
           if (outputScale) {
             scene.style.width = sw + "px";
             scene.style.height = sh + "px";
             scene.style.transform = "translate(0px,0px) scale(" + scaleX + "," + scaleY + ")";
-            nodes.forEach(function (node) {
-              rememberBox(node);
-              node.style.left = node.dataset.origLeft + "px";
-              node.style.top = node.dataset.origTop + "px";
-              node.style.width = node.dataset.origWidth + "px";
-              node.style.height = node.dataset.origHeight + "px";
-            });
-            return;
+          } else {
+            scene.style.width = vw + "px";
+            scene.style.height = vh + "px";
+            scene.style.transform = "none";
           }
-          // 块仍按视口撑满，但不对整棵内容做 transform，字体保持原尺寸
-          scene.style.width = vw + "px";
-          scene.style.height = vh + "px";
-          scene.style.transform = "none";
           nodes.forEach(function (node) {
-            rememberBox(node);
-            node.style.left = (Number(node.dataset.origLeft) * scaleX) + "px";
-            node.style.top = (Number(node.dataset.origTop) * scaleY) + "px";
-            node.style.width = (Number(node.dataset.origWidth) * scaleX) + "px";
-            node.style.height = (Number(node.dataset.origHeight) * scaleY) + "px";
+            applyBoxScale(node, sx, sy);
+            var inner = node.querySelectorAll("[data-viewport-sizer], [data-viewport-item]");
+            inner.forEach(function (el) {
+              applyBoxScale(el, sx, sy);
+            });
           });
         }
         fitScene();

package/src/panel/ai/applyAssistantAction.ts

@@ -201,6 +201,7 @@ function applyBlueprintAddNode(
     clock: "clock",
     fetch: "fetch",
     json: "json",
+    storage: "storage",
     and: "and",
     event: "event",
   };

package/src/panel/components/ElementsLayer.tsx

@@ -6,6 +6,12 @@ import { buildChartOption, CHART_TYPES } from "../utils/chartOptionBuilder";
 import { PREVIEW_LAYOUT_EVENT } from "../utils/panelStateIO";
 import { TableNodeContent, type TableCellActionHandler } from "./table/TableNodeContent";
 import { comparePanelElementsPaintOrder } from "../utils/gridPlacement";
+import {
+  isViewportNode,
+  normalizeViewportOverflow,
+  viewportOverflowStyle,
+  viewportWindowContentScale,
+} from "../utils/viewportPlacement";
 import { cssTextLineHeight, cssTextAlignStyle } from "../utils/panelElementDefaults";
 import { mergeScene3dConfig } from "@arronqzy/view-scene3d";
 import { Scene3dNodeContent } from "@arronqzy/view-scene3d/react";
@@ -724,18 +730,30 @@ function ReferenceNodeContent({
 
     const innerW = Math.max(1, element.width);
     const innerH = Math.max(1, element.height);
-    const scale = Math.max(0.05, Math.min(innerW / sourceWidth, innerH / sourceHeight));
-    const mappedW = sourceWidth * scale;
-    const mappedH = sourceHeight * scale;
+    const windowFit = isViewportNode(element);
+    const windowScale = windowFit
+      ? viewportWindowContentScale(element, allElements)
+      : { scaleX: 1, scaleY: 1 };
+    const scaleX = windowFit
+      ? windowScale.scaleX
+      : Math.max(0.05, Math.min(innerW / sourceWidth, innerH / sourceHeight));
+    const scaleY = windowFit
+      ? windowScale.scaleY
+      : scaleX;
+    const mappedW = sourceWidth * scaleX;
+    const mappedH = sourceHeight * scaleY;
 
     return {
       minX,
       minY,
-      scale,
-      offsetX: (innerW - mappedW) / 2,
-      offsetY: (innerH - mappedH) / 2,
+      scaleX,
+      scaleY,
+      sourceWidth: mappedW,
+      sourceHeight: mappedH,
+      offsetX: windowFit ? 0 : (innerW - mappedW) / 2,
+      offsetY: windowFit ? 0 : (innerH - mappedH) / 2,
     };
-  }, [element.height, element.width, sourceNodes]);
+  }, [allElements, element, sourceNodes]);
 
   if (!layout || sourceNodes.length === 0) {
     const hintText = element.refLayerId ? t("panel.config.refLayerEmpty") : t("panel.config.selectRefLayer");
@@ -748,20 +766,50 @@ function ReferenceNodeContent({
     );
   }
 
+  const overflowCss = isViewportNode(element)
+    ? viewportOverflowStyle(normalizeViewportOverflow(element.viewportOverflow))
+    : { overflowX: "hidden" as const, overflowY: "hidden" as const };
+  const canScroll =
+    isViewportNode(element) &&
+    (overflowCss.overflowX === "auto" || overflowCss.overflowY === "auto");
+
   return (
-    <div className="pointer-events-none relative h-full w-full overflow-hidden">
+    <div
+      className="relative h-full w-full"
+      style={{
+        overflowX: overflowCss.overflowX,
+        overflowY: overflowCss.overflowY,
+        pointerEvents: isViewportNode(element) ? "auto" : "none",
+      }}
+      onWheel={canScroll ? (e) => e.stopPropagation() : undefined}
+    >
+      <div
+        className="pointer-events-none relative"
+        data-viewport-sizer={isViewportNode(element) ? "true" : undefined}
+        style={
+          isViewportNode(element)
+            ? {
+                width: layout.sourceWidth,
+                height: layout.sourceHeight,
+                minWidth: "100%",
+                minHeight: "100%",
+              }
+            : { width: "100%", height: "100%" }
+        }
+      >
       {sourceNodes.map((node) => {
         const box = getNodeAABB(node);
-        const left = layout.offsetX + (box.left - layout.minX) * layout.scale;
-        const top = layout.offsetY + (box.top - layout.minY) * layout.scale;
-        const width = Math.max(12, node.width * layout.scale);
-        const height = Math.max(10, node.height * layout.scale);
-        const boxWidth = Math.max(12, (box.right - box.left) * layout.scale);
-        const boxHeight = Math.max(10, (box.bottom - box.top) * layout.scale);
+        const left = layout.offsetX + (box.left - layout.minX) * layout.scaleX;
+        const top = layout.offsetY + (box.top - layout.minY) * layout.scaleY;
+        const width = Math.max(12, node.width * layout.scaleX);
+        const height = Math.max(10, node.height * layout.scaleY);
+        const boxWidth = Math.max(12, (box.right - box.left) * layout.scaleX);
+        const boxHeight = Math.max(10, (box.bottom - box.top) * layout.scaleY);
         return (
           <div
             key={node.id}
             className="absolute overflow-visible"
+            data-viewport-item={isViewportNode(element) ? "true" : undefined}
             style={{
               left,
               top,
@@ -771,6 +819,7 @@ function ReferenceNodeContent({
           >
             <div
               className="absolute"
+              data-viewport-item={isViewportNode(element) ? "true" : undefined}
               style={{
                 left: (boxWidth - width) / 2,
                 top: (boxHeight - height) / 2,
@@ -783,7 +832,7 @@ function ReferenceNodeContent({
             >
               {CHART_TYPES.has(node.materialType ?? "") ? (
                 <ChartNodeContent element={node} />
-              ) : node.materialType === "reference" ? (
+              ) : node.materialType === "reference" || node.materialType === "viewport" ? (
                 <ReferenceNodeContent
                   element={node}
                   allElements={allElements}
@@ -803,6 +852,7 @@ function ReferenceNodeContent({
           </div>
         );
       })}
+      </div>
     </div>
   );
 }
@@ -887,6 +937,7 @@ export const ElementsLayer = React.memo(function ElementsLayer({
               zIndex: el.zIndex ?? 1,
               transform: `rotate(${el.rotate ?? 0}deg)`,
               transformOrigin: "center center",
+              overflow: el.materialType === "viewport" ? "hidden" : undefined,
               boxSizing: "border-box",
               ...getNodeVisualStyle(el),
             }}
@@ -897,7 +948,7 @@ export const ElementsLayer = React.memo(function ElementsLayer({
                 previewLayoutKey={previewLayoutKey}
                 previewMode={previewMode}
               />
-            ) : el.materialType === "reference" ? (
+            ) : el.materialType === "reference" || el.materialType === "viewport" ? (
               <ReferenceNodeContent element={el} allElements={allElements} />
             ) : el.materialType === "grid" ? (
               <GridNodeContent

package/src/panel/components/MaterialSidebar.tsx

@@ -63,6 +63,7 @@ const MATERIAL_LABEL_KEYS: Record<string, string> = {
   text: "panel.material.text",
   rect: "panel.material.rect",
   grid: "panel.material.grid",
+  viewport: "panel.material.viewport",
   image: "panel.material.image",
   video: "panel.material.video",
   audio: "panel.material.audio",
@@ -374,6 +375,18 @@ function MaterialPreview({ id }: { id: string }) {
       </div>
     );
   }
+  if (id === "viewport") {
+    return (
+      <div className={common}>
+        <div className="absolute inset-1.5 overflow-hidden rounded-sm border border-primary/70 bg-primary/10">
+          <div className="absolute left-1 top-1 h-6 w-8 rounded-[2px] bg-primary/45" />
+          <div className="absolute left-6 top-4 h-7 w-10 rounded-[2px] bg-primary/30" />
+          <div className="absolute bottom-0 right-0 h-1.5 w-6 rounded-tl bg-primary/55" />
+          <div className="absolute bottom-0 right-0 top-2 w-1.5 rounded-l bg-primary/40" />
+        </div>
+      </div>
+    );
+  }
 
   return <div className={common} />;
 }
@@ -403,6 +416,7 @@ function getDefaultCategories(t: (key: string) => string): MaterialCategory[] {
         { id: "geometry", title: t("panel.material.geometry") },
         { id: "scene3d", title: t("panel.material.scene3d") },
         { id: "grid", title: t("panel.material.grid") },
+        { id: "viewport", title: t("panel.material.viewport") },
         { id: "image", title: t("panel.material.image") },
         { id: "reference", title: t("panel.material.reference") },
       ],
@@ -568,9 +582,8 @@ export function MaterialSidebar({
   };
 
   const getNodeChildren = (node: PanelElement, sourceOverride?: PanelElement[]) => {
-    const isRef = node.materialType === "reference";
+    const isRef = node.materialType === "reference" || node.materialType === "viewport";
     const isGrid = node.materialType === "grid";
-    // 必须用节点自身所在图层查找子节点；外层传入的 layerId 在深嵌套/引用子树中会错位，导致子节点不显示在对应网格下
     const gridChildren = isGrid
       ? [...(childrenByGridByLayer.get(node.layerId)?.get(node.id) ?? [])].sort(
           compareGridTreeChildOrder
@@ -611,7 +624,7 @@ export function MaterialSidebar({
   ) => {
     const selected = selectedIds.includes(node.id);
     if (!nodeMatchesTreeSearch(node, visited, sourceOverride)) return null;
-    const isRef = node.materialType === "reference";
+    const isRef = node.materialType === "reference" || node.materialType === "viewport";
     const refMode = node.refCopyMode ?? "shallow";
     const isDeepRef = isRef && refMode === "deep";
     const children = getNodeChildren(node, sourceOverride);
@@ -829,17 +842,11 @@ export function MaterialSidebar({
   };
 
   const hasRefInSubtree = (node: PanelElement, visited: Set<string>): boolean => {
-    if (node.materialType === "reference") return true;
-    if (node.materialType !== "reference") return false;
+    if (node.materialType === "reference" || node.materialType === "viewport") return true;
     if (visited.has(node.id)) return false;
     const nextVisited = new Set(visited);
     nextVisited.add(node.id);
-    const children =
-      node.refCopyMode === "deep"
-        ? node.refSnapshot ?? []
-        : node.refLayerId
-          ? elementsByLayer.get(node.refLayerId) ?? []
-          : [];
+    const children = getNodeChildren(node);
     return children.some((child) => hasRefInSubtree(child, nextVisited));
   };
 

package/src/panel/components/PanelConfigSidebar.tsx

@@ -28,6 +28,11 @@ import type {
   ReferenceCopyMode,
 } from "../types";
 import { buildChartOption, CHART_TYPES, getChartLabelsDisplayText, getChartValuesDisplayText } from "../utils/chartOptionBuilder";
+import {
+  VIEWPORT_OVERFLOW_MODES,
+  normalizeViewportOverflow,
+  type ViewportOverflowMode,
+} from "../utils/viewportPlacement";
 import type { PanelLayer } from "../types";
 import { getPanelMessages } from "../constants/messages";
 import { ViewElementScopePanel } from "./ViewElementScopePanel";
@@ -1863,7 +1868,7 @@ export function PanelConfigSidebar({
                       </label>
                     </div>
                       ) : null}
-                      {el.materialType === "reference" ? (
+                      {el.materialType === "reference" || el.materialType === "viewport" ? (
                     <div className="grid grid-cols-2 gap-2">
                       <label className="block space-y-1.5">
                         <div>{t("panel.config.refLayer")}</div>
@@ -1895,6 +1900,34 @@ export function PanelConfigSidebar({
                       </label>
                     </div>
                       ) : null}
+                      {el.materialType === "viewport" ? (
+                    <label className="block space-y-1.5">
+                      <div>{t("panel.config.viewportOverflow")}</div>
+                      <Select
+                        value={normalizeViewportOverflow(el.viewportOverflow)}
+                        onValueChange={(value) =>
+                          updateElement(el.id, {
+                            viewportOverflow: value as ViewportOverflowMode,
+                          })
+                        }
+                      >
+                        <SelectTrigger className="h-7"><SelectValue /></SelectTrigger>
+                        <SelectContent>
+                          {VIEWPORT_OVERFLOW_MODES.map((mode) => (
+                            <SelectItem key={mode} value={mode}>
+                              {mode === "scroll-x"
+                                ? t("panel.config.viewportOverflowScrollX")
+                                : mode === "scroll-y"
+                                  ? t("panel.config.viewportOverflowScrollY")
+                                  : mode === "scroll"
+                                    ? t("panel.config.viewportOverflowScroll")
+                                    : t("panel.config.viewportOverflowClip")}
+                            </SelectItem>
+                          ))}
+                        </SelectContent>
+                      </Select>
+                    </label>
+                      ) : null}
                     </div>
                   </fieldset>
                 </CardContent>
@@ -3603,6 +3636,111 @@ export function PanelConfigSidebar({
                 {t("panel.config.gridHint")}
               </>
             )
+          ) : selectedElement.materialType === "viewport" ? (
+            renderSection(
+              "viewportConfig",
+              t("panel.config.sectionViewport"),
+              <>
+                {renderFieldGroup(
+                  t("panel.config.groupRefSource"),
+                  <label className="block space-y-1">
+                    <div>{t("panel.config.refLayer")}</div>
+                    <Select
+                      value={selectedElement.refLayerId ?? "__none__"}
+                      onValueChange={(value) =>
+                        updateElement(selectedElement.id, {
+                          refLayerId: value === "__none__" ? undefined : value,
+                        })
+                      }
+                    >
+                      <SelectTrigger className="h-7">
+                        <SelectValue placeholder={t("panel.config.pleaseSelectLayer")} />
+                      </SelectTrigger>
+                      <SelectContent>
+                        <SelectItem value="__none__">{t("panel.config.noneNoRef")}</SelectItem>
+                        {layers
+                          .filter((l) => l.id !== selectedElement.layerId)
+                          .map((l) => (
+                            <SelectItem key={l.id} value={l.id}>
+                              {l.name}
+                            </SelectItem>
+                          ))}
+                      </SelectContent>
+                    </Select>
+                  </label>
+                )}
+                {renderFieldGroup(
+                  t("panel.config.groupCopyStrategy"),
+                  <>
+                    <label className="block space-y-1">
+                      <div>{t("panel.config.copyMode")}</div>
+                      <Select
+                        value={selectedElement.refCopyMode ?? "shallow"}
+                        onValueChange={(value) =>
+                          setReferenceCopyMode?.(
+                            selectedElement.id,
+                            value as ReferenceCopyMode
+                          )
+                        }
+                      >
+                        <SelectTrigger className="h-7">
+                          <SelectValue placeholder={t("panel.config.selectCopyMode")} />
+                        </SelectTrigger>
+                        <SelectContent>
+                          <SelectItem value="shallow">{t("panel.config.shallowFollow")}</SelectItem>
+                          <SelectItem value="deep">{t("panel.config.deepFreeze")}</SelectItem>
+                        </SelectContent>
+                      </Select>
+                    </label>
+                  </>,
+                  <>{t("panel.config.copyStrategyHint")}</>,
+                  { groupKey: "viewportCopyStrategy", defaultOpen: false }
+                )}
+                {renderFieldGroup(
+                  t("panel.config.groupViewportOverflow"),
+                  <label className="block space-y-1">
+                    <div>{t("panel.config.viewportOverflow")}</div>
+                    <Select
+                      value={normalizeViewportOverflow(selectedElement.viewportOverflow)}
+                      onValueChange={(value) =>
+                        updateElement(selectedElement.id, {
+                          viewportOverflow: value as ViewportOverflowMode,
+                        })
+                      }
+                    >
+                      <SelectTrigger className="h-7">
+                        <SelectValue placeholder={t("panel.config.viewportOverflow")} />
+                      </SelectTrigger>
+                      <SelectContent>
+                        {VIEWPORT_OVERFLOW_MODES.map((mode) => (
+                          <SelectItem key={mode} value={mode}>
+                            {mode === "scroll-x"
+                              ? t("panel.config.viewportOverflowScrollX")
+                              : mode === "scroll-y"
+                                ? t("panel.config.viewportOverflowScrollY")
+                                : mode === "scroll"
+                                  ? t("panel.config.viewportOverflowScroll")
+                                  : t("panel.config.viewportOverflowClip")}
+                          </SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                  </label>
+                )}
+              </>,
+              true,
+              [
+                t("panel.config.searchKwViewport"),
+                "viewport",
+                t("panel.config.refLayer"),
+                t("panel.config.viewportOverflow"),
+                t("panel.config.viewportOverflowScrollX"),
+                t("panel.config.viewportOverflowClip"),
+                t("panel.material.shallowCopy"),
+                t("panel.material.deepCopy"),
+              ],
+              <>{t("panel.config.viewportHint")}</>
+            )
           ) : selectedElement.materialType === "reference" ? (
             renderSection(
               "reference",

package/src/panel/components/WorkspaceConfigSidebar.tsx

@@ -62,6 +62,7 @@ export type WorkspaceConfigSidebarProps = Omit<
         | "lifecyclePhase"
         | "fetchConfig"
         | "jsonConfig"
+        | "storageConfig"
         | "logicConfig"
         | "clockConfig"
         | "eventConfig"

package/src/panel/hooks/usePanelElements.ts

@@ -16,6 +16,7 @@ import {
   getDefaultChartConfig,
   getDefaultTableConfig,
   getDefaultGridConfig,
+  getDefaultViewportConfig,
   getDefaultLayer,
   getDefaultNodeName,
   getDefaultScene3dConfigForMaterial,
@@ -552,7 +553,10 @@ export function usePanelElements() {
       .filter((n) => isPanelElementNode(n) && n.props)
       .map((n) => n.props as PanelElement);
     const desiredMode = options?.referenceCopyMode;
-    if (nextProps.materialType === "reference" && desiredMode) {
+    if (
+      (nextProps.materialType === "reference" || nextProps.materialType === "viewport") &&
+      desiredMode
+    ) {
       if (desiredMode === "deep" && nextProps.refLayerId) {
         nextProps.refCopyMode = "deep";
         nextProps.refSnapshot = buildDeepReferenceSnapshot(all, nextProps.refLayerId);
@@ -596,7 +600,9 @@ export function usePanelElements() {
       name: getDefaultNodeName(materialType, t),
       ...getDefaultTextContent(materialType, t),
       ...getDefaultGridConfig(materialType),
-      refCopyMode: materialType === "reference" ? "shallow" : undefined,
+      ...getDefaultViewportConfig(materialType),
+      refCopyMode:
+        materialType === "reference" || materialType === "viewport" ? "shallow" : undefined,
       chart: getDefaultChartConfig(materialType, t),
       table: getDefaultTableConfig(materialType, t),
       geometryShape: materialType === "geometry" ? "rect" : undefined,
@@ -700,7 +706,7 @@ export function usePanelElements() {
         .filter((n) => isPanelElementNode(n) && n.props)
         .map((n) => n.props as PanelElement);
       const target = all.find((el) => el.id === id);
-      if (!target || target.materialType !== "reference") return;
+      if (!target || (target.materialType !== "reference" && target.materialType !== "viewport")) return;
       const currentLayers =
         (current.variables?.layers as PanelLayer[] | undefined) ?? [DEFAULT_LAYER];
       const layer = currentLayers.find((l) => l.id === target.layerId);
@@ -895,7 +901,7 @@ export function usePanelElements() {
         if (target.isMapping) return false;
         const willBeDeleted = mode === "remove" && el.layerId === layerId;
         if (willBeDeleted) return false;
-        if (el.materialType !== "reference") return false;
+        if (el.materialType !== "reference" && el.materialType !== "viewport") return false;
         if (el.refLayerId !== layerId) return false;
         return (el.refCopyMode ?? "shallow") !== "deep";
       });

package/src/panel/library/capture-preview-snapshot.ts

@@ -620,7 +620,8 @@ async function paintPanelElementOntoCanvas(
     liveNode &&
     (el.materialType === "reference" ||
       el.materialType === "table" ||
-      el.materialType === "grid")
+      el.materialType === "grid" ||
+      el.materialType === "viewport")
   ) {
     try {
       await drawNodeOntoCanvas(ctx, liveNode, 0, 0, w, h, 0);
@@ -681,7 +682,8 @@ export async function capturePreviewLayerSnapshot(
   ctx.fillStyle = options.backgroundColor ?? "#ffffff";
   ctx.fillRect(0, 0, width, height);
 
-  const sorted = [...elements].sort((a, b) => (a.zIndex ?? 1) - (b.zIndex ?? 1));
+  const sorted = [...elements]
+    .sort((a, b) => (a.zIndex ?? 1) - (b.zIndex ?? 1));
   for (const el of sorted) {
     const liveNode =
       options.canvasRoot?.querySelector<HTMLElement>(

package/src/panel/types.ts

@@ -54,6 +54,8 @@ export type PanelElementStyle = {
 
 export type ReferenceCopyMode = "shallow" | "deep";
 
+export type ViewportOverflowMode = "scroll-x" | "scroll-y" | "scroll" | "clip";
+
 import type { PanelTableConfig } from "@arronqzy/view-table";
 import type { Scene3dConfig } from "@arronqzy/view-scene3d";
 
@@ -83,6 +85,8 @@ export type PanelElement = {
   gridPadding?: number;
   gridSnapThreshold?: number;
   parentGridId?: string;
+  /** 视窗节点：只显示自身尺寸内的引用图层内容，超出部分滚动或裁剪 */
+  viewportOverflow?: ViewportOverflowMode;
   gridSlotIndex?: number;
   gridColSpan?: number;
   gridRowSpan?: number;

package/src/panel/utils/panelElementDefaults.ts

@@ -17,6 +17,7 @@ const DEFAULT_NODE_NAME_KEYS: Record<string, string> = {
   funnel: "panel.defaults.funnel",
   text: "panel.defaults.text",
   grid: "panel.defaults.grid",
+  viewport: "panel.defaults.viewport",
   image: "panel.defaults.image",
   video: "panel.defaults.video",
   audio: "panel.defaults.audio",
@@ -70,6 +71,8 @@ export function getDefaultSizeByMaterial(materialType: string) {
       return { width: 180, height: 120 };
     case "grid":
       return { width: 320, height: 220 };
+    case "viewport":
+      return { width: 360, height: 240 };
     case "image":
       return { width: 220, height: 140 };
     case "video":
@@ -141,6 +144,13 @@ export function getDefaultGridConfig(materialType: string) {
   } as const;
 }
 
+export function getDefaultViewportConfig(materialType: string) {
+  if (materialType !== "viewport") return {};
+  return {
+    viewportOverflow: "clip" as const,
+  };
+}
+
 export function getDefaultChartConfig(
   materialType: string,
   t: TranslateFn = tFallback

package/src/panel/utils/panelElementNodes.ts

@@ -26,9 +26,11 @@ export function buildDeepReferenceSnapshot(
   const layerNodes = allElements.filter((el) => el.layerId === layerId);
   return layerNodes.map((el) => {
     const cloned = clonePanelElement(el);
-    if (cloned.materialType === "reference" && cloned.refLayerId) {
-      cloned.refCopyMode = "deep";
-      cloned.refSnapshot = buildDeepReferenceSnapshot(allElements, cloned.refLayerId, nextVisited);
+    if (cloned.materialType === "reference" || cloned.materialType === "viewport") {
+      if (cloned.refLayerId) {
+        cloned.refCopyMode = "deep";
+        cloned.refSnapshot = buildDeepReferenceSnapshot(allElements, cloned.refLayerId, nextVisited);
+      }
     }
     return cloned;
   });

package/src/panel/utils/viewportPlacement.ts

@@ -0,0 +1,73 @@
+export const VIEWPORT_OVERFLOW_MODES = [
+  "scroll-x",
+  "scroll-y",
+  "scroll",
+  "clip",
+] as const;
+
+export type ViewportOverflowMode = (typeof VIEWPORT_OVERFLOW_MODES)[number];
+
+export const DEFAULT_VIEWPORT_OVERFLOW: ViewportOverflowMode = "clip";
+
+export function isViewportOverflowMode(
+  value: unknown
+): value is ViewportOverflowMode {
+  return (
+    value === "scroll-x" ||
+    value === "scroll-y" ||
+    value === "scroll" ||
+    value === "clip"
+  );
+}
+
+export function normalizeViewportOverflow(
+  value: unknown
+): ViewportOverflowMode {
+  return isViewportOverflowMode(value) ? value : DEFAULT_VIEWPORT_OVERFLOW;
+}
+
+export function viewportOverflowStyle(mode: ViewportOverflowMode): {
+  overflowX: "hidden" | "auto";
+  overflowY: "hidden" | "auto";
+} {
+  switch (mode) {
+    case "scroll-x":
+      return { overflowX: "auto", overflowY: "hidden" };
+    case "scroll-y":
+      return { overflowX: "hidden", overflowY: "auto" };
+    case "scroll":
+      return { overflowX: "auto", overflowY: "auto" };
+    default:
+      return { overflowX: "hidden", overflowY: "hidden" };
+  }
+}
+
+export function isViewportNode(
+  el: { materialType?: string } | undefined
+): boolean {
+  return el?.materialType === "viewport";
+}
+
+/** 引用节点与视窗节点都通过选择图层来预览内容 */
+export function isLayerPreviewNode(
+  el: { materialType?: string } | undefined
+): boolean {
+  return el?.materialType === "reference" || el?.materialType === "viewport";
+}
+
+/**
+ * 视窗按自身宽高开窗；预览里节点会被整体拉满视口，
+ * 内部引用内容必须用同一套缩放，滚动比例才和编辑态一致。
+ */
+export function viewportWindowContentScale(
+  current: { id: string; width: number; height: number },
+  originals: ReadonlyArray<{ id: string; width: number; height: number }>
+): { scaleX: number; scaleY: number } {
+  const original = originals.find((n) => n.id === current.id);
+  const ow = Math.max(1, original?.width ?? current.width);
+  const oh = Math.max(1, original?.height ?? current.height);
+  return {
+    scaleX: Math.max(1, current.width) / ow,
+    scaleY: Math.max(1, current.height) / oh,
+  };
+}