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

package/dist/document-workspace.d.ts

@@ -9,7 +9,15 @@ export interface DocumentPanelRequest {
         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

@@ -1,5 +1,8 @@
 function createDocumentWorkspace() {
     let open;
+    let source;
+    const listeners = new Set();
+    const notify = () => listeners.forEach(listener => listener());
     return {
         open(request) {
             if (!open)
@@ -11,6 +14,23 @@ function createDocumentWorkspace() {
             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); };
         }
     };
 }

package/dist/sprite-tabs.d.ts

@@ -12,6 +12,9 @@ interface Target {
     isOriginal: boolean;
     isStage: boolean;
     getName(): string;
+    getCostumes?(): {
+        assetId?: string;
+    }[];
     getCurrentCostume?(): {
         asset?: CostumeAsset;
     } | undefined;
@@ -74,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

@@ -5,6 +5,7 @@ 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');
@@ -44,10 +45,15 @@ function createAssetSelections(target, source) {
 }
 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) {
@@ -83,13 +89,21 @@ export function mountSpriteTabs(root, content, options) {
     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,
@@ -384,7 +398,7 @@ export function mountSpriteTabs(root, content, options) {
         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(),
@@ -421,6 +435,8 @@ export function mountSpriteTabs(root, content, options) {
         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) {
@@ -432,7 +448,7 @@ export function mountSpriteTabs(root, content, options) {
         do {
             id = 'document-view-' + ++nextView;
         } while (views.has(id) || documents.has(id) || vm.runtime.targets.some(target => target.id === id));
-        const title = request.filename + ' (' + providerId + ' / ' + documentId + ')';
+        const title = documentTitle(request);
         documents.set(id, { request });
         try {
             dockview.addPanel({ id, title, component: documentComponent, renderer: 'always' });
@@ -463,6 +479,8 @@ export function mountSpriteTabs(root, content, options) {
     function openStage() {
         if (!stagePane)
             return;
+        if (pendingRestore)
+            finishRestore();
         const existing = dockview.getPanel(stagePanelId);
         if (existing) {
             existing.api.setActive();
@@ -514,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) {
@@ -521,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)
@@ -557,6 +694,7 @@ export function mountSpriteTabs(root, content, options) {
         finally {
             syncing = false;
         }
+        scheduleRestore();
     }
     function disposeView(view) {
         for (const stored of view.snapshots?.values() ?? [])
@@ -577,6 +715,7 @@ export function mountSpriteTabs(root, content, options) {
         finally {
             syncing = false;
         }
+        scheduleSave();
     });
     const removal = dockview.onDidRemovePanel(panel => {
         const item = documents.get(panel.id);
@@ -598,8 +737,15 @@ 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 disconnectDocuments = multiView && getDocumentWorkspace(vm).connect(openDocument);
+    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);
@@ -614,6 +760,15 @@ 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);
@@ -730,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,
@@ -749,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.5",
+  "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

@@ -4,8 +4,16 @@ export interface DocumentPanelRequest {
     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;
@@ -15,6 +23,22 @@ function createDocumentWorkspace() {
         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); };
         }
     };
 }

package/src/sprite-tabs.ts

@@ -1,7 +1,7 @@
 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';
@@ -10,6 +10,8 @@ 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';
 
@@ -24,6 +26,7 @@ interface Target {
     isOriginal: boolean;
     isStage: boolean;
     getName(): string;
+    getCostumes?(): {assetId?: string}[];
     getCurrentCostume?(): {asset?: CostumeAsset} | undefined;
 }
 
@@ -120,6 +123,8 @@ 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;
@@ -129,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;
@@ -181,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;
@@ -219,13 +234,21 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
     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,
@@ -496,7 +519,7 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
         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(),
@@ -533,6 +556,7 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
     }
 
     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) {
@@ -544,7 +568,7 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
         do {
             id = 'document-view-' + ++nextView;
         } while (views.has(id) || documents.has(id) || vm.runtime.targets.some(target => target.id === id));
-        const title = request.filename + ' (' + providerId + ' / ' + documentId + ')';
+        const title = documentTitle(request);
         documents.set(id, {request});
         try {
             dockview.addPanel({id, title, component: documentComponent, renderer: 'always'});
@@ -574,6 +598,7 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
 
     function openStage() {
         if (!stagePane) return;
+        if (pendingRestore) finishRestore();
         const existing = dockview.getPanel(stagePanelId);
         if (existing) {
             existing.api.setActive();
@@ -624,6 +649,7 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
             viewAdapter?.restore(describe(view), view.snapshots?.get(section)?.snapshot);
         }
         refreshSurfaces();
+        scheduleSave();
         return true;
     }
 
@@ -631,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() {
@@ -663,6 +789,7 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
         } finally {
             syncing = false;
         }
+        scheduleRestore();
     }
 
     function disposeView(view: View<Snapshot>) {
@@ -681,6 +808,7 @@ export function mountSpriteTabs<Snapshot>(root: HTMLElement, content: HTMLElemen
         } finally {
             syncing = false;
         }
+        scheduleSave();
     });
     const removal = dockview.onDidRemovePanel(panel => {
         const item = documents.get(panel.id);
@@ -699,8 +827,14 @@ 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 disconnectDocuments = multiView && getDocumentWorkspace(vm).connect(openDocument);
+    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);
@@ -715,6 +849,12 @@ 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);
@@ -853,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,
@@ -871,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};
+}