@kubohiroya/turbowarp-plus-editor-layout 0.0.0-stage → 0.1.2

package/README.ja.md

@@ -0,0 +1,51 @@
+# TurboWarp Plus Editor Layout
+
+同じ document 内で「編集領域／ステージ列」と「ステージ／対象領域」の境界を調整する。ホストは `createLayout(React)` に既存の React を渡し、`render` に渡される境界・スタイル・表示サイズを既存コンポーネントに接続する。ホストがストレージとキーを指定し、このパッケージが設定を保存・復元する。
+
+境界はドラッグ、矢印キー、Home／End で移動できる。Enter またはダブルクリックで、その境界を既定の位置に戻す。
+
+## Editor での配分
+
+| 境界 | 最小サイズ |
+| --- | --- |
+| 編集領域／ステージ列 | 編集領域 500 px、ステージ列 350 px |
+| ステージ／対象領域 | ステージ 135 px、対象領域 175 px |
+
+境界の幅は 8 px。分割比率は各領域の最小サイズまでに制限する。最小サイズを両立できない表示領域では通常配分に戻し、表示領域を広げると保存した比率で分割を再開する。プロパティと一覧はスプライト選択ペイン内にまとまっており、バックパックは開閉式のトレイなので、この段階では既存の操作で扱う。メニューバーは分割領域の外にある。
+
+Scratch 配置では分割を既定で有効にする。既存のステージサイズボタンを押すと、指定したプリセットで配分を初期化する。設定は作品や SB3 と別に保存する。分割だけを無効にする場合は Web の起動 URL に `twPlusSplitter=0` を指定するか、Desktop を `TW_PLUS_DESKTOP_SPLITTER=0` で起動する。
+
+## Plus 標準配置
+
+`createStandardLayout(React, {styles, targetStyles, context})` は、⚓️ での配置切り替え、ステージの表示と計測、スプライト一覧の2列配置を担当する。`editor.css` と `targets.css` をクラス名マップとして渡す。ホストは起動設定、ストレージ、ウィンドウ操作部品、パレット表示のコールバックと描画先を渡す。配置メニューの描画を差し替える場合は、任意の `LayoutMenu` コンポーネントをファクトリーに渡す。ステージを隠しても同じ描画先を使う。
+
+試験用ホストの `/example/?standard=1` で Plus と Scratch の往復を確認できる。`standard=0` は起動時の切り戻しを再現する。
+
+Editor はこのパッケージの `0.1.0` をローカル依存としてロックし、Editor のリビジョンと一緒にソースを固定する。
+
+## 検証
+
+`npm test` で配分・縦横比・設定の読み書きを、`npm run test:browser` で独立した試験用ホストを検証する。試験用ホストを手動で開くには、このディレクトリで `npm install` と `python3 -m http.server` を実行し、`/example/` を表示する。
+
+Editor のルートから、`site/source.json` の GUI を `npm run build:pages` でビルドし、`E2E_GUI_ROOT=/absolute/gui-checkout E2E_PATH_PREFIX=/turbowarp-plus-editor/ node --test test/editor-layout.browser.ts` を実行する。同じ GUI をホスト接続なしでビルドしたディレクトリを `E2E_LAYOUT_BARE_BUILD` に渡すと、GUI 単体の動作も検証する。
+## 別窓ステージとスプライト設定
+
+`attachStageInput` は、ホストから渡された別ウィンドウの document とキャンバスを使って、入力の購読と解放を管理する。ポインター処理とドラッグ状態の解除はホストのコールバックを使用する。
+
+`sprite-properties` は設定フォーム、一覧のスタイル、選択が変わった場合の編集拒否と VM への更新を担当する。ホストは選択中の値、VM、従来フォームと表示先を渡す。
+
+設定フォームは以前のスプライト設定ソース `80825f7`、ウィンドウ部品は以前の配布アーカイブのソース `b0390c3` から移設した。Scratch GUI の本家実装はこのパッケージに取り込まず、パッケージの既存ライセンスは GPL-3.0-or-later とする。
+
+## Editor と組み合わせたローカル検証
+
+`npm test` でタブの状態管理、ファイルメニューの操作、既存レイアウトを検証する。
+`TW_PLUS_LAYOUT_EDITOR_URL` に、固定済み Scratch GUI と組み合わせた Editor の URL を指定して
+`npm run test:browser` を実行すると、既存のタブ列・編集パネル接続で Dockview を検証する。
+ファイルメニューの任意接続を備えた GUI を確認する場合は、同じコマンドに
+`TW_PLUS_LAYOUT_FILE_MENU_URL` を指定する。
+
+Plus 標準配置ではスプライト編集タブを既定で表示する。`twPlusDockviewSpriteTabs=0` で従来の編集表示に戻る。
+Editor がファイルメニューの接続口を提供している場合は、各項目のアイコンと「機能拡張の追加」を表示する。
+`twPlusExtensionFileMenu=0` で左下のボタンに戻る。起動時のパラメーターを変更したら再読み込みする。
+
+Web 版の Plus 標準配置で `twPlusDockview=1` を付けて起動すると、スプライト編集ペインを左右・上下に分割できます。同じスプライトを複数のペインで開いた場合、表示セクション、コスチュームと音の選択、素材一覧のスクロール位置をペインごとに保持します。変数の値はプロジェクト内で共有され、編集中のペインで変更できます。URL から `twPlusDockview=1` を外して再読み込みすると、通常のスプライトタブに戻ります。

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# TurboWarp Plus Editor Layout
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[日本語](README.ja.md)
+
+Resize the divider between the editor and the stage column, or the divider between the stage and the target pane, within a single document. The host passes its React instance to `createLayout(React)` and connects the dividers, styles, and display dimensions provided by the `render` callback to its existing components. The host supplies a storage provider and key, and this package saves and restores the layout settings.
+
+Drag a divider or use the arrow keys, Home, or End to move it. Press Enter or double-click to reset that divider to its default position.
+
+## Editor layout sizing
+
+| Divider | Minimum sizes |
+| --- | --- |
+| Editor / stage column | Editor 500 px, stage column 350 px |
+| Stage / target pane | Stage 135 px, target pane 175 px |
+
+Dividers are 8 px wide. Each split is constrained by the minimum size of its panes. If the available space is too small to satisfy both minimums, the editor falls back to its usual sizing. The split resumes at the saved ratio when the available space grows. The sprite properties and list stay together in the sprite selector, and the backpack remains a collapsible tray. The menu bar sits outside the split area.
+
+Dividers are enabled by default in the Scratch layout. Selecting a stage size preset resets the split to that preset. Layout settings are stored separately from projects and SB3 files. To disable the dividers, add `twPlusSplitter=0` to the Web launch URL or start Desktop with `TW_PLUS_DESKTOP_SPLITTER=0`.
+
+## Plus standard layout
+
+`createStandardLayout(React, {styles, targetStyles, context})` handles layout switching via the anchor control (⚓️), stage visibility and measurement, and the two-column sprite list. Pass `editor.css` and `targets.css` as class-name maps. The host provides startup settings, storage, window controls, and the callback and mount point for the palette. Pass an optional `LayoutMenu` component to the factory to customize the layout menu. The stage keeps the same mount point while hidden.
+
+Use `/example/?standard=1` in the test host to try the Plus layout. Use `standard=0` to try the startup fallback to the Scratch layout.
+
+The Editor locks version `0.1.0` of this package as a local dependency and pins its source alongside the Editor revision.
+
+## Verification
+
+Run `npm test` to verify split sizing, aspect ratios, and settings persistence. Run `npm run test:browser` to test the standalone host. To open the test host manually, run `npm install` and `python3 -m http.server` in this directory, then open `/example/`.
+
+From the Editor root, build the GUI pinned in `site/source.json` with `npm run build:pages`, then run `E2E_GUI_ROOT=/absolute/gui-checkout E2E_PATH_PREFIX=/turbowarp-plus-editor/ node --test test/editor-layout.browser.ts`. To verify the GUI on its own, set `E2E_LAYOUT_BARE_BUILD` to the directory where the same GUI was built without the host integration.
+
+## Separate stage window and sprite properties
+
+`attachStageInput` manages input subscriptions and cleanup using the separate window's document and canvas provided by the host. Pointer handling and drag cleanup use the host's callbacks.
+
+`sprite-properties` provides the properties form and list styles, rejects stale edits when the selected sprite changes, and applies updates to the VM. The host provides the selected values, the VM, the fallback form, and the mount point.
+
+The properties form came from the previous sprite properties source at `80825f7`, and the window components came from the source of the previous release archive at `b0390c3`. The extraction kept the upstream Scratch GUI implementation in its original repository. Its existing license is GPL-3.0-or-later.
+
+## Local verification with the Editor
+
+Run `npm test` to check tab state, file menu actions, and the existing layout. Set `TW_PLUS_LAYOUT_EDITOR_URL` to an Editor URL built with the pinned Scratch GUI and run `npm run test:browser` to verify Dockview through the existing tab strip and editor panel integration. Set `TW_PLUS_LAYOUT_FILE_MENU_URL` for the same command to check a GUI build with the optional file menu integration.
+
+Sprite editing tabs are enabled by default in the Plus standard layout. Set `twPlusDockviewSpriteTabs=0` to restore the previous editing view. When the Editor exposes the file menu integration, the menu shows item icons and the Add Extension command. Set `twPlusExtensionFileMenu=0` to use the button at the bottom left again. Reload the editor after changing startup parameters.
+
+In the Plus web editor, add `twPlusDockview=1` to enable split sprite panes. Each pane remembers its section, costume and sound selections, and asset-list scroll position. Variable values are shared across panes and can be changed in the active pane. Remove the startup parameter and reload to return to the regular sprite tabs.

