@kubohiroya/turbowarp-plus-editor-layout 0.1.4 → 0.1.6

package/dist/document-workspace.d.ts

@@ -0,0 +1,23 @@
+export interface DocumentPanelRequest {
+    reference: {
+        providerId: string;
+        documentId: string;
+    };
+    filename: string;
+    mount(element: HTMLElement, close: () => void): {
+        requestClose(): void;
+        dispose(): void;
+    };
+}
+interface DocumentPanelSource {
+    getPanelRequest(reference: DocumentPanelRequest['reference']): DocumentPanelRequest | undefined;
+    subscribePanelRequests(listener: () => void): () => void;
+}
+export declare function getDocumentWorkspace(vm: object): {
+    open(request: DocumentPanelRequest): boolean;
+    connect(handler: NonNullable<(request: DocumentPanelRequest) => void>): () => void;
+    connectSource(next: DocumentPanelSource): () => void;
+    resolve(reference: DocumentPanelRequest["reference"]): DocumentPanelRequest;
+    subscribe(listener: () => void): () => void;
+};
+export {};

package/dist/document-workspace.js

@@ -0,0 +1,45 @@
+function createDocumentWorkspace() {
+    let open;
+    let source;
+    const listeners = new Set();
+    const notify = () => listeners.forEach(listener => listener());
+    return {
+        open(request) {
+            if (!open)
+                return false;
+            open(request);
+            return true;
+        },
+        connect(handler) {
+            open = handler;
+            return () => { if (open === handler)
+                open = undefined; };
+        },
+        connectSource(next) {
+            source = next;
+            const unsubscribe = next.subscribePanelRequests(notify);
+            notify();
+            return () => {
+                unsubscribe();
+                if (source === next)
+                    source = undefined;
+            };
+        },
+        resolve(reference) {
+            return source?.getPanelRequest(reference);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        }
+    };
+}
+const workspaces = new WeakMap();
+export function getDocumentWorkspace(vm) {
+    let workspace = workspaces.get(vm);
+    if (!workspace) {
+        workspace = createDocumentWorkspace();
+        workspaces.set(vm, workspace);
+    }
+    return workspace;
+}

package/dist/sprite-tabs.d.ts

@@ -2,6 +2,7 @@ import React from 'react';
 import type { SpriteVariable } from './sprite-asset-pane.tsx';
 import type { SpriteSearchResult } from './sprite-editor-toolbar.tsx';
 import type { DockviewStagePane } from './dockview-stage.ts';
