@arronqzy/vue-view 0.1.9 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arronqzy/vue-view",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Vue 3 visual view editor for Abuilder (Ant Design Vue)",
   "license": "MIT",
   "type": "module",
@@ -23,13 +23,13 @@
     "selecto": "^1.26.3",
     "uuid": "^13.0.0",
     "vue": "^3.5.13",
-    "@arronqzy/blueprint-dsl": "1.0.9",
-    "@arronqzy/i18n": "0.1.7",
-    "@arronqzy/view-scene3d": "0.1.2",
-    "@arronqzy/view-table": "0.1.5",
-    "@arronqzy/vue-rx-store": "0.1.3",
+    "@arronqzy/blueprint-dsl": "1.0.10",
     "@arronqzy/rx-store": "1.0.5",
-    "@arronqzy/vue-blueprint": "0.1.7"
+    "@arronqzy/view-table": "0.1.5",
+    "@arronqzy/vue-blueprint": "0.1.8",
+    "@arronqzy/i18n": "0.1.8",
+    "@arronqzy/view-scene3d": "0.1.2",
+    "@arronqzy/vue-rx-store": "0.1.3"
   },
   "peerDependencies": {
     "vue": "^3.4.0"
@@ -39,8 +39,8 @@
     "eslint": "^8.57.0",
     "typescript": "^5.5.4",
     "vue-tsc": "^2.2.0",
-    "@arronqzy/typescript-config": "1.0.0",
-    "@arronqzy/eslint-config": "0.0.0"
+    "@arronqzy/eslint-config": "0.0.0",
+    "@arronqzy/typescript-config": "1.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/panel/components/ElementsLayer.vue

@@ -85,7 +85,7 @@ const NodeContent = defineComponent({
           previewMode: p.previewMode,
         });
       }
-      if (el.materialType === "reference") {
+      if (el.materialType === "reference" || el.materialType === "viewport") {
         return h(ReferenceNodeContent, {
           element: el,
           allElements: p.allElements,
@@ -145,7 +145,8 @@ const NodeContent = defineComponent({
 const sortedElements = computed(() => {
   const byId = new Map<string, PanelElement>();
   for (const el of props.allElements) byId.set(el.id, el);
-  return [...props.elements].sort((a, b) => comparePanelElementsPaintOrder(a, b, byId));
+  return [...props.elements]
+    .sort((a, b) => comparePanelElementsPaintOrder(a, b, byId));
 });
 
 function onSelect(id: string, event: MouseEvent) {
@@ -200,6 +201,7 @@ function hasViewEvent(el: PanelElement) {
       transform: `rotate(${el.rotate ?? 0}deg)`,
       transformOrigin: 'center center',
       boxSizing: 'border-box',
+      overflow: el.materialType === 'viewport' ? 'hidden' : undefined,
       ...getNodeVisualStyle(el),
     }"
     @mousedown="onSelect(el.id, $event)"

package/src/panel/components/MaterialPreview.vue

@@ -157,5 +157,13 @@ const common =
       />
     </div>
   </div>
+  <div v-else-if="id === 'viewport'" :class="common">
+    <div class="absolute inset-1.5 overflow-hidden rounded-sm border border-primary/70 bg-primary/10">
+      <div class="absolute left-1 top-1 h-6 w-8 rounded-[2px] bg-primary/45" />
+      <div class="absolute left-6 top-4 h-7 w-10 rounded-[2px] bg-primary/30" />
+      <div class="absolute bottom-0 right-0 h-1.5 w-6 rounded-tl bg-primary/55" />
+      <div class="absolute bottom-0 right-0 top-2 w-1.5 rounded-l bg-primary/40" />
+    </div>
+  </div>
   <div v-else :class="common" />
 </template>

package/src/panel/components/MaterialSidebar.vue

@@ -157,17 +157,26 @@ function setExpanded(key: string, next: boolean) {
 }
 
 function hasRefInSubtree(node: PanelElement, visited: Set<string>): boolean {
-  if (node.materialType === "reference") return true;
+  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 ?? []
+  const children = getTreeChildren(node);
+  return children.some((child) => hasRefInSubtree(child, nextVisited));
+}
+
+function getTreeChildren(node: PanelElement, sourceOverride?: PanelElement[]) {
+  if (node.materialType === "reference" || node.materialType === "viewport") {
+    return node.refCopyMode === "deep"
+      ? node.refSnapshot ?? sourceOverride ?? []
       : node.refLayerId
         ? elementsByLayer.value.get(node.refLayerId) ?? []
         : [];
-  return children.some((child) => hasRefInSubtree(child, nextVisited));
+  }
+  if (node.materialType === "grid") {
+    return [...(childrenByGridByLayer.value.get(node.layerId)?.get(node.id) ?? [])];
+  }
+  return [];
 }
 
 function nodeMatchesTreeSearch(node: PanelElement, visited: Set<string>): boolean {
@@ -177,19 +186,7 @@ function nodeMatchesTreeSearch(node: PanelElement, visited: Set<string>): boolea
   if (visited.has(node.id)) return false;
   const nextVisited = new Set(visited);
   nextVisited.add(node.id);
-  const isRef = node.materialType === "reference";
-  const isGrid = node.materialType === "grid";
-  const gridChildren = isGrid
-    ? [...(childrenByGridByLayer.value.get(node.layerId)?.get(node.id) ?? [])]
-    : [];
-  const children = isRef
-    ? node.refCopyMode === "deep"
-      ? node.refSnapshot ?? []
-      : node.refLayerId
-        ? elementsByLayer.value.get(node.refLayerId) ?? []
-        : []
-    : gridChildren;
-  return children.some((child) => nodeMatchesTreeSearch(child, nextVisited));
+  return getTreeChildren(node).some((child) => nodeMatchesTreeSearch(child, nextVisited));
 }
 
 function getRootNodes(layerId: string) {

package/src/panel/components/MaterialSidebarTreeNode.vue

@@ -38,7 +38,9 @@ const emit = defineEmits<{
 
 const nodeKey = computed(() => `node:${props.path}`);
 const selected = computed(() => props.selectedIds.includes(props.node.id));
-const isRef = computed(() => props.node.materialType === "reference");
+const isRef = computed(
+  () => props.node.materialType === "reference" || props.node.materialType === "viewport"
+);
 const refMode = computed(() => props.node.refCopyMode ?? "shallow");
 const isDeepRef = computed(() => isRef.value && refMode.value === "deep");
 const nodeHomeLayer = computed(() => props.layerById.get(props.node.layerId));
@@ -82,7 +84,7 @@ function nodeMatchesTreeSearch(
   const next = new Set(visited);
   next.add(node.id);
   const childList =
-    node.materialType === "reference"
+    node.materialType === "reference" || node.materialType === "viewport"
       ? node.refCopyMode === "deep"
         ? node.refSnapshot ?? sourceOverride ?? []
         : node.refLayerId

package/src/panel/components/PanelConfigSidebar.vue

@@ -22,6 +22,7 @@ import PanelConfigVideoSection from "./config/PanelConfigVideoSection.vue";
 import PanelConfigGeometrySection from "./config/PanelConfigGeometrySection.vue";
 import PanelConfigScene3dSection from "./config/PanelConfigScene3dSection.vue";
 import PanelConfigGridSection from "./config/PanelConfigGridSection.vue";
+import PanelConfigViewportSection from "./config/PanelConfigViewportSection.vue";
 import PanelConfigGridChildSpan from "./config/PanelConfigGridChildSpan.vue";
 import PanelConfigReferenceSection from "./config/PanelConfigReferenceSection.vue";
 import PanelConfigTableSection from "./table/PanelConfigTableSection.vue";
@@ -156,6 +157,9 @@ const visibleSectionCount = computed(() => {
   if (materialType.value === "image") checks.push(["imageConfig", t("panel.config.sectionImage"), [t("panel.defaults.image")]]);
   if (materialType.value === "geometry") checks.push(["geometryConfig", t("panel.config.sectionGeometry"), [t("panel.defaults.geometry")]]);
   if (materialType.value === "grid") checks.push(["gridConfig", t("panel.config.sectionGrid"), [t("panel.config.searchKwGrid")]]);
+  if (materialType.value === "viewport") {
+    checks.push(["viewportConfig", t("panel.config.sectionViewport"), [t("panel.config.searchKwViewport"), t("panel.config.refLayer")]]);
+  }
   if (props.selectedElement?.parentGridId) {
     checks.push(["gridChildSpan", t("panel.config.sectionGridChildSpan"), [t("panel.config.searchKwCrossCol")]]);
   }
@@ -354,6 +358,18 @@ watch(
               @update:open="(v) => setSectionExpanded('gridConfig', v)"
             />
 
+            <PanelConfigViewportSection
+              v-if="materialType === 'viewport' && shouldShowSection('viewportConfig', t('panel.config.sectionViewport'), [t('panel.config.searchKwViewport'), t('panel.config.viewportOverflow'), t('panel.config.refLayer')])"
+              :element="selectedElement"
+              :layers="layers"
+              :is-editable="isNodeEditable"
+              :open="isSectionExpanded('viewportConfig')"
+              :force-open="forceOpenSections"
+              :set-reference-copy-mode="setReferenceCopyMode"
+              :update-element="updateElement"
+              @update:open="(v) => setSectionExpanded('viewportConfig', v)"
+            />
+
             <PanelConfigGridChildSpan
               v-if="selectedElement.parentGridId && shouldShowSection('gridChildSpan', t('panel.config.sectionGridChildSpan'), [t('panel.config.searchKwCrossCol'), t('panel.config.searchKwCrossRow')])"
               :element="selectedElement"
@@ -394,7 +410,7 @@ watch(
             />
 
             <div
-              v-if="!isChartElement && materialType && !['text', 'table', 'audio', 'video', 'image', 'geometry', 'grid', 'reference'].includes(materialType)"
+              v-if="!isChartElement && materialType && !['text', 'table', 'audio', 'video', 'image', 'geometry', 'grid', 'viewport', 'reference'].includes(materialType)"
               class="text-xs leading-6 text-gray-500"
             >
               {{ t("panel.config.notChartType") }}

package/src/panel/components/WorkspaceConfigSidebar.vue

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

package/src/panel/components/config/PanelConfigMultiSelect.vue

@@ -4,6 +4,11 @@ import { computed, ref } from "vue";
 import { Card, Checkbox, Input, InputNumber, Select } from "ant-design-vue";
 import type { PanelElement, PanelLayer, ReferenceCopyMode } from "../../types";
 import { CHART_TYPES } from "../../utils/chartOptionBuilder";
+import {
+  VIEWPORT_OVERFLOW_MODES,
+  normalizeViewportOverflow,
+  type ViewportOverflowMode,
+} from "../../utils/viewportPlacement";
 
 const { t, locale } = useI18n();
 const props = defineProps<{
@@ -357,7 +362,7 @@ function setNodeCardExpanded(id: string, open: boolean) {
               </div>
             </template>
 
-            <template v-if="el.materialType === 'reference'">
+            <template v-if="el.materialType === 'reference' || el.materialType === 'viewport'">
               <div class="grid grid-cols-2 gap-2">
                 <label class="block space-y-1">
                   <div>{{ t("panel.config.refLayer") }}</div>
@@ -392,6 +397,30 @@ function setNodeCardExpanded(id: string, open: boolean) {
               </div>
             </template>
 
+            <template v-if="el.materialType === 'viewport'">
+              <label class="block space-y-1">
+                <div>{{ t("panel.config.viewportOverflow") }}</div>
+                <Select
+                  size="small"
+                  class="w-full"
+                  :value="normalizeViewportOverflow(el.viewportOverflow)"
+                  @update:value="(v) => updateElement(el.id, { viewportOverflow: v as ViewportOverflowMode })"
+                >
+                  <Select.Option v-for="mode in VIEWPORT_OVERFLOW_MODES" :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")
+                    }}
+                  </Select.Option>
+                </Select>
+              </label>
+            </template>
+
             <template v-if="el.materialType === 'image'">
               <label class="block space-y-1">
                 <div>{{ t("panel.config.backgroundImageUrl") }}</div>

package/src/panel/components/config/PanelConfigViewportSection.vue

@@ -0,0 +1,114 @@
+<script setup lang="ts">
+import { useI18n } from "@arronqzy/i18n/vue";
+import { Select } from "ant-design-vue";
+import type { PanelElement, PanelLayer, ReferenceCopyMode } from "../../types";
+import {
+  VIEWPORT_OVERFLOW_MODES,
+  normalizeViewportOverflow,
+  type ViewportOverflowMode,
+} from "../../utils/viewportPlacement";
+import ConfigFieldGroup from "./ConfigFieldGroup.vue";
+import ConfigSection from "./ConfigSection.vue";
+
+const { t } = useI18n();
+const props = defineProps<{
+  element: PanelElement;
+  layers: PanelLayer[];
+  isEditable: boolean;
+  open: boolean;
+  forceOpen?: boolean;
+  setReferenceCopyMode?: (id: string, mode: ReferenceCopyMode) => void;
+  updateElement: (
+    id: string,
+    patch: Partial<PanelElement>,
+    options?: { batchId?: string; meta?: Record<string, unknown> }
+  ) => void;
+}>();
+
+const emit = defineEmits<{
+  "update:open": [value: boolean];
+}>();
+
+const overflowLabelKey: Record<ViewportOverflowMode, string> = {
+  "scroll-x": "panel.config.viewportOverflowScrollX",
+  "scroll-y": "panel.config.viewportOverflowScrollY",
+  scroll: "panel.config.viewportOverflowScroll",
+  clip: "panel.config.viewportOverflowClip",
+};
+
+function patch(next: Partial<PanelElement>) {
+  props.updateElement(props.element.id, next);
+}
+</script>
+
+<template>
+  <ConfigSection
+    :title="t('panel.config.sectionViewport')"
+    :open="open"
+    :force-open="forceOpen"
+    @update:open="emit('update:open', $event)"
+  >
+    <template #hint>
+      {{ t("panel.config.viewportHint") }}
+    </template>
+    <ConfigFieldGroup :title="t('panel.config.groupRefSource')">
+      <label class="block space-y-1">
+        <div>{{ t("panel.config.refLayer") }}</div>
+        <Select
+          size="small"
+          class="w-full"
+          :value="element.refLayerId ?? '__none__'"
+          :disabled="!isEditable"
+          @update:value="(v) => patch({ refLayerId: v === '__none__' ? undefined : String(v) })"
+        >
+          <Select.Option value="__none__">{{ t("panel.config.noneNoRef") }}</Select.Option>
+          <Select.Option
+            v-for="layer in layers.filter((l) => l.id !== element.layerId)"
+            :key="layer.id"
+            :value="layer.id"
+          >
+            {{ layer.name }}
+          </Select.Option>
+        </Select>
+      </label>
+    </ConfigFieldGroup>
+    <ConfigFieldGroup
+      :title="t('panel.config.groupCopyStrategy')"
+      collapsible
+      :default-open="false"
+    >
+      <template #hint>
+        {{ t("panel.config.copyStrategyHint") }}
+      </template>
+      <label class="block space-y-1">
+        <div>{{ t("panel.config.copyMode") }}</div>
+        <Select
+          size="small"
+          class="w-full"
+          :value="element.refCopyMode ?? 'shallow'"
+          :disabled="!isEditable"
+          @update:value="(v) => setReferenceCopyMode?.(element.id, v as ReferenceCopyMode)"
+        >
+          <Select.Option value="shallow">{{ t("panel.config.shallowFollow") }}</Select.Option>
+          <Select.Option value="deep">{{ t("panel.config.deepFreeze") }}</Select.Option>
+        </Select>
+      </label>
+    </ConfigFieldGroup>
+    <ConfigFieldGroup :title="t('panel.config.groupViewportOverflow')">
+      <label class="block space-y-1">
+        <div>{{ t("panel.config.viewportOverflow") }}</div>
+        <Select
+          size="small"
+          class="w-full"
+          :value="normalizeViewportOverflow(element.viewportOverflow)"
+          :disabled="!isEditable"
+          @update:value="(v) => patch({ viewportOverflow: v as ViewportOverflowMode })"
+        >
+          <Select.Option v-for="mode in VIEWPORT_OVERFLOW_MODES" :key="mode" :value="mode">
+            {{ t(overflowLabelKey[mode]) }}
+          </Select.Option>
+        </Select>
+      </label>
+    </ConfigFieldGroup>
+  </ConfigSection>
+</template>

package/src/panel/components/elementsLayerNodes.ts

@@ -16,6 +16,12 @@ import type { PanelElement } from "../types";
 import { buildChartOption, CHART_TYPES } from "../utils/chartOptionBuilder";
 import { PREVIEW_LAYOUT_EVENT } from "../utils/panelStateIO";
 import { cssTextLineHeight, cssTextAlignStyle } from "../utils/panelElementDefaults";
+import {
+  isViewportNode,
+  normalizeViewportOverflow,
+  viewportOverflowStyle,
+  viewportWindowContentScale,
+} from "../utils/viewportPlacement";
 import TableNodeContent from "./table/TableNodeContent.vue";
 import Scene3dNodeContent from "@arronqzy/view-scene3d/vue";
 
@@ -712,15 +718,25 @@ export const ReferenceNodeContent = defineComponent({
       const sourceHeight = Math.max(1, maxY - minY);
       const innerW = Math.max(1, p.element.width);
       const innerH = Math.max(1, p.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(p.element);
+      const windowScale = windowFit
+        ? viewportWindowContentScale(p.element, p.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,
       };
     });
 
@@ -739,20 +755,27 @@ export const ReferenceNodeContent = defineComponent({
         ]);
       }
 
-      return h("div", { class: "pointer-events-none relative h-full w-full overflow-hidden" }, [
-        ...sourceNodes.value.map((node) => {
+      const overflowCss = isViewportNode(p.element)
+        ? viewportOverflowStyle(normalizeViewportOverflow(p.element.viewportOverflow))
+        : { overflowX: "hidden" as const, overflowY: "hidden" as const };
+      const canScroll =
+        isViewportNode(p.element) &&
+        (overflowCss.overflowX === "auto" || overflowCss.overflowY === "auto");
+
+      const innerNodes = sourceNodes.value.map((node) => {
           const box = getNodeAABB(node);
-          const left = layout.value!.offsetX + (box.left - layout.value!.minX) * layout.value!.scale;
-          const top = layout.value!.offsetY + (box.top - layout.value!.minY) * layout.value!.scale;
-          const width = Math.max(12, node.width * layout.value!.scale);
-          const height = Math.max(10, node.height * layout.value!.scale);
-          const boxWidth = Math.max(12, (box.right - box.left) * layout.value!.scale);
-          const boxHeight = Math.max(10, (box.bottom - box.top) * layout.value!.scale);
+          const left = layout.value!.offsetX + (box.left - layout.value!.minX) * layout.value!.scaleX;
+          const top = layout.value!.offsetY + (box.top - layout.value!.minY) * layout.value!.scaleY;
+          const width = Math.max(12, node.width * layout.value!.scaleX);
+          const height = Math.max(10, node.height * layout.value!.scaleY);
+          const boxWidth = Math.max(12, (box.right - box.left) * layout.value!.scaleX);
+          const boxHeight = Math.max(10, (box.bottom - box.top) * layout.value!.scaleY);
           return h(
             "div",
             {
               key: node.id,
               class: "absolute overflow-visible",
+              "data-viewport-item": isViewportNode(p.element) ? "true" : undefined,
               style: { left, top, width: boxWidth, height: boxHeight },
             },
             [
@@ -760,6 +783,7 @@ export const ReferenceNodeContent = defineComponent({
                 "div",
                 {
                   class: "absolute",
+                  "data-viewport-item": isViewportNode(p.element) ? "true" : undefined,
                   style: {
                     left: (boxWidth - width) / 2,
                     top: (boxHeight - height) / 2,
@@ -777,7 +801,7 @@ export const ReferenceNodeContent = defineComponent({
                         previewLayoutKey: p.previewLayoutKey,
                         previewMode: p.previewMode,
                       })
-                    : node.materialType === "reference"
+                    : node.materialType === "reference" || node.materialType === "viewport"
                       ? h(ReferenceNodeContent as Component, {
                           element: node,
                           allElements: p.allElements,
@@ -800,8 +824,42 @@ export const ReferenceNodeContent = defineComponent({
               ),
             ]
           );
-        }),
-      ]);
+        });
+
+      return h(
+        "div",
+        {
+          class: "relative h-full w-full",
+          style: {
+            overflowX: overflowCss.overflowX,
+            overflowY: overflowCss.overflowY,
+            pointerEvents: isViewportNode(p.element) ? "auto" : "none",
+          },
+          onWheel: canScroll
+            ? (e: WheelEvent) => {
+                e.stopPropagation();
+              }
+            : undefined,
+        },
+        [
+          h(
+            "div",
+            {
+              class: "pointer-events-none relative",
+              "data-viewport-sizer": isViewportNode(p.element) ? "true" : undefined,
+              style: isViewportNode(p.element)
+                ? {
+                    width: layout.value.sourceWidth,
+                    height: layout.value.sourceHeight,
+                    minWidth: "100%",
+                    minHeight: "100%",
+                  }
+                : { width: "100%", height: "100%" },
+            },
+            innerNodes
+          ),
+        ]
+      );
     };
   },
 }) as Component;

package/src/panel/components/materialSidebarData.ts

@@ -26,6 +26,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",
@@ -68,6 +69,7 @@ export function getDefaultCategories(t: TranslateFn): 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") },
       ],

package/src/panel/hooks/usePanelElements.ts

@@ -16,6 +16,7 @@ import {
   DEFAULT_LAYER_ID,
   getDefaultChartConfig,
   getDefaultGridConfig,
+  getDefaultViewportConfig,
   getDefaultNodeName,
   getDefaultScene3dConfigForMaterial,
   getDefaultSizeByMaterial,
@@ -569,7 +570,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);
@@ -611,7 +615,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,
@@ -712,7 +718,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);
@@ -904,7 +910,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/types.ts

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

package/src/panel/utils/panelElementDefaults.ts

@@ -15,6 +15,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",
@@ -71,6 +72,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":
@@ -145,6 +148,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 = tForLocale("zh-CN")

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,
+  };
+}