package/dist/dockview-styles.d.ts

@@ -0,0 +1 @@
+import 'dockview/dist/styles/dockview.css';

package/dist/dockview-styles.js

@@ -0,0 +1 @@
+import 'dockview/dist/styles/dockview.css';

package/dist/extension-file-menu.d.ts

@@ -0,0 +1,31 @@
+import React from 'react';
+interface ExtensionMenuOptions {
+    locale?: string;
+    MenuSection: React.ElementType;
+    MenuItem: React.ElementType;
+    onAddExtension?: () => void;
+    onRequestClose(): void;
+}
+export declare function renderExtensionFileMenu({ locale, MenuSection, MenuItem, onAddExtension, onRequestClose }: ExtensionMenuOptions): React.ReactElement<any, string | React.JSXElementConstructor<any>>;
+declare const glyphs: {
+    new: string;
+    window: string;
+    save: string;
+    copy: string;
+    remix: string;
+    open: string;
+    'save-as': string;
+    download: string;
+    package: string;
+    restore: string;
+    properties: string;
+    payloads: string;
+    'bundle-assets': string;
+    diagnostics: string;
+};
+export declare function createFileMenuItem(MenuItem: React.ElementType, extensionIcon: string): ({ command, children, ...props }: {
+    command?: keyof typeof glyphs | "extension";
+    children: React.ReactNode;
+    [prop: string]: unknown;
+}) => React.ReactElement<any, string | React.JSXElementConstructor<any>>;
+export {};

package/dist/extension-file-menu.js

@@ -0,0 +1,56 @@
+import React from 'react';
+export function renderExtensionFileMenu({ locale = 'en', MenuSection, MenuItem, onAddExtension, onRequestClose }) {
+    if (!onAddExtension)
+        return null;
+    function open() {
+        onRequestClose();
+        onAddExtension();
+    }
+    return React.createElement(MenuSection, null, React.createElement(MenuItem, { command: 'extension', onClick: open }, React.createElement('span', {
+        role: 'button',
+        tabIndex: 0,
+        onKeyDown(event) {
+            if (event.key !== 'Enter' && event.key !== ' ')
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            open();
+        }
+    }, /^ja(?:-|$)/i.test(locale) ? '機能拡張の追加' : 'Add Extension')));
+}
+const glyphs = {
+    new: 'M5 3h9l5 5v13H5z M14 3v5h5 M9 14h6 M12 11v6',
+    window: 'M3 5h18v14H3z M3 9h18 M9 14h6 M12 11v6',
+    save: 'M4 3h13l3 3v15H4z M8 3v6h8V3 M8 21v-7h8v7',
+    copy: 'M8 8h12v13H8z M16 8V3H3v13h5',
+    remix: 'M18 8a7 7 0 1 0 0 8 M18 3v5h-5 M18 8l2-2',
+    open: 'M3 6h7l2 2h9l-2 11H3z M3 11h16',
+    'save-as': 'M4 3h13l3 3v15H4z M8 3v6h8V3 M9 17h6 M12 14v6',
+    download: 'M12 3v12 M7 10l5 5 5-5 M4 17v4h16v-4',
+    package: 'm12 3 8 4v10l-8 4-8-4V7z M4 7l8 4 8-4 M12 11v10 M8 5l8 4',
+    restore: 'M4 10a8 8 0 1 1 2 8 M4 4v6h6 M12 7v5l3 2',
+    properties: 'M4 6h16 M4 12h16 M4 18h16 M8 3v6 M16 9v6 M10 15v6',
+    payloads: 'M9 5 4 12l5 7 M15 5l5 7-5 7 M14 4l-4 16',
+    'bundle-assets': 'M4 5h16v14H4z M12 8v8 M8 12h8',
+    diagnostics: 'M3 12h4l2-5 4 10 2-5h6'
+};
+const iconSize = 16;
+const iconStyle = { width: iconSize, height: iconSize, flex: 'none' };
+const rowStyle = { display: 'inline-flex', alignItems: 'center', gap: 8, verticalAlign: 'middle' };
+export function createFileMenuItem(MenuItem, extensionIcon) {
+    return function FileMenuItem({ command, children, ...props }) {
+        let icon;
+        if (command === 'extension') {
+            icon = React.createElement('span', { 'aria-hidden': true, 'data-file-menu-icon': command, style: {
+                    ...iconStyle, backgroundColor: 'currentColor', mask: `url("${extensionIcon}") center / contain no-repeat`
+                } });
+        }
+        else if (command && glyphs[command]) {
+            icon = React.createElement('svg', { 'aria-hidden': true, 'data-file-menu-icon': command,
+                viewBox: '0 0 24 24', style: iconStyle, fill: 'none', stroke: 'currentColor', strokeWidth: 1.7,
+                strokeLinecap: 'round', strokeLinejoin: 'round' }, React.createElement('path', { d: glyphs[command] }));
+        }
+        return React.createElement(MenuItem, props, icon ?
+            React.createElement('span', { style: rowStyle }, icon, React.createElement('span', null, children)) : children);
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+export { attachExternalMonitorDrag } from './monitor-drag.ts';
+export { attachStageInput } from './stage-input.ts';
+type Axis = 'columns' | 'rows';
+type Ratios = Record<Axis, number | null>;
+type LayoutStorage = Pick<Storage, 'getItem' | 'setItem'>;
+export declare function splitAxis(length: number, ratio: number | null, fallback: number, minimumFirst: number, minimumSecond: number): {
+    available: number;
+    minimum: number;
+    maximum: number;
+    first: number;
+    second: number;
+};
+export declare function readRatios(storage: LayoutStorage | null, key: string): Ratios;
+export declare function writeRatios(storage: LayoutStorage | null, key: string, ratios: Ratios): void;
+export declare function fitStage(columnWidth: number, rowHeight: number, aspect: number, horizontalInset: number, verticalInset: number): number;
+export declare function createSplitter(React: any): ({ axis, split, rtl, label, onChange, onReset, className }: {
+    axis: any;
+    split: any;
+    rtl: any;
+    label: any;
+    onChange: any;
+    onReset: any;
+    className: any;
+}) => any;
+export declare function createLayout(React: any): ({ render, enabled, fullscreen, rtl, labels, separatorClassName, stageTools, defaultStageWidth, defaultStageHeight, stageAspect, horizontalInset, verticalInset, minimumEditor, minimumStageColumn, minimumStageRow, minimumTargets, storage, storageKey }: {
+    render: any;
+    enabled: any;
+    fullscreen: any;
+    rtl: any;
+    labels: any;
+    separatorClassName: any;
+    stageTools: any;
+    defaultStageWidth: any;
+    defaultStageHeight: any;
+    stageAspect: any;
+    horizontalInset: any;
+    verticalInset: any;
+    minimumEditor: any;
+    minimumStageColumn: any;
+    minimumStageRow: any;
+    minimumTargets: any;
+    storage: any;
+    storageKey: any;
+}) => any;
+export { createTargetList } from './targets.ts';
+export { attachHorizontalWorkspaceZoom, workspaceControlsCorner } from './workspace-zoom.ts';

package/dist/index.js

@@ -0,0 +1,166 @@
+export { attachExternalMonitorDrag } from "./monitor-drag.js";
+export { attachStageInput } from "./stage-input.js";
+const separatorSize = 8;
+const keyboardStep = 16;
+export function splitAxis(length, ratio, fallback, minimumFirst, minimumSecond) {
+    const available = Math.max(0, Math.round(length) - separatorSize);
+    const minimum = Math.min(minimumFirst, available);
+    const maximum = Math.max(minimum, available - minimumSecond);
+    const desired = ratio === null ? fallback : available * ratio;
+    const first = Math.round(Math.min(maximum, Math.max(minimum, desired)));
+    return { available, minimum, maximum, first, second: available - first };
+}
+export function readRatios(storage, key) {
+    try {
+        const saved = JSON.parse(storage?.getItem(key));
+        if (saved?.version === 1) {
+            const ratio = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1 ? value : null;
+            return { columns: ratio(saved.columns), rows: ratio(saved.rows) };
+        }
+    }
+    catch {
+        // Storage can be unavailable or contain obsolete data.
+    }
+    return { columns: null, rows: null };
+}
+export function writeRatios(storage, key, ratios) {
+    try {
+        storage?.setItem(key, JSON.stringify({ version: 1, ...ratios }));
+    }
+    catch {
+        // Keep the current layout usable when persistence is denied.
+    }
+}
+export function fitStage(columnWidth, rowHeight, aspect, horizontalInset, verticalInset) {
+    return Math.max(1, Math.floor(Math.min(columnWidth - horizontalInset, (rowHeight - verticalInset) * aspect)));
+}
+export function createSplitter(React) {
+    return function Splitter({ axis, split, rtl, label, onChange, onReset, className }) {
+        const drag = React.useRef(null);
+        const vertical = axis === 'columns';
+        const coordinate = event => vertical ? event.clientX : event.clientY;
+        const direction = vertical && rtl ? -1 : 1;
+        const update = position => {
+            if (split.available > 0) {
+                const value = Math.max(split.minimum, Math.min(split.maximum, position));
+                onChange(value / split.available);
+            }
+        };
+        const onKeyDown = event => {
+            const { key } = event;
+            const previous = vertical ? 'ArrowLeft' : 'ArrowUp';
+            const next = vertical ? 'ArrowRight' : 'ArrowDown';
+            if (key === previous)
+                update(split.first - keyboardStep * direction);
+            else if (key === next)
+                update(split.first + keyboardStep * direction);
+            else if (key === 'Home')
+                update(split.minimum);
+            else if (key === 'End')
+                update(split.maximum);
+            else if (key === 'Enter')
+                onReset();
+            else
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+        };
+        const clearDrag = event => {
+            if (drag.current?.id === event.pointerId)
+                drag.current = null;
+        };
+        return React.createElement('div', {
+            role: 'separator',
+            tabIndex: 0,
+            'aria-label': label,
+            'aria-orientation': vertical ? 'vertical' : 'horizontal',
+            'aria-valuemin': split.minimum,
+            'aria-valuemax': split.maximum,
+            'aria-valuenow': split.first,
+            className,
+            style: {
+                touchAction: 'none',
+                userSelect: 'none',
+                cursor: vertical ? 'col-resize' : 'row-resize'
+            },
+            onKeyDown,
+            onDoubleClick: onReset,
+            onPointerDown: event => {
+                if (event.button !== 0 || drag.current)
+                    return;
+                drag.current = { id: event.pointerId, start: coordinate(event), first: split.first };
+                event.currentTarget.setPointerCapture(event.pointerId);
+                event.currentTarget.focus();
+                event.preventDefault();
+            },
+            onPointerMove: event => {
+                if (drag.current?.id !== event.pointerId)
+                    return;
+                update(drag.current.first + (coordinate(event) - drag.current.start) * direction);
+            },
+            onPointerUp: clearDrag,
+            onPointerCancel: clearDrag,
+            onLostPointerCapture: clearDrag
+        });
+    };
+}
+export function createLayout(React) {
+    const Splitter = createSplitter(React);
+    return function SplitLayout({ render, enabled, fullscreen, rtl, labels, separatorClassName, stageTools, defaultStageWidth, defaultStageHeight, stageAspect, horizontalInset, verticalInset, minimumEditor, minimumStageColumn, minimumStageRow, minimumTargets, storage, storageKey }) {
+        const [ratios, setRatios] = React.useState(() => readRatios(storage, storageKey));
+        const [size, setSize] = React.useState(null);
+        const element = React.useRef(null);
+        const observe = React.useCallback(node => {
+            element.current = node;
+        }, []);
+        const active = enabled && !fullscreen;
+        React.useLayoutEffect(() => {
+            const node = element.current;
+            const ResizeObserver = node?.ownerDocument.defaultView.ResizeObserver;
+            if (!active || !ResizeObserver)
+                return;
+            const measure = () => {
+                const { clientWidth: width, clientHeight: height } = node;
+                setSize(previous => previous?.width === width && previous.height === height ?
+                    previous : { width, height });
+            };
+            measure();
+            const observer = new ResizeObserver(measure);
+            observer.observe(node);
+            return () => observer.disconnect();
+        }, [active]);
+        const base = { observe, stageTools };
+        if (!active || !size ||
+            size.width < minimumEditor + separatorSize + minimumStageColumn ||
+            size.height < minimumStageRow + separatorSize + minimumTargets)
+            return render(base);
+        const columns = splitAxis(size.width, ratios.columns, size.width - separatorSize - Math.max(minimumStageColumn, defaultStageWidth + horizontalInset), minimumEditor, minimumStageColumn);
+        const rows = splitAxis(size.height, ratios.rows, defaultStageHeight + verticalInset, minimumStageRow, minimumTargets);
+        const save = updated => {
+            setRatios(updated);
+            writeRatios(storage, storageKey, updated);
+        };
+        const change = (axis, value) => save({ ...ratios, [axis]: value });
+        const separator = (axis, split) => React.createElement(Splitter, {
+            axis, split, rtl,
+            label: labels[axis],
+            className: separatorClassName,
+            onChange: value => change(axis, value),
+            onReset: () => change(axis, null)
+        });
+        return render({
+            ...base,
+            columnSplitter: separator('columns', columns),
+            rowSplitter: separator('rows', rows),
+            bodyStyle: { display: 'grid', gridTemplateColumns: `minmax(0, 1fr) ${separatorSize}px ${columns.second}px` },
+            editorStyle: { minWidth: 0, minHeight: 0 },
+            stageColumnStyle: { display: 'grid', minWidth: 0, minHeight: 0,
+                gridTemplateRows: `${rows.first}px ${separatorSize}px minmax(0, 1fr)` },
+            stageDisplayWidth: fitStage(columns.second, rows.first, stageAspect, horizontalInset, verticalInset),
+            editorWidth: columns.first,
+            handleStagePreset: () => save({ columns: null, rows: null })
+        });
+    };
+}
+export { createTargetList } from "./targets.js";
+export { attachHorizontalWorkspaceZoom, workspaceControlsCorner } from "./workspace-zoom.js";

package/dist/monitor-drag.d.ts

@@ -0,0 +1,4 @@
+export declare function attachExternalMonitorDrag(element: HTMLElement, onMove: (event: PointerEvent, position: {
+    x: number;
+    y: number;
+}) => void, isDraggable: () => boolean, editorDocument: Document): () => void;

package/dist/monitor-drag.js

@@ -0,0 +1,78 @@
+export function attachExternalMonitorDrag(element, onMove, isDraggable, editorDocument) {
+    let drag;
+    function clear() {
+        if (!drag)
+            return;
+        const { id, translate } = drag;
+        drag = undefined;
+        element.style.translate = translate;
+        if (element.hasPointerCapture(id))
+            element.releasePointerCapture(id);
+    }
+    function start(event) {
+        const owner = element.ownerDocument;
+        if (drag || owner === editorDocument || event.pointerType !== 'mouse' || event.button !== 0 ||
+            !isDraggable() || event.target.closest?.('.no-drag'))
+            return;
+        const overlay = element.closest('.monitor-overlay');
+        if (!overlay || !overlay.clientWidth || !overlay.clientHeight)
+            return;
+        const rect = overlay.getBoundingClientRect();
+        if (!rect.width || !rect.height)
+            return;
+        const scaleX = rect.width / overlay.clientWidth;
+        const scaleY = rect.height / overlay.clientHeight;
+        const monitorRect = element.getBoundingClientRect();
+        const left = Math.round((monitorRect.left - rect.left) / scaleX);
+        const top = Math.round((monitorRect.top - rect.top) / scaleY);
+        drag = {
+            id: event.pointerId, owner, clientX: event.clientX, clientY: event.clientY,
+            scaleX, scaleY, left, top, offsetLeft: element.offsetLeft, offsetTop: element.offsetTop,
+            minX: -left, minY: -top,
+            maxX: overlay.clientWidth - element.offsetWidth - left,
+            maxY: overlay.clientHeight - element.offsetHeight - top,
+            translate: element.style.translate
+        };
+        element.setPointerCapture(drag.id);
+        // Stop the compatibility mousedown from starting the in-editor drag path.
+        event.preventDefault();
+    }
+    function offset(event) {
+        const x = Math.round((event.clientX - drag.clientX) / drag.scaleX);
+        const y = Math.round((event.clientY - drag.clientY) / drag.scaleY);
+        return {
+            x: Math.max(drag.minX, Math.min(drag.maxX, x)),
+            y: Math.max(drag.minY, Math.min(drag.maxY, y))
+        };
+    }
+    function move(event) {
+        if (drag?.id !== event.pointerId)
+            return;
+        if (drag.owner !== element.ownerDocument)
+            return clear();
+        const { x, y } = offset(event);
+        element.style.translate = `${x}px ${y}px`;
+    }
+    function finish(event) {
+        if (drag?.id !== event.pointerId)
+            return;
+        const position = event.type === 'pointerup' && drag.owner === element.ownerDocument && offset(event);
+        const { left, top, offsetLeft, offsetTop } = drag;
+        clear();
+        if (!position || !(position.x || position.y))
+            return;
+        onMove(event, { x: left + position.x - offsetLeft, y: top + position.y - offsetTop });
+        // Keep the editor's existing drag transform and update only the layout position.
+        element.style.left = `${offsetLeft + position.x}px`;
+        element.style.top = `${offsetTop + position.y}px`;
+    }
+    const handlers = { pointerdown: start, pointermove: move, pointerup: finish,
+        pointercancel: finish, lostpointercapture: finish };
+    for (const [name, handler] of Object.entries(handlers))
+        element.addEventListener(name, handler);
+    return () => {
+        for (const [name, handler] of Object.entries(handlers))
+            element.removeEventListener(name, handler);
+        clear();
+    };
+}

package/dist/sprite-asset-pane.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+export interface SpriteMediaAsset {
+    /** Host identity for this item within its target, independent of the list order. */
+    id: string;
+    name: string;
+    imageUrl?: string;
+    duration?: number;
+    /** Downsampled waveform magnitudes in the range from zero to one. */
+    peaks?: readonly number[];
+}
+export interface SpriteVariable {
+    id: string;
+    name: string;
+    value: string | number;
+    scope?: 'local' | 'global';
+}
+interface PaneProps {
+    locale: string;
+    editable: boolean;
+}
+export interface SpriteMediaPaneProps extends PaneProps {
+    kind: 'costumes' | 'sounds';
+    items: readonly SpriteMediaAsset[];
+    selectedId: string | null;
+    detailOnly?: boolean;
+    onSelect(id: string): void;
+    /** Optional host surface. It must honor editable without unmounting its layout. */
+    renderEditor?(selected: SpriteMediaAsset, editable: boolean): React.ReactNode;
+}
+export interface SpriteVariablePaneProps extends PaneProps {
+    kind: 'variables';
+    variables: readonly SpriteVariable[];
+    onWrite(id: string, value: SpriteVariable['value']): void;
+}
+export type SpriteAssetPaneProps = SpriteMediaPaneProps | SpriteVariablePaneProps;
+export declare function SpriteAssetPane(props: SpriteAssetPaneProps): React.JSX.Element;
+export {};

package/dist/sprite-asset-pane.js

@@ -0,0 +1,109 @@
+import React from 'react';
+const english = {
+    costumes: 'Costumes', sounds: 'Sounds', variables: 'Variables', name: 'Name', value: 'Value',
+    local: 'Sprite', global: 'Project', emptyCostumes: 'No costumes', emptySounds: 'No sounds',
+    emptyVariables: 'No variables', selectCostume: 'Select a costume', selectSound: 'Select a sound',
+    imageUnavailable: 'Image unavailable', waveformUnavailable: 'Waveform unavailable', waveform: 'Waveform',
+    seconds: 's'
+};
+const japanese = {
+    costumes: 'コスチューム', sounds: '音', variables: '変数', name: '名前', value: '値',
+    local: 'スプライト', global: '作品', emptyCostumes: 'コスチュームがありません', emptySounds: '音がありません',
+    emptyVariables: '変数がありません', selectCostume: 'コスチュームを選択してください', selectSound: '音を選択してください',
+    imageUnavailable: '画像を表示できません', waveformUnavailable: '波形を表示できません', waveform: '波形',
+    seconds: '秒'
+};
+const labelsFor = (locale) => /^ja(?:-|$)/i.test(locale) ? japanese : english;
+function Waveform({ name, peaks, label }) {
+    const path = peaks.map((sample, index) => {
+        const x = (index + 0.5) * 100 / peaks.length;
+        const magnitude = Number.isFinite(sample) ? Math.max(0, Math.min(sample, 1)) : 0;
+        const y = magnitude * 49;
+        return 'M' + x + ' ' + (50 - y) + 'V' + (50 + y);
+    }).join(' ');
+    return React.createElement("svg", { className: "tw-sprite-media__waveform", viewBox: "0 0 100 100", preserveAspectRatio: "none", role: "img", "aria-label": label + ': ' + name },
+        React.createElement("path", { d: "M0 50H100", vectorEffect: "non-scaling-stroke", className: "tw-sprite-media__axis" }),
+        React.createElement("path", { d: path, vectorEffect: "non-scaling-stroke", className: "tw-sprite-media__peaks" }));
+}
+function MediaPane({ kind, items, selectedId, onSelect, renderEditor, editable, locale, detailOnly }) {
+    const labels = labelsFor(locale);
+    const isSound = kind === 'sounds';
+    const selected = items.find(asset => asset.id === selectedId);
+    const duration = selected?.duration;
+    return React.createElement("section", { className: detailOnly ? 'tw-sprite-media tw-sprite-media--detail' : 'tw-sprite-media', "aria-label": labels[kind] },
+        !detailOnly && React.createElement("ul", { className: "tw-sprite-media__list", "aria-label": labels[kind] }, items.map(asset => React.createElement("li", { key: asset.id },
+            React.createElement("button", { type: "button", className: "tw-sprite-media__item", "aria-current": asset.id === selectedId || undefined, "aria-disabled": !editable || undefined, tabIndex: editable ? 0 : -1, onClick: () => {
+                    if (editable)
+                        onSelect(asset.id);
+                } },
+                asset.imageUrl ? React.createElement("img", { src: asset.imageUrl, alt: "", className: "tw-sprite-media__thumbnail" }) :
+                    React.createElement("span", { className: "tw-sprite-media__symbol", "aria-hidden": "true" }, isSound ? '♪' : '◫'),
+                React.createElement("span", { className: "tw-sprite-media__name" }, asset.name))))),
+        React.createElement("div", { className: "tw-sprite-media__detail" }, selected ? React.createElement(React.Fragment, null,
+            React.createElement("h3", { className: "tw-sprite-media__title" }, selected.name),
+            React.createElement("div", { className: "tw-sprite-media__surface" }, renderEditor?.(selected, editable) ?? (isSound ?
+                (selected.peaks?.length ? React.createElement(Waveform, { peaks: selected.peaks, name: selected.name, label: labels.waveform }) :
+                    React.createElement("p", null, labels.waveformUnavailable)) :
+                (selected.imageUrl ? React.createElement("img", { src: selected.imageUrl, alt: selected.name, className: "tw-sprite-media__preview" }) :
+                    React.createElement("p", null, labels.imageUnavailable)))),
+            isSound && Number.isFinite(duration) && duration >= 0 &&
+                React.createElement("p", { className: "tw-sprite-media__duration" },
+                    new Intl.NumberFormat(locale, { maximumFractionDigits: 2 }).format(duration),
+                    " ",
+                    labels.seconds)) : React.createElement("p", null, items.length ? (isSound ? labels.selectSound : labels.selectCostume) :
+            (isSound ? labels.emptySounds : labels.emptyCostumes))));
+}
+function VariableField({ variable, editable, onWrite }) {
+    const [text, setText] = React.useState(null);
+    const pending = React.useRef(null);
+    const finish = (save) => {
+        const draft = pending.current;
+        if (!draft)
+            return;
+        pending.current = null;
+        setText(null);
+        if (!save || draft.text === String(variable.value))
+            return;
+        const number = Number(draft.text);
+        const value = typeof draft.variable.value === 'number' && draft.text.trim() && Number.isFinite(number) ?
+            number : draft.text;
+        draft.write(draft.variable.id, value);
+    };
+    React.useLayoutEffect(() => {
+        // A click can change the active pane before the old input receives blur.
+        if (!editable)
+            finish(true);
+    }, [editable]);
+    return React.createElement("input", { className: "tw-sprite-variables__input", "aria-label": variable.name, "data-variable-id": variable.id, readOnly: !editable, tabIndex: editable ? 0 : -1, value: text ?? String(variable.value), onChange: event => {
+            if (!editable)
+                return;
+            const next = event.currentTarget.value;
+            pending.current = { text: next, variable, write: onWrite };
+            setText(next);
+        }, onBlur: () => finish(true), onKeyDown: event => {
+            if (!editable || event.nativeEvent.isComposing)
+                return;
+            if (event.key !== 'Enter' && event.key !== 'Escape')
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            finish(event.key === 'Enter');
+        } });
+}
+function VariablePane({ variables, editable, onWrite, locale }) {
+    const labels = labelsFor(locale);
+    return React.createElement("section", { className: "tw-sprite-variables", "aria-label": labels.variables }, variables.length ? React.createElement("table", { className: "tw-sprite-variables__table" },
+        React.createElement("thead", null,
+            React.createElement("tr", null,
+                React.createElement("th", { scope: "col" }, labels.name),
+                React.createElement("th", { scope: "col" }, labels.value))),
+        React.createElement("tbody", null, variables.map(variable => React.createElement("tr", { key: variable.id },
+            React.createElement("th", { scope: "row" },
+                variable.name,
+                variable.scope && React.createElement("span", { className: "tw-sprite-variables__scope" }, labels[variable.scope])),
+            React.createElement("td", null,
+                React.createElement(VariableField, { variable: variable, editable: editable, onWrite: onWrite })))))) : React.createElement("p", null, labels.emptyVariables));
+}
+export function SpriteAssetPane(props) {
+    return props.kind === 'variables' ? React.createElement(VariablePane, { ...props }) : React.createElement(MediaPane, { ...props });
+}