+export { getDocumentWorkspace } from './document-workspace.ts';
 export { useDockviewStage } from './dockview-stage.ts';
 interface CostumeAsset {
     encodeDataURI(): string;
@@ -11,6 +12,9 @@ interface Target {
     isOriginal: boolean;
     isStage: boolean;
     getName(): string;
+    getCostumes?(): {
+        assetId?: string;
+    }[];
     getCurrentCostume?(): {
         asset?: CostumeAsset;
     } | undefined;
@@ -73,6 +77,12 @@ interface TabOptions<Snapshot = unknown> {
     resize(): void;
     reopenLabel: string;
     multiView?: boolean;
+    layoutStorage?: {
+        storage: Storage;
+        key: string;
+        isProjectLoading?(): boolean;
+        subscribeProject?(listener: () => void): (() => void) | undefined;
+    };
     stagePane?: DockviewStagePane;
     variables?: boolean;
     locale?: string;

package/dist/sprite-tabs.js

@@ -4,6 +4,9 @@ import { createDockview, DefaultTab, themeLight } from 'dockview';
 import { createSpriteLayoutMenu } from "./sprite-layout-menu.js";
 import { SpriteAssetPane } from "./sprite-asset-pane.js";
 import { SpriteEditorToolbar, spriteEditorSections } from "./sprite-editor-toolbar.js";
+import { getDocumentWorkspace } from "./document-workspace.js";
+import { readWorkspaceLayout } from "./workspace-layout.js";
+export { getDocumentWorkspace } from "./document-workspace.js";
 export { useDockviewStage } from "./dockview-stage.js";
 const variableSection = spriteEditorSections.indexOf('variables');
 function createAssetSelections(target, source) {
@@ -41,10 +44,16 @@ function createAssetSelections(target, source) {
     return { selected, ports, layouts, selectors, scroll };
 }
 const stagePanelId = 'tw-plus-stage-display';
+const documentComponent = 'tw-plus-document';
+const documentTitle = ({ filename, reference: { providerId, documentId } }) => `${filename} (${providerId} / ${documentId})`;
 const renameLabels = {
     en: { title: 'Rename sprite', name: 'Sprite name', cancel: 'Cancel', save: 'Rename' },
     ja: { title: 'スプライト名の変更', name: 'スプライト名', cancel: 'キャンセル', save: '変更' }
 };
+const targetName = (target) => target.isStage ? 'Stage' : target.getName();
+const projectSignature = (targets) => JSON.stringify(targets
+    .map(target => JSON.stringify([target.isStage, targetName(target), target.getCostumes?.()[0]?.assetId ?? '']))
+    .sort());
 class SpriteTab extends DefaultTab {
     icon;
     constructor(document) {
@@ -76,16 +85,25 @@ export function mountSpriteTabs(root, content, options) {
     const editLabel = /^ja(?:-|$)/i.test(locale) ? 'クリックしてこのビューで編集' : 'Activate this view to edit';
     const slots = new Map();
     const views = new Map();
+    const documents = new Map();
     const costumeIcons = new WeakMap();
     const remembered = new WeakMap();
     const lastUsed = new WeakMap();
-    const closed = new WeakSet();
+    let closed = new WeakSet();
     let active;
     let observed = vm.editingTarget;
     let syncing = false;
     let nextView = 0;
     let renameDialog;
     const text = options.renameLabels ?? renameLabels.en;
+    const persistence = multiView && options.layoutStorage;
+    const window = document.defaultView;
+    const documentWorkspace = multiView && getDocumentWorkspace(vm);
+    let pendingRestore = Boolean(persistence);
+    let restoreFrame;
+    let restoreTimeout;
+    let saveFrame;
+    const originalTargets = () => vm.runtime.targets.filter(target => target.isOriginal);
     const dockview = createDockview(root, {
         theme: themeLight,
         disableFloatingGroups: true,
@@ -98,8 +116,17 @@ export function mountSpriteTabs(root, content, options) {
                 return [];
             return [{ label: text.title, action: () => openRenameDialog(target) }];
         },
-        createComponent: ({ name }) => {
+        createComponent: ({ name, id: componentId }) => {
             const element = document.createElement('div');
+            if (name === documentComponent) {
+                element.className = 'tw-plus-document-slot';
+                return { element, init({ api }) {
+                        const item = documents.get(componentId);
+                        element.dataset.providerId = item.request.reference.providerId;
+                        element.dataset.documentId = item.request.reference.documentId;
+                        item.session = item.request.mount(element, () => api.close());
+                    } };
+            }
             if (name === stagePanelId) {
                 element.className = 'tw-plus-dockview-stage-slot';
                 return { element, init() { stagePane.attach(element); } };
@@ -189,7 +216,7 @@ export function mountSpriteTabs(root, content, options) {
                 split('below', group.activePanel.id); },
             close: () => { if (group.activePanel)
                 closeSplit(group.activePanel.id); },
-            canClose: () => dockview.groups.length > 1,
+            canClose: () => canCloseGroup(group),
             canSplit: () => views.has(group.activePanel?.id)
         });
         return { ...menu, init() { } };
@@ -328,8 +355,8 @@ export function mountSpriteTabs(root, content, options) {
         view.snapshots.set(view.section, { snapshot, view: descriptor });
     }
     function show(panel) {
-        if (panel?.id === stagePanelId) {
-            // Displaying the Stage does not select the Stage target or interrupt the sprite editor.
+        if (panel?.id === stagePanelId || documents.has(panel?.id)) {
+            // Utility panels do not change the VM editing target.
             refreshSurfaces();
             return;
         }
@@ -368,10 +395,10 @@ export function mountSpriteTabs(root, content, options) {
     }
     function add(target, splitPosition, section) {
         let id = target.id;
-        if (splitPosition || views.has(id) || id === stagePanelId) {
+        if (splitPosition || views.has(id) || id === stagePanelId || documents.has(id)) {
             do {
                 id = 'sprite-view-' + ++nextView;
-            } while (views.has(id) || vm.runtime.targets.some(item => item.id === id));
+            } while (views.has(id) || documents.has(id) || vm.runtime.targets.some(item => item.id === id));
         }
         const source = splitPosition && views.get(splitPosition.referencePanel);
         views.set(id, { id, target, section: section ?? remembered.get(target) ?? options.getSection(),
@@ -407,9 +434,53 @@ export function mountSpriteTabs(root, content, options) {
             [...views.values()].find(item => item.target === target);
         activateView(view?.id ?? add(target).id);
     }
+    function openDocument(request) {
+        if (pendingRestore)
+            finishRestore();
+        const { providerId, documentId } = request.reference;
+        for (const [id, { request: opened }] of documents) {
+            if (opened.reference.providerId === providerId && opened.reference.documentId === documentId) {
+                dockview.getPanel(id)?.api.setActive();
+                return;
+            }
+        }
+        let id;
+        do {
+            id = 'document-view-' + ++nextView;
+        } while (views.has(id) || documents.has(id) || vm.runtime.targets.some(target => target.id === id));
+        const title = documentTitle(request);
+        documents.set(id, { request });
+        try {
+            dockview.addPanel({ id, title, component: documentComponent, renderer: 'always' });
+        }
+        catch (error) {
+            documents.get(id)?.session?.dispose();
+            documents.delete(id);
+            throw error;
+        }
+    }
+    function guardDocumentClose(event) {
+        const element = event.target;
+        const tab = element.closest('[data-tab-panel-id]');
+        const item = documents.get(tab?.dataset.tabPanelId);
+        if (!item)
+            return;
+        const close = event.type === 'click' ? Boolean(element.closest('.dv-default-tab-action')) :
+            event.target === tab && ['Delete', 'Backspace'].includes(event.key);
+        if (!close)
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        item.session?.requestClose();
+    }
+    function canCloseGroup(group) {
+        return dockview.groups.length > 1 && group.panels.every(panel => !documents.has(panel.id));
+    }
     function openStage() {
         if (!stagePane)
             return;
+        if (pendingRestore)
+            finishRestore();
         const existing = dockview.getPanel(stagePanelId);
         if (existing) {
             existing.api.setActive();
@@ -433,7 +504,7 @@ export function mountSpriteTabs(root, content, options) {
     }
     function closeSplit(id = active?.id) {
         const panel = dockview.getPanel(id);
-        if (!multiView || !panel || dockview.groups.length <= 1)
+        if (!multiView || !panel || !canCloseGroup(panel.api.group))
             return false;
         syncing = true;
         try {
@@ -461,6 +532,7 @@ export function mountSpriteTabs(root, content, options) {
             viewAdapter?.restore(describe(view), view.snapshots?.get(section)?.snapshot);
         }
         refreshSurfaces();
+        scheduleSave();
         return true;
     }
     function syncActiveSection(section) {
@@ -468,6 +540,124 @@ export function mountSpriteTabs(root, content, options) {
             return;
         active.section = section;
         refreshSurfaces();
+        scheduleSave();
+    }
+    function writeLayout() {
+        saveFrame = undefined;
+        const targets = originalTargets();
+        if (!persistence || pendingRestore || syncing || !targets.length || persistence.isProjectLoading?.())
+            return;
+        const { grid, activeGroup } = dockview.toJSON();
+        if (!activeGroup || grid.width <= 0 || grid.height <= 0)
+            return;
+        const panels = Object.create(null);
+        for (const [id, view] of views) {
+            panels[id] = { kind: 'sprite', name: targetName(view.target), stage: view.target.isStage, section: view.section };
+        }
+        if (dockview.getPanel(stagePanelId))
+            panels[stagePanelId] = { kind: 'stage' };
+        for (const [id, { request }] of documents)
+            panels[id] = { kind: 'document', ...request.reference };
+        const snapshot = { version: 1, project: projectSignature(targets), grid, activeGroup,
+            editingView: active?.id, panels };
+        try {
+            persistence.storage.setItem(persistence.key, JSON.stringify(snapshot));
+        }
+        catch { /* Storage can be unavailable. */ }
+    }
+    function scheduleSave() {
+        if (persistence && !pendingRestore && saveFrame === undefined) {
+            saveFrame = window.requestAnimationFrame(writeLayout);
+        }
+    }
+    function flushLayout() {
+        if (saveFrame !== undefined) {
+            window.cancelAnimationFrame(saveFrame);
+            writeLayout();
+        }
+    }
+    function finishRestore() {
+        pendingRestore = false;
+        window.clearTimeout(restoreTimeout);
+    }
+    function restoreLayout() {
+        restoreFrame = undefined;
+        if (!pendingRestore || !persistence || persistence.isProjectLoading?.())
+            return;
+        const targets = originalTargets();
+        if (!targets.length || !vm.editingTarget)
+            return;
+        let stored;
+        try {
+            const raw = persistence.storage.getItem(persistence.key);
+            if (raw)
+                stored = readWorkspaceLayout(raw, projectSignature(targets));
+        }
+        catch { /* Storage can be unavailable. */ }
+        if (!stored)
+            return finishRestore();
+        const resolvedSprites = new Map();
+        const resolvedDocuments = new Map();
+        const panels = Object.create(null);
+        for (const [id, reference] of Object.entries(stored.panels)) {
+            if (reference.kind === 'sprite') {
+                const target = targets.find(item => item.isStage === reference.stage && targetName(item) === reference.name);
+                if (!target || id === stagePanelId || (reference.section === variableSection && !options.variables))
+                    return finishRestore();
+                resolvedSprites.set(id, { id, target, section: reference.section, assets: createAssetSelections(target) });
+                panels[id] = { id, title: target.getName(), contentComponent: 'sprite', params: { icon: getIcon(target) } };
+            }
+            else if (reference.kind === 'stage') {
+                if (!stagePane || id !== stagePanelId)
+                    return finishRestore();
+                panels[id] = { id, title: stagePane.title, contentComponent: stagePanelId, renderer: 'always' };
+            }
+            else {
+                if (id === stagePanelId)
+                    return finishRestore();
+                const request = documentWorkspace && documentWorkspace.resolve(reference);
+                if (!request) {
+                    // The project can finish loading before the Blockly host publishes its document catalog.
+                    restoreTimeout ??= window.setTimeout(finishRestore, 2000);
+                    return;
+                }
+                resolvedDocuments.set(id, request);
+                panels[id] = { id, title: documentTitle(request), contentComponent: documentComponent, renderer: 'always' };
+            }
+        }
+        finishRestore();
+        syncing = true;
+        try {
+            dockview.clear();
+            active = undefined;
+            const represented = new Set([...resolvedSprites.values()].map(view => view.target));
+            closed = new WeakSet(targets.filter(target => !represented.has(target)));
+            for (const [id, view] of resolvedSprites)
+                views.set(id, view);
+            for (const [id, request] of resolvedDocuments)
+                documents.set(id, { request });
+            dockview.fromJSON({ grid: stored.grid, activeGroup: stored.activeGroup, panels });
+            const selected = dockview.activePanel;
+            show(views.has(selected?.id) ? selected : dockview.getPanel(stored.editingView) ?? selected);
+        }
+        catch {
+            dockview.clear();
+            for (const view of views.values())
+                disposeView(view);
+            for (const item of documents.values())
+                item.session?.dispose();
+            documents.clear();
+            closed = new WeakSet();
+            active = undefined;
+        }
+        finally {
+            syncing = false;
+        }
+        refresh();
+    }
+    function scheduleRestore() {
+        if (pendingRestore && restoreFrame === undefined)
+            restoreFrame = window.requestAnimationFrame(restoreLayout);
     }
     function refresh() {
         if (syncing)
@@ -504,6 +694,7 @@ export function mountSpriteTabs(root, content, options) {
         finally {
             syncing = false;
         }
+        scheduleRestore();
     }
     function disposeView(view) {
         for (const stored of view.snapshots?.values() ?? [])
@@ -524,8 +715,15 @@ export function mountSpriteTabs(root, content, options) {
         finally {
             syncing = false;
         }
+        scheduleSave();
     });
     const removal = dockview.onDidRemovePanel(panel => {
+        const item = documents.get(panel.id);
+        if (item) {
+            documents.delete(panel.id);
+            item.session?.dispose();
+            return;
+        }
         if (panel.id === stagePanelId) {
             stagePane?.attach(null);
             return;
@@ -539,7 +737,17 @@ export function mountSpriteTabs(root, content, options) {
         if (![...views.values()].some(item => item.target === view.target))
             closed.add(view.target);
     });
-    const layout = multiView && dockview.onDidLayoutChange(refreshSurfaces);
+    const layout = multiView && dockview.onDidLayoutChange(() => {
+        refreshSurfaces();
+        scheduleSave();
+    });
+    const disconnectDocuments = documentWorkspace && documentWorkspace.connect(openDocument);
+    const unsubscribeDocuments = persistence && documentWorkspace && documentWorkspace.subscribe(scheduleRestore);
+    const unsubscribeProject = persistence && persistence.subscribeProject?.(scheduleRestore);
+    if (persistence)
+        window.addEventListener('pagehide', flushLayout);
+    root.addEventListener('click', guardDocumentClose, true);
+    root.addEventListener('keydown', guardDocumentClose, true);
     vm.on('targetsUpdate', refresh);
     refresh();
     return {
@@ -552,6 +760,22 @@ export function mountSpriteTabs(root, content, options) {
         currentView: () => active && describe(active),
         views: () => [...views.values()].map(view => describe(view)),
         dispose() {
+            flushLayout();
+            window.cancelAnimationFrame(restoreFrame);
+            window.clearTimeout(restoreTimeout);
+            if (persistence)
+                window.removeEventListener('pagehide', flushLayout);
+            if (unsubscribeDocuments)
+                unsubscribeDocuments();
+            if (unsubscribeProject)
+                unsubscribeProject();
+            if (disconnectDocuments)
+                disconnectDocuments();
+            root.removeEventListener('click', guardDocumentClose, true);
+            root.removeEventListener('keydown', guardDocumentClose, true);
+            for (const item of documents.values())
+                item.session?.dispose();
+            documents.clear();
             stagePane?.attach(null);
             renameDialog?.remove();
             renameDialog = undefined;
@@ -661,6 +885,7 @@ function SpriteTabs(props) {
             resize: () => latest.current.resize(),
             reopenLabel: props.reopenLabel,
             multiView: props.multiView,
+            layoutStorage: props.layoutStorage,
             stagePane: props.stagePane,
             variables: hasVariables,
             locale: props.locale,
@@ -680,7 +905,7 @@ function SpriteTabs(props) {
             instance.dispose();
         };
     }, [content, props.enabled, props.vm, props.reopenLabel, props.multiView, props.locale,
-        props.viewAdapter, props.stagePane, props.renameLabels, hasVariables, hasToolbar, hasAssetPreview]);
+        props.viewAdapter, props.stagePane, props.layoutStorage, props.renameLabels, hasVariables, hasToolbar, hasAssetPreview]);
     React.useLayoutEffect(() => {
         controller.current?.syncActiveSection(props.activeSection);
     }, [props.activeSection]);

package/dist/workspace-layout.d.ts

@@ -0,0 +1,24 @@
+import type { SerializedDockview } from 'dockview';
+import type { DocumentPanelRequest } from './document-workspace.ts';
+type Grid = SerializedDockview['grid'];
+export type PanelReference = {
+    kind: 'sprite';
+    name: string;
+    stage: boolean;
+    section: number;
+} | {
+    kind: 'stage';
+} | ({
+    kind: 'document';
+} & DocumentPanelRequest['reference']);
+export interface WorkspaceLayout {
+    version: 1;
+    project: string;
+    grid: Grid;
+    activeGroup: string;
+    editingView?: string;
+    panels: Record<string, PanelReference>;
+}
+/** Rebuild only the supported docked grid and logical panel references from storage. */
+export declare function readWorkspaceLayout(raw: string, project: string): WorkspaceLayout | undefined;
+export {};

package/dist/workspace-layout.js

@@ -0,0 +1,88 @@
+import { Orientation } from 'dockview';
+const limit = 256;
+const validId = (value) => typeof value === 'string' && value.length > 0 && value.length <= 1024;
+const size = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 100000;
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Rebuild only the supported docked grid and logical panel references from storage. */
+export function readWorkspaceLayout(raw, project) {
+    if (raw.length > 1024 * 1024)
+        return;
+    let input;
+    try {
+        input = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    if (!record(input) || input.version !== 1 || input.project !== project || !record(input.grid) ||
+        !record(input.panels) || !validId(input.activeGroup))
+        return;
+    const { width, height, orientation } = input.grid;
+    if (!size(width) || !width || !size(height) || !height ||
+        (orientation !== Orientation.HORIZONTAL && orientation !== Orientation.VERTICAL))
+        return;
+    const groups = new Set();
+    const ids = new Set();
+    let nodes = 0;
+    function readNode(node, depth) {
+        if (depth > 32 || ++nodes > limit || !record(node) || !size(node.size))
+            return;
+        if (node.type === 'branch' && Array.isArray(node.data) && node.data.length > 0 && node.data.length <= limit) {
+            const data = [];
+            for (const child of node.data) {
+                const next = readNode(child, depth + 1);
+                if (!next)
+                    return;
+                data.push(next);
+            }
+            return { type: 'branch', size: node.size, data };
+        }
+        if (node.type !== 'leaf' || !record(node.data))
+            return;
+        const { id, views, activeView } = node.data;
+        if (!validId(id) || groups.has(id) || !Array.isArray(views) || !views.length ||
+            views.length > limit || !validId(activeView) || !views.includes(activeView))
+            return;
+        groups.add(id);
+        for (const panel of views) {
+            if (!validId(panel) || ids.has(panel) || ids.size >= limit)
+                return;
+            ids.add(panel);
+        }
+        return { type: 'leaf', size: node.size, data: { id, views, activeView } };
+    }
+    const root = readNode(input.grid.root, 0);
+    if (root?.type !== 'branch' || !groups.has(input.activeGroup) ||
+        ids.size !== Object.keys(input.panels).length)
+        return;
+    const panels = Object.create(null);
+    const documents = new Set();
+    let hasStage = false;
+    for (const id of ids) {
+        const panel = input.panels[id];
+        if (!Object.hasOwn(input.panels, id) || !record(panel))
+            return;
+        if (panel.kind === 'sprite' && validId(panel.name) && typeof panel.stage === 'boolean' &&
+            typeof panel.section === 'number' && Number.isInteger(panel.section) && panel.section >= 0 && panel.section <= 3) {
+            panels[id] = { kind: 'sprite', name: panel.name, stage: panel.stage, section: panel.section };
+        }
+        else if (panel.kind === 'stage' && !hasStage) {
+            hasStage = true;
+            panels[id] = { kind: 'stage' };
+        }
+        else if (panel.kind === 'document' && validId(panel.providerId) && validId(panel.documentId)) {
+            const key = JSON.stringify([panel.providerId, panel.documentId]);
+            if (documents.has(key))
+                return;
+            documents.add(key);
+            panels[id] = { kind: 'document', providerId: panel.providerId, documentId: panel.documentId };
+        }
+        else
+            return;
+    }
+    const editingView = input.editingView;
+    if (editingView !== undefined && (!validId(editingView) || panels[editingView]?.kind !== 'sprite'))
+        return;
+    return { version: 1, project, grid: { root, width, height, orientation }, activeGroup: input.activeGroup,
+        editingView: typeof editingView === 'string' ? editingView : undefined, panels };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-plus-editor-layout",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Resizable panes and layout for TurboWarp Plus Editor",
   "type": "module",
   "license": "GPL-3.0-or-later",

package/src/document-workspace.ts

@@ -0,0 +1,55 @@
+export interface DocumentPanelRequest {
+    reference: {providerId: string; documentId: string};
+    filename: string;
+    mount(element: HTMLElement, close: () => void): {requestClose(): void; dispose(): void};
+}
+
+interface DocumentPanelSource {
+    getPanelRequest(reference: DocumentPanelRequest['reference']): DocumentPanelRequest | undefined;
+    subscribePanelRequests(listener: () => void): () => void;
+}
+
+function createDocumentWorkspace() {
+    let open: ((request: DocumentPanelRequest) => void) | undefined;
+    let source: DocumentPanelSource | undefined;
+    const listeners = new Set<() => void>();
+    const notify = () => listeners.forEach(listener => listener());
+    return {
+        open(request: DocumentPanelRequest) {
+            if (!open) return false;
+            open(request);
+            return true;
+        },
+        connect(handler: NonNullable<typeof open>) {
+            open = handler;
+            return () => { if (open === handler) open = undefined; };
+        },
+        connectSource(next: DocumentPanelSource) {
+            source = next;
+            const unsubscribe = next.subscribePanelRequests(notify);
+            notify();
+            return () => {
+                unsubscribe();
+                if (source === next) source = undefined;
+            };
+        },
+        resolve(reference: DocumentPanelRequest['reference']) {
+            return source?.getPanelRequest(reference);
+        },
+        subscribe(listener: () => void) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        }
+    };
+}
+
+const workspaces = new WeakMap<object, ReturnType<typeof createDocumentWorkspace>>();
+
+export function getDocumentWorkspace(vm: object) {
+    let workspace = workspaces.get(vm);
+    if (!workspace) {
+        workspace = createDocumentWorkspace();
+        workspaces.set(vm, workspace);
+    }
+    return workspace;
+}

package/src/editor.css

@@ -774,3 +774,10 @@ details.layout-menu button {
 .floating-stage:has([data-stage-in-workspace]:empty) {
     pointer-events: none;
 }
+
+:global(.tw-plus-document-slot) {
+    inline-size: 100%;
+    block-size: 100%;
+    min-inline-size: 0;
+    min-block-size: 0;
+}

package/src/sprite-tabs.ts

@@ -1,13 +1,19 @@
 import React from 'react';
 import {createPortal} from 'react-dom';
 import {createDockview, DefaultTab, themeLight} from 'dockview';
-import type {DockviewGroupPanel, GroupPanelPartInitParameters, IDockviewPanel} from 'dockview';
+import type {DockviewGroupPanel, GroupPanelPartInitParameters, IDockviewPanel, SerializedDockview} from 'dockview';
 import {createSpriteLayoutMenu} from './sprite-layout-menu.ts';
 import {SpriteAssetPane} from './sprite-asset-pane.tsx';
 import type {SpriteVariable} from './sprite-asset-pane.tsx';
 import {SpriteEditorToolbar, spriteEditorSections} from './sprite-editor-toolbar.tsx';
 import type {SpriteSearchResult} from './sprite-editor-toolbar.tsx';
 import type {DockviewStagePane} from './dockview-stage.ts';
+import {getDocumentWorkspace} from './document-workspace.ts';
+import type {DocumentPanelRequest} from './document-workspace.ts';
+import {readWorkspaceLayout} from './workspace-layout.ts';
+import type {PanelReference, WorkspaceLayout} from './workspace-layout.ts';
+
+export {getDocumentWorkspace} from './document-workspace.ts';
 
 export {useDockviewStage} from './dockview-stage.ts';
 
@@ -20,6 +26,7 @@ interface Target {
     isOriginal: boolean;
     isStage: boolean;
     getName(): string;
+    getCostumes?(): {assetId?: string}[];
     getCurrentCostume?(): {asset?: CostumeAsset} | undefined;
 }
 
@@ -115,6 +122,9 @@ function createAssetSelections(target: Target, source?: {
 export type SpriteSplitDirection = 'right' | 'below';
 
 const stagePanelId = 'tw-plus-stage-display';
+const documentComponent = 'tw-plus-document';
+const documentTitle = ({filename, reference: {providerId, documentId}}: DocumentPanelRequest) =>
+    `${filename} (${providerId} / ${documentId})`;
 
 interface TabOptions<Snapshot = unknown> {
     vm: Project;
@@ -124,6 +134,12 @@ interface TabOptions<Snapshot = unknown> {
     resize(): void;
     reopenLabel: string;
     multiView?: boolean;
+    layoutStorage?: {
+        storage: Storage;
+        key: string;
+        isProjectLoading?(): boolean;
+        subscribeProject?(listener: () => void): (() => void) | undefined;
+    };
     stagePane?: DockviewStagePane;
     variables?: boolean;
     locale?: string;
@@ -176,6 +192,10 @@ const renameLabels = {
     ja: {title: 'スプライト名の変更', name: 'スプライト名', cancel: 'キャンセル', save: '変更'}
 };
 type RenameLabels = typeof renameLabels.en;
+const targetName = (target: Target) => target.isStage ? 'Stage' : target.getName();
+const projectSignature = (targets: readonly Target[]) => JSON.stringify(targets
+    .map(target => JSON.stringify([target.isStage, targetName(target), target.getCostumes?.()[0]?.assetId ?? '']))
+    .sort());
 
 class SpriteTab extends DefaultTab {
     private readonly icon: HTMLImageElement;
@@ -210,16 +230,25 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
     const editLabel = /^ja(?:-|$)/i.test(locale) ? 'クリックしてこのビューで編集' : 'Activate this view to edit';
     const slots = new Map<string, TabSlot>();
     const views = new Map<string, View<Snapshot>>();
+    const documents = new Map<string, {request: DocumentPanelRequest; session?: ReturnType<DocumentPanelRequest['mount']>}>();
     const costumeIcons = new WeakMap<CostumeAsset, string>();
     const remembered = new WeakMap<Target, number>();
     const lastUsed = new WeakMap<Target, View<Snapshot>>();
-    const closed = new WeakSet<Target>();
+    let closed = new WeakSet<Target>();
     let active: View<Snapshot> | undefined;
     let observed = vm.editingTarget;
     let syncing = false;
     let nextView = 0;
     let renameDialog: HTMLDialogElement | undefined;
     const text = options.renameLabels ?? renameLabels.en;
+    const persistence = multiView && options.layoutStorage;
+    const window = document.defaultView;
+    const documentWorkspace = multiView && getDocumentWorkspace(vm);
+    let pendingRestore = Boolean(persistence);
+    let restoreFrame: number | undefined;
+    let restoreTimeout: number | undefined;
+    let saveFrame: number | undefined;
+    const originalTargets = () => vm.runtime.targets.filter(target => target.isOriginal);
 
     const dockview = createDockview(root, {
         theme: themeLight,
@@ -232,8 +261,17 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
             if (!target || target.isStage || !vm.renameSprite) return [];
             return [{label: text.title, action: () => openRenameDialog(target)}];
         },
-        createComponent: ({name}) => {
+        createComponent: ({name, id: componentId}) => {
             const element = document.createElement('div');
+            if (name === documentComponent) {
+                element.className = 'tw-plus-document-slot';
+                return {element, init({api}) {
+                    const item = documents.get(componentId);
+                    element.dataset.providerId = item.request.reference.providerId;
+                    element.dataset.documentId = item.request.reference.documentId;
+                    item.session = item.request.mount(element, () => api.close());
+                }};
+            }
             if (name === stagePanelId) {
                 element.className = 'tw-plus-dockview-stage-slot';
                 return {element, init() { stagePane.attach(element); }};
@@ -312,7 +350,7 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
             splitRight: () => { if (group.activePanel) split('right', group.activePanel.id); },
             splitBelow: () => { if (group.activePanel) split('below', group.activePanel.id); },
             close: () => { if (group.activePanel) closeSplit(group.activePanel.id); },
-            canClose: () => dockview.groups.length > 1,
+            canClose: () => canCloseGroup(group),
             canSplit: () => views.has(group.activePanel?.id)
         });
         return {...menu, init() {}};
@@ -444,8 +482,8 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
     }
 
     function show(panel: IDockviewPanel | undefined) {
-        if (panel?.id === stagePanelId) {
-            // Displaying the Stage does not select the Stage target or interrupt the sprite editor.
+        if (panel?.id === stagePanelId || documents.has(panel?.id)) {
+            // Utility panels do not change the VM editing target.
             refreshSurfaces();
             return;
         }
@@ -478,10 +516,10 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
 
     function add(target: Target, splitPosition?: {referencePanel: string; direction: SpriteSplitDirection}, section?: number) {
         let id = target.id;
-        if (splitPosition || views.has(id) || id === stagePanelId) {
+        if (splitPosition || views.has(id) || id === stagePanelId || documents.has(id)) {
             do {
                 id = 'sprite-view-' + ++nextView;
-            } while (views.has(id) || vm.runtime.targets.some(item => item.id === id));
+            } while (views.has(id) || documents.has(id) || vm.runtime.targets.some(item => item.id === id));
         }
         const source = splitPosition && views.get(splitPosition.referencePanel);
         views.set(id, {id, target, section: section ?? remembered.get(target) ?? options.getSection(),
@@ -517,8 +555,50 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
         activateView(view?.id ?? add(target).id);
     }
 
+    function openDocument(request: DocumentPanelRequest) {
+        if (pendingRestore) finishRestore();
+        const {providerId, documentId} = request.reference;
+        for (const [id, {request: opened}] of documents) {
+            if (opened.reference.providerId === providerId && opened.reference.documentId === documentId) {
+                dockview.getPanel(id)?.api.setActive();
+                return;
+            }
+        }
+        let id: string;
+        do {
+            id = 'document-view-' + ++nextView;
+        } while (views.has(id) || documents.has(id) || vm.runtime.targets.some(target => target.id === id));
+        const title = documentTitle(request);
+        documents.set(id, {request});
+        try {
+            dockview.addPanel({id, title, component: documentComponent, renderer: 'always'});
+        } catch (error) {
+            documents.get(id)?.session?.dispose();
+            documents.delete(id);
+            throw error;
+        }
+    }
+
+    function guardDocumentClose(event: MouseEvent | KeyboardEvent) {
+        const element = event.target as HTMLElement;
+        const tab = element.closest<HTMLElement>('[data-tab-panel-id]');
+        const item = documents.get(tab?.dataset.tabPanelId);
+        if (!item) return;
+        const close = event.type === 'click' ? Boolean(element.closest('.dv-default-tab-action')) :
+            event.target === tab && ['Delete', 'Backspace'].includes((event as KeyboardEvent).key);
+        if (!close) return;
+        event.preventDefault();
+        event.stopPropagation();
+        item.session?.requestClose();
+    }
+
+    function canCloseGroup(group: DockviewGroupPanel) {
+        return dockview.groups.length > 1 && group.panels.every(panel => !documents.has(panel.id));
+    }
+
     function openStage() {
         if (!stagePane) return;
+        if (pendingRestore) finishRestore();
         const existing = dockview.getPanel(stagePanelId);
         if (existing) {
             existing.api.setActive();
@@ -544,7 +624,7 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
 
     function closeSplit(id = active?.id) {
         const panel = dockview.getPanel(id);
-        if (!multiView || !panel || dockview.groups.length <= 1) return false;
+        if (!multiView || !panel || !canCloseGroup(panel.api.group)) return false;
         syncing = true;
         try {
             dockview.removeGroup(panel.api.group);
@@ -569,6 +649,7 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
             viewAdapter?.restore(describe(view), view.snapshots?.get(section)?.snapshot);
         }
         refreshSurfaces();
+        scheduleSave();
         return true;
     }
 
@@ -576,6 +657,106 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
         if (!active || !usesNativeSection(active.section) || active.section === section) return;
         active.section = section;
         refreshSurfaces();
+        scheduleSave();
+    }
+
+    function writeLayout() {
+        saveFrame = undefined;
+        const targets = originalTargets();
+        if (!persistence || pendingRestore || syncing || !targets.length || persistence.isProjectLoading?.()) return;
+        const {grid, activeGroup} = dockview.toJSON();
+        if (!activeGroup || grid.width <= 0 || grid.height <= 0) return;
+        const panels: Record<string, PanelReference> = Object.create(null);
+        for (const [id, view] of views) {
+            panels[id] = {kind: 'sprite', name: targetName(view.target), stage: view.target.isStage, section: view.section};
+        }
+        if (dockview.getPanel(stagePanelId)) panels[stagePanelId] = {kind: 'stage'};
+        for (const [id, {request}] of documents) panels[id] = {kind: 'document', ...request.reference};
+        const snapshot: WorkspaceLayout = {version: 1, project: projectSignature(targets), grid, activeGroup,
+            editingView: active?.id, panels};
+        try { persistence.storage.setItem(persistence.key, JSON.stringify(snapshot)); } catch { /* Storage can be unavailable. */ }
+    }
+
+    function scheduleSave() {
+        if (persistence && !pendingRestore && saveFrame === undefined) {
+            saveFrame = window.requestAnimationFrame(writeLayout);
+        }
+    }
+
+    function flushLayout() {
+        if (saveFrame !== undefined) {
+            window.cancelAnimationFrame(saveFrame);
+            writeLayout();
+        }
+    }
+
+    function finishRestore() {
+        pendingRestore = false;
+        window.clearTimeout(restoreTimeout);
+    }
+
+    function restoreLayout() {
+        restoreFrame = undefined;
+        if (!pendingRestore || !persistence || persistence.isProjectLoading?.()) return;
+        const targets = originalTargets();
+        if (!targets.length || !vm.editingTarget) return;
+        let stored: WorkspaceLayout | undefined;
+        try {
+            const raw = persistence.storage.getItem(persistence.key);
+            if (raw) stored = readWorkspaceLayout(raw, projectSignature(targets));
+        } catch { /* Storage can be unavailable. */ }
+        if (!stored) return finishRestore();
+        const resolvedSprites = new Map<string, View<Snapshot>>();
+        const resolvedDocuments = new Map<string, DocumentPanelRequest>();
+        const panels: SerializedDockview['panels'] = Object.create(null);
+        for (const [id, reference] of Object.entries(stored.panels)) {
+            if (reference.kind === 'sprite') {
+                const target = targets.find(item => item.isStage === reference.stage && targetName(item) === reference.name);
+                if (!target || id === stagePanelId || (reference.section === variableSection && !options.variables)) return finishRestore();
+                resolvedSprites.set(id, {id, target, section: reference.section, assets: createAssetSelections(target)});
+                panels[id] = {id, title: target.getName(), contentComponent: 'sprite', params: {icon: getIcon(target)}};
+            } else if (reference.kind === 'stage') {
+                if (!stagePane || id !== stagePanelId) return finishRestore();
+                panels[id] = {id, title: stagePane.title, contentComponent: stagePanelId, renderer: 'always'};
+            } else {
+                if (id === stagePanelId) return finishRestore();
+                const request = documentWorkspace && documentWorkspace.resolve(reference);
+                if (!request) {
+                    // The project can finish loading before the Blockly host publishes its document catalog.
+                    restoreTimeout ??= window.setTimeout(finishRestore, 2000);
+                    return;
+                }
+                resolvedDocuments.set(id, request);
+                panels[id] = {id, title: documentTitle(request), contentComponent: documentComponent, renderer: 'always'};
+            }
+        }
+        finishRestore();
+        syncing = true;
+        try {
+            dockview.clear();
+            active = undefined;
+            const represented = new Set([...resolvedSprites.values()].map(view => view.target));
+            closed = new WeakSet(targets.filter(target => !represented.has(target)));
+            for (const [id, view] of resolvedSprites) views.set(id, view);
+            for (const [id, request] of resolvedDocuments) documents.set(id, {request});
+            dockview.fromJSON({grid: stored.grid, activeGroup: stored.activeGroup, panels});
+            const selected = dockview.activePanel;
+            show(views.has(selected?.id) ? selected : dockview.getPanel(stored.editingView) ?? selected);
+        } catch {
+            dockview.clear();
+            for (const view of views.values()) disposeView(view);
+            for (const item of documents.values()) item.session?.dispose();
+            documents.clear();
+            closed = new WeakSet();
+            active = undefined;
+        } finally {
+            syncing = false;
+        }
+        refresh();
+    }
+
+    function scheduleRestore() {
+        if (pendingRestore && restoreFrame === undefined) restoreFrame = window.requestAnimationFrame(restoreLayout);
     }
 
     function refresh() {
@@ -608,6 +789,7 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
         } finally {
             syncing = false;
         }
+        scheduleRestore();
     }
 
     function disposeView(view: View<Snapshot>) {
@@ -626,8 +808,15 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
         } finally {
             syncing = false;
         }
+        scheduleSave();
     });
     const removal = dockview.onDidRemovePanel(panel => {
+        const item = documents.get(panel.id);
+        if (item) {
+            documents.delete(panel.id);
+            item.session?.dispose();
+            return;
+        }
         if (panel.id === stagePanelId) {
             stagePane?.attach(null);
             return;
@@ -638,7 +827,16 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
         disposeView(view);
         if (![...views.values()].some(item => item.target === view.target)) closed.add(view.target);
     });
-    const layout = multiView && dockview.onDidLayoutChange(refreshSurfaces);
+    const layout = multiView && dockview.onDidLayoutChange(() => {
+        refreshSurfaces();
+        scheduleSave();
+    });
+    const disconnectDocuments = documentWorkspace && documentWorkspace.connect(openDocument);
+    const unsubscribeDocuments = persistence && documentWorkspace && documentWorkspace.subscribe(scheduleRestore);
+    const unsubscribeProject = persistence && persistence.subscribeProject?.(scheduleRestore);
+    if (persistence) window.addEventListener('pagehide', flushLayout);
+    root.addEventListener('click', guardDocumentClose, true);
+    root.addEventListener('keydown', guardDocumentClose, true);
     vm.on('targetsUpdate', refresh);
     refresh();
     return {
@@ -651,6 +849,17 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
         currentView: () => active && describe(active),
         views: () => [...views.values()].map(view => describe(view)),
         dispose() {
+            flushLayout();
+            window.cancelAnimationFrame(restoreFrame);
+            window.clearTimeout(restoreTimeout);
+            if (persistence) window.removeEventListener('pagehide', flushLayout);
+            if (unsubscribeDocuments) unsubscribeDocuments();
+            if (unsubscribeProject) unsubscribeProject();
+            if (disconnectDocuments) disconnectDocuments();
+            root.removeEventListener('click', guardDocumentClose, true);
+            root.removeEventListener('keydown', guardDocumentClose, true);
+            for (const item of documents.values()) item.session?.dispose();
+            documents.clear();
             stagePane?.attach(null);
             renameDialog?.remove();
             renameDialog = undefined;
@@ -784,6 +993,7 @@ function SpriteTabs<Snapshot>(props: SpriteTabsProps<Snapshot>) {
             resize: () => latest.current.resize(),
             reopenLabel: props.reopenLabel,
             multiView: props.multiView,
+            layoutStorage: props.layoutStorage,
             stagePane: props.stagePane,
             variables: hasVariables,
             locale: props.locale,
@@ -802,7 +1012,7 @@ function SpriteTabs<Snapshot>(props: SpriteTabsProps<Snapshot>) {
             instance.dispose();
         };
     }, [content, props.enabled, props.vm, props.reopenLabel, props.multiView, props.locale,
-        props.viewAdapter, props.stagePane, props.renameLabels, hasVariables, hasToolbar, hasAssetPreview]);
+        props.viewAdapter, props.stagePane, props.layoutStorage, props.renameLabels, hasVariables, hasToolbar, hasAssetPreview]);
     React.useLayoutEffect(() => {
         controller.current?.syncActiveSection(props.activeSection);
     }, [props.activeSection]);

package/src/workspace-layout.ts

@@ -0,0 +1,90 @@
+import {Orientation} from 'dockview';
+import type {SerializedDockview} from 'dockview';
+import type {DocumentPanelRequest} from './document-workspace.ts';
+
+type Grid = SerializedDockview['grid'];
+type Node = Grid['root'];
+export type PanelReference =
+    | {kind: 'sprite'; name: string; stage: boolean; section: number}
+    | {kind: 'stage'}
+    | ({kind: 'document'} & DocumentPanelRequest['reference']);
+
+export interface WorkspaceLayout {
+    version: 1;
+    project: string;
+    grid: Grid;
+    activeGroup: string;
+    editingView?: string;
+    panels: Record<string, PanelReference>;
+}
+
+const limit = 256;
+const validId = (value: unknown): value is string =>
+    typeof value === 'string' && value.length > 0 && value.length <= 1024;
+const size = (value: unknown): value is number =>
+    typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 100000;
+const record = (value: unknown): value is Record<string, unknown> =>
+    value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** Rebuild only the supported docked grid and logical panel references from storage. */
+export function readWorkspaceLayout(raw: string, project: string): WorkspaceLayout | undefined {
+    if (raw.length > 1024 * 1024) return;
+    let input: unknown;
+    try { input = JSON.parse(raw); } catch { return; }
+    if (!record(input) || input.version !== 1 || input.project !== project || !record(input.grid) ||
+        !record(input.panels) || !validId(input.activeGroup)) return;
+    const {width, height, orientation} = input.grid;
+    if (!size(width) || !width || !size(height) || !height ||
+        (orientation !== Orientation.HORIZONTAL && orientation !== Orientation.VERTICAL)) return;
+    const groups = new Set<string>();
+    const ids = new Set<string>();
+    let nodes = 0;
+    function readNode(node: unknown, depth: number): Node | undefined {
+        if (depth > 32 || ++nodes > limit || !record(node) || !size(node.size)) return;
+        if (node.type === 'branch' && Array.isArray(node.data) && node.data.length > 0 && node.data.length <= limit) {
+            const data: Node[] = [];
+            for (const child of node.data) {
+                const next = readNode(child, depth + 1);
+                if (!next) return;
+                data.push(next);
+            }
+            return {type: 'branch', size: node.size, data};
+        }
+        if (node.type !== 'leaf' || !record(node.data)) return;
+        const {id, views, activeView} = node.data;
+        if (!validId(id) || groups.has(id) || !Array.isArray(views) || !views.length ||
+            views.length > limit || !validId(activeView) || !views.includes(activeView)) return;
+        groups.add(id);
+        for (const panel of views) {
+            if (!validId(panel) || ids.has(panel) || ids.size >= limit) return;
+            ids.add(panel);
+        }
+        return {type: 'leaf', size: node.size, data: {id, views, activeView}};
+    }
+    const root = readNode(input.grid.root, 0);
+    if (root?.type !== 'branch' || !groups.has(input.activeGroup) ||
+        ids.size !== Object.keys(input.panels).length) return;
+    const panels: WorkspaceLayout['panels'] = Object.create(null);
+    const documents = new Set<string>();
+    let hasStage = false;
+    for (const id of ids) {
+        const panel = input.panels[id];
+        if (!Object.hasOwn(input.panels, id) || !record(panel)) return;
+        if (panel.kind === 'sprite' && validId(panel.name) && typeof panel.stage === 'boolean' &&
+            typeof panel.section === 'number' && Number.isInteger(panel.section) && panel.section >= 0 && panel.section <= 3) {
+            panels[id] = {kind: 'sprite', name: panel.name, stage: panel.stage, section: panel.section};
+        } else if (panel.kind === 'stage' && !hasStage) {
+            hasStage = true;
+            panels[id] = {kind: 'stage'};
+        } else if (panel.kind === 'document' && validId(panel.providerId) && validId(panel.documentId)) {
+            const key = JSON.stringify([panel.providerId, panel.documentId]);
+            if (documents.has(key)) return;
+            documents.add(key);
+            panels[id] = {kind: 'document', providerId: panel.providerId, documentId: panel.documentId};
+        } else return;
+    }
+    const editingView = input.editingView;
+    if (editingView !== undefined && (!validId(editingView) || panels[editingView]?.kind !== 'sprite')) return;
+    return {version: 1, project, grid: {root, width, height, orientation}, activeGroup: input.activeGroup,
+        editingView: typeof editingView === 'string' ? editingView : undefined, panels};
+}