@arronqzy/vue-view 0.1.9 → 0.1.11

package/README.md

@@ -29,7 +29,21 @@ createApp(VueViewPanel).use(Antd).mount("#app");
 import { VueViewOnlinePreview, parseOnlinePreviewSearchParams } from "@arronqzy/vue-view";
 ```
 
-URL 参数：`?preview=online&projectId=<id>&pid=<instanceId>`
+URL 参数：`?preview=online&projectId=<id>&pid=<instanceId>`。也可传入 `workspace` 直接预览宿主数据（优先于 `projectId`）。
+
+### 宿主集成
+
+```ts
+import {
+  addEventSubscription,
+  AbuilderEvents,
+  parseWorkspaceData,
+  createEmptyWorkspace,
+  createWorkspaceProjectId,
+} from "@arronqzy/vue-view";
+```
+
+创建 / 同步工作区会发出 `workspace:add` / `workspace:sync`。`parseWorkspaceData` 的 `value` 可作 `initialWorkspace`。IndexedDB CRUD 与 `getPreviewSnapshot` **不导出**（后者仅 React 实现）。
 
 ## 依赖
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arronqzy/vue-view",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "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/i18n": "0.1.8",
+    "@arronqzy/blueprint-dsl": "1.0.11",
+    "@arronqzy/rx-store": "1.0.5",
     "@arronqzy/view-scene3d": "0.1.2",
     "@arronqzy/view-table": "0.1.5",
-    "@arronqzy/vue-rx-store": "0.1.3",
-    "@arronqzy/rx-store": "1.0.5",
-    "@arronqzy/vue-blueprint": "0.1.7"
+    "@arronqzy/vue-blueprint": "0.1.9",
+    "@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/index.ts

@@ -1,4 +1,30 @@
 export { default as VueViewPanel } from "./panel/VueViewPanel.vue";
 export { default as VueViewOnlinePreview } from "./panel/VueViewOnlinePreview.vue";
 export { parseOnlinePreviewSearchParams } from "./panel/parseOnlinePreviewSearchParams";
+export type { WorkspaceProjectRecord } from "./panel/library/workspace-project-db";
 export type * from "./panel/types";
+export {
+  parseViewData,
+  validateViewData,
+  parseBlueprintData,
+  validateBlueprintData,
+  validateWorkspaceData,
+  parseWorkspaceData,
+  createEmptyWorkspace,
+} from "./panel/library/parse-workspace-data";
+export { createWorkspaceProjectId } from "./panel/library/workspace-project-db";
+export {
+  addEventSubscription,
+  AbuilderEvents,
+} from "./panel/library/event-subscription";
+export type {
+  AbuilderEventName,
+  AbuilderEventPayloadMap,
+  WorkspaceAddEventPayload,
+  WorkspaceSyncEventPayload,
+  WorkspaceData,
+} from "./panel/library/event-subscription";
+export type {
+  ParseCheckResult,
+  WorkspaceParseCheckResult,
+} from "./panel/library/parse-workspace-data";

package/src/panel/VueViewOnlinePreview.vue

@@ -22,7 +22,10 @@ import {
   useViewScopeStoreVersion,
 } from "./scope/view-scope-store";
 import { resolvePanelElementScope } from "./utils/scope-template";
-import { getWorkspaceProject } from "./library/workspace-project-db";
+import {
+  getWorkspaceProject,
+  type WorkspaceProjectRecord,
+} from "./library/workspace-project-db";
 import { readWorkspacePreviewCache } from "./library/workspace-project-cache";
 import { subscribeWorkspaceProjectUpdates } from "./library/workspace-project-sync";
 import {
@@ -41,8 +44,12 @@ const { t, locale } = useI18n();
 const PREVIEW_BOOT_PHASES: PageLifecyclePhase[] = ["mounted"];
 
 const props = defineProps<{
-  projectId: string;
+  /** 从 IndexedDB / 缓存按 ID 加载；与 `workspace` 二选一，优先 `workspace` */
+  projectId?: string;
   previewInstanceId?: string;
+  nameSpace?: string | null;
+  /** 直接传入完整工作区，用于宿主后端加载后预览 */
+  workspace?: WorkspaceProjectRecord | null;
 }>();
 
 const loadError = ref<string | null>(null);
@@ -53,7 +60,7 @@ const blueprintLibraryItems = ref<BlueprintLibraryListItem[]>([]);
 const layoutRevision = ref(0);
 const layoutReady = ref(false);
 const sceneRef = ref<HTMLDivElement | null>(null);
-const outputScale = ref(readOutputScale());
+const outputScale = ref(readOutputScale(props.nameSpace));
 const fillScale = ref({ scaleX: 1, scaleY: 1 });
 
 const layers = computed(() => (panelState.value ? parsePanelLayers(panelState.value) : []));
@@ -64,10 +71,19 @@ const allElements = computed(() =>
   panelState.value ? parseAllPanelElements(panelState.value) : []
 );
 
+const resolvedProjectId = computed(
+  () => props.workspace?.id ?? props.projectId ?? ""
+);
+
+function workspaceTitle(record: WorkspaceProjectRecord) {
+  const product = typeof record.productName === "string" ? record.productName : "";
+  return product.trim() || record.name || t("panel.workspace.previewDocTitle");
+}
+
 async function loadWorkspaceRecord(projectId: string) {
-  const fromDb = await getWorkspaceProject(projectId);
+  const fromDb = await getWorkspaceProject(projectId, props.nameSpace);
   if (fromDb) return fromDb;
-  return readWorkspacePreviewCache(projectId);
+  return readWorkspacePreviewCache(projectId, props.nameSpace);
 }
 
 function applyTitleIcon(titleIconDataUrl?: string) {
@@ -82,13 +98,7 @@ function applyTitleIcon(titleIconDataUrl?: string) {
   }
 }
 
-async function loadProject() {
-  const record = await loadWorkspaceRecord(props.projectId);
-  if (!record) {
-    loadError.value = t("panel.messages.workspaceNotFound");
-    panelState.value = null;
-    return;
-  }
+function applyWorkspaceRecord(record: WorkspaceProjectRecord) {
   const normalized = normalizeImportedPanelState(record.panelState);
   if (!normalized) {
     loadError.value = t("panel.messages.workspaceDataInvalid");
@@ -99,24 +109,56 @@ async function loadProject() {
   clearViewElementScopes();
   panelState.value = normalized;
   blueprintGraph.value = BlueprintGraph.fromDocument(record.blueprintDocument);
-  document.title = record.productName.trim() || record.name || t("panel.workspace.previewDocTitle");
+  document.title = workspaceTitle(record);
   applyTitleIcon(record.titleIconDataUrl);
   projectRevision.value += 1;
 }
 
-onMounted(() => {
-  void loadProject();
-});
+async function loadProject() {
+  if (props.workspace) {
+    applyWorkspaceRecord(props.workspace);
+    return;
+  }
+  if (!props.projectId) {
+    loadError.value = t("panel.messages.workspaceNotFound");
+    panelState.value = null;
+    return;
+  }
+  const record = await loadWorkspaceRecord(props.projectId);
+  if (!record) {
+    loadError.value = t("panel.messages.workspaceNotFound");
+    panelState.value = null;
+    return;
+  }
+  applyWorkspaceRecord(record);
+}
 
-onMounted(() => {
-  const unsub = subscribeWorkspaceProjectUpdates(props.projectId, () => {
+watch(
+  () => [props.workspace, props.projectId, props.nameSpace] as const,
+  () => {
     void loadProject();
-  });
-  onUnmounted(unsub);
-});
+  },
+  { immediate: true }
+);
+
+watch(
+  () => [props.workspace, props.projectId, props.nameSpace] as const,
+  ([workspace, projectId, nameSpace], _prev, onCleanup) => {
+    if (workspace || !projectId) return;
+    const unsub = subscribeWorkspaceProjectUpdates(
+      projectId,
+      () => {
+        void loadProject();
+      },
+      nameSpace
+    );
+    onCleanup(unsub);
+  },
+  { immediate: true }
+);
 
 watch(projectRevision, () => {
-  void listBlueprintLibrary().then((items) => {
+  void listBlueprintLibrary(props.nameSpace).then((items) => {
     blueprintLibraryItems.value = items;
   });
 });
@@ -126,9 +168,9 @@ const blueprintLibraryNameById = computed(
 );
 
 const resolveLibraryBlueprint: LibraryBlueprintResolver = async (libraryBlueprintId) => {
-  const record = await getBlueprintLibraryRecord(libraryBlueprintId);
+  const record = await getBlueprintLibraryRecord(libraryBlueprintId, props.nameSpace);
   if (!record) return null;
-  const items = await listBlueprintLibrary();
+  const items = await listBlueprintLibrary(props.nameSpace);
   const nameById = new Map(items.map((item) => [item.id, item.name]));
   return documentToRunnableGraph(record.document, { libraryNameById: nameById });
 };
@@ -167,7 +209,7 @@ const displayElements = computed(() =>
 );
 
 function applySceneFit() {
-  const enabled = readOutputScale();
+  const enabled = readOutputScale(props.nameSpace);
   outputScale.value = enabled;
   const fill = applyPreviewSceneFill(
     sceneRef.value,
@@ -277,7 +319,7 @@ function noopSelect() {}
     v-else
     class="min-h-screen w-full overflow-hidden bg-white text-gray-900"
     data-preview-mode="online"
-    :data-project-id="projectId"
+    :data-project-id="resolvedProjectId"
     :data-preview-instance-id="previewInstanceId ?? ''"
     :data-preview-node-count="String(displayElements.length)"
   >

package/src/panel/VueViewPanel.vue

@@ -78,8 +78,10 @@ const props = withDefaults(
   defineProps<{
     class?: string;
     initialZoom?: number;
+    nameSpace?: string | null;
+    initialWorkspace?: WorkspaceProjectRecord | null;
   }>(),
-  { initialZoom: 1 }
+  { initialZoom: 1, nameSpace: null, initialWorkspace: null }
 );
 
 const {
@@ -296,9 +298,9 @@ const {
 } = useBlueprintNodeSelectionGuard(selectedBlueprintNodeId, applyBlueprintNodeSelection);
 
 const resolveLibraryBlueprint: LibraryBlueprintResolver = async (libraryBlueprintId) => {
-  const record = await getBlueprintLibraryRecord(libraryBlueprintId);
+  const record = await getBlueprintLibraryRecord(libraryBlueprintId, props.nameSpace);
   if (!record) return null;
-  const items = await listBlueprintLibrary();
+  const items = await listBlueprintLibrary(props.nameSpace);
   const nameById = new Map(items.map((item) => [item.id, item.name]));
   return documentToRunnableGraph(record.document, { libraryNameById: nameById });
 };
@@ -319,6 +321,7 @@ const blueprintDebugSession = useBlueprintDebugSession({
   libraryNameById: blueprintLibraryNameById,
   onExecutionBlocked: handleBlueprintExecutionBlocked,
   onViewScopeUpdate: handleViewScopeUpdate,
+  nameSpace: () => props.nameSpace,
 });
 
 const blueprintDebugToolbar = computed(() => ({
@@ -359,7 +362,7 @@ function handleUpdateAllowFalseSignalPropagation(value: boolean) {
 }
 
 async function refreshBlueprintLibrary() {
-  blueprintLibraryItems.value = await listBlueprintLibrary();
+  blueprintLibraryItems.value = await listBlueprintLibrary(props.nameSpace);
 }
 
 onMounted(() => {
@@ -402,6 +405,8 @@ const workspaceProjects = useWorkspaceProjects({
   },
   panelRevision: computed(() => `${historyCursor.value}|${allElements.value.length}`),
   onProjectApplied: handleWorkspaceProjectApplied,
+  initialWorkspace: () => props.initialWorkspace,
+  nameSpace: () => props.nameSpace,
 });
 
 const { triggerBlueprintNode, emitViewEvent, firedLifecyclePhases } = useBlueprintPageLifecycle({
@@ -440,7 +445,7 @@ const blueprintNodeOptions = computed(() =>
 );
 async function loadBlueprintFromLibrary(id: string) {
   await runBusyTask(t("common.loadingBlueprint"), async () => {
-    const record = await getBlueprintLibraryRecord(id);
+    const record = await getBlueprintLibraryRecord(id, props.nameSpace);
     if (!record) {
       message.error(panelMessages().blueprintNotFound);
       void refreshBlueprintLibrary();
@@ -487,14 +492,14 @@ async function syncBlueprintToLibrary() {
   const libraryId = activeBlueprintLibraryId.value;
   if (!libraryId) return;
   await runBusyTask(t("common.syncingBlueprint"), async () => {
-    const record = await getBlueprintLibraryRecord(libraryId);
+    const record = await getBlueprintLibraryRecord(libraryId, props.nameSpace);
     if (!record) return;
     await putBlueprintLibraryRecord({
       ...record,
       document: blueprintGraph.value.document,
       name: blueprintMeta.value.name,
       remark: blueprintMeta.value.remark,
-    });
+    }, props.nameSpace);
     blueprintSyncedDocument.value = blueprintGraph.value.document;
     message.success(panelMessages().blueprintSyncedToLibrary);
     await refreshBlueprintLibrary();
@@ -510,7 +515,7 @@ async function saveBlueprintToLibrary(meta: BlueprintMetaDraft) {
       meta,
       source: "saved",
     });
-    await putBlueprintLibraryRecord(record);
+    await putBlueprintLibraryRecord(record, props.nameSpace);
     activeBlueprintLibraryId.value = id;
     blueprintSyncedDocument.value = blueprintGraph.value.document;
     blueprintMeta.value = meta;
@@ -526,7 +531,7 @@ function handleExport() {
     const url = URL.createObjectURL(blob);
     const a = document.createElement("a");
     a.href = url;
-    const safeName = (productName.value.trim() || "panel")
+    const safeName = ((productName.value ?? "").trim() || "panel")
       .replace(/[\\/:*?"<>|]/g, "-")
       .replace(/\s+/g, "-");
     a.download = `${safeName}-${Date.now()}.json`;
@@ -566,7 +571,7 @@ async function handleBlueprintImportFile(file: File) {
       const text = await file.text();
       const payload = parseBlueprintImportFile(await parseJsonText(text));
       const record = libraryRecordFromImport(payload);
-      await putBlueprintLibraryRecord(record);
+      await putBlueprintLibraryRecord(record, props.nameSpace);
       await refreshBlueprintLibrary();
       if (!activeBlueprintLibraryId.value) snapshotWorkspaceBlueprint();
       await loadBlueprintFromLibrary(record.id);

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>