From 6d87a59d960bf8cdcf183d27585a840a0585817b Mon Sep 17 00:00:00 2001
From: ash <gracelllx@qq.com>
Date: Mon, 13 Jul 2026 16:12:23 +0800
Subject: [PATCH 01/10] Implement Source Editor MVP

---
 .../src/editor/SourceEditor.ts                | 144 +++++++++++
 .../pagx-playground/src/editor/index.ts       | 231 ++++++++++++++++++
 .../pagx-playground/src/editor/styles.ts      | 211 ++++++++++++++++
 playground/pagx-playground/src/index.ts       |  84 ++++++-
 playground/pagx-playground/static/index.html  |  17 ++
 5 files changed, 685 insertions(+), 2 deletions(-)
 create mode 100644 playground/pagx-playground/src/editor/SourceEditor.ts
 create mode 100644 playground/pagx-playground/src/editor/index.ts
 create mode 100644 playground/pagx-playground/src/editor/styles.ts

diff --git a/playground/pagx-playground/src/editor/SourceEditor.ts b/playground/pagx-playground/src/editor/SourceEditor.ts
new file mode 100644
index 0000000000..97ccb16f62
--- /dev/null
+++ b/playground/pagx-playground/src/editor/SourceEditor.ts
@@ -0,0 +1,144 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making libpag available.
+//
+//  Copyright (C) 2026 Tencent. All rights reserved.
+//
+//  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file
+//  except in compliance with the License. You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  unless required by applicable law or agreed to in writing, software distributed under the
+//  license is distributed on an "as is" basis, without warranties or conditions of any kind,
+//  either express or implied. see the license for the specific language governing permissions
+//  and limitations under the license.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+import { EditorView, keymap } from '@codemirror/view';
+import { EditorState } from '@codemirror/state';
+import { basicSetup } from 'codemirror';
+import { xml } from '@codemirror/lang-xml';
+import { syntaxHighlighting, HighlightStyle } from '@codemirror/language';
+import { searchKeymap, highlightSelectionMatches } from '@codemirror/search';
+import { tags } from '@lezer/highlight';
+
+/** Syntax highlight colors matching the desktop client (VS Code Dark+ palette). */
+const pagxHighlightStyle = HighlightStyle.define([
+    { tag: tags.tagName, color: '#569CD6' },
+    { tag: tags.attributeName, color: '#9CDCFE' },
+    { tag: tags.attributeValue, color: '#CE9178' },
+    { tag: tags.string, color: '#CE9178' },
+    { tag: tags.comment, color: '#6A9955' },
+    { tag: tags.meta, color: '#808080' },
+    { tag: tags.processingInstruction, color: '#808080' },
+    { tag: tags.content, color: '#D4D4D4' },
+    { tag: tags.angleBracket, color: '#569CD6' },
+]);
+
+/**
+ * Wraps a CodeMirror 6 instance for editing PAGX XML source.
+ * The editor is created lazily on first open to avoid impacting initial page load.
+ */
+export class SourceEditor {
+    private host: HTMLElement;
+    private view: EditorView | null = null;
+
+    constructor(host: HTMLElement) {
+        this.host = host;
+    }
+
+    /** Creates the CodeMirror view if it does not exist yet. */
+    private ensureView(): void {
+        if (this.view !== null) {
+            return;
+        }
+        this.view = new EditorView({
+            parent: this.host,
+            state: EditorState.create({
+                doc: '',
+                extensions: [
+                    basicSetup,
+                    xml(),
+                    syntaxHighlighting(pagxHighlightStyle),
+                    highlightSelectionMatches(),
+                    keymap.of([...searchKeymap]),
+                    EditorView.theme({
+                        '&': {
+                            backgroundColor: '#1E1E1E',
+                            color: '#D4D4D4',
+                            height: '100%',
+                        },
+                        '.cm-content': {
+                            fontFamily: 'Menlo, Monaco, "Courier New", monospace',
+                            fontSize: '13px',
+                            caretColor: '#FFFFFF',
+                        },
+                        '.cm-cursor': {
+                            borderLeftColor: '#FFFFFF',
+                            borderLeftWidth: '2px',
+                        },
+                        '.cm-gutters': {
+                            backgroundColor: '#1E1E1E',
+                            color: '#6E7681',
+                            border: 'none',
+                            borderRight: '1px solid #3C3C3C',
+                        },
+                        '.cm-activeLine': {
+                            backgroundColor: '#2D2D2D',
+                        },
+                        '.cm-activeLineGutter': {
+                            backgroundColor: '#2D2D2D',
+                        },
+                        '.cm-selectionBackground, ::selection': {
+                            backgroundColor: '#264F78',
+                        },
+                        '&.cm-focused .cm-selectionBackground': {
+                            backgroundColor: '#264F78',
+                        },
+                    }),
+                ],
+            }),
+        });
+    }
+
+    /** Replaces the entire document content. */
+    setContent(text: string): void {
+        this.ensureView();
+        if (this.view === null) {
+            return;
+        }
+        const trimmed = text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text;
+        this.view.dispatch({
+            changes: {
+                from: 0,
+                to: this.view.state.doc.length,
+                insert: trimmed,
+            },
+        });
+    }
+
+    /** Returns the current document text. */
+    getContent(): string {
+        if (this.view === null) {
+            return '';
+        }
+        return this.view.state.doc.toString();
+    }
+
+    /** Moves keyboard focus into the editor. */
+    focus(): void {
+        if (this.view !== null) {
+            this.view.focus();
+        }
+    }
+
+    /** Releases the CodeMirror instance and frees DOM nodes. */
+    destroy(): void {
+        if (this.view !== null) {
+            this.view.destroy();
+            this.view = null;
+        }
+    }
+}
diff --git a/playground/pagx-playground/src/editor/index.ts b/playground/pagx-playground/src/editor/index.ts
new file mode 100644
index 0000000000..51964bdf8b
--- /dev/null
+++ b/playground/pagx-playground/src/editor/index.ts
@@ -0,0 +1,231 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making libpag available.
+//
+//  Copyright (C) 2026 Tencent. All rights reserved.
+//
+//  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file
+//  except in compliance with the License. You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  unless required by applicable law or agreed to in writing, software distributed under the
+//  license is distributed on an "as is" basis, without warranties or conditions of any kind,
+//  either express or implied. see the license for the specific language governing permissions
+//  and limitations under the license.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+import { SourceEditor } from './SourceEditor';
+import { EDITOR_STYLES } from './styles';
+
+const MOBILE_BREAKPOINT = 768;
+const TOAST_DURATION_MS = 2000;
+
+let panel: HTMLElement | null = null;
+let editor: SourceEditor | null = null;
+let currentXmlText: string | null = null;
+let toastTimer: number | undefined;
+let toastEl: HTMLElement | null = null;
+
+/** Callbacks provided by the host application to apply/save XML changes. */
+export interface EditorCallbacks {
+    /** Applies XML text to the PAGX view. Returns empty string on success, error message on failure. */
+    onApply: (xmlText: string) => string;
+    /** Applies and saves XML text to a file. Returns empty string on success, error message on failure. */
+    onSave: (xmlText: string) => string;
+}
+
+let callbacks: EditorCallbacks | null = null;
+
+/** Dispatched by index.ts after a PAGX file is loaded or cleared. */
+interface PagxLoadedDetail {
+    xmlText: string | null;
+}
+
+declare global {
+    interface WindowEventMap {
+        'pagx:loaded': CustomEvent<PagxLoadedDetail>;
+    }
+}
+
+/** True when the keyboard event originates from an editable element. */
+function isEditableTarget(target: EventTarget | null): boolean {
+    if (!(target instanceof HTMLElement)) {
+        return false;
+    }
+    const tag = target.tagName;
+    return tag === 'INPUT' || tag === 'TEXTAREA' || target.isContentEditable;
+}
+
+/** True when the editor panel is currently shown. */
+function isPanelOpen(): boolean {
+    return panel !== null && panel.classList.contains('visible');
+}
+
+function showToast(message: string, success: boolean): void {
+    if (toastEl === null) {
+        return;
+    }
+    toastEl.textContent = message;
+    toastEl.className = `editor-toast visible ${success ? 'success' : 'error'}`;
+    window.clearTimeout(toastTimer);
+    toastTimer = window.setTimeout(() => {
+        if (toastEl !== null) {
+            toastEl.className = 'editor-toast';
+        }
+    }, TOAST_DURATION_MS);
+}
+
+function openPanel(): void {
+    if (panel === null) {
+        return;
+    }
+    if (editor === null) {
+        const host = panel.querySelector('.editor-host');
+        if (host instanceof HTMLElement) {
+            editor = new SourceEditor(host);
+        }
+    }
+    if (editor !== null && currentXmlText !== null) {
+        editor.setContent(currentXmlText);
+    }
+    panel.classList.add('visible');
+    const container = document.getElementById('container');
+    if (container !== null) {
+        container.classList.add('with-editor');
+    }
+}
+
+function closePanel(): void {
+    if (panel === null) {
+        return;
+    }
+    panel.classList.remove('visible');
+    const container = document.getElementById('container');
+    if (container !== null) {
+        container.classList.remove('with-editor');
+    }
+}
+
+function togglePanel(): void {
+    if (isPanelOpen()) {
+        closePanel();
+    } else {
+        openPanel();
+    }
+}
+
+function handleKeydown(event: KeyboardEvent): void {
+    if (event.key !== 'l' && event.key !== 'L') {
+        return;
+    }
+    // Ignore when the user is typing inside an input/textarea/contenteditable.
+    if (isEditableTarget(event.target)) {
+        return;
+    }
+    // Ignore modifier combos (Ctrl+L, Shift+L, etc.) - only bare L triggers.
+    if (event.ctrlKey || event.metaKey || event.altKey) {
+        return;
+    }
+    // No file loaded yet - silently ignore, matching desktop "enabled: hasPAGFile".
+    if (currentXmlText === null) {
+        return;
+    }
+    // Mobile screens are too narrow for side-by-side layout.
+    if (window.innerWidth < MOBILE_BREAKPOINT) {
+        showToast('Please use desktop to edit source', false);
+        return;
+    }
+    event.preventDefault();
+    togglePanel();
+}
+
+function handlePagxLoaded(event: Event): void {
+    const detail = (event as CustomEvent<PagxLoadedDetail>).detail;
+    currentXmlText = detail ? detail.xmlText : null;
+    if (currentXmlText === null) {
+        // File cleared (goHome) - close panel and clear editor content.
+        if (isPanelOpen()) {
+            closePanel();
+        }
+        if (editor !== null) {
+            editor.setContent('');
+        }
+    } else if (isPanelOpen() && editor !== null) {
+        // Panel already open and a new file loaded - refresh content.
+        editor.setContent(currentXmlText);
+    }
+}
+
+function handleDiscard(): void {
+    if (editor === null) {
+        return;
+    }
+    if (currentXmlText !== null) {
+        editor.setContent(currentXmlText);
+    }
+    showToast('Changes discarded', true);
+}
+
+function handleApply(): void {
+    if (editor === null || callbacks === null) {
+        return;
+    }
+    const xmlText = editor.getContent();
+    const error = callbacks.onApply(xmlText);
+    showToast(error === '' ? 'Changes applied' : error, error === '');
+}
+
+function handleSave(): void {
+    if (editor === null || callbacks === null) {
+        return;
+    }
+    const xmlText = editor.getContent();
+    const error = callbacks.onSave(xmlText);
+    showToast(error === '' ? 'File saved' : error, error === '');
+}
+
+/**
+ * Initializes the Source Editor module. Wires up DOM elements, keyboard
+ * shortcut (L to toggle) and the pagx:loaded event. Safe to call once
+ * after DOM is ready.
+ */
+export function init(cb: EditorCallbacks): void {
+    callbacks = cb;
+    // Inject editor styles once. CSS lives in styles.ts to keep the module self-contained
+    // without requiring a rollup CSS plugin.
+    const styleEl = document.createElement('style');
+    styleEl.textContent = EDITOR_STYLES;
+    document.head.appendChild(styleEl);
+
+    panel = document.getElementById('editor-panel');
+    if (panel === null) {
+        console.warn('SourceEditor: #editor-panel element not found, skipping init.');
+        return;
+    }
+    const closeBtn = panel.querySelector('.editor-close-btn');
+    if (closeBtn !== null) {
+        closeBtn.addEventListener('click', closePanel);
+    }
+    const discardBtn = panel.querySelector('.editor-btn.discard');
+    if (discardBtn !== null) {
+        discardBtn.addEventListener('click', handleDiscard);
+    }
+    const applyBtn = panel.querySelector('.editor-btn.apply');
+    if (applyBtn !== null) {
+        applyBtn.addEventListener('click', handleApply);
+    }
+    const saveBtn = panel.querySelector('.editor-btn.save');
+    if (saveBtn !== null) {
+        saveBtn.addEventListener('click', handleSave);
+    }
+    toastEl = document.querySelector('.editor-toast');
+    if (toastEl === null) {
+        toastEl = document.createElement('div');
+        toastEl.className = 'editor-toast';
+        document.body.appendChild(toastEl);
+    }
+    document.addEventListener('keydown', handleKeydown);
+    window.addEventListener('pagx:loaded', handlePagxLoaded);
+}
diff --git a/playground/pagx-playground/src/editor/styles.ts b/playground/pagx-playground/src/editor/styles.ts
new file mode 100644
index 0000000000..807ac27150
--- /dev/null
+++ b/playground/pagx-playground/src/editor/styles.ts
@@ -0,0 +1,211 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////
+//
+//  Tencent is pleased to support the open source community by making libpag available.
+//
+//  Copyright (C) 2026 Tencent. All rights reserved.
+//
+//  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file
+//  except in compliance with the License. You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+//  unless required by applicable law or agreed to in writing, software distributed under the
+//  license is distributed on an "as IS" basis, without warranties or conditions of any kind,
+//  either express or implied. see the license for the specific language governing permissions
+//  and limitations under the license.
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////
+
+/** CSS rules for the editor panel, injected at runtime to avoid a separate rollup CSS plugin. */
+export const EDITOR_STYLES = `
+#editor-panel {
+    position: fixed;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    width: 50%;
+    display: none;
+    flex-direction: column;
+    background: #1E1E1E;
+    border-left: 1px solid #3C3C3C;
+    z-index: 10;
+}
+
+#editor-panel.visible {
+    display: flex;
+}
+
+.container.with-editor {
+    width: 50%;
+    margin: 0;
+}
+
+#editor-panel .editor-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    height: 40px;
+    padding: 0 12px;
+    background: #252526;
+    border-bottom: 1px solid #3C3C3C;
+    flex-shrink: 0;
+}
+
+#editor-panel .editor-title {
+    color: #CCCCCC;
+    font-size: 13px;
+    font-weight: 500;
+    user-select: none;
+}
+
+#editor-panel .editor-close-btn {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 28px;
+    height: 28px;
+    border: none;
+    background: transparent;
+    color: #CCCCCC;
+    cursor: pointer;
+    border-radius: 4px;
+    padding: 0;
+}
+
+#editor-panel .editor-close-btn:hover {
+    background: #3C3C3C;
+}
+
+#editor-panel .editor-host {
+    flex: 1;
+    overflow: hidden;
+    position: relative;
+}
+
+#editor-panel .editor-host .cm-editor {
+    height: 100%;
+    font-size: 13px;
+    font-family: Menlo, Monaco, 'Courier New', monospace;
+}
+
+#editor-panel .editor-host .cm-scroller {
+    overflow: auto;
+}
+
+#editor-panel .editor-host .cm-gutters {
+    background: #1E1E1E;
+    border-right: 1px solid #3C3C3C;
+    color: #6E7681;
+}
+
+#editor-panel .editor-host .cm-focused {
+    outline: none;
+}
+
+.editor-toast {
+    position: fixed;
+    top: 16px;
+    left: 50%;
+    transform: translateX(-50%);
+    padding: 8px 16px;
+    border-radius: 18px;
+    color: #FFFFFF;
+    font-size: 13px;
+    z-index: 1000;
+    opacity: 0;
+    transition: opacity 0.2s ease-in-out;
+    pointer-events: none;
+    white-space: nowrap;
+}
+
+.editor-toast.visible {
+    opacity: 0.95;
+}
+
+.editor-toast.success {
+    background: #2E7D32;
+}
+
+.editor-toast.error {
+    background: #C62828;
+}
+
+#editor-panel .editor-button-bar {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 12px;
+    height: 48px;
+    background: #16161D;
+    border-top: 1px solid #3C3C3C;
+    flex-shrink: 0;
+}
+
+#editor-panel .editor-btn {
+    width: 80px;
+    height: 32px;
+    border: 1px solid;
+    border-radius: 4px;
+    color: #FFFFFF;
+    font-size: 12px;
+    cursor: pointer;
+    transition: background 0.1s, transform 0.1s;
+    padding: 0;
+}
+
+#editor-panel .editor-btn:hover {
+    transform: scale(1.05);
+}
+
+#editor-panel .editor-btn:active {
+    transform: scale(1.0);
+}
+
+#editor-panel .editor-btn.discard {
+    background: #3C3C3C;
+    border-color: #4B4B5A;
+}
+
+#editor-panel .editor-btn.discard:hover {
+    background: #5C5C6A;
+    border-color: #8B8B9A;
+}
+
+#editor-panel .editor-btn.apply {
+    background: #448EF9;
+    border-color: #5BA3FF;
+}
+
+#editor-panel .editor-btn.apply:hover {
+    background: #5BA3FF;
+    border-color: #8BC4FF;
+}
+
+#editor-panel .editor-btn.save {
+    background: #388E3C;
+    border-color: #4CAF50;
+}
+
+#editor-panel .editor-btn.save:hover {
+    background: #4CAF50;
+    border-color: #81C784;
+}
+
+#editor-panel .editor-host .cm-scroller::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+}
+
+#editor-panel .editor-host .cm-scroller::-webkit-scrollbar-thumb {
+    background: rgba(75, 75, 90, 0.67);
+    border-radius: 4px;
+}
+
+#editor-panel .editor-host .cm-scroller::-webkit-scrollbar-track {
+    background: transparent;
+}
+
+#editor-panel .editor-host .cm-scroller::-webkit-scrollbar-thumb:hover {
+    background: rgba(90, 90, 110, 0.8);
+}
+`;
diff --git a/playground/pagx-playground/src/index.ts b/playground/pagx-playground/src/index.ts
index 02f6cd482c..e6b02aa250 100644
--- a/playground/pagx-playground/src/index.ts
+++ b/playground/pagx-playground/src/index.ts
@@ -18,6 +18,7 @@
 
 import { PAGXInit } from '../wasm-mt/pagx-viewer.esm';
 import type { PAGXView, PAGXModule } from '../../pagx-viewer/src/ts/pagx';
+import { init as initEditor } from './editor';
 
 interface I18nStrings {
     dropText: string;
@@ -820,6 +821,9 @@ function goHome(pushHistory: boolean = true): void {
     if (pushHistory) {
         history.pushState(null, '', window.location.pathname);
     }
+
+    // Notify the Source Editor module that the document has been cleared.
+    window.dispatchEvent(new CustomEvent('pagx:loaded', { detail: { xmlText: null } }));
 }
 
 function isSafeRelativePath(path: string): boolean {
@@ -883,6 +887,29 @@ async function loadPAGXData(data: Uint8Array, name: string, baseURL: string) {
     toolbar.classList.remove('hidden');
     navBtns.classList.add('hidden');
     document.title = 'PAGX Playground - ' + name;
+    currentFileName = name;
+
+    // Notify the Source Editor module that a new XML document is available.
+    const decoder = new TextDecoder('utf-8');
+    const xmlText = decoder.decode(data);
+    window.dispatchEvent(new CustomEvent('pagx:loaded', { detail: { xmlText } }));
+}
+
+const LOADING_TIMEOUT_MS = 60000;
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+    let timer: number | undefined;
+    const timeout = new Promise<never>((_, reject) => {
+        timer = window.setTimeout(
+            () => reject(new Error('Loading timed out. Please check your network and try again.')),
+            ms
+        );
+    });
+    return Promise.race([promise, timeout]).finally(() => {
+        if (timer !== undefined) {
+            window.clearTimeout(timer);
+        }
+    }) as Promise<T>;
 }
 
 async function prepareForLoading(): Promise<void> {
@@ -901,7 +928,17 @@ async function prepareForLoading(): Promise<void> {
     }
 
     const loadingStartTime = Date.now();
-    await Promise.all([wasmLoadPromise, fontLoadPromise]);
+    try {
+        await withTimeout(
+            Promise.all([wasmLoadPromise, fontLoadPromise]),
+            LOADING_TIMEOUT_MS
+        );
+    } catch (error) {
+        // Reset promises so the next attempt can retry from scratch.
+        wasmLoadPromise = null;
+        fontLoadPromise = null;
+        throw error;
+    }
     updateProgressUI();
 
     const elapsed = Date.now() - loadingStartTime;
@@ -922,7 +959,8 @@ async function loadPAGXFile(file: File) {
         history.replaceState(null, '', window.location.pathname);
     } catch (error) {
         console.error('Failed to load PAGX file:', error);
-        showErrorUI(t().errorFormat);
+        const message = error instanceof Error ? error.message : t().errorFormat;
+        showErrorUI(message);
     }
 }
 
@@ -1125,6 +1163,7 @@ function applyI18n(): void {
 
 let sampleFiles: string[] = [];
 let currentPlayingFile: string | null = null;
+let currentFileName: string = 'export.pagx';
 
 async function loadSampleList(): Promise<void> {
     if (sampleFiles.length > 0) {
@@ -1250,6 +1289,47 @@ if (typeof window !== 'undefined') {
         if (sampleName) {
             loadPAGXSample(sampleName, false);
         }
+
+        // Initialize the Source Editor module (keyboard shortcut L to toggle).
+        initEditor({
+            onApply: (xmlText: string): string => {
+                if (playgroundState.pagxView === null) {
+                    return 'PAGXView not initialized';
+                }
+                try {
+                    const data = new TextEncoder().encode(xmlText);
+                    playgroundState.pagxView.parsePAGX(data);
+                    playgroundState.pagxView.buildLayers();
+                    playgroundState.pagxView.draw();
+                    return '';
+                } catch (e) {
+                    return e instanceof Error ? e.message : String(e);
+                }
+            },
+            onSave: (xmlText: string): string => {
+                if (playgroundState.pagxView === null) {
+                    return 'PAGXView not initialized';
+                }
+                try {
+                    const data = new TextEncoder().encode(xmlText);
+                    playgroundState.pagxView.parsePAGX(data);
+                    playgroundState.pagxView.buildLayers();
+                    playgroundState.pagxView.draw();
+                    const blob = new Blob([xmlText], { type: 'application/xml' });
+                    const url = URL.createObjectURL(blob);
+                    const a = document.createElement('a');
+                    a.href = url;
+                    a.download = currentFileName.endsWith('.pagx') ? currentFileName : currentFileName + '.pagx';
+                    document.body.appendChild(a);
+                    a.click();
+                    document.body.removeChild(a);
+                    URL.revokeObjectURL(url);
+                    return '';
+                } catch (e) {
+                    return e instanceof Error ? e.message : String(e);
+                }
+            },
+        });
     };
 
     // Observe container resize. The C++ PAGXView::draw() now auto-detects
diff --git a/playground/pagx-playground/static/index.html b/playground/pagx-playground/static/index.html
index e40bb4b4a5..645fe43364 100644
--- a/playground/pagx-playground/static/index.html
+++ b/playground/pagx-playground/static/index.html
@@ -86,6 +86,23 @@
             </svg>
         </button>
     </div>
+    <div id="editor-panel">
+        <div class="editor-header">
+            <span class="editor-title">Source Editor</span>
+            <button class="editor-close-btn" title="Close (L)">
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" width="16" height="16">
+                    <line x1="18" y1="6" x2="6" y2="18"/>
+                    <line x1="6" y1="6" x2="18" y2="18"/>
+                </svg>
+            </button>
+        </div>
+        <div class="editor-host"></div>
+        <div class="editor-button-bar">
+            <button class="editor-btn discard" title="Discard">Discard</button>
+            <button class="editor-btn apply" title="Apply">Apply</button>
+            <button class="editor-btn save" title="Save">Save</button>
+        </div>
+    </div>
     <div id="drop-zone" class="drop-zone">
         <div class="brand">
             <img class="logo" src="./logo.png" alt="PAGX Logo"/>

From c22d8a95584e6aa885c0ceb5663086d4c70e4c09 Mon Sep 17 00:00:00 2001
From: ash <gracelllx@qq.com>
Date: Mon, 13 Jul 2026 20:01:11 +0800
Subject: [PATCH 02/10] mplement command mode and fix display bug caused by
 coordinate transformation error

---
 .../src/editor/SourceEditor.ts                | 27 +++++++++++--------
 .../pagx-playground/src/editor/styles.ts      | 25 +++++++++++++++++
 playground/pagx-viewer/src/cpp/PAGXView.cpp   |  4 +--
 3 files changed, 43 insertions(+), 13 deletions(-)

diff --git a/playground/pagx-playground/src/editor/SourceEditor.ts b/playground/pagx-playground/src/editor/SourceEditor.ts
index 97ccb16f62..d5e8452c0c 100644
--- a/playground/pagx-playground/src/editor/SourceEditor.ts
+++ b/playground/pagx-playground/src/editor/SourceEditor.ts
@@ -18,10 +18,11 @@
 
 import { EditorView, keymap } from '@codemirror/view';
 import { EditorState } from '@codemirror/state';
-import { basicSetup } from 'codemirror';
+import { minimalSetup } from 'codemirror';
+import { defaultKeymap, historyKeymap } from '@codemirror/commands';
 import { xml } from '@codemirror/lang-xml';
 import { syntaxHighlighting, HighlightStyle } from '@codemirror/language';
-import { searchKeymap, highlightSelectionMatches } from '@codemirror/search';
+import { highlightSelectionMatches } from '@codemirror/search';
 import { tags } from '@lezer/highlight';
 
 /** Syntax highlight colors matching the desktop client (VS Code Dark+ palette). */
@@ -39,7 +40,7 @@ const pagxHighlightStyle = HighlightStyle.define([
 
 /**
  * Wraps a CodeMirror 6 instance for editing PAGX XML source.
- * The editor is created lazily on first open to avoid impacting initial page load.
+ * Search relies on the browser's built-in Ctrl+F.
  */
 export class SourceEditor {
     private host: HTMLElement;
@@ -47,23 +48,23 @@ export class SourceEditor {
 
     constructor(host: HTMLElement) {
         this.host = host;
+        this.createView();
     }
 
-    /** Creates the CodeMirror view if it does not exist yet. */
-    private ensureView(): void {
-        if (this.view !== null) {
-            return;
-        }
+    private createView(): void {
         this.view = new EditorView({
             parent: this.host,
             state: EditorState.create({
                 doc: '',
                 extensions: [
-                    basicSetup,
+                    minimalSetup,
                     xml(),
                     syntaxHighlighting(pagxHighlightStyle),
                     highlightSelectionMatches(),
-                    keymap.of([...searchKeymap]),
+                    // basicSetup includes searchKeymap which intercepts Ctrl+F. Use minimalSetup
+                    // (which omits it) and add only the keymaps we need, so the browser's
+                    // built-in Ctrl+F is free to handle search.
+                    keymap.of([...defaultKeymap, ...historyKeymap]),
                     EditorView.theme({
                         '&': {
                             backgroundColor: '#1E1E1E',
@@ -105,7 +106,6 @@ export class SourceEditor {
 
     /** Replaces the entire document content. */
     setContent(text: string): void {
-        this.ensureView();
         if (this.view === null) {
             return;
         }
@@ -134,6 +134,11 @@ export class SourceEditor {
         }
     }
 
+    /** Returns the underlying CodeMirror view, or null if not yet created. */
+    getView(): EditorView | null {
+        return this.view;
+    }
+
     /** Releases the CodeMirror instance and frees DOM nodes. */
     destroy(): void {
         if (this.view !== null) {
diff --git a/playground/pagx-playground/src/editor/styles.ts b/playground/pagx-playground/src/editor/styles.ts
index 807ac27150..9d2d20855b 100644
--- a/playground/pagx-playground/src/editor/styles.ts
+++ b/playground/pagx-playground/src/editor/styles.ts
@@ -92,6 +92,11 @@ export const EDITOR_STYLES = `
     overflow: auto;
 }
 
+/* Fix white square at scrollbar corner */
+#editor-panel .editor-host .cm-scroller::-webkit-scrollbar-corner {
+    background: #1E1E1E;
+}
+
 #editor-panel .editor-host .cm-gutters {
     background: #1E1E1E;
     border-right: 1px solid #3C3C3C;
@@ -102,6 +107,26 @@ export const EDITOR_STYLES = `
     outline: none;
 }
 
+/* Selection highlight */
+#editor-panel .editor-host .cm-editor .cm-selectionBackground,
+#editor-panel .editor-host .cm-editor.cm-focused .cm-selectionBackground,
+#editor-panel .editor-host .cm-editor ::selection {
+    background-color: rgba(68, 142, 249, 0.35) !important;
+}
+
+#editor-panel .editor-host .cm-editor .cm-selectionLayer .cm-selectionBackground {
+    background-color: rgba(68, 142, 249, 0.35);
+}
+
+/* highlightSelectionMatches - subtle highlight for matching text under cursor */
+#editor-panel .editor-host .cm-editor .cm-selectionMatch {
+    background-color: rgba(234, 179, 8, 0.15);
+}
+
+#editor-panel .editor-host .cm-editor .cm-selectionMatch-selected {
+    background-color: rgba(68, 142, 249, 0.3);
+}
+
 .editor-toast {
     position: fixed;
     top: 16px;
diff --git a/playground/pagx-viewer/src/cpp/PAGXView.cpp b/playground/pagx-viewer/src/cpp/PAGXView.cpp
index 880e115552..75af3df58b 100644
--- a/playground/pagx-viewer/src/cpp/PAGXView.cpp
+++ b/playground/pagx-viewer/src/cpp/PAGXView.cpp
@@ -146,8 +146,8 @@ void PAGXView::buildLayers() {
   // TODO: Remove ResolveAllImagePatternMatrices() and ResolveAllGradientCoordinates() after the
   // pagx exporter adapts to relative coordinates for image and gradient fills. Currently we force
   // them to absolute coordinates to ensure correct rendering.
-  ResolveAllImagePatternMatrices(document.get());
-  ResolveAllGradientCoordinates(document.get());
+  // ResolveAllImagePatternMatrices(document.get());
+  // ResolveAllGradientCoordinates(document.get());
   document->applyLayout(&fontConfig);
   scene = PAGScene::Make(document);
   if (scene == nullptr) {

From 6268f50492e7688c381abeeb82eb6ca604834f57 Mon Sep 17 00:00:00 2001
From: ash <gracelllx@qq.com>
Date: Tue, 14 Jul 2026 10:45:11 +0800
Subject: [PATCH 03/10] Add simple XML detection and new icons

---
 .../pagx-playground/src/editor/index.ts       | 25 ++++++++++++++++++-
 playground/pagx-playground/src/index.ts       |  9 ++++++-
 playground/pagx-playground/static/index.html  |  6 +++++
 3 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/playground/pagx-playground/src/editor/index.ts b/playground/pagx-playground/src/editor/index.ts
index 51964bdf8b..1811bd6797 100644
--- a/playground/pagx-playground/src/editor/index.ts
+++ b/playground/pagx-playground/src/editor/index.ts
@@ -108,7 +108,7 @@ function closePanel(): void {
     }
 }
 
-function togglePanel(): void {
+export function togglePanel(): void {
     if (isPanelOpen()) {
         closePanel();
     } else {
@@ -158,6 +158,19 @@ function handlePagxLoaded(event: Event): void {
     }
 }
 
+/** Validates XML well-formedness using DOMParser. Returns empty string on success, error message on failure. */
+function validateXml(xmlText: string): string {
+    const parser = new DOMParser();
+    const doc = parser.parseFromString(xmlText, 'application/xml');
+    const parseError = doc.querySelector('parsererror');
+    if (parseError) {
+        const errorText = parseError.textContent || 'Invalid XML';
+        const firstLine = errorText.trim().split('\n')[0].trim();
+        return firstLine || 'Invalid XML format';
+    }
+    return '';
+}
+
 function handleDiscard(): void {
     if (editor === null) {
         return;
@@ -173,6 +186,11 @@ function handleApply(): void {
         return;
     }
     const xmlText = editor.getContent();
+    const validationError = validateXml(xmlText);
+    if (validationError !== '') {
+        showToast(validationError, false);
+        return;
+    }
     const error = callbacks.onApply(xmlText);
     showToast(error === '' ? 'Changes applied' : error, error === '');
 }
@@ -182,6 +200,11 @@ function handleSave(): void {
         return;
     }
     const xmlText = editor.getContent();
+    const validationError = validateXml(xmlText);
+    if (validationError !== '') {
+        showToast(validationError, false);
+        return;
+    }
     const error = callbacks.onSave(xmlText);
     showToast(error === '' ? 'File saved' : error, error === '');
 }
diff --git a/playground/pagx-playground/src/index.ts b/playground/pagx-playground/src/index.ts
index e6b02aa250..747a12a61a 100644
--- a/playground/pagx-playground/src/index.ts
+++ b/playground/pagx-playground/src/index.ts
@@ -18,7 +18,7 @@
 
 import { PAGXInit } from '../wasm-mt/pagx-viewer.esm';
 import type { PAGXView, PAGXModule } from '../../pagx-viewer/src/ts/pagx';
-import { init as initEditor } from './editor';
+import { init as initEditor, togglePanel as toggleEditorPanel } from './editor';
 
 interface I18nStrings {
     dropText: string;
@@ -1330,6 +1330,13 @@ if (typeof window !== 'undefined') {
                 }
             },
         });
+
+        const sourceEditorBtn = document.getElementById('source-editor-btn');
+        if (sourceEditorBtn) {
+            sourceEditorBtn.addEventListener('click', () => {
+                toggleEditorPanel();
+            });
+        }
     };
 
     // Observe container resize. The C++ PAGXView::draw() now auto-detects
diff --git a/playground/pagx-playground/static/index.html b/playground/pagx-playground/static/index.html
index 645fe43364..80843be9b6 100644
--- a/playground/pagx-playground/static/index.html
+++ b/playground/pagx-playground/static/index.html
@@ -77,6 +77,12 @@
                 <path d="M3 3v5h5"/>
             </svg>
         </button>
+        <button id="source-editor-btn" class="toolbar-btn" title="Source Editor (L)">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <polyline points="16 18 22 12 16 6"/>
+                <polyline points="8 6 2 12 8 18"/>
+            </svg>
+        </button>
         <span class="toolbar-divider"></span>
         <button id="leave-btn" class="toolbar-btn" title="Leave">
             <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">

From 938f5306e3db5103d8e61cfbdde7594264accec4 Mon Sep 17 00:00:00 2001
From: ash <gracelllx@qq.com>
Date: Wed, 15 Jul 2026 12:07:47 +0800
Subject: [PATCH 04/10] Add web single-thread compilation and improve undo
 functionality

---
 playground/pagx-playground/package.json       |   3 +
 .../pagx-playground/scripts/prebuild.js       | 156 +++++++-----------
 playground/pagx-playground/scripts/publish.js |   2 +-
 playground/pagx-playground/scripts/rollup.js  |  20 ++-
 .../src/editor/SourceEditor.ts                |  16 +-
 .../pagx-playground/src/editor/index.ts       |   7 +-
 .../pagx-playground/src/editor/styles.ts      |   2 +-
 playground/pagx-playground/src/index.ts       |  12 +-
 playground/pagx-playground/static/server.js   |  49 ++++--
 9 files changed, 148 insertions(+), 119 deletions(-)

diff --git a/playground/pagx-playground/package.json b/playground/pagx-playground/package.json
index ce69992285..128b2f8f50 100644
--- a/playground/pagx-playground/package.json
+++ b/playground/pagx-playground/package.json
@@ -10,6 +10,9 @@
     "prebuild": "node scripts/prebuild.js",
     "build": "npm run prebuild && rollup -c ./scripts/rollup.js",
     "build:release": "node scripts/prebuild.js --release && BUILD_MODE=release rollup -c ./scripts/rollup.js",
+    "prebuild:st": "node scripts/prebuild.js --arch st",
+    "build:st": "npm run prebuild:st && ARCH=wasm rollup -c ./scripts/rollup.js",
+    "build:release:st": "node scripts/prebuild.js --arch st --release && ARCH=wasm BUILD_MODE=release rollup -c ./scripts/rollup.js",
     "publish": "node scripts/publish.js",
     "server": "node static/server.js"
   },
diff --git a/playground/pagx-playground/scripts/prebuild.js b/playground/pagx-playground/scripts/prebuild.js
index 59dabe0ae5..507e589424 100644
--- a/playground/pagx-playground/scripts/prebuild.js
+++ b/playground/pagx-playground/scripts/prebuild.js
@@ -20,16 +20,20 @@
 /**
  * Prebuild script for pagx-playground.
  *
- * This script ensures pagx-viewer is built and copies the wasm files to wasm-mt/
- * before the main rollup build starts.
+ * This script copies the pre-built pagx-viewer wasm/glue files to wasm-mt/
+ * before the main rollup build starts. It does NOT build pagx-viewer itself;
+ * if the required artifacts are missing, the user must build them first in
+ * the pagx-viewer directory.
  *
  * Usage:
- *   node scripts/prebuild.js [--release]
+ *   node scripts/prebuild.js                  # multi-threaded (default), debug
+ *   node scripts/prebuild.js --arch st        # single-threaded, debug
+ *   node scripts/prebuild.js --release        # multi-threaded, release
+ *   node scripts/prebuild.js --arch st --release  single-threaded, release
  */
 
 import fs from 'fs';
 import path from 'path';
-import { execSync } from 'child_process';
 import { fileURLToPath } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -38,88 +42,41 @@ const __dirname = path.dirname(__filename);
 const PLAYGROUND_DIR = path.dirname(__dirname);
 const PAGX_VIEWER_DIR = path.resolve(PLAYGROUND_DIR, '../pagx-viewer');
 const PAGX_VIEWER_LIB_DIR = path.join(PAGX_VIEWER_DIR, 'lib');
-const WASM_MT_DIR = path.join(PLAYGROUND_DIR, 'wasm-mt');
+const OUTPUT_DIR = path.join(PLAYGROUND_DIR, 'wasm-mt');
 
-const REQUIRED_FILES = ['pagx-viewer.wasm', 'pagx-viewer.esm.js'];
-
-// Source directories/files that should invalidate the build when newer than the artifacts.
-const SOURCE_PATHS = [
-  path.join(PAGX_VIEWER_DIR, 'src'),
-  path.join(PAGX_VIEWER_DIR, 'CMakeLists.txt'),
-  path.join(PAGX_VIEWER_DIR, 'package.json'),
-];
-
-const isRelease = process.argv.includes('--release');
-
-/**
- * Returns the most recent modification time (in ms) among the given files/directories.
- * Directories are walked recursively. Missing paths are skipped.
- */
-function latestMtimeMs(targetPath) {
-  let latest = 0;
-  const stack = [targetPath];
-  while (stack.length > 0) {
-    const current = stack.pop();
-    let stat;
-    try {
-      stat = fs.statSync(current);
-    } catch {
-      continue;
-    }
-    if (stat.isDirectory()) {
-      for (const entry of fs.readdirSync(current)) {
-        stack.push(path.join(current, entry));
-      }
-    } else if (stat.mtimeMs > latest) {
-      latest = stat.mtimeMs;
-    }
-  }
-  return latest;
+// Parse CLI arguments: --arch <mt|st> selects the wasm flavor (default: auto-detect).
+const CLI_ARGS = process.argv.slice(2);
+function getArgValue(name) {
+  const index = CLI_ARGS.indexOf(name);
+  return index !== -1 ? CLI_ARGS[index + 1] : null;
 }
-
-/**
- * Check if pagx-viewer artifacts exist and are newer than the sources.
- */
-function isPagxViewerBuilt() {
-  let oldestArtifactMs = Number.POSITIVE_INFINITY;
-  for (const file of REQUIRED_FILES) {
-    const filePath = path.join(PAGX_VIEWER_LIB_DIR, file);
-    if (!fs.existsSync(filePath)) {
-      return false;
-    }
-    const artifactMs = fs.statSync(filePath).mtimeMs;
-    if (artifactMs < oldestArtifactMs) {
-      oldestArtifactMs = artifactMs;
-    }
-  }
-  let latestSourceMs = 0;
-  for (const sourcePath of SOURCE_PATHS) {
-    const ms = latestMtimeMs(sourcePath);
-    if (ms > latestSourceMs) {
-      latestSourceMs = ms;
-    }
-  }
-  return latestSourceMs <= oldestArtifactMs;
+const archArg = getArgValue('--arch');
+const isRelease = CLI_ARGS.includes('--release');
+
+// Auto-detect which arch artifacts exist in pagx-viewer/lib/.
+// If neither exists, fall back to the default (multi-threaded) and let
+// copyWasmFiles() report the error with helpful instructions.
+function detectArch() {
+  const mtExists = fs.existsSync(path.join(PAGX_VIEWER_LIB_DIR, 'pagx-viewer.wasm'));
+  const stExists = fs.existsSync(path.join(PAGX_VIEWER_LIB_DIR, 'pagx-viewer.st.wasm'));
+  if (archArg === 'st') return true;
+  if (archArg === 'mt') return false;
+  // No explicit --arch: prefer whichever exists. If both exist, pick multi-threaded.
+  if (stExists && !mtExists) return true;
+  return false;
 }
 
-/**
- * Build pagx-viewer.
- */
-function buildPagxViewer() {
-  const buildCmd = isRelease ? 'npm run build:release' : 'npm run build';
-  console.log(`Building pagx-viewer (${isRelease ? 'release' : 'debug'})...`);
-  console.log(`  Running: ${buildCmd}`);
-  try {
-    execSync(buildCmd, {
-      cwd: PAGX_VIEWER_DIR,
-      stdio: 'inherit',
-    });
-    console.log('  pagx-viewer built successfully.\n');
-  } catch (error) {
-    console.error('Failed to build pagx-viewer:', error.message);
-    process.exit(1);
-  }
-}
+const isSingleThreaded = detectArch();
+
+// The single-threaded variant adds a `.st` infix so its glue/wasm don't collide
+// with the multi-threaded ones.
+const artifactInfix = isSingleThreaded ? '.st' : '';
+const REQUIRED_FILES = [`pagx-viewer${artifactInfix}.wasm`, `pagx-viewer${artifactInfix}.esm.js`];
+// When switching arch, remove the opposite-arch artifacts from the output dir
+// so a stale wasm/glue of the wrong flavor can't linger.
+const STALE_NAMES = isSingleThreaded
+  ? ['pagx-viewer.wasm', 'pagx-viewer.esm.js']
+  : ['pagx-viewer.st.wasm', 'pagx-viewer.st.esm.js'];
 
 /**
  * Copy wasm files to wasm-mt/.
@@ -127,18 +84,35 @@ function buildPagxViewer() {
 function copyWasmFiles() {
   console.log('Copying wasm files to wasm-mt/...');
 
-  if (!fs.existsSync(WASM_MT_DIR)) {
-    fs.mkdirSync(WASM_MT_DIR, { recursive: true });
+  if (!fs.existsSync(OUTPUT_DIR)) {
+    fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+  }
+
+  // Remove artifacts from the opposite arch before copying.
+  for (const stale of STALE_NAMES) {
+    const stalePath = path.join(OUTPUT_DIR, stale);
+    if (fs.existsSync(stalePath)) {
+      fs.unlinkSync(stalePath);
+      console.log(`  Removed stale: ${stale}`);
+    }
   }
 
   for (const file of REQUIRED_FILES) {
     const src = path.join(PAGX_VIEWER_LIB_DIR, file);
-    const dest = path.join(WASM_MT_DIR, file);
+    const dest = path.join(OUTPUT_DIR, file);
     if (fs.existsSync(src)) {
       fs.copyFileSync(src, dest);
       console.log(`  Copied: ${file}`);
     } else {
-      console.error(`  ERROR: Source file not found: ${src}`);
+      console.error(`\nERROR: Required artifact not found: ${src}`);
+      console.error('Please build pagx-viewer first:');
+      let buildCmd;
+      if (isSingleThreaded) {
+        buildCmd = isRelease ? 'npm run build:release:st' : 'npm run build:debug:st';
+      } else {
+        buildCmd = isRelease ? 'npm run build:release' : 'npm run build:debug';
+      }
+      console.error(`  cd ${PAGX_VIEWER_DIR} && ${buildCmd}\n`);
       process.exit(1);
     }
   }
@@ -147,14 +121,8 @@ function copyWasmFiles() {
 }
 
 function main() {
-  console.log('Prebuild: Preparing pagx-viewer wasm files...\n');
-
-  if (!isPagxViewerBuilt()) {
-    console.log('pagx-viewer not built or out of date, building now...\n');
-    buildPagxViewer();
-  } else {
-    console.log('pagx-viewer already built and up to date.\n');
-  }
+  const archLabel = isSingleThreaded ? 'single-threaded' : 'multi-threaded';
+  console.log(`Prebuild: Preparing pagx-viewer (${archLabel}) wasm files...\n`);
 
   copyWasmFiles();
 
diff --git a/playground/pagx-playground/scripts/publish.js b/playground/pagx-playground/scripts/publish.js
index d8070c9b5c..e95ab5b86f 100644
--- a/playground/pagx-playground/scripts/publish.js
+++ b/playground/pagx-playground/scripts/publish.js
@@ -18,8 +18,8 @@
  * Output structure:
  *     <output>/index.html
  *     <output>/index.css
- *     <output>/fonts/
  *     <output>/wasm-mt/
+ *     <output>/fonts/
  *     <output>/samples/           (.pagx files, images, and generated index.json)
  *     <output>/skills/<name>/     (static skill files for online browsing)
  *     <output>/skills/<name>.zip  (skill archive for AI tool downloads)
diff --git a/playground/pagx-playground/scripts/rollup.js b/playground/pagx-playground/scripts/rollup.js
index 9ba772f51a..4a75005896 100644
--- a/playground/pagx-playground/scripts/rollup.js
+++ b/playground/pagx-playground/scripts/rollup.js
@@ -37,6 +37,21 @@ const fileHeaderPath = path.resolve(libpagRoot, '.idea/fileTemplates/includes/PA
 const banner = existsSync(fileHeaderPath) ? readFileSync(fileHeaderPath, 'utf-8') : '';
 const isRelease = process.env.BUILD_MODE === 'release';
 
+// Detect the pagx-viewer arch by checking which glue file was copied into wasm-mt/.
+// This must stay in sync with prebuild.js's auto-detection logic.
+function detectGlueInfix() {
+  if (process.env.ARCH === 'wasm') return '.st';
+  if (process.env.ARCH === 'mt') return '';
+  // No explicit ARCH env: check which .esm.js actually exists.
+  if (!existsSync(path.join(playgroundRoot, 'wasm-mt/pagx-viewer.esm.js'))
+      && existsSync(path.join(playgroundRoot, 'wasm-mt/pagx-viewer.st.esm.js'))) {
+    return '.st';
+  }
+  return '';  // default to multi-threaded
+}
+const glueInfix = detectGlueInfix();
+const glueTarget = path.resolve(playgroundRoot, `wasm-mt/pagx-viewer${glueInfix}.esm.js`);
+
 // Clean up old source map files in release mode
 if (isRelease) {
     const outputDir = path.resolve(playgroundRoot, 'wasm-mt');
@@ -53,13 +68,16 @@ if (isRelease) {
 }
 
 const plugins = [
-    esbuild({tsconfig: path.resolve(__dirname, "../src/tsconfig.json"), minify: isRelease}),
+    esbuild({tsconfig: path.resolve(__dirname, "../src/tsconfig.json"), minify: isRelease, define: { __PAGX_INFIX__: JSON.stringify(glueInfix) }}),
     json(),
     resolve({ extensions: ['.ts', '.js'] }),
     commonJs(),
     alias({
         entries: [
             { find: '@tgfx', replacement: path.resolve(libpagRoot, 'third_party/tgfx/web/src') },
+            // Map the virtual `pagx-viewer-glue` import in src/index.ts to the selected
+            // arch's pagx-viewer ES module (single-threaded adds a `.st` infix).
+            { find: 'pagx-viewer-glue', replacement: glueTarget },
         ],
     }),
     {
diff --git a/playground/pagx-playground/src/editor/SourceEditor.ts b/playground/pagx-playground/src/editor/SourceEditor.ts
index d5e8452c0c..64c89925ac 100644
--- a/playground/pagx-playground/src/editor/SourceEditor.ts
+++ b/playground/pagx-playground/src/editor/SourceEditor.ts
@@ -16,7 +16,7 @@
 //
 /////////////////////////////////////////////////////////////////////////////////////////////////
 
-import { EditorView, keymap } from '@codemirror/view';
+import { EditorView, keymap, lineNumbers } from '@codemirror/view';
 import { EditorState } from '@codemirror/state';
 import { minimalSetup } from 'codemirror';
 import { defaultKeymap, historyKeymap } from '@codemirror/commands';
@@ -43,21 +43,24 @@ const pagxHighlightStyle = HighlightStyle.define([
  * Search relies on the browser's built-in Ctrl+F.
  */
 export class SourceEditor {
-    private host: HTMLElement;
+    private readonly host: HTMLElement;
     private view: EditorView | null = null;
 
     constructor(host: HTMLElement) {
         this.host = host;
-        this.createView();
+        // Defer EditorView creation to the first setContent call so that the initial
+        // document is the loaded XML content (not an empty doc). This prevents
+        // Ctrl+Z from unwinding past the load point into an empty editor.
     }
 
-    private createView(): void {
+    private createView(initialContent: string): void {
         this.view = new EditorView({
             parent: this.host,
             state: EditorState.create({
-                doc: '',
+                doc: initialContent,
                 extensions: [
                     minimalSetup,
+                    lineNumbers(),
                     xml(),
                     syntaxHighlighting(pagxHighlightStyle),
                     highlightSelectionMatches(),
@@ -106,10 +109,11 @@ export class SourceEditor {
 
     /** Replaces the entire document content. */
     setContent(text: string): void {
+        const trimmed = text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text;
         if (this.view === null) {
+            this.createView(trimmed);
             return;
         }
-        const trimmed = text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text;
         this.view.dispatch({
             changes: {
                 from: 0,
diff --git a/playground/pagx-playground/src/editor/index.ts b/playground/pagx-playground/src/editor/index.ts
index 1811bd6797..372ad0fafe 100644
--- a/playground/pagx-playground/src/editor/index.ts
+++ b/playground/pagx-playground/src/editor/index.ts
@@ -145,12 +145,15 @@ function handlePagxLoaded(event: Event): void {
     const detail = (event as CustomEvent<PagxLoadedDetail>).detail;
     currentXmlText = detail ? detail.xmlText : null;
     if (currentXmlText === null) {
-        // File cleared (goHome) - close panel and clear editor content.
+        // File cleared (goHome) - close panel and destroy the editor instance so that
+        // the next file load creates a fresh view with clean undo history rooted at the
+        // new content (instead of an empty doc reachable via Ctrl+Z).
         if (isPanelOpen()) {
             closePanel();
         }
         if (editor !== null) {
-            editor.setContent('');
+            editor.destroy();
+            editor = null;
         }
     } else if (isPanelOpen() && editor !== null) {
         // Panel already open and a new file loaded - refresh content.
diff --git a/playground/pagx-playground/src/editor/styles.ts b/playground/pagx-playground/src/editor/styles.ts
index 9d2d20855b..85e2cb21e4 100644
--- a/playground/pagx-playground/src/editor/styles.ts
+++ b/playground/pagx-playground/src/editor/styles.ts
@@ -10,7 +10,7 @@
 //      http://www.apache.org/licenses/LICENSE-2.0
 //
 //  unless required by applicable law or agreed to in writing, software distributed under the
-//  license is distributed on an "as IS" basis, without warranties or conditions of any kind,
+//  license is distributed on an "as is" basis, without warranties or conditions of any kind,
 //  either express or implied. see the license for the specific language governing permissions
 //  and limitations under the license.
 //
diff --git a/playground/pagx-playground/src/index.ts b/playground/pagx-playground/src/index.ts
index 747a12a61a..c1a94db80c 100644
--- a/playground/pagx-playground/src/index.ts
+++ b/playground/pagx-playground/src/index.ts
@@ -16,7 +16,9 @@
 //
 /////////////////////////////////////////////////////////////////////////////////////////////////
 
-import { PAGXInit } from '../wasm-mt/pagx-viewer.esm';
+// Resolved to the selected arch's pagx-viewer glue at build time via the
+// `pagx-viewer-glue` alias in scripts/rollup.js (single-threaded adds a `.st` infix).
+import { PAGXInit } from 'pagx-viewer-glue';
 import type { PAGXView, PAGXModule } from '../../pagx-viewer/src/ts/pagx';
 import { init as initEditor, togglePanel as toggleEditorPanel } from './editor';
 
@@ -116,7 +118,13 @@ const MAX_ZOOM = 1000.0;
 // Font URLs for preloading
 const FONT_URL = './fonts/NotoSansSC-Regular.otf';
 const EMOJI_FONT_URL = './fonts/NotoColorEmoji.ttf';
-const WASM_URL = './wasm-mt/pagx-viewer.wasm';
+
+// __PAGX_INFIX__ is injected at build time by scripts/rollup.js: empty for the
+// multi-threaded build, ".st" for the single-threaded build. The matching wasm is
+// placed at wasm-mt/ by scripts/prebuild.js.
+declare const __PAGX_INFIX__: string;
+const WASM_INFIX = __PAGX_INFIX__;
+const WASM_URL = `./wasm-mt/pagx-viewer${WASM_INFIX}.wasm`;
 
 // Estimated sizes for progress calculation (in bytes)
 const ESTIMATED_WASM_SIZE = 2400000;
diff --git a/playground/pagx-playground/static/server.js b/playground/pagx-playground/static/server.js
index 1ae1a74f74..45785dc06a 100644
--- a/playground/pagx-playground/static/server.js
+++ b/playground/pagx-playground/static/server.js
@@ -19,6 +19,7 @@
 import express from 'express';
 import path from 'path';
 import fs from 'fs';
+import os from 'os';
 import { execFile } from 'child_process';
 import { fileURLToPath } from 'url';
 
@@ -27,14 +28,22 @@ const __dirname = path.dirname(__filename);
 const playgroundDir = path.resolve(__dirname, '..');
 const libpagDir = path.resolve(__dirname, '../../..');
 
+// Detect whether the current build is single-threaded or multi-threaded by checking
+// which pagx-viewer artifact exists. Multi-threaded builds require COOP/COEP headers
+// for SharedArrayBuffer support; single-threaded builds do not.
+const isSingleThreaded = fs.existsSync(path.join(playgroundDir, 'wasm-mt/pagx-viewer.st.wasm')) &&
+                         !fs.existsSync(path.join(playgroundDir, 'wasm-mt/pagx-viewer.wasm'));
+
 const app = express();
 
-// Enable SharedArrayBuffer (required for multi-threaded builds)
-app.use((req, res, next) => {
-  res.set('Cross-Origin-Opener-Policy', 'same-origin');
-  res.set('Cross-Origin-Embedder-Policy', 'require-corp');
-  next();
-});
+// Only enable COOP/COEP for multi-threaded (SharedArrayBuffer) builds
+if (!isSingleThreaded) {
+  app.use((req, res, next) => {
+    res.set('Cross-Origin-Opener-Policy', 'same-origin');
+    res.set('Cross-Origin-Embedder-Policy', 'require-corp');
+    next();
+  });
+}
 
 app.use('', express.static(playgroundDir, {
   setHeaders: (res, filePath) => {
@@ -72,16 +81,32 @@ app.get('/', (req, res) => {
 });
 
 const port = 8080;
-app.listen(port, () => {
-  const url = `http://localhost:${port}/`;
+
+/** Returns the first non-internal IPv4 address for LAN sharing, or 'localhost' if none. */
+function getLanIp() {
+  const interfaces = os.networkInterfaces();
+  for (const name of Object.keys(interfaces)) {
+    for (const net of interfaces[name] ?? []) {
+      if (net.family === 'IPv4' && !net.internal) {
+        return net.address;
+      }
+    }
+  }
+  return 'localhost';
+}
+
+app.listen(port, '0.0.0.0', () => {
+  const localUrl = `http://localhost:${port}/`;
+  const lanUrl = `http://${getLanIp()}:${port}/`;
   if (process.platform === 'darwin') {
-    execFile('open', [url]);
+    execFile('open', [localUrl]);
   } else if (process.platform === 'win32') {
     // `start` is a cmd.exe builtin, not a standalone executable; invoke via cmd /c.
     // The empty string after `start` is the window title placeholder.
-    execFile('cmd', ['/c', 'start', '', url]);
+    execFile('cmd', ['/c', 'start', '', localUrl]);
   } else {
-    execFile('xdg-open', [url]);
+    execFile('xdg-open', [localUrl]);
   }
-  console.log(`PAGX Playground running at ${url}`);
+  console.log(`PAGX Playground running at ${localUrl}`);
+  console.log(`LAN access: ${lanUrl}`);
 });

From 2cc0d4324ecd7028c391ce3cd0a15748addf1332 Mon Sep 17 00:00:00 2001
From: ash <gracelllx@qq.com>
Date: Wed, 15 Jul 2026 19:47:37 +0800
Subject: [PATCH 05/10] Add player feature (with known bugs)

---
 playground/pagx-playground/README.md          |  68 ++--
 playground/pagx-playground/README.zh_CN.md    |  63 ++--
 playground/pagx-playground/scripts/publish.js |   2 +-
 playground/pagx-playground/src/index.ts       | 308 +++++++++++++++---
 playground/pagx-playground/static/index.css   | 175 ++++++++++
 playground/pagx-playground/static/index.html  |  21 +-
 playground/pagx-playground/static/next.png    |   3 +
 playground/pagx-playground/static/pause.png   |   3 +
 playground/pagx-playground/static/play.png    |   3 +
 .../pagx-playground/static/previous.png       |   3 +
 playground/pagx-playground/static/server.js   |  14 +-
 playground/pagx-viewer/src/cpp/PAGXView.cpp   |  78 +++++
 playground/pagx-viewer/src/cpp/PAGXView.h     |  11 +
 playground/pagx-viewer/src/cpp/binding.cpp    |  24 +-
 playground/pagx-viewer/src/ts/pagx-view.ts    |  69 ++++
 playground/pagx-viewer/src/ts/types.ts        |  46 +++
 16 files changed, 806 insertions(+), 85 deletions(-)
 create mode 100755 playground/pagx-playground/static/next.png
 create mode 100644 playground/pagx-playground/static/pause.png
 create mode 100755 playground/pagx-playground/static/play.png
 create mode 100755 playground/pagx-playground/static/previous.png

diff --git a/playground/pagx-playground/README.md b/playground/pagx-playground/README.md
index 2293dbef84..1f53f7cd66 100644
--- a/playground/pagx-playground/README.md
+++ b/playground/pagx-playground/README.md
@@ -39,6 +39,25 @@ pagx-playground/
 First, ensure you have installed all the tools and dependencies listed in the
 [README.md](../../README.md#Development) in the project root, including Emscripten.
 
+> Important: The playground does not compile any WebAssembly itself. It consumes the compiled
+> WASM artifacts from [pagx-viewer](../pagx-viewer). You must build pagx-viewer first, and the
+> multi-threaded (MT) / single-threaded (ST) choice is made there, not here. Read the
+> [pagx-viewer README](../pagx-viewer/README.md) before building the playground.
+
+### Build pagx-viewer First
+
+The MT and ST WASM builds are produced in pagx-viewer, not in the playground. Pick the flavor
+you need there:
+
+```bash
+# In playground/pagx-viewer
+npm install
+npm run build:release       # multi-threaded (default, requires SharedArrayBuffer)
+npm run build:release:st    # single-threaded (no SharedArrayBuffer required)
+```
+
+See the [pagx-viewer README](../pagx-viewer/README.md) for the full build matrix.
+
 ### Install Dependencies
 
 ```bash
@@ -48,31 +67,53 @@ npm install
 
 ### Build
 
+Build the playground against the viewer artifacts. Use the plain commands to bundle against the
+multi-threaded viewer build, or the `:st` variants for the single-threaded one:
+
 ```bash
-# Build the TypeScript source
+# Bundle against the multi-threaded viewer artifacts (default)
 npm run build
-
-# Build release version (minified)
 npm run build:release
 
+# Bundle against the single-threaded viewer artifacts
+npm run build:st
+npm run build:release:st
+
 # Clean build artifacts
 npm run clean
 ```
 
+The `:st` variants only tell the playground bundler to pick up the single-threaded viewer
+artifacts; the actual MT/ST WASM compilation happens in pagx-viewer. Multi-threaded builds rely
+on `SharedArrayBuffer`, which requires the `Cross-Origin-Opener-Policy` and
+`Cross-Origin-Embedder-Policy` headers. The development server detects the build type
+automatically and only sends these headers for multi-threaded builds, so no manual configuration
+is needed when switching between the two.
+
 ## Development
 
 ### Run Development Server
 
-Start a local development server with hot reload:
+Start a local development server:
 
 ```bash
 npm run server
 ```
 
-The server will automatically open http://localhost:8081 in your browser.
+The server automatically opens the playground in your default browser and applies the correct
+COOP/COEP headers based on the detected build type (see [Build](#build)).
+
+### LAN Sharing
 
-> Note: The development server requires SharedArrayBuffer for WASM threading.
-> If you encounter issues, ensure your browser supports the required COOP/COEP headers.
+By default the server binds to `localhost` only. To share it with other devices on the same
+network (e.g. testing on a phone), enable LAN binding with the `PAGX_LAN` environment variable:
+
+```bash
+PAGX_LAN=1 npm run server
+```
+
+The console then prints a `LAN access` URL. Only enable this on trusted networks, as it exposes
+the local file server to any device on the LAN.
 
 ## Publish
 
@@ -101,19 +142,6 @@ npm run publish -- -o /path/to/output
 npm run publish -- --skip-build
 ```
 
-## Use with PAGX Viewer
-
-The playground consumes the compiled artifacts from [pagx-viewer](../pagx-viewer).
-Make sure to build the pagx-viewer first before building the playground:
-
-```bash
-# In playground/pagx-viewer
-npm run build:release
-
-# Then in playground/pagx-playground
-npm run build:release
-```
-
 ## Browser Requirements
 
 - Chrome 69+
diff --git a/playground/pagx-playground/README.zh_CN.md b/playground/pagx-playground/README.zh_CN.md
index b38721f6f4..b7de783990 100644
--- a/playground/pagx-playground/README.zh_CN.md
+++ b/playground/pagx-playground/README.zh_CN.md
@@ -38,6 +38,23 @@ pagx-playground/
 首先，请确保已安装项目根目录 [README.md](../../README.md#Development) 中列出的所有工具和依赖，
 包括 Emscripten。
 
+> 重要：Playground 本身不编译任何 WebAssembly，它直接使用 [pagx-viewer](../pagx-viewer) 编译出的
+> WASM 产物。你必须先构建 pagx-viewer，并且多线程（MT）/ 单线程（ST）的选择是在 pagx-viewer 中完成的，
+> 而不是在这里。构建 playground 前请先阅读 [pagx-viewer README](../pagx-viewer/README.zh_CN.md)。
+
+### 先构建 pagx-viewer
+
+MT 和 ST 的 WASM 构建都是在 pagx-viewer 中进行的，而非 playground。请在那里选择所需的版本：
+
+```bash
+# 在 playground/pagx-viewer 中
+npm install
+npm run build:release       # 多线程（默认，需要 SharedArrayBuffer）
+npm run build:release:st    # 单线程（无需 SharedArrayBuffer）
+```
+
+完整的构建命令矩阵参见 [pagx-viewer README](../pagx-viewer/README.zh_CN.md)。
+
 ### 安装依赖
 
 ```bash
@@ -47,31 +64,50 @@ npm install
 
 ### 构建
 
+Playground 基于 viewer 的产物进行打包。使用普通命令对应多线程 viewer 构建，使用 `:st` 变体对应单线程构建：
+
 ```bash
-# 构建 TypeScript 源码
+# 对应多线程 viewer 产物（默认）
 npm run build
-
-# 构建 Release 版本（压缩）
 npm run build:release
 
+# 对应单线程 viewer 产物
+npm run build:st
+npm run build:release:st
+
 # 清理构建产物
 npm run clean
 ```
 
+`:st` 变体只是告诉 playground 打包器选用单线程 viewer 产物；真正的 MT/ST WASM 编译发生在
+pagx-viewer 中。多线程构建依赖 `SharedArrayBuffer`，需要 `Cross-Origin-Opener-Policy` 和
+`Cross-Origin-Embedder-Policy` 头。开发服务器会自动检测构建类型，仅在多线程构建时发送这些头，
+因此在两种构建之间切换时无需手动配置。
+
 ## 开发
 
 ### 启动开发服务器
 
-启动本地开发服务器，支持热更新：
+启动本地开发服务器：
 
 ```bash
 npm run server
 ```
 
-服务器将自动在浏览器中打开 http://localhost:8081。
+服务器会自动在默认浏览器中打开 playground，并根据检测到的构建类型应用对应的 COOP/COEP 头
+（参见[构建](#构建)）。
+
+### 局域网分享
 
-> 注意：开发服务器需要 SharedArrayBuffer 来支持 WASM 多线程。
-> 如果遇到问题，请确保浏览器支持所需的 COOP/COEP 头。
+默认情况下服务器仅绑定 `localhost`。如需与同一网络下的其他设备共享（例如在手机上测试），
+可通过 `PAGX_LAN` 环境变量启用局域网绑定：
+
+```bash
+PAGX_LAN=1 npm run server
+```
+
+启用后控制台会打印 `LAN access` 地址。请仅在可信网络中启用，因为它会将本地文件服务器
+暴露给局域网内的任意设备。
 
 ## 发布
 
@@ -99,19 +135,6 @@ npm run publish -- -o /path/to/output
 npm run publish -- --skip-build
 ```
 
-## 与 PAGX Viewer 配合使用
-
-Playground 依赖 [pagx-viewer](../pagx-viewer) 的构建产物。
-构建 playground 前请先构建 pagx-viewer：
-
-```bash
-# 在 playground/pagx-viewer 中
-npm run build:release
-
-# 然后在 playground/pagx-playground 中
-npm run build:release
-```
-
 ## 浏览器要求
 
 - Chrome 69+
diff --git a/playground/pagx-playground/scripts/publish.js b/playground/pagx-playground/scripts/publish.js
index e95ab5b86f..d8070c9b5c 100644
--- a/playground/pagx-playground/scripts/publish.js
+++ b/playground/pagx-playground/scripts/publish.js
@@ -18,8 +18,8 @@
  * Output structure:
  *     <output>/index.html
  *     <output>/index.css
- *     <output>/wasm-mt/
  *     <output>/fonts/
+ *     <output>/wasm-mt/
  *     <output>/samples/           (.pagx files, images, and generated index.json)
  *     <output>/skills/<name>/     (static skill files for online browsing)
  *     <output>/skills/<name>.zip  (skill archive for AI tool downloads)
diff --git a/playground/pagx-playground/src/index.ts b/playground/pagx-playground/src/index.ts
index c1a94db80c..dbd718e4b9 100644
--- a/playground/pagx-playground/src/index.ts
+++ b/playground/pagx-playground/src/index.ts
@@ -123,8 +123,7 @@ const EMOJI_FONT_URL = './fonts/NotoColorEmoji.ttf';
 // multi-threaded build, ".st" for the single-threaded build. The matching wasm is
 // placed at wasm-mt/ by scripts/prebuild.js.
 declare const __PAGX_INFIX__: string;
-const WASM_INFIX = __PAGX_INFIX__;
-const WASM_URL = `./wasm-mt/pagx-viewer${WASM_INFIX}.wasm`;
+const WASM_URL = `./wasm-mt/pagx-viewer${__PAGX_INFIX__}.wasm`;
 
 // Estimated sizes for progress calculation (in bytes)
 const ESTIMATED_WASM_SIZE = 2400000;
@@ -708,6 +707,12 @@ function bindCanvasEvents(canvas: HTMLElement) {
     // Set initial cursor style
     canvas.style.cursor = 'grab';
 
+    // A press whose pointer barely moves is treated as a click that toggles playback,
+    // while a larger movement is a pan gesture handled by the gesture manager.
+    const CLICK_MOVE_THRESHOLD = 5;
+    let pressStartX = 0;
+    let pressStartY = 0;
+
     // Wheel events for scroll and zoom
     canvas.addEventListener('wheel', (e: WheelEvent) => {
         e.preventDefault();
@@ -717,13 +722,20 @@ function bindCanvasEvents(canvas: HTMLElement) {
     // Mouse drag events
     canvas.addEventListener('mousedown', (e: MouseEvent) => {
         e.preventDefault();
+        pressStartX = e.clientX;
+        pressStartY = e.clientY;
         gestureManager.onMouseDown(e, canvas);
     });
     canvas.addEventListener('mousemove', (e: MouseEvent) => {
         gestureManager.onMouseMove(e, playgroundState);
     });
-    canvas.addEventListener('mouseup', () => {
+    canvas.addEventListener('mouseup', (e: MouseEvent) => {
         gestureManager.onMouseUp(canvas);
+        if (e.button === 0 &&
+            Math.abs(e.clientX - pressStartX) < CLICK_MOVE_THRESHOLD &&
+            Math.abs(e.clientY - pressStartY) < CLICK_MOVE_THRESHOLD) {
+            togglePlayback();
+        }
     });
     canvas.addEventListener('mouseleave', () => {
         gestureManager.onMouseUp(canvas);
@@ -732,6 +744,10 @@ function bindCanvasEvents(canvas: HTMLElement) {
     // Touch events for mobile
     canvas.addEventListener('touchstart', (e: TouchEvent) => {
         e.preventDefault();
+        if (e.touches.length === 1) {
+            pressStartX = e.touches[0].clientX;
+            pressStartY = e.touches[0].clientY;
+        }
         gestureManager.onTouchStart(e, canvas);
     }, { passive: false });
     canvas.addEventListener('touchmove', (e: TouchEvent) => {
@@ -739,7 +755,15 @@ function bindCanvasEvents(canvas: HTMLElement) {
         gestureManager.onTouchMove(e, canvas, playgroundState);
     }, { passive: false });
     canvas.addEventListener('touchend', (e: TouchEvent) => {
+        const wasSingleTouch = e.touches.length === 0 && e.changedTouches.length === 1;
         gestureManager.onTouchEnd(e, canvas);
+        if (wasSingleTouch) {
+            const touch = e.changedTouches[0];
+            if (Math.abs(touch.clientX - pressStartX) < CLICK_MOVE_THRESHOLD &&
+                Math.abs(touch.clientY - pressStartY) < CLICK_MOVE_THRESHOLD) {
+                togglePlayback();
+            }
+        }
     });
     canvas.addEventListener('touchcancel', (e: TouchEvent) => {
         gestureManager.onTouchEnd(e, canvas);
@@ -801,11 +825,112 @@ function hideDropZone(): void {
     }
 }
 
+function showPlaybackBar(): void {
+    const playbackBar = document.getElementById('playback-bar') as HTMLDivElement;
+    if (!playbackBar) {
+        return;
+    }
+    // Static PAGX has no animation (zero duration); hide the playback bar for it.
+    const hasAnimation = !!playgroundState.pagxView && playgroundState.pagxView.durationMicros() > 0;
+    if (hasAnimation) {
+        playbackBar.classList.remove('hidden');
+        updatePlaybackUI();
+    } else {
+        playbackBar.classList.add('hidden');
+    }
+}
+
+function formatTime(microseconds: number): string {
+    const seconds = Math.max(0, microseconds / 1_000_000);
+    return seconds.toFixed(2) + 's';
+}
+
+function getCurrentFrame(): number {
+    const view = playgroundState.pagxView;
+    if (!view) return 0;
+    const rate = view.currentFrameRate();
+    if (rate <= 0) return 0;
+    return Math.round(Math.max(0, view.currentTimeMicros()) * rate / 1_000_000);
+}
+
+function getTotalFrames(): number {
+    const view = playgroundState.pagxView;
+    if (!view) return 0;
+    const rate = view.currentFrameRate();
+    if (rate <= 0) return 0;
+    return Math.ceil(view.durationMicros() * rate / 1_000_000);
+}
+
+function updatePlayPauseIcon(): void {
+    const playPauseImg = document.getElementById('play-pause-img') as HTMLImageElement;
+    if (!playgroundState.pagxView || !playPauseImg) {
+        return;
+    }
+    const playing = playgroundState.pagxView.isPlaying();
+    playPauseImg.src = playing ? './pause.png' : './play.png';
+}
+
+function updateSliderFill(slider: HTMLInputElement): void {
+    const pct = (parseFloat(slider.value) / 1000) * 100;
+    slider.style.background =
+        'linear-gradient(90deg, #4c7cf3, #8b5cf0, #ec5b9c) no-repeat 0 0 / ' +
+        pct + '% 100%, rgba(255, 255, 255, 0.18)';
+}
+
+function updateProgressSlider(): void {
+    const slider = document.getElementById('progress-slider') as HTMLInputElement;
+    if (!playgroundState.pagxView || !slider) {
+        return;
+    }
+    const duration = playgroundState.pagxView.durationMicros();
+    if (duration <= 0) {
+        slider.value = '0';
+        updateSliderFill(slider);
+        return;
+    }
+    const current = Math.max(0, playgroundState.pagxView.currentTimeMicros());
+    slider.value = String(Math.round((current / duration) * 1000));
+    updateSliderFill(slider);
+}
+
+function updateTimeDisplay(): void {
+    const timeText = document.getElementById('time-text');
+    const frameText = document.getElementById('frame-text');
+    if (!playgroundState.pagxView || !timeText || !frameText) {
+        return;
+    }
+    const current = playgroundState.pagxView.currentTimeMicros();
+    const duration = playgroundState.pagxView.durationMicros();
+    timeText.textContent = formatTime(current) + ' / ' + formatTime(duration);
+    frameText.textContent = String(getCurrentFrame()) + ' / ' + String(getTotalFrames());
+}
+
+function updatePlaybackUI(): void {
+    updatePlayPauseIcon();
+    updateProgressSlider();
+    updateTimeDisplay();
+}
+
+function togglePlayback(): void {
+    const view = playgroundState.pagxView;
+    if (!view || view.durationMicros() <= 0) {
+        return;
+    }
+    if (view.isPlaying()) {
+        view.pause();
+    } else {
+        view.play();
+    }
+    updatePlaybackUI();
+}
+
 function hidePlaybackUI(): void {
     const canvas = document.getElementById('pagx-canvas') as HTMLCanvasElement;
     const toolbar = document.getElementById('toolbar') as HTMLDivElement;
+    const playbackBar = document.getElementById('playback-bar') as HTMLDivElement;
     canvas.classList.add('hidden');
     toolbar.classList.add('hidden');
+    playbackBar.classList.add('hidden');
 }
 
 const DEFAULT_TITLE = 'PAGX Playground';
@@ -818,8 +943,10 @@ function goHome(pushHistory: boolean = true): void {
     const canvas = document.getElementById('pagx-canvas') as HTMLCanvasElement;
     const toolbar = document.getElementById('toolbar') as HTMLDivElement;
     const navBtns = document.getElementById('nav-btns') as HTMLDivElement;
+    const playbackBar = document.getElementById('playback-bar') as HTMLDivElement;
     canvas.classList.add('hidden');
     toolbar.classList.add('hidden');
+    playbackBar.classList.add('hidden');
     navBtns.classList.remove('hidden');
     document.title = DEFAULT_TITLE;
     showDropZoneUI();
@@ -894,6 +1021,7 @@ async function loadPAGXData(data: Uint8Array, name: string, baseURL: string) {
     canvas.classList.remove('hidden');
     toolbar.classList.remove('hidden');
     navBtns.classList.add('hidden');
+    showPlaybackBar();
     document.title = 'PAGX Playground - ' + name;
     currentFileName = name;
 
@@ -1034,8 +1162,16 @@ function setupDragAndDrop() {
         document.body.addEventListener(eventName, preventDefaults, false);
     });
 
+    const isFileDrag = (e: DragEvent): boolean => {
+        const types = e.dataTransfer?.types;
+        return types ? Array.prototype.indexOf.call(types, 'Files') !== -1 : false;
+    };
+
     ['dragenter', 'dragover'].forEach(eventName => {
-        container.addEventListener(eventName, () => {
+        container.addEventListener(eventName, (e: Event) => {
+            if (!isFileDrag(e as DragEvent)) {
+                return;
+            }
             dropZone.classList.add('drag-over');
             dropZone.classList.remove('hidden');
         }, false);
@@ -1088,6 +1224,105 @@ function setupDragAndDrop() {
     });
 }
 
+function setupPlaybackControls(): void {
+    const playPauseBtn = document.getElementById('play-pause-btn') as HTMLButtonElement;
+    const prevFrameBtn = document.getElementById('prev-frame-btn') as HTMLButtonElement;
+    const nextFrameBtn = document.getElementById('next-frame-btn') as HTMLButtonElement;
+    const progressSlider = document.getElementById('progress-slider') as HTMLInputElement;
+
+    if (playPauseBtn) {
+        playPauseBtn.addEventListener('click', () => {
+            togglePlayback();
+        });
+    }
+
+    if (prevFrameBtn) {
+        prevFrameBtn.addEventListener('click', () => {
+            if (!playgroundState.pagxView) return;
+            playgroundState.pagxView.goToPreviousFrame();
+            updatePlaybackUI();
+        });
+    }
+
+    if (nextFrameBtn) {
+        nextFrameBtn.addEventListener('click', () => {
+            if (!playgroundState.pagxView) return;
+            playgroundState.pagxView.goToNextFrame();
+            updatePlaybackUI();
+        });
+    }
+
+    let isDraggingSlider = false;
+    let wasPlayingBeforeDrag = false;
+    if (progressSlider) {
+        const seekToSliderValue = () => {
+            if (!playgroundState.pagxView) return;
+            const duration = playgroundState.pagxView.durationMicros();
+            if (duration <= 0) return;
+            const value = parseFloat(progressSlider.value);
+            const targetTime = (value / 1000) * duration;
+            playgroundState.pagxView.setCurrentTimeMicros(targetTime);
+        };
+        progressSlider.addEventListener('input', () => {
+            if (!playgroundState.pagxView) return;
+            // Pause on drag start so the frame follows the slider instead of the render loop
+            // advancing over it; remember the state to restore on release.
+            if (!isDraggingSlider) {
+                isDraggingSlider = true;
+                wasPlayingBeforeDrag = playgroundState.pagxView.isPlaying();
+                if (wasPlayingBeforeDrag) {
+                    playgroundState.pagxView.pause();
+                }
+            }
+            updateSliderFill(progressSlider);
+            seekToSliderValue();
+            updateTimeDisplay();
+            updatePlayPauseIcon();
+        });
+        progressSlider.addEventListener('change', () => {
+            isDraggingSlider = false;
+            if (!playgroundState.pagxView) return;
+            seekToSliderValue();
+            if (wasPlayingBeforeDrag) {
+                playgroundState.pagxView.play();
+                wasPlayingBeforeDrag = false;
+            }
+            updatePlaybackUI();
+            // Release focus so the Space shortcut keeps working after dragging.
+            progressSlider.blur();
+        });
+    }
+
+    // Keyboard shortcut: Space for play/pause
+    document.addEventListener('keydown', (e: KeyboardEvent) => {
+        if (e.code !== 'Space') return;
+        // Ignore only text entry fields; the range slider must still respond to Space.
+        const target = e.target;
+        const isTextInput =
+            (target instanceof HTMLInputElement && target.type !== 'range') ||
+            target instanceof HTMLTextAreaElement;
+        if (isTextInput) return;
+        const canvas = document.getElementById('pagx-canvas');
+        if (!canvas || canvas.classList.contains('hidden')) return;
+        e.preventDefault();
+        togglePlayback();
+    });
+
+    // Update playback UI periodically. Also fire once on the play -> stop transition so the slider,
+    // time and icon settle on the final frame after a single (non-looping) playback ends.
+    let wasPlaying = false;
+    setInterval(() => {
+        if (!playgroundState.pagxView) return;
+        const canvas = document.getElementById('pagx-canvas');
+        if (!canvas || canvas.classList.contains('hidden')) return;
+        const playing = playgroundState.pagxView.isPlaying();
+        if (!isDraggingSlider && (playing || wasPlaying)) {
+            updatePlaybackUI();
+        }
+        wasPlaying = playing;
+    }, 100);
+}
+
 function checkWebGL2Support(): boolean {
     const canvas = document.createElement('canvas');
     const gl = canvas.getContext('webgl2');
@@ -1271,6 +1506,7 @@ if (typeof window !== 'undefined') {
 
         // Setup drag and drop early so UI is responsive
         setupDragAndDrop();
+        setupPlaybackControls();
 
         if (!checkWasmSupport() || !checkWebGL2Support()) {
             showErrorUI(getBrowserRequirements());
@@ -1298,44 +1534,40 @@ if (typeof window !== 'undefined') {
             loadPAGXSample(sampleName, false);
         }
 
+        // Encodes XML, reparses and redraws the view. Shared by the editor's Apply
+        // and Save actions. Returns '' on success, otherwise an error message.
+        const applyXmlToView = (xmlText: string): string => {
+            if (playgroundState.pagxView === null) {
+                return 'PAGXView not initialized';
+            }
+            try {
+                const data = new TextEncoder().encode(xmlText);
+                playgroundState.pagxView.parsePAGX(data);
+                playgroundState.pagxView.buildLayers();
+                playgroundState.pagxView.draw();
+                return '';
+            } catch (e) {
+                return e instanceof Error ? e.message : String(e);
+            }
+        };
         // Initialize the Source Editor module (keyboard shortcut L to toggle).
         initEditor({
-            onApply: (xmlText: string): string => {
-                if (playgroundState.pagxView === null) {
-                    return 'PAGXView not initialized';
-                }
-                try {
-                    const data = new TextEncoder().encode(xmlText);
-                    playgroundState.pagxView.parsePAGX(data);
-                    playgroundState.pagxView.buildLayers();
-                    playgroundState.pagxView.draw();
-                    return '';
-                } catch (e) {
-                    return e instanceof Error ? e.message : String(e);
-                }
-            },
+            onApply: applyXmlToView,
             onSave: (xmlText: string): string => {
-                if (playgroundState.pagxView === null) {
-                    return 'PAGXView not initialized';
-                }
-                try {
-                    const data = new TextEncoder().encode(xmlText);
-                    playgroundState.pagxView.parsePAGX(data);
-                    playgroundState.pagxView.buildLayers();
-                    playgroundState.pagxView.draw();
-                    const blob = new Blob([xmlText], { type: 'application/xml' });
-                    const url = URL.createObjectURL(blob);
-                    const a = document.createElement('a');
-                    a.href = url;
-                    a.download = currentFileName.endsWith('.pagx') ? currentFileName : currentFileName + '.pagx';
-                    document.body.appendChild(a);
-                    a.click();
-                    document.body.removeChild(a);
-                    URL.revokeObjectURL(url);
-                    return '';
-                } catch (e) {
-                    return e instanceof Error ? e.message : String(e);
+                const error = applyXmlToView(xmlText);
+                if (error !== '') {
+                    return error;
                 }
+                const blob = new Blob([xmlText], { type: 'application/xml' });
+                const url = URL.createObjectURL(blob);
+                const a = document.createElement('a');
+                a.href = url;
+                a.download = currentFileName.endsWith('.pagx') ? currentFileName : currentFileName + '.pagx';
+                document.body.appendChild(a);
+                a.click();
+                document.body.removeChild(a);
+                URL.revokeObjectURL(url);
+                return '';
             },
         });
 
diff --git a/playground/pagx-playground/static/index.css b/playground/pagx-playground/static/index.css
index b076bbe804..f42da198c3 100644
--- a/playground/pagx-playground/static/index.css
+++ b/playground/pagx-playground/static/index.css
@@ -427,6 +427,142 @@ html, body {
     white-space: nowrap;
 }
 
+/* Playback bar - centered compact pill, mimicking the macOS player control bar */
+.playback-bar {
+    position: absolute;
+    left: 50%;
+    transform: translateX(-50%);
+    bottom: 16px;
+    z-index: 150;
+    display: flex;
+    align-items: center;
+    gap: 14px;
+    padding: 12px 24px;
+    background: #20202A;
+    border-radius: 8px;
+}
+
+.playback-bar.hidden {
+    display: none;
+}
+
+.playback-btn {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0;
+    background: transparent;
+    border: none;
+    cursor: pointer;
+    opacity: 0.8;
+    transition: opacity 0.15s ease;
+}
+
+.playback-btn:hover {
+    opacity: 0.9;
+}
+
+.playback-btn:active {
+    opacity: 1;
+}
+
+.playback-btn:disabled {
+    opacity: 0.3;
+    cursor: not-allowed;
+}
+
+/* Play / Pause - reuse desktop client icon (blue circle with glow) */
+.playback-btn-primary {
+    width: 48px;
+    height: 48px;
+    margin-right: 4px;
+}
+
+.playback-btn-primary img {
+    display: block;
+    width: 48px;
+    height: 48px;
+}
+
+/* Frame-step buttons (prev/next frame) - reuse desktop client icons */
+.playback-btn-step {
+    width: 24px;
+    height: 48px;
+}
+
+.playback-btn-step img {
+    display: block;
+    width: 24px;
+    height: 20px;
+    /* Nudge the arrow glyphs down a touch so they sit on the progress bar center line */
+    margin-top: 3px;
+}
+
+/* Widen the gap between the prev/next frame buttons */
+#next-frame-btn {
+    margin-left: 20px;
+}
+
+.progress-wrapper {
+    width: 260px;
+    margin-left: 16px;
+    margin-right: 8px;
+}
+
+.time-display {
+    display: flex;
+    align-items: center;
+    gap: 16px;
+    margin-left: 8px;
+    color: #ffffff;
+    font-size: 12px;
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+}
+
+.time-divider {
+    width: 1px;
+    height: 14px;
+    background: rgba(255, 255, 255, 0.28);
+}
+
+.progress-slider {
+    -webkit-appearance: none;
+    appearance: none;
+    width: 100%;
+    height: 4px;
+    background: rgba(255, 255, 255, 0.18);
+    border-radius: 2px;
+    outline: none;
+    cursor: pointer;
+}
+
+.progress-slider::-webkit-slider-thumb {
+    -webkit-appearance: none;
+    appearance: none;
+    width: 12px;
+    height: 12px;
+    background: #fff;
+    border-radius: 50%;
+    cursor: pointer;
+    box-shadow: 0 1px 4px rgba(0, 0, 0, 0.4);
+    transition: transform 0.15s ease;
+}
+
+.progress-slider::-webkit-slider-thumb:hover {
+    transform: scale(1.2);
+}
+
+.progress-slider::-moz-range-thumb {
+    width: 12px;
+    height: 12px;
+    background: #fff;
+    border: none;
+    border-radius: 50%;
+    cursor: pointer;
+    box-shadow: 0 1px 4px rgba(0, 0, 0, 0.4);
+}
+
 /* Mobile */
 @media (max-width: 600px) {
     .drop-zone {
@@ -452,6 +588,19 @@ html, body {
     .file-name {
         max-width: 150px;
     }
+
+    /* On small screens fall back to a full-width bar with a flexible progress track. */
+    .playback-bar {
+        left: 16px;
+        right: 16px;
+        transform: none;
+    }
+
+    .progress-wrapper {
+        width: auto;
+        flex: 1;
+        min-width: 80px;
+    }
 }
 
 /* Samples page */
@@ -564,4 +713,30 @@ html, body {
     .samples-list .sample-name {
         font-size: 10px;
     }
+
+    .playback-bar {
+        left: 8px;
+        right: 8px;
+        bottom: 8px;
+        padding: 8px 12px;
+        gap: 8px;
+    }
+
+    .playback-btn-primary,
+    .playback-btn-primary img {
+        width: 40px;
+        height: 40px;
+    }
+
+    .playback-btn-step,
+    .playback-btn-step img {
+        width: 22px;
+        height: 18px;
+    }
+
+    .time-display {
+        font-size: 11px;
+        gap: 10px;
+        margin-left: 4px;
+    }
 }
diff --git a/playground/pagx-playground/static/index.html b/playground/pagx-playground/static/index.html
index 80843be9b6..b172de1958 100644
--- a/playground/pagx-playground/static/index.html
+++ b/playground/pagx-playground/static/index.html
@@ -111,7 +111,7 @@
     </div>
     <div id="drop-zone" class="drop-zone">
         <div class="brand">
-            <img class="logo" src="./logo.png" alt="PAGX Logo"/>
+            <img class="logo" src="./logo.png" alt="PAGX Logo" draggable="false"/>
             <h1 class="title">PAGX Playground</h1>
         </div>
         <div id="drop-zone-content" class="drop-zone-content">
@@ -141,6 +141,25 @@ <h1 class="title">PAGX Playground</h1>
             <p id="error-message" class="error-message"></p>
         </div>
     </div>
+    <div id="playback-bar" class="playback-bar hidden">
+        <button id="play-pause-btn" class="playback-btn playback-btn-primary" title="Play / Pause (Space)">
+            <img id="play-pause-img" src="./play.png" alt="Play / Pause" draggable="false"/>
+        </button>
+        <button id="prev-frame-btn" class="playback-btn playback-btn-step" title="Previous Frame">
+            <img src="./previous.png" alt="Previous Frame" draggable="false"/>
+        </button>
+        <button id="next-frame-btn" class="playback-btn playback-btn-step" title="Next Frame">
+            <img src="./next.png" alt="Next Frame" draggable="false"/>
+        </button>
+        <div class="progress-wrapper">
+            <input id="progress-slider" class="progress-slider" type="range" min="0" max="1000" value="0" step="1"/>
+        </div>
+        <div id="time-display" class="time-display">
+            <span id="time-text" class="time-text">0.00s / 0.00s</span>
+            <span class="time-divider"></span>
+            <span id="frame-text" class="frame-text">0 / 0</span>
+        </div>
+    </div>
 </div>
 <div id="samples-page" class="samples-page hidden">
     <div class="samples-header">
diff --git a/playground/pagx-playground/static/next.png b/playground/pagx-playground/static/next.png
new file mode 100755
index 0000000000..988a0d2e32
--- /dev/null
+++ b/playground/pagx-playground/static/next.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:18ebfd712d4bd763b6e991a90718737f02718dc151bd1718c3da3535b9eabd17
+size 1827
diff --git a/playground/pagx-playground/static/pause.png b/playground/pagx-playground/static/pause.png
new file mode 100644
index 0000000000..cca72b0404
--- /dev/null
+++ b/playground/pagx-playground/static/pause.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:47f8a2689ab77e45f245ce1be9463328dd28f40a6bda77f385d92c2b5525c4c5
+size 9465
diff --git a/playground/pagx-playground/static/play.png b/playground/pagx-playground/static/play.png
new file mode 100755
index 0000000000..e96dd9160c
--- /dev/null
+++ b/playground/pagx-playground/static/play.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:02d6327ab57f8d524c942c12648ea8ceb6be2accf10948b5039585e4578e22c2
+size 10365
diff --git a/playground/pagx-playground/static/previous.png b/playground/pagx-playground/static/previous.png
new file mode 100755
index 0000000000..05de8888b5
--- /dev/null
+++ b/playground/pagx-playground/static/previous.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:51be6154e4d8b6b0568c1b9d2d7ee745bb07049ea6a169da3b67232c13bba76d
+size 1813
diff --git a/playground/pagx-playground/static/server.js b/playground/pagx-playground/static/server.js
index 45785dc06a..03c3a27991 100644
--- a/playground/pagx-playground/static/server.js
+++ b/playground/pagx-playground/static/server.js
@@ -80,7 +80,7 @@ app.get('/', (req, res) => {
   res.redirect('/index.html');
 });
 
-const port = 8080;
+const port = 8000;
 
 /** Returns the first non-internal IPv4 address for LAN sharing, or 'localhost' if none. */
 function getLanIp() {
@@ -95,9 +95,13 @@ function getLanIp() {
   return 'localhost';
 }
 
-app.listen(port, '0.0.0.0', () => {
+// LAN sharing is opt-in for security: set PAGX_LAN=1 to expose the server on the local
+// network so other devices (e.g. phones) can access it. Defaults to localhost-only.
+const enableLan = process.env.PAGX_LAN === '1';
+const host = enableLan ? '0.0.0.0' : '127.0.0.1';
+
+app.listen(port, host, () => {
   const localUrl = `http://localhost:${port}/`;
-  const lanUrl = `http://${getLanIp()}:${port}/`;
   if (process.platform === 'darwin') {
     execFile('open', [localUrl]);
   } else if (process.platform === 'win32') {
@@ -108,5 +112,7 @@ app.listen(port, '0.0.0.0', () => {
     execFile('xdg-open', [localUrl]);
   }
   console.log(`PAGX Playground running at ${localUrl}`);
-  console.log(`LAN access: ${lanUrl}`);
+  if (enableLan) {
+    console.log(`LAN access: http://${getLanIp()}:${port}/`);
+  }
 });
diff --git a/playground/pagx-viewer/src/cpp/PAGXView.cpp b/playground/pagx-viewer/src/cpp/PAGXView.cpp
index 75af3df58b..cb1d66d03a 100644
--- a/playground/pagx-viewer/src/cpp/PAGXView.cpp
+++ b/playground/pagx-viewer/src/cpp/PAGXView.cpp
@@ -437,4 +437,82 @@ void PAGXView::updateAdaptiveTileRefinement() {
   }
 }
 
+void PAGXView::play() {
+  if (defaultTimeline != nullptr) {
+    defaultTimeline->play();
+  }
+}
+
+void PAGXView::pause() {
+  if (defaultTimeline != nullptr) {
+    defaultTimeline->pause();
+  }
+}
+
+bool PAGXView::isPlaying() const {
+  if (defaultTimeline != nullptr) {
+    return defaultTimeline->isPlaying();
+  }
+  return false;
+}
+
+int64_t PAGXView::currentTimeMicros() const {
+  if (defaultTimeline != nullptr) {
+    return defaultTimeline->currentTime();
+  }
+  return 0;
+}
+
+int64_t PAGXView::durationMicros() const {
+  if (defaultTimeline != nullptr) {
+    return defaultTimeline->duration();
+  }
+  return 0;
+}
+
+float PAGXView::currentFrameRate() const {
+  if (defaultTimeline != nullptr) {
+    return defaultTimeline->frameRate();
+  }
+  return 0.0f;
+}
+
+void PAGXView::setCurrentTimeMicros(int64_t micros) {
+  if (defaultTimeline != nullptr) {
+    defaultTimeline->setCurrentTime(micros);
+    lastAnimationTimeMs = -1.0;
+  }
+}
+
+void PAGXView::goToPreviousFrame() {
+  if (defaultTimeline == nullptr || defaultTimeline->frameRate() <= 0.0f) {
+    return;
+  }
+  // Stepping a frame always pauses playback first, matching the desktop client behavior.
+  pause();
+  int64_t frameDurationUs = static_cast<int64_t>(1000000.0 / defaultTimeline->frameRate());
+  int64_t newTime = defaultTimeline->currentTime() - frameDurationUs;
+  if (newTime < 0) {
+    newTime = 0;
+  }
+  setCurrentTimeMicros(newTime);
+  defaultTimeline->apply();
+}
+
+void PAGXView::goToNextFrame() {
+  if (defaultTimeline == nullptr || defaultTimeline->frameRate() <= 0.0f) {
+    return;
+  }
+  // Stepping a frame always pauses playback first, matching the desktop client behavior.
+  pause();
+  int64_t frameDurationUs = static_cast<int64_t>(1000000.0 / defaultTimeline->frameRate());
+  int64_t duration = defaultTimeline->duration();
+  int64_t newTime = defaultTimeline->currentTime() + frameDurationUs;
+  if (duration > 0 && newTime > duration) {
+    newTime = duration;
+  }
+  setCurrentTimeMicros(newTime);
+  defaultTimeline->apply();
+}
+
 }  // namespace pagx
diff --git a/playground/pagx-viewer/src/cpp/PAGXView.h b/playground/pagx-viewer/src/cpp/PAGXView.h
index 4457464442..3217f8a4cf 100644
--- a/playground/pagx-viewer/src/cpp/PAGXView.h
+++ b/playground/pagx-viewer/src/cpp/PAGXView.h
@@ -78,6 +78,17 @@ class PAGXView {
     return pagxHeight;
   }
 
+  // Playback control methods
+  void play();
+  void pause();
+  bool isPlaying() const;
+  int64_t currentTimeMicros() const;
+  int64_t durationMicros() const;
+  float currentFrameRate() const;
+  void setCurrentTimeMicros(int64_t micros);
+  void goToPreviousFrame();
+  void goToNextFrame();
+
  private:
   void updateContentTransform();
   void applyDisplayTransform();
diff --git a/playground/pagx-viewer/src/cpp/binding.cpp b/playground/pagx-viewer/src/cpp/binding.cpp
index 70312f764b..ab3d5703e5 100644
--- a/playground/pagx-viewer/src/cpp/binding.cpp
+++ b/playground/pagx-viewer/src/cpp/binding.cpp
@@ -46,5 +46,27 @@ EMSCRIPTEN_BINDINGS(PAGXPlayground) {
       .function("_clearBackgroundColor", &pagx::PAGXView::clearBackgroundColor)
       .function("_draw", &pagx::PAGXView::draw)
       .function("_contentWidth", &pagx::PAGXView::contentWidth)
-      .function("_contentHeight", &pagx::PAGXView::contentHeight);
+      .function("_contentHeight", &pagx::PAGXView::contentHeight)
+      .function("_play", &pagx::PAGXView::play)
+      .function("_pause", &pagx::PAGXView::pause)
+      .function("_isPlaying", &pagx::PAGXView::isPlaying)
+      // Wrap int64_t returns/params as double: emscripten::bind does not support 64-bit integers.
+      .function(
+          "_currentTimeMicros",
+          optional_override([](pagx::PAGXView& self) -> double {
+            return static_cast<double>(self.currentTimeMicros());
+          }))
+      .function(
+          "_durationMicros",
+          optional_override([](pagx::PAGXView& self) -> double {
+            return static_cast<double>(self.durationMicros());
+          }))
+      .function("_currentFrameRate", &pagx::PAGXView::currentFrameRate)
+      .function(
+          "_setCurrentTimeMicros",
+          optional_override([](pagx::PAGXView& self, double micros) {
+            self.setCurrentTimeMicros(static_cast<int64_t>(micros));
+          }))
+      .function("_goToPreviousFrame", &pagx::PAGXView::goToPreviousFrame)
+      .function("_goToNextFrame", &pagx::PAGXView::goToNextFrame);
 }
diff --git a/playground/pagx-viewer/src/ts/pagx-view.ts b/playground/pagx-viewer/src/ts/pagx-view.ts
index e53e31dc38..48c365f693 100644
--- a/playground/pagx-viewer/src/ts/pagx-view.ts
+++ b/playground/pagx-viewer/src/ts/pagx-view.ts
@@ -293,6 +293,75 @@ export class PAGXView {
     this.nativeView._draw();
   }
 
+  // Playback control methods
+
+  /**
+   * Starts or resumes playback of the default timeline.
+   */
+  public play(): void {
+    this.nativeView._play();
+  }
+
+  /**
+   * Pauses playback of the default timeline.
+   */
+  public pause(): void {
+    this.nativeView._pause();
+  }
+
+  /**
+   * Returns whether the default timeline is currently playing.
+   */
+  public isPlaying(): boolean {
+    return this.nativeView._isPlaying();
+  }
+
+  /**
+   * Returns the current playback time in microseconds.
+   */
+  public currentTimeMicros(): number {
+    return this.nativeView._currentTimeMicros();
+  }
+
+  /**
+   * Returns the total duration in microseconds. Returns 0 if no content is loaded.
+   */
+  public durationMicros(): number {
+    return this.nativeView._durationMicros();
+  }
+
+  /**
+   * Returns the frame rate of the animation. Returns 0 if no content is loaded.
+   */
+  public currentFrameRate(): number {
+    return this.nativeView._currentFrameRate();
+  }
+
+  /**
+   * Sets the current playback time in microseconds.
+   * @param micros Time position in microseconds
+   */
+  public setCurrentTimeMicros(micros: number): void {
+    this.nativeView._setCurrentTimeMicros(micros);
+    if (!this._isRunning) {
+      this.nativeView._draw();
+    }
+  }
+
+  /**
+   * Goes to the previous frame. Pauses playback if currently playing.
+   */
+  public goToPreviousFrame(): void {
+    this.nativeView._goToPreviousFrame();
+  }
+
+  /**
+   * Goes to the next frame. Pauses playback if currently playing.
+   */
+  public goToNextFrame(): void {
+    this.nativeView._goToNextFrame();
+  }
+
   /**
    * Starts the render loop.
    */
diff --git a/playground/pagx-viewer/src/ts/types.ts b/playground/pagx-viewer/src/ts/types.ts
index 3bb6692285..9103881d09 100644
--- a/playground/pagx-viewer/src/ts/types.ts
+++ b/playground/pagx-viewer/src/ts/types.ts
@@ -130,6 +130,52 @@ export interface _PAGXView {
    */
   _contentHeight(): number;
 
+  /**
+   * Starts or resumes playback of the default timeline.
+   */
+  _play(): void;
+
+  /**
+   * Pauses playback of the default timeline.
+   */
+  _pause(): void;
+
+  /**
+   * Returns whether the default timeline is currently playing.
+   */
+  _isPlaying(): boolean;
+
+  /**
+   * Returns the current playback time in microseconds.
+   */
+  _currentTimeMicros(): number;
+
+  /**
+   * Returns the total duration in microseconds.
+   */
+  _durationMicros(): number;
+
+  /**
+   * Returns the frame rate of the animation.
+   */
+  _currentFrameRate(): number;
+
+  /**
+   * Sets the current playback time in microseconds.
+   * @param micros Time in microseconds
+   */
+  _setCurrentTimeMicros(micros: number): void;
+
+  /**
+   * Goes to the previous frame. Pauses if currently playing.
+   */
+  _goToPreviousFrame(): void;
+
+  /**
+   * Goes to the next frame. Pauses if currently playing.
+   */
+  _goToNextFrame(): void;
+
   /**
    * Releases the native resources. Must be called when done.
    */

From 5f9e64e4b9e43f9be87459f6c94a2bb46d9029e4 Mon Sep 17 00:00:00 2001
From: ash <gracelllx@qq.com>
Date: Wed, 15 Jul 2026 21:42:32 +0800
Subject: [PATCH 06/10] Complete playback feature and add loop playback

---
 playground/pagx-playground/src/index.ts      |  20 ++++
 playground/pagx-playground/static/index.css  |  39 +++++++
 playground/pagx-playground/static/index.html |  10 ++
 playground/pagx-viewer/src/cpp/PAGXView.cpp  | 106 ++++++++++++++-----
 playground/pagx-viewer/src/cpp/PAGXView.h    |  16 +++
 playground/pagx-viewer/src/cpp/binding.cpp   |   4 +-
 playground/pagx-viewer/src/ts/pagx-view.ts   |  17 +++
 playground/pagx-viewer/src/ts/types.ts       |  11 ++
 8 files changed, 194 insertions(+), 29 deletions(-)

diff --git a/playground/pagx-playground/src/index.ts b/playground/pagx-playground/src/index.ts
index dbd718e4b9..83391091ed 100644
--- a/playground/pagx-playground/src/index.ts
+++ b/playground/pagx-playground/src/index.ts
@@ -905,10 +905,19 @@ function updateTimeDisplay(): void {
     frameText.textContent = String(getCurrentFrame()) + ' / ' + String(getTotalFrames());
 }
 
+function updateLoopIcon(): void {
+    const loopBtn = document.getElementById('loop-btn');
+    if (!playgroundState.pagxView || !loopBtn) {
+        return;
+    }
+    loopBtn.classList.toggle('active', playgroundState.pagxView.isLoop());
+}
+
 function updatePlaybackUI(): void {
     updatePlayPauseIcon();
     updateProgressSlider();
     updateTimeDisplay();
+    updateLoopIcon();
 }
 
 function togglePlayback(): void {
@@ -1252,6 +1261,17 @@ function setupPlaybackControls(): void {
         });
     }
 
+    const loopBtn = document.getElementById('loop-btn') as HTMLButtonElement;
+    if (loopBtn) {
+        loopBtn.addEventListener('click', () => {
+            if (!playgroundState.pagxView) return;
+            playgroundState.pagxView.setLoop(!playgroundState.pagxView.isLoop());
+            updateLoopIcon();
+            // Release focus so the Space shortcut keeps working after clicking.
+            loopBtn.blur();
+        });
+    }
+
     let isDraggingSlider = false;
     let wasPlayingBeforeDrag = false;
     if (progressSlider) {
diff --git a/playground/pagx-playground/static/index.css b/playground/pagx-playground/static/index.css
index f42da198c3..c5e1346815 100644
--- a/playground/pagx-playground/static/index.css
+++ b/playground/pagx-playground/static/index.css
@@ -526,6 +526,45 @@ html, body {
     background: rgba(255, 255, 255, 0.28);
 }
 
+/* Loop toggle - always a white loop icon. When looping is off (no .active class) a diagonal slash
+   is overlaid to signal a "no loop" state. The inline SVG follows the button's currentColor so the
+   state switch needs no swapped image assets. */
+.playback-btn-loop {
+    width: 24px;
+    height: 48px;
+    margin-left: 16px;
+    color: #ffffff;
+    opacity: 1;
+}
+
+.playback-btn-loop svg {
+    display: block;
+    width: 20px;
+    height: 20px;
+}
+
+/* The slash is hidden while looping (.active) and revealed when it is off. The thicker
+   background-colored line underneath cuts a gap so the white slash reads clearly over the arrows. */
+.playback-btn-loop .loop-slash,
+.playback-btn-loop .loop-slash-bg {
+    display: none;
+}
+
+.playback-btn-loop:not(.active) .loop-slash,
+.playback-btn-loop:not(.active) .loop-slash-bg {
+    display: block;
+}
+
+.loop-slash-bg {
+    stroke: #20202A;
+    stroke-width: 4;
+}
+
+.loop-slash {
+    stroke: currentColor;
+    stroke-width: 2;
+}
+
 .progress-slider {
     -webkit-appearance: none;
     appearance: none;
diff --git a/playground/pagx-playground/static/index.html b/playground/pagx-playground/static/index.html
index b172de1958..aa4f84fee4 100644
--- a/playground/pagx-playground/static/index.html
+++ b/playground/pagx-playground/static/index.html
@@ -159,6 +159,16 @@ <h1 class="title">PAGX Playground</h1>
             <span class="time-divider"></span>
             <span id="frame-text" class="frame-text">0 / 0</span>
         </div>
+        <button id="loop-btn" class="playback-btn playback-btn-loop" title="Loop">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                <polyline points="17 1 21 5 17 9"></polyline>
+                <path d="M3 11V9a4 4 0 0 1 4-4h14"></path>
+                <polyline points="7 23 3 19 7 15"></polyline>
+                <path d="M21 13v2a4 4 0 0 1-4 4H3"></path>
+                <line class="loop-slash-bg" x1="3" y1="21" x2="21" y2="3"></line>
+                <line class="loop-slash" x1="3" y1="21" x2="21" y2="3"></line>
+            </svg>
+        </button>
     </div>
 </div>
 <div id="samples-page" class="samples-page hidden">
diff --git a/playground/pagx-viewer/src/cpp/PAGXView.cpp b/playground/pagx-viewer/src/cpp/PAGXView.cpp
index 07b9b3f93d..b2b39e506b 100644
--- a/playground/pagx-viewer/src/cpp/PAGXView.cpp
+++ b/playground/pagx-viewer/src/cpp/PAGXView.cpp
@@ -111,6 +111,7 @@ void PAGXView::parsePAGX(const val& pagxData) {
   document = nullptr;
   scene = nullptr;
   defaultTimeline = nullptr;
+  defaultAnimation = nullptr;
   lastRecording = nullptr;
   lastAnimationTimeMs = -1.0;
   auto data = GetPagxDataFromEmscripten(pagxData);
@@ -148,6 +149,11 @@ void PAGXView::buildLayers() {
     return;
   }
   defaultTimeline = scene->getDefaultTimeline();
+  defaultAnimation = nullptr;
+  if (defaultTimeline != nullptr && defaultTimeline->type() == TimelineType::Animation) {
+    defaultAnimation = std::static_pointer_cast<PAGAnimation>(defaultTimeline);
+  }
+  playing = true;
   lastAnimationTimeMs = -1.0;
   pagxWidth = scene->width();
   pagxHeight = scene->height();
@@ -165,8 +171,38 @@ void PAGXView::advanceTimelines(double frameStartMs) {
   if (deltaUs <= 0) {
     return;
   }
-  if (defaultTimeline != nullptr) {
-    defaultTimeline->advanceAndApply(deltaUs);
+  if (playing) {
+    if (defaultAnimation != nullptr) {
+      int64_t duration = defaultAnimation->duration();
+      int64_t before = defaultAnimation->currentTime();
+      // Let the engine advance and wrap according to the file's loop mode; this keeps the in-cycle
+      // motion intact, including PingPong mirroring. The view only overrides what happens at a cycle
+      // boundary based on loopEnabled, so the file's loop flag never dictates repeat vs stop.
+      bool changed = defaultAnimation->advanceAndApply(deltaUs);
+      int64_t after = defaultAnimation->currentTime();
+      if (!changed) {
+        // A Once file clamps at the last frame and stops changing. Rewind to the head either way;
+        // when looping keep playing for the next cycle, otherwise park on the first frame so a
+        // finished single pass resets to the start instead of freezing on the last frame.
+        if (duration > 0) {
+          defaultAnimation->setCurrentTime(0);
+          defaultAnimation->apply();
+        }
+        if (!loopEnabled) {
+          playing = false;
+        }
+      } else if (!loopEnabled && duration > 0 && after < before) {
+        // A Loop/PingPong file wrapped or reversed past the end while the user wants a single pass.
+        // Forward motion is monotonic until the boundary, so the first backward step marks one
+        // completed pass: rewind to the first frame and stop there.
+        defaultAnimation->setCurrentTime(0);
+        defaultAnimation->apply();
+        playing = false;
+      }
+    } else if (defaultTimeline != nullptr) {
+      // Non-animation timelines (state machines) have no seekable duration to gate; drive as-is.
+      defaultTimeline->advanceAndApply(deltaUs);
+    }
   }
   if (scene != nullptr) {
     scene->advanceAndApply(deltaUs);
@@ -444,81 +480,95 @@ void PAGXView::updateAdaptiveTileRefinement() {
 }
 
 void PAGXView::play() {
-  if (defaultTimeline != nullptr) {
-    defaultTimeline->play();
+  if (defaultAnimation != nullptr) {
+    // If playback is parked at the end (a finished single pass), restart from the first frame so
+    // pressing play replays instead of staying stuck at the last frame.
+    int64_t duration = defaultAnimation->duration();
+    if (duration > 0 && defaultAnimation->currentTime() >= duration) {
+      defaultAnimation->setCurrentTime(0);
+      defaultAnimation->apply();
+      presentImmediately = true;
+    }
   }
+  playing = true;
 }
 
 void PAGXView::pause() {
-  if (defaultTimeline != nullptr) {
-    defaultTimeline->pause();
-  }
+  playing = false;
 }
 
 bool PAGXView::isPlaying() const {
-  if (defaultTimeline != nullptr) {
-    return defaultTimeline->isPlaying();
-  }
-  return false;
+  return playing;
 }
 
 int64_t PAGXView::currentTimeMicros() const {
-  if (defaultTimeline != nullptr) {
-    return defaultTimeline->currentTime();
+  if (defaultAnimation != nullptr) {
+    return defaultAnimation->currentTime();
   }
   return 0;
 }
 
 int64_t PAGXView::durationMicros() const {
-  if (defaultTimeline != nullptr) {
-    return defaultTimeline->duration();
+  if (defaultAnimation != nullptr) {
+    return defaultAnimation->duration();
   }
   return 0;
 }
 
 float PAGXView::currentFrameRate() const {
-  if (defaultTimeline != nullptr) {
-    return defaultTimeline->frameRate();
+  if (defaultAnimation != nullptr) {
+    return defaultAnimation->frameRate();
   }
   return 0.0f;
 }
 
 void PAGXView::setCurrentTimeMicros(int64_t micros) {
-  if (defaultTimeline != nullptr) {
-    defaultTimeline->setCurrentTime(micros);
+  if (defaultAnimation != nullptr) {
+    defaultAnimation->setCurrentTime(micros);
+    // setCurrentTime only moves the playhead; apply() is required to reflect it in the content.
+    // Force a present so a manual seek (e.g. dragging the progress bar while paused) updates the
+    // frame immediately instead of being skipped by the idle dirty gate in draw().
+    defaultAnimation->apply();
     lastAnimationTimeMs = -1.0;
+    presentImmediately = true;
   }
 }
 
 void PAGXView::goToPreviousFrame() {
-  if (defaultTimeline == nullptr || defaultTimeline->frameRate() <= 0.0f) {
+  if (defaultAnimation == nullptr || defaultAnimation->frameRate() <= 0.0f) {
     return;
   }
   // Stepping a frame always pauses playback first, matching the desktop client behavior.
   pause();
-  int64_t frameDurationUs = static_cast<int64_t>(1000000.0 / defaultTimeline->frameRate());
-  int64_t newTime = defaultTimeline->currentTime() - frameDurationUs;
+  int64_t frameDurationUs = static_cast<int64_t>(1000000.0 / defaultAnimation->frameRate());
+  int64_t newTime = defaultAnimation->currentTime() - frameDurationUs;
   if (newTime < 0) {
     newTime = 0;
   }
   setCurrentTimeMicros(newTime);
-  defaultTimeline->apply();
 }
 
 void PAGXView::goToNextFrame() {
-  if (defaultTimeline == nullptr || defaultTimeline->frameRate() <= 0.0f) {
+  if (defaultAnimation == nullptr || defaultAnimation->frameRate() <= 0.0f) {
     return;
   }
   // Stepping a frame always pauses playback first, matching the desktop client behavior.
   pause();
-  int64_t frameDurationUs = static_cast<int64_t>(1000000.0 / defaultTimeline->frameRate());
-  int64_t duration = defaultTimeline->duration();
-  int64_t newTime = defaultTimeline->currentTime() + frameDurationUs;
+  int64_t frameDurationUs = static_cast<int64_t>(1000000.0 / defaultAnimation->frameRate());
+  int64_t duration = defaultAnimation->duration();
+  int64_t newTime = defaultAnimation->currentTime() + frameDurationUs;
   if (duration > 0 && newTime > duration) {
     newTime = duration;
   }
   setCurrentTimeMicros(newTime);
-  defaultTimeline->apply();
+}
+
+void PAGXView::setLoop(bool loop) {
+  loopEnabled = loop;
+}
+
+bool PAGXView::isLoop() const {
+  return loopEnabled;
 }
 
 }  // namespace pagx
diff --git a/playground/pagx-viewer/src/cpp/PAGXView.h b/playground/pagx-viewer/src/cpp/PAGXView.h
index 3217f8a4cf..33ba0ef32a 100644
--- a/playground/pagx-viewer/src/cpp/PAGXView.h
+++ b/playground/pagx-viewer/src/cpp/PAGXView.h
@@ -22,6 +22,7 @@
 #include <deque>
 #include "pag/gpu.h"
 #include "pagx/FontConfig.h"
+#include "pagx/PAGAnimation.h"
 #include "pagx/PAGScene.h"
 #include "pagx/PAGSurface.h"
 #include "pagx/PAGTimeline.h"
@@ -88,6 +89,8 @@ class PAGXView {
   void setCurrentTimeMicros(int64_t micros);
   void goToPreviousFrame();
   void goToNextFrame();
+  void setLoop(bool loop);
+  bool isLoop() const;
 
  private:
   void updateContentTransform();
@@ -107,6 +110,19 @@ class PAGXView {
   std::shared_ptr<PAGSurface> pagSurface = nullptr;
   std::shared_ptr<PAGScene> scene = nullptr;
   std::shared_ptr<PAGTimeline> defaultTimeline = nullptr;
+  // The default timeline downcast to PAGAnimation when it is an animation. The playback value
+  // methods (duration/frameRate/currentTime/setCurrentTime) live on PAGAnimation, not on the
+  // PAGTimeline base, so they are routed through this pointer. Null when there is no default
+  // timeline or it is not an animation.
+  std::shared_ptr<PAGAnimation> defaultAnimation = nullptr;
+  // Playback state maintained by the view itself. The timeline API no longer carries play/pause
+  // state, and PAGComposition::pauseTimeline cannot gate the top-level timeline driven here, so the
+  // view gates advancement on this flag.
+  bool playing = true;
+  // Player-level loop switch that overrides the file's loop mode at cycle boundaries: the engine
+  // still drives in-cycle motion (including PingPong mirroring), but whether a completed cycle
+  // repeats or stops is decided here instead of by the file's LoopMode. Defaults to looping.
+  bool loopEnabled = true;
   std::unique_ptr<tgfx::Recording> lastRecording = nullptr;
   double lastAnimationTimeMs = -1.0;
   int lastSurfaceWidth = 0;
diff --git a/playground/pagx-viewer/src/cpp/binding.cpp b/playground/pagx-viewer/src/cpp/binding.cpp
index ab3d5703e5..a455261dbe 100644
--- a/playground/pagx-viewer/src/cpp/binding.cpp
+++ b/playground/pagx-viewer/src/cpp/binding.cpp
@@ -68,5 +68,7 @@ EMSCRIPTEN_BINDINGS(PAGXPlayground) {
             self.setCurrentTimeMicros(static_cast<int64_t>(micros));
           }))
       .function("_goToPreviousFrame", &pagx::PAGXView::goToPreviousFrame)
-      .function("_goToNextFrame", &pagx::PAGXView::goToNextFrame);
+      .function("_goToNextFrame", &pagx::PAGXView::goToNextFrame)
+      .function("_setLoop", &pagx::PAGXView::setLoop)
+      .function("_isLoop", &pagx::PAGXView::isLoop);
 }
diff --git a/playground/pagx-viewer/src/ts/pagx-view.ts b/playground/pagx-viewer/src/ts/pagx-view.ts
index 48c365f693..7695c152de 100644
--- a/playground/pagx-viewer/src/ts/pagx-view.ts
+++ b/playground/pagx-viewer/src/ts/pagx-view.ts
@@ -362,6 +362,23 @@ export class PAGXView {
     this.nativeView._goToNextFrame();
   }
 
+  /**
+   * Sets whether playback loops, overriding the loop mode stored in the file. When enabled, each
+   * cycle repeats (preserving PingPong mirroring); when disabled, playback stops at the last frame
+   * after a single pass.
+   * @param loop true to loop, false to play once
+   */
+  public setLoop(loop: boolean): void {
+    this.nativeView._setLoop(loop);
+  }
+
+  /**
+   * Returns whether playback is set to loop.
+   */
+  public isLoop(): boolean {
+    return this.nativeView._isLoop();
+  }
+
   /**
    * Starts the render loop.
    */
diff --git a/playground/pagx-viewer/src/ts/types.ts b/playground/pagx-viewer/src/ts/types.ts
index 9103881d09..14af0bf545 100644
--- a/playground/pagx-viewer/src/ts/types.ts
+++ b/playground/pagx-viewer/src/ts/types.ts
@@ -176,6 +176,17 @@ export interface _PAGXView {
    */
   _goToNextFrame(): void;
 
+  /**
+   * Sets whether playback loops, overriding the file's loop mode.
+   * @param loop true to repeat after each cycle, false to stop at the end after a single pass
+   */
+  _setLoop(loop: boolean): void;
+
+  /**
+   * Returns whether playback is set to loop.
+   */
+  _isLoop(): boolean;
+
   /**
    * Releases the native resources. Must be called when done.
    */

From e6f1496455cb0f3270d94ef9b041fd30e785e25f Mon Sep 17 00:00:00 2001
From: ash <gracelllx@qq.com>
Date: Wed, 15 Jul 2026 23:00:44 +0800
Subject: [PATCH 07/10] Refactor and fix bugs

---
 playground/pagx-playground/package.json     |  8 ++++
 playground/pagx-playground/src/index.ts     | 36 +++++++++++---
 playground/pagx-viewer/src/cpp/PAGXView.cpp | 53 ++++-----------------
 playground/pagx-viewer/src/cpp/PAGXView.h   |  2 -
 playground/pagx-viewer/src/cpp/binding.cpp  |  2 -
 playground/pagx-viewer/src/ts/pagx-view.ts  | 18 +------
 playground/pagx-viewer/src/ts/types.ts      | 13 +----
 7 files changed, 52 insertions(+), 80 deletions(-)

diff --git a/playground/pagx-playground/package.json b/playground/pagx-playground/package.json
index 128b2f8f50..fbf136db8c 100644
--- a/playground/pagx-playground/package.json
+++ b/playground/pagx-playground/package.json
@@ -31,6 +31,14 @@
     "typescript": "~5.0.3"
   },
   "dependencies": {
+    "@codemirror/commands": "^6.10.4",
+    "@codemirror/lang-xml": "^6.1.0",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/search": "^6.7.1",
+    "@codemirror/state": "^6.7.1",
+    "@codemirror/view": "^6.43.6",
+    "@lezer/highlight": "^1.2.3",
+    "codemirror": "^6.0.2",
     "express": "^4.21.1",
     "highlight.js": "^11.9.0",
     "marked": "^15.0.0",
diff --git a/playground/pagx-playground/src/index.ts b/playground/pagx-playground/src/index.ts
index 83391091ed..7b9d06191c 100644
--- a/playground/pagx-playground/src/index.ts
+++ b/playground/pagx-playground/src/index.ts
@@ -928,11 +928,36 @@ function togglePlayback(): void {
     if (view.isPlaying()) {
         view.pause();
     } else {
+        // Restart from the head when starting playback at the last frame (the user stepped or
+        // dragged the playhead to the end), so play replays instead of being stuck at the end.
+        if (view.currentTimeMicros() >= view.durationMicros()) {
+            view.setCurrentTimeMicros(0);
+        }
         view.play();
     }
     updatePlaybackUI();
 }
 
+// Steps the playhead by one frame in the given direction (-1 previous, +1 next). Stepping always
+// pauses first, then seeks by a single frame duration clamped to the animation range. Composed from
+// the view's playback primitives so the frame-navigation policy lives in the UI layer.
+function stepFrame(direction: number): void {
+    const view = playgroundState.pagxView;
+    if (!view) {
+        return;
+    }
+    const rate = view.currentFrameRate();
+    const duration = view.durationMicros();
+    if (rate <= 0 || duration <= 0) {
+        return;
+    }
+    view.pause();
+    const frameDurationUs = 1_000_000 / rate;
+    const target = view.currentTimeMicros() + direction * frameDurationUs;
+    view.setCurrentTimeMicros(Math.max(0, Math.min(duration, target)));
+    updatePlaybackUI();
+}
+
 function hidePlaybackUI(): void {
     const canvas = document.getElementById('pagx-canvas') as HTMLCanvasElement;
     const toolbar = document.getElementById('toolbar') as HTMLDivElement;
@@ -1022,6 +1047,9 @@ async function loadPAGXData(data: Uint8Array, name: string, baseURL: string) {
     playgroundState.pagxView.parsePAGX(data);
     await loadExternalFiles(baseURL);
     playgroundState.pagxView.buildLayers();
+    // The view is a reused singleton, so reset loop to its default enabled state so each newly
+    // opened file starts fresh instead of inheriting the previous file's loop toggle.
+    playgroundState.pagxView.setLoop(true);
     gestureManager.resetTransform(playgroundState);
     updateSize();
     // Draw the first frame before showing canvas to avoid flashing old content
@@ -1247,17 +1275,13 @@ function setupPlaybackControls(): void {
 
     if (prevFrameBtn) {
         prevFrameBtn.addEventListener('click', () => {
-            if (!playgroundState.pagxView) return;
-            playgroundState.pagxView.goToPreviousFrame();
-            updatePlaybackUI();
+            stepFrame(-1);
         });
     }
 
     if (nextFrameBtn) {
         nextFrameBtn.addEventListener('click', () => {
-            if (!playgroundState.pagxView) return;
-            playgroundState.pagxView.goToNextFrame();
-            updatePlaybackUI();
+            stepFrame(1);
         });
     }
 
diff --git a/playground/pagx-viewer/src/cpp/PAGXView.cpp b/playground/pagx-viewer/src/cpp/PAGXView.cpp
index b2b39e506b..5f3437d46c 100644
--- a/playground/pagx-viewer/src/cpp/PAGXView.cpp
+++ b/playground/pagx-viewer/src/cpp/PAGXView.cpp
@@ -194,7 +194,10 @@ void PAGXView::advanceTimelines(double frameStartMs) {
       } else if (!loopEnabled && duration > 0 && after < before) {
         // A Loop/PingPong file wrapped or reversed past the end while the user wants a single pass.
         // Forward motion is monotonic until the boundary, so the first backward step marks one
-        // completed pass: rewind to the first frame and stop there.
+        // completed pass: rewind to the first frame and stop there. For PingPong this counts the
+        // forward half as the single pass and stops as soon as it reaches the end, so the mirrored
+        // return half is not played — "single pass" is inherently ambiguous for PingPong and this
+        // is the accepted tradeoff.
         defaultAnimation->setCurrentTime(0);
         defaultAnimation->apply();
         playing = false;
@@ -203,9 +206,12 @@ void PAGXView::advanceTimelines(double frameStartMs) {
       // Non-animation timelines (state machines) have no seekable duration to gate; drive as-is.
       defaultTimeline->advanceAndApply(deltaUs);
     }
-  }
-  if (scene != nullptr) {
-    scene->advanceAndApply(deltaUs);
+    // Drive the scene inside the playing gate so pausing freezes the whole picture: this advances
+    // the auto-playing nested compositions, which would otherwise keep animating (and keep
+    // hasContentChanged() true) even while the top-level animation is paused.
+    if (scene != nullptr) {
+      scene->advanceAndApply(deltaUs);
+    }
   }
 }
 
@@ -480,16 +486,6 @@ void PAGXView::updateAdaptiveTileRefinement() {
 }
 
 void PAGXView::play() {
-  if (defaultAnimation != nullptr) {
-    // If playback is parked at the end (a finished single pass), restart from the first frame so
-    // pressing play replays instead of staying stuck at the last frame.
-    int64_t duration = defaultAnimation->duration();
-    if (duration > 0 && defaultAnimation->currentTime() >= duration) {
-      defaultAnimation->setCurrentTime(0);
-      defaultAnimation->apply();
-      presentImmediately = true;
-    }
-  }
   playing = true;
 }
 
@@ -534,35 +530,6 @@ void PAGXView::setCurrentTimeMicros(int64_t micros) {
   }
 }
 
-void PAGXView::goToPreviousFrame() {
-  if (defaultAnimation == nullptr || defaultAnimation->frameRate() <= 0.0f) {
-    return;
-  }
-  // Stepping a frame always pauses playback first, matching the desktop client behavior.
-  pause();
-  int64_t frameDurationUs = static_cast<int64_t>(1000000.0 / defaultAnimation->frameRate());
-  int64_t newTime = defaultAnimation->currentTime() - frameDurationUs;
-  if (newTime < 0) {
-    newTime = 0;
-  }
-  setCurrentTimeMicros(newTime);
-}
-
-void PAGXView::goToNextFrame() {
-  if (defaultAnimation == nullptr || defaultAnimation->frameRate() <= 0.0f) {
-    return;
-  }
-  // Stepping a frame always pauses playback first, matching the desktop client behavior.
-  pause();
-  int64_t frameDurationUs = static_cast<int64_t>(1000000.0 / defaultAnimation->frameRate());
-  int64_t duration = defaultAnimation->duration();
-  int64_t newTime = defaultAnimation->currentTime() + frameDurationUs;
-  if (duration > 0 && newTime > duration) {
-    newTime = duration;
-  }
-  setCurrentTimeMicros(newTime);
-}
-
 void PAGXView::setLoop(bool loop) {
   loopEnabled = loop;
 }
diff --git a/playground/pagx-viewer/src/cpp/PAGXView.h b/playground/pagx-viewer/src/cpp/PAGXView.h
index 33ba0ef32a..60e1492e4a 100644
--- a/playground/pagx-viewer/src/cpp/PAGXView.h
+++ b/playground/pagx-viewer/src/cpp/PAGXView.h
@@ -87,8 +87,6 @@ class PAGXView {
   int64_t durationMicros() const;
   float currentFrameRate() const;
   void setCurrentTimeMicros(int64_t micros);
-  void goToPreviousFrame();
-  void goToNextFrame();
   void setLoop(bool loop);
   bool isLoop() const;
 
diff --git a/playground/pagx-viewer/src/cpp/binding.cpp b/playground/pagx-viewer/src/cpp/binding.cpp
index a455261dbe..ab7917213e 100644
--- a/playground/pagx-viewer/src/cpp/binding.cpp
+++ b/playground/pagx-viewer/src/cpp/binding.cpp
@@ -67,8 +67,6 @@ EMSCRIPTEN_BINDINGS(PAGXPlayground) {
           optional_override([](pagx::PAGXView& self, double micros) {
             self.setCurrentTimeMicros(static_cast<int64_t>(micros));
           }))
-      .function("_goToPreviousFrame", &pagx::PAGXView::goToPreviousFrame)
-      .function("_goToNextFrame", &pagx::PAGXView::goToNextFrame)
       .function("_setLoop", &pagx::PAGXView::setLoop)
       .function("_isLoop", &pagx::PAGXView::isLoop);
 }
diff --git a/playground/pagx-viewer/src/ts/pagx-view.ts b/playground/pagx-viewer/src/ts/pagx-view.ts
index 7695c152de..6412961ff4 100644
--- a/playground/pagx-viewer/src/ts/pagx-view.ts
+++ b/playground/pagx-viewer/src/ts/pagx-view.ts
@@ -348,24 +348,10 @@ export class PAGXView {
     }
   }
 
-  /**
-   * Goes to the previous frame. Pauses playback if currently playing.
-   */
-  public goToPreviousFrame(): void {
-    this.nativeView._goToPreviousFrame();
-  }
-
-  /**
-   * Goes to the next frame. Pauses playback if currently playing.
-   */
-  public goToNextFrame(): void {
-    this.nativeView._goToNextFrame();
-  }
-
   /**
    * Sets whether playback loops, overriding the loop mode stored in the file. When enabled, each
-   * cycle repeats (preserving PingPong mirroring); when disabled, playback stops at the last frame
-   * after a single pass.
+   * cycle repeats (preserving PingPong mirroring); when disabled, playback rewinds to the first
+   * frame and stops after a single pass.
    * @param loop true to loop, false to play once
    */
   public setLoop(loop: boolean): void {
diff --git a/playground/pagx-viewer/src/ts/types.ts b/playground/pagx-viewer/src/ts/types.ts
index 14af0bf545..29df55e463 100644
--- a/playground/pagx-viewer/src/ts/types.ts
+++ b/playground/pagx-viewer/src/ts/types.ts
@@ -166,19 +166,10 @@ export interface _PAGXView {
    */
   _setCurrentTimeMicros(micros: number): void;
 
-  /**
-   * Goes to the previous frame. Pauses if currently playing.
-   */
-  _goToPreviousFrame(): void;
-
-  /**
-   * Goes to the next frame. Pauses if currently playing.
-   */
-  _goToNextFrame(): void;
-
   /**
    * Sets whether playback loops, overriding the file's loop mode.
-   * @param loop true to repeat after each cycle, false to stop at the end after a single pass
+   * @param loop true to repeat after each cycle, false to rewind to the first frame and stop after
+   *   a single pass
    */
   _setLoop(loop: boolean): void;
 

From f10acdbb6dc999485743e160552bca2eed539616 Mon Sep 17 00:00:00 2001
From: ash <gracelllx@qq.com>
Date: Thu, 16 Jul 2026 14:33:12 +0800
Subject: [PATCH 08/10] style: polish icon effects and fix bugs

---
 .../src/editor/SourceEditor.ts                | 116 ++++++++----------
 .../pagx-playground/src/editor/index.ts       |  73 ++++++++++-
 .../pagx-playground/src/editor/styles.ts      |  31 +++--
 playground/pagx-playground/src/index.ts       |   9 +-
 playground/pagx-playground/static/index.css   |  50 +++++---
 playground/pagx-playground/static/index.html  |  27 ++--
 6 files changed, 201 insertions(+), 105 deletions(-)

diff --git a/playground/pagx-playground/src/editor/SourceEditor.ts b/playground/pagx-playground/src/editor/SourceEditor.ts
index 64c89925ac..b6f12612ee 100644
--- a/playground/pagx-playground/src/editor/SourceEditor.ts
+++ b/playground/pagx-playground/src/editor/SourceEditor.ts
@@ -53,74 +53,66 @@ export class SourceEditor {
         // Ctrl+Z from unwinding past the load point into an empty editor.
     }
 
+    private createState(initialContent: string): EditorState {
+        return EditorState.create({
+            doc: initialContent,
+            extensions: [
+                minimalSetup,
+                lineNumbers(),
+                xml(),
+                syntaxHighlighting(pagxHighlightStyle),
+                highlightSelectionMatches(),
+                // basicSetup includes searchKeymap which intercepts Ctrl+F. Use minimalSetup
+                // (which omits it) and add only the keymaps we need, so the browser's
+                // built-in Ctrl+F is free to handle search.
+                keymap.of([...defaultKeymap, ...historyKeymap]),
+                // Theme covers only CodeMirror internals that styles.ts does not target.
+                // Gutter and selection colors live in styles.ts (higher specificity overrides
+                // this theme anyway), so keeping them here would create two sources of truth.
+                EditorView.theme({
+                    '&': {
+                        backgroundColor: '#1E1E1E',
+                        color: '#D4D4D4',
+                        height: '100%',
+                    },
+                    '.cm-content': {
+                        fontFamily: 'Menlo, Monaco, "Courier New", monospace',
+                        fontSize: '13px',
+                        caretColor: '#FFFFFF',
+                    },
+                    '.cm-cursor': {
+                        borderLeftColor: '#FFFFFF',
+                        borderLeftWidth: '2px',
+                    },
+                    '.cm-activeLine': {
+                        backgroundColor: '#2D2D2D',
+                    },
+                    '.cm-activeLineGutter': {
+                        backgroundColor: '#2D2D2D',
+                    },
+                }),
+            ],
+        });
+    }
+
     private createView(initialContent: string): void {
         this.view = new EditorView({
             parent: this.host,
-            state: EditorState.create({
-                doc: initialContent,
-                extensions: [
-                    minimalSetup,
-                    lineNumbers(),
-                    xml(),
-                    syntaxHighlighting(pagxHighlightStyle),
-                    highlightSelectionMatches(),
-                    // basicSetup includes searchKeymap which intercepts Ctrl+F. Use minimalSetup
-                    // (which omits it) and add only the keymaps we need, so the browser's
-                    // built-in Ctrl+F is free to handle search.
-                    keymap.of([...defaultKeymap, ...historyKeymap]),
-                    EditorView.theme({
-                        '&': {
-                            backgroundColor: '#1E1E1E',
-                            color: '#D4D4D4',
-                            height: '100%',
-                        },
-                        '.cm-content': {
-                            fontFamily: 'Menlo, Monaco, "Courier New", monospace',
-                            fontSize: '13px',
-                            caretColor: '#FFFFFF',
-                        },
-                        '.cm-cursor': {
-                            borderLeftColor: '#FFFFFF',
-                            borderLeftWidth: '2px',
-                        },
-                        '.cm-gutters': {
-                            backgroundColor: '#1E1E1E',
-                            color: '#6E7681',
-                            border: 'none',
-                            borderRight: '1px solid #3C3C3C',
-                        },
-                        '.cm-activeLine': {
-                            backgroundColor: '#2D2D2D',
-                        },
-                        '.cm-activeLineGutter': {
-                            backgroundColor: '#2D2D2D',
-                        },
-                        '.cm-selectionBackground, ::selection': {
-                            backgroundColor: '#264F78',
-                        },
-                        '&.cm-focused .cm-selectionBackground': {
-                            backgroundColor: '#264F78',
-                        },
-                    }),
-                ],
-            }),
+            state: this.createState(initialContent),
         });
     }
 
-    /** Replaces the entire document content. */
+    /** Replaces the entire document content, resetting the undo history to this content. */
     setContent(text: string): void {
         const trimmed = text.charCodeAt(0) === 0xFEFF ? text.slice(1) : text;
         if (this.view === null) {
             this.createView(trimmed);
             return;
         }
-        this.view.dispatch({
-            changes: {
-                from: 0,
-                to: this.view.state.doc.length,
-                insert: trimmed,
-            },
-        });
+        // Rebuild the state instead of dispatching a change so the undo history is rooted at this
+        // content. A plain change dispatch would be recorded as an undoable edit, letting Ctrl+Z
+        // revert to a previously loaded file's content.
+        this.view.setState(this.createState(trimmed));
     }
 
     /** Returns the current document text. */
@@ -131,18 +123,6 @@ export class SourceEditor {
         return this.view.state.doc.toString();
     }
 
-    /** Moves keyboard focus into the editor. */
-    focus(): void {
-        if (this.view !== null) {
-            this.view.focus();
-        }
-    }
-
-    /** Returns the underlying CodeMirror view, or null if not yet created. */
-    getView(): EditorView | null {
-        return this.view;
-    }
-
     /** Releases the CodeMirror instance and frees DOM nodes. */
     destroy(): void {
         if (this.view !== null) {
diff --git a/playground/pagx-playground/src/editor/index.ts b/playground/pagx-playground/src/editor/index.ts
index 372ad0fafe..6f9d2d84ec 100644
--- a/playground/pagx-playground/src/editor/index.ts
+++ b/playground/pagx-playground/src/editor/index.ts
@@ -21,12 +21,19 @@ import { EDITOR_STYLES } from './styles';
 
 const MOBILE_BREAKPOINT = 768;
 const TOAST_DURATION_MS = 2000;
+// Resizing bounds: the panel never shrinks below MIN_PANEL_WIDTH, and always leaves at least
+// MIN_CANVAS_WIDTH for the preview area on the left.
+const MIN_PANEL_WIDTH = 320;
+const MIN_CANVAS_WIDTH = 360;
 
 let panel: HTMLElement | null = null;
 let editor: SourceEditor | null = null;
 let currentXmlText: string | null = null;
 let toastTimer: number | undefined;
 let toastEl: HTMLElement | null = null;
+let resizer: HTMLElement | null = null;
+let panelWidthPx: number | null = null;
+let resizing = false;
 
 /** Callbacks provided by the host application to apply/save XML changes. */
 export interface EditorCallbacks {
@@ -68,11 +75,13 @@ function showToast(message: string, success: boolean): void {
         return;
     }
     toastEl.textContent = message;
-    toastEl.className = `editor-toast visible ${success ? 'success' : 'error'}`;
+    toastEl.classList.add('visible');
+    toastEl.classList.toggle('success', success);
+    toastEl.classList.toggle('error', !success);
     window.clearTimeout(toastTimer);
     toastTimer = window.setTimeout(() => {
         if (toastEl !== null) {
-            toastEl.className = 'editor-toast';
+            toastEl.classList.remove('visible', 'success', 'error');
         }
     }, TOAST_DURATION_MS);
 }
@@ -108,6 +117,56 @@ function closePanel(): void {
     }
 }
 
+/** Applies a panel width in pixels, clamped to the resize bounds, via the --editor-width variable. */
+function applyPanelWidth(px: number): void {
+    const max = Math.max(MIN_PANEL_WIDTH, window.innerWidth - MIN_CANVAS_WIDTH);
+    const clamped = Math.max(MIN_PANEL_WIDTH, Math.min(px, max));
+    panelWidthPx = clamped;
+    document.documentElement.style.setProperty('--editor-width', `${clamped}px`);
+}
+
+function onResizeMove(event: PointerEvent): void {
+    if (!resizing) {
+        return;
+    }
+    applyPanelWidth(window.innerWidth - event.clientX);
+}
+
+function onResizeEnd(event: PointerEvent): void {
+    if (!resizing) {
+        return;
+    }
+    resizing = false;
+    document.body.style.userSelect = '';
+    document.body.style.cursor = '';
+    if (resizer !== null) {
+        resizer.classList.remove('dragging');
+        if (resizer.hasPointerCapture(event.pointerId)) {
+            resizer.releasePointerCapture(event.pointerId);
+        }
+    }
+}
+
+function onResizeStart(event: PointerEvent): void {
+    event.preventDefault();
+    resizing = true;
+    document.body.style.userSelect = 'none';
+    document.body.style.cursor = 'ew-resize';
+    if (resizer !== null) {
+        resizer.classList.add('dragging');
+        // Pointer capture routes subsequent pointermove/pointerup to the resizer even when the
+        // cursor leaves the browser window, avoiding a stuck resizing state on mouseup-loss.
+        resizer.setPointerCapture(event.pointerId);
+    }
+}
+
+/** Re-clamps the current panel width so the panel/canvas bounds stay valid after a window resize. */
+function onWindowResize(): void {
+    if (panelWidthPx !== null) {
+        applyPanelWidth(panelWidthPx);
+    }
+}
+
 export function togglePanel(): void {
     if (isPanelOpen()) {
         closePanel();
@@ -230,6 +289,16 @@ export function init(cb: EditorCallbacks): void {
         console.warn('SourceEditor: #editor-panel element not found, skipping init.');
         return;
     }
+    resizer = panel.querySelector<HTMLElement>('.editor-resizer');
+    if (resizer !== null) {
+        // Pointer events with setPointerCapture keep the drag alive even when the cursor leaves
+        // the window; pointermove/pointerup are attached to the resizer itself thanks to capture.
+        resizer.addEventListener('pointerdown', onResizeStart);
+        resizer.addEventListener('pointermove', onResizeMove);
+        resizer.addEventListener('pointerup', onResizeEnd);
+        resizer.addEventListener('pointercancel', onResizeEnd);
+    }
+    window.addEventListener('resize', onWindowResize);
     const closeBtn = panel.querySelector('.editor-close-btn');
     if (closeBtn !== null) {
         closeBtn.addEventListener('click', closePanel);
diff --git a/playground/pagx-playground/src/editor/styles.ts b/playground/pagx-playground/src/editor/styles.ts
index 85e2cb21e4..1ed7a14a26 100644
--- a/playground/pagx-playground/src/editor/styles.ts
+++ b/playground/pagx-playground/src/editor/styles.ts
@@ -23,7 +23,10 @@ export const EDITOR_STYLES = `
     top: 0;
     right: 0;
     bottom: 0;
-    width: 50%;
+    /* Width is driven by the --editor-width variable set while dragging the resizer; falls back
+       to 50% before any drag. min-width guards the CSS-only case against an overly narrow panel. */
+    width: var(--editor-width, 50%);
+    min-width: 320px;
     display: none;
     flex-direction: column;
     background: #1E1E1E;
@@ -31,12 +34,29 @@ export const EDITOR_STYLES = `
     z-index: 10;
 }
 
+#editor-panel .editor-resizer {
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    left: -3px;
+    width: 6px;
+    cursor: ew-resize;
+    z-index: 20;
+    background: transparent;
+    transition: background 0.15s ease;
+}
+
+#editor-panel .editor-resizer:hover,
+#editor-panel .editor-resizer.dragging {
+    background: #448EF9;
+}
+
 #editor-panel.visible {
     display: flex;
 }
 
 .container.with-editor {
-    width: 50%;
+    width: calc(100% - var(--editor-width, 50%));
     margin: 0;
 }
 
@@ -107,17 +127,14 @@ export const EDITOR_STYLES = `
     outline: none;
 }
 
-/* Selection highlight */
+/* Selection highlight. !important guards against CodeMirror's baseTheme and any focused-state
+   rule that may be injected inline; specificity alone is not always enough. */
 #editor-panel .editor-host .cm-editor .cm-selectionBackground,
 #editor-panel .editor-host .cm-editor.cm-focused .cm-selectionBackground,
 #editor-panel .editor-host .cm-editor ::selection {
     background-color: rgba(68, 142, 249, 0.35) !important;
 }
 
-#editor-panel .editor-host .cm-editor .cm-selectionLayer .cm-selectionBackground {
-    background-color: rgba(68, 142, 249, 0.35);
-}
-
 /* highlightSelectionMatches - subtle highlight for matching text under cursor */
 #editor-panel .editor-host .cm-editor .cm-selectionMatch {
     background-color: rgba(234, 179, 8, 0.15);
diff --git a/playground/pagx-playground/src/index.ts b/playground/pagx-playground/src/index.ts
index 7b9d06191c..b708951203 100644
--- a/playground/pagx-playground/src/index.ts
+++ b/playground/pagx-playground/src/index.ts
@@ -835,6 +835,7 @@ function showPlaybackBar(): void {
     if (hasAnimation) {
         playbackBar.classList.remove('hidden');
         updatePlaybackUI();
+        updateLoopIcon();
     } else {
         playbackBar.classList.add('hidden');
     }
@@ -910,14 +911,18 @@ function updateLoopIcon(): void {
     if (!playgroundState.pagxView || !loopBtn) {
         return;
     }
-    loopBtn.classList.toggle('active', playgroundState.pagxView.isLoop());
+    const looping = playgroundState.pagxView.isLoop();
+    loopBtn.classList.toggle('active', looping);
 }
 
 function updatePlaybackUI(): void {
     updatePlayPauseIcon();
     updateProgressSlider();
     updateTimeDisplay();
-    updateLoopIcon();
+    // updateLoopIcon is intentionally NOT called here: the loop state only changes on user
+    // click, so refreshing it on the 100ms playback tick would be wasted DOM work. Call sites
+    // that toggle the loop state (loop button handler, initial showPlaybackBar) update it
+    // explicitly.
 }
 
 function togglePlayback(): void {
diff --git a/playground/pagx-playground/static/index.css b/playground/pagx-playground/static/index.css
index c5e1346815..3fbe9a0083 100644
--- a/playground/pagx-playground/static/index.css
+++ b/playground/pagx-playground/static/index.css
@@ -440,6 +440,11 @@ html, body {
     padding: 12px 24px;
     background: #20202A;
     border-radius: 8px;
+    /* Lock the pill to its natural content width so a narrow viewport clips the sides evenly
+       instead of collapsing the internal controls (buttons, time display, progress bar). This
+       relies on the parent .container having overflow: hidden so the overflowing edges are
+       clipped rather than pushing the layout wider or leaking onto the editor panel. */
+    min-width: max-content;
 }
 
 .playback-bar.hidden {
@@ -494,8 +499,8 @@ html, body {
     display: block;
     width: 24px;
     height: 20px;
-    /* Nudge the arrow glyphs down a touch so they sit on the progress bar center line */
-    margin-top: 3px;
+    /* Nudge the arrow glyphs down so they sit on the progress bar center line */
+    margin-top: 5px;
 }
 
 /* Widen the gap between the prev/next frame buttons */
@@ -512,8 +517,12 @@ html, body {
 .time-display {
     display: flex;
     align-items: center;
+    /* Right-align so the frame counter stays close to the loop button; the fixed width keeps
+       the bar length stable while the time/frame digit counts change, absorbing slack on the left. */
+    justify-content: flex-end;
     gap: 16px;
     margin-left: 8px;
+    width: 168px;
     color: #ffffff;
     font-size: 12px;
     font-variant-numeric: tabular-nums;
@@ -526,9 +535,9 @@ html, body {
     background: rgba(255, 255, 255, 0.28);
 }
 
-/* Loop toggle - always a white loop icon. When looping is off (no .active class) a diagonal slash
-   is overlaid to signal a "no loop" state. The inline SVG follows the button's currentColor so the
-   state switch needs no swapped image assets. */
+/* Loop toggle - shows the sequence (repeat) icon when looping is off, and the single (repeat-one,
+   marked with a "1") icon when looping is on. Both inline SVGs follow the button's currentColor so
+   the state switch needs no swapped image assets. */
 .playback-btn-loop {
     width: 24px;
     height: 48px;
@@ -543,26 +552,25 @@ html, body {
     height: 20px;
 }
 
-/* The slash is hidden while looping (.active) and revealed when it is off. The thicker
-   background-colored line underneath cuts a gap so the white slash reads clearly over the arrows. */
-.playback-btn-loop .loop-slash,
-.playback-btn-loop .loop-slash-bg {
-    display: none;
+/* The single-loop icon uses a wider viewBox (26x20) to accommodate the arrowhead protruding
+   from the rounded rectangle, so it needs a wider box to stay in proportion. */
+.playback-btn-loop .loop-icon-single {
+    width: 24px;
+    height: 18px;
 }
 
-.playback-btn-loop:not(.active) .loop-slash,
-.playback-btn-loop:not(.active) .loop-slash-bg {
-    display: block;
+/* The icon reflects the current playback mode: play-once shows the "1" (single) icon,
+   loop shows the sequence-loop icon. */
+.playback-btn-loop .loop-icon-sequence {
+    display: none;
 }
 
-.loop-slash-bg {
-    stroke: #20202A;
-    stroke-width: 4;
+.playback-btn-loop.active .loop-icon-single {
+    display: none;
 }
 
-.loop-slash {
-    stroke: currentColor;
-    stroke-width: 2;
+.playback-btn-loop.active .loop-icon-sequence {
+    display: block;
 }
 
 .progress-slider {
@@ -633,6 +641,9 @@ html, body {
         left: 16px;
         right: 16px;
         transform: none;
+        /* Override the desktop min-width: on narrow layouts the bar stretches with the viewport
+           and its internal controls shrink instead of overflowing. */
+        min-width: 0;
     }
 
     .progress-wrapper {
@@ -779,3 +790,4 @@ html, body {
         margin-left: 4px;
     }
 }
+
diff --git a/playground/pagx-playground/static/index.html b/playground/pagx-playground/static/index.html
index aa4f84fee4..383050e750 100644
--- a/playground/pagx-playground/static/index.html
+++ b/playground/pagx-playground/static/index.html
@@ -93,6 +93,7 @@
         </button>
     </div>
     <div id="editor-panel">
+        <div class="editor-resizer" title="Drag to resize"></div>
         <div class="editor-header">
             <span class="editor-title">Source Editor</span>
             <button class="editor-close-btn" title="Close (L)">
@@ -142,13 +143,13 @@ <h1 class="title">PAGX Playground</h1>
         </div>
     </div>
     <div id="playback-bar" class="playback-bar hidden">
-        <button id="play-pause-btn" class="playback-btn playback-btn-primary" title="Play / Pause (Space)">
+        <button id="play-pause-btn" class="playback-btn playback-btn-primary" aria-label="Play / Pause">
             <img id="play-pause-img" src="./play.png" alt="Play / Pause" draggable="false"/>
         </button>
-        <button id="prev-frame-btn" class="playback-btn playback-btn-step" title="Previous Frame">
+        <button id="prev-frame-btn" class="playback-btn playback-btn-step" aria-label="Previous Frame">
             <img src="./previous.png" alt="Previous Frame" draggable="false"/>
         </button>
-        <button id="next-frame-btn" class="playback-btn playback-btn-step" title="Next Frame">
+        <button id="next-frame-btn" class="playback-btn playback-btn-step" aria-label="Next Frame">
             <img src="./next.png" alt="Next Frame" draggable="false"/>
         </button>
         <div class="progress-wrapper">
@@ -159,14 +160,26 @@ <h1 class="title">PAGX Playground</h1>
             <span class="time-divider"></span>
             <span id="frame-text" class="frame-text">0 / 0</span>
         </div>
-        <button id="loop-btn" class="playback-btn playback-btn-loop" title="Loop">
-            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+        <button id="loop-btn" class="playback-btn playback-btn-loop" aria-label="Loop">
+            <svg class="loop-icon-sequence" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
                 <polyline points="17 1 21 5 17 9"></polyline>
                 <path d="M3 11V9a4 4 0 0 1 4-4h14"></path>
                 <polyline points="7 23 3 19 7 15"></polyline>
                 <path d="M21 13v2a4 4 0 0 1-4 4H3"></path>
-                <line class="loop-slash-bg" x1="3" y1="21" x2="21" y2="3"></line>
-                <line class="loop-slash" x1="3" y1="21" x2="21" y2="3"></line>
+            </svg>
+            <svg class="loop-icon-single" viewBox="0 0 26 20" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                <!-- Flat rounded-rectangle loop with an independent chevron arrowhead attached at
+                     the top-right. The outline is a full closed rounded rectangle; the arrowhead is
+                     a separate ">"-shaped polyline whose vertex sits exactly on the top edge of the
+                     rectangle, so the two strokes visually merge without leaving a gap. This matches
+                     the Feather-Icons "repeat" style used by the sibling loop-icon above. -->
+                <path d="M20 6v8a3 3 0 0 1-3 3H5a3 3 0 0 1-3-3V6a3 3 0 0 1 3-3h14"></path>
+                <polyline points="15 1 19 3 15 5"></polyline>
+                <!-- Digit "1": a single polyline (short top serif joined into the vertical stem)
+                     so the two strokes share a proper round-join instead of stacking two round caps.
+                     The serif is intentionally short and centered inside the rounded rectangle to
+                     stop it from visually merging with the outline. -->
+                <polyline points="10 8 11 7.2 11 14"></polyline>
             </svg>
         </button>
     </div>

From 01e3e652f398027c340ca81a5847c1c3125b26f4 Mon Sep 17 00:00:00 2001
From: ash <gracelllx@qq.com>
Date: Thu, 16 Jul 2026 15:21:07 +0800
Subject: [PATCH 09/10] code format

---
 playground/pagx-viewer/src/cpp/binding.cpp | 24 ++++++++--------------
 1 file changed, 9 insertions(+), 15 deletions(-)

diff --git a/playground/pagx-viewer/src/cpp/binding.cpp b/playground/pagx-viewer/src/cpp/binding.cpp
index ab7917213e..e701895834 100644
--- a/playground/pagx-viewer/src/cpp/binding.cpp
+++ b/playground/pagx-viewer/src/cpp/binding.cpp
@@ -51,22 +51,16 @@ EMSCRIPTEN_BINDINGS(PAGXPlayground) {
       .function("_pause", &pagx::PAGXView::pause)
       .function("_isPlaying", &pagx::PAGXView::isPlaying)
       // Wrap int64_t returns/params as double: emscripten::bind does not support 64-bit integers.
-      .function(
-          "_currentTimeMicros",
-          optional_override([](pagx::PAGXView& self) -> double {
-            return static_cast<double>(self.currentTimeMicros());
-          }))
-      .function(
-          "_durationMicros",
-          optional_override([](pagx::PAGXView& self) -> double {
-            return static_cast<double>(self.durationMicros());
-          }))
+      .function("_currentTimeMicros", optional_override([](pagx::PAGXView& self) -> double {
+                  return static_cast<double>(self.currentTimeMicros());
+                }))
+      .function("_durationMicros", optional_override([](pagx::PAGXView& self) -> double {
+                  return static_cast<double>(self.durationMicros());
+                }))
       .function("_currentFrameRate", &pagx::PAGXView::currentFrameRate)
-      .function(
-          "_setCurrentTimeMicros",
-          optional_override([](pagx::PAGXView& self, double micros) {
-            self.setCurrentTimeMicros(static_cast<int64_t>(micros));
-          }))
+      .function("_setCurrentTimeMicros", optional_override([](pagx::PAGXView& self, double micros) {
+                  self.setCurrentTimeMicros(static_cast<int64_t>(micros));
+                }))
       .function("_setLoop", &pagx::PAGXView::setLoop)
       .function("_isLoop", &pagx::PAGXView::isLoop);
 }

From 76f66039ceca984b66853db93a794fa014ee1306 Mon Sep 17 00:00:00 2001
From: ash <gracelllx@qq.com>
Date: Mon, 20 Jul 2026 17:02:58 +0800
Subject: [PATCH 10/10] Update according to review comments

---
 playground/pagx-playground/package.json       |  5 +-
 playground/pagx-playground/scripts/rollup.js  |  4 +-
 .../src/editor/SourceEditor.ts                | 19 ++++-
 playground/pagx-playground/src/index.ts       | 74 +++++++++++++------
 playground/pagx-viewer/src/cpp/PAGXView.cpp   |  8 +-
 playground/pagx-viewer/src/cpp/PAGXView.h     |  2 +-
 playground/pagx-viewer/src/cpp/binding.cpp    |  2 +-
 playground/pagx-viewer/src/ts/pagx-view.ts    |  4 +-
 playground/pagx-viewer/src/ts/types.ts        |  2 +-
 9 files changed, 81 insertions(+), 39 deletions(-)

diff --git a/playground/pagx-playground/package.json b/playground/pagx-playground/package.json
index fbf136db8c..bddb4ae8e3 100644
--- a/playground/pagx-playground/package.json
+++ b/playground/pagx-playground/package.json
@@ -11,8 +11,8 @@
     "build": "npm run prebuild && rollup -c ./scripts/rollup.js",
     "build:release": "node scripts/prebuild.js --release && BUILD_MODE=release rollup -c ./scripts/rollup.js",
     "prebuild:st": "node scripts/prebuild.js --arch st",
-    "build:st": "npm run prebuild:st && ARCH=wasm rollup -c ./scripts/rollup.js",
-    "build:release:st": "node scripts/prebuild.js --arch st --release && ARCH=wasm BUILD_MODE=release rollup -c ./scripts/rollup.js",
+    "build:st": "npm run prebuild:st && ARCH=st rollup -c ./scripts/rollup.js",
+    "build:release:st": "node scripts/prebuild.js --arch st --release && ARCH=st BUILD_MODE=release rollup -c ./scripts/rollup.js",
     "publish": "node scripts/publish.js",
     "server": "node static/server.js"
   },
@@ -38,7 +38,6 @@
     "@codemirror/state": "^6.7.1",
     "@codemirror/view": "^6.43.6",
     "@lezer/highlight": "^1.2.3",
-    "codemirror": "^6.0.2",
     "express": "^4.21.1",
     "highlight.js": "^11.9.0",
     "marked": "^15.0.0",
diff --git a/playground/pagx-playground/scripts/rollup.js b/playground/pagx-playground/scripts/rollup.js
index 4a75005896..1033e61294 100644
--- a/playground/pagx-playground/scripts/rollup.js
+++ b/playground/pagx-playground/scripts/rollup.js
@@ -38,9 +38,9 @@ const banner = existsSync(fileHeaderPath) ? readFileSync(fileHeaderPath, 'utf-8'
 const isRelease = process.env.BUILD_MODE === 'release';
 
 // Detect the pagx-viewer arch by checking which glue file was copied into wasm-mt/.
-// This must stay in sync with prebuild.js's auto-detection logic.
+// This must stay in sync with prebuild.js's auto-detection logic (both accept ARCH=st|mt).
 function detectGlueInfix() {
-  if (process.env.ARCH === 'wasm') return '.st';
+  if (process.env.ARCH === 'st') return '.st';
   if (process.env.ARCH === 'mt') return '';
   // No explicit ARCH env: check which .esm.js actually exists.
   if (!existsSync(path.join(playgroundRoot, 'wasm-mt/pagx-viewer.esm.js'))
diff --git a/playground/pagx-playground/src/editor/SourceEditor.ts b/playground/pagx-playground/src/editor/SourceEditor.ts
index b6f12612ee..e7880d3511 100644
--- a/playground/pagx-playground/src/editor/SourceEditor.ts
+++ b/playground/pagx-playground/src/editor/SourceEditor.ts
@@ -16,15 +16,26 @@
 //
 /////////////////////////////////////////////////////////////////////////////////////////////////
 
-import { EditorView, keymap, lineNumbers } from '@codemirror/view';
+import { EditorView, keymap, lineNumbers, highlightSpecialChars, drawSelection } from '@codemirror/view';
 import { EditorState } from '@codemirror/state';
-import { minimalSetup } from 'codemirror';
-import { defaultKeymap, historyKeymap } from '@codemirror/commands';
+import { defaultKeymap, historyKeymap, history } from '@codemirror/commands';
 import { xml } from '@codemirror/lang-xml';
-import { syntaxHighlighting, HighlightStyle } from '@codemirror/language';
+import { syntaxHighlighting, HighlightStyle, defaultHighlightStyle } from '@codemirror/language';
 import { highlightSelectionMatches } from '@codemirror/search';
 import { tags } from '@lezer/highlight';
 
+// Inline replacement for the `codemirror` meta-package's `minimalSetup`. We depend directly on
+// the @codemirror/* sub-packages so npm never has to reconcile the meta-package's own version
+// pins against ours (mismatched pins spawn duplicate EditorState instances, which then trip
+// instanceof checks inside CodeMirror at runtime). Sourced from codemirror v6's minimalSetup.
+const minimalSetup = [
+    highlightSpecialChars(),
+    history(),
+    drawSelection(),
+    syntaxHighlighting(defaultHighlightStyle, { fallback: true }),
+    keymap.of([...defaultKeymap, ...historyKeymap]),
+];
+
 /** Syntax highlight colors matching the desktop client (VS Code Dark+ palette). */
 const pagxHighlightStyle = HighlightStyle.define([
     { tag: tags.tagName, color: '#569CD6' },
diff --git a/playground/pagx-playground/src/index.ts b/playground/pagx-playground/src/index.ts
index b708951203..4d84278b82 100644
--- a/playground/pagx-playground/src/index.ts
+++ b/playground/pagx-playground/src/index.ts
@@ -849,7 +849,7 @@ function formatTime(microseconds: number): string {
 function getCurrentFrame(): number {
     const view = playgroundState.pagxView;
     if (!view) return 0;
-    const rate = view.currentFrameRate();
+    const rate = view.frameRate();
     if (rate <= 0) return 0;
     return Math.round(Math.max(0, view.currentTimeMicros()) * rate / 1_000_000);
 }
@@ -857,7 +857,7 @@ function getCurrentFrame(): number {
 function getTotalFrames(): number {
     const view = playgroundState.pagxView;
     if (!view) return 0;
-    const rate = view.currentFrameRate();
+    const rate = view.frameRate();
     if (rate <= 0) return 0;
     return Math.ceil(view.durationMicros() * rate / 1_000_000);
 }
@@ -951,7 +951,7 @@ function stepFrame(direction: number): void {
     if (!view) {
         return;
     }
-    const rate = view.currentFrameRate();
+    const rate = view.frameRate();
     const duration = view.durationMicros();
     if (rate <= 0 || duration <= 0) {
         return;
@@ -964,12 +964,9 @@ function stepFrame(direction: number): void {
 }
 
 function hidePlaybackUI(): void {
-    const canvas = document.getElementById('pagx-canvas') as HTMLCanvasElement;
-    const toolbar = document.getElementById('toolbar') as HTMLDivElement;
-    const playbackBar = document.getElementById('playback-bar') as HTMLDivElement;
-    canvas.classList.add('hidden');
-    toolbar.classList.add('hidden');
-    playbackBar.classList.add('hidden');
+    document.getElementById('pagx-canvas')?.classList.add('hidden');
+    document.getElementById('toolbar')?.classList.add('hidden');
+    document.getElementById('playback-bar')?.classList.add('hidden');
 }
 
 const DEFAULT_TITLE = 'PAGX Playground';
@@ -979,14 +976,10 @@ function goHome(pushHistory: boolean = true): void {
         playgroundState.pagxView.clear();
         gestureManager.resetTransform(playgroundState);
     }
-    const canvas = document.getElementById('pagx-canvas') as HTMLCanvasElement;
-    const toolbar = document.getElementById('toolbar') as HTMLDivElement;
-    const navBtns = document.getElementById('nav-btns') as HTMLDivElement;
-    const playbackBar = document.getElementById('playback-bar') as HTMLDivElement;
-    canvas.classList.add('hidden');
-    toolbar.classList.add('hidden');
-    playbackBar.classList.add('hidden');
-    navBtns.classList.remove('hidden');
+    document.getElementById('pagx-canvas')?.classList.add('hidden');
+    document.getElementById('toolbar')?.classList.add('hidden');
+    document.getElementById('playback-bar')?.classList.add('hidden');
+    document.getElementById('nav-btns')?.classList.remove('hidden');
     document.title = DEFAULT_TITLE;
     showDropZoneUI();
     currentPlayingFile = null;
@@ -1039,6 +1032,17 @@ async function loadExternalFiles(baseURL: string): Promise<void> {
     await Promise.all(fetches);
 }
 
+// Shared post-reparse UI refresh. Any call site that runs parsePAGX + buildLayers must invoke
+// this so the canvas backing store, playback bar visibility and playback UI values stay in sync
+// with the newly parsed document; forgetting it leaves the UI stuck on the previous file's
+// duration/dimensions.
+function refreshUIAfterReparse(): void {
+    updateSize();
+    // showPlaybackBar handles the static-image case (duration === 0 → hide) and refreshes the
+    // slider / time / loop icon internally when the bar becomes visible.
+    showPlaybackBar();
+}
+
 async function loadPAGXData(data: Uint8Array, name: string, baseURL: string) {
     const navBtns = document.getElementById('nav-btns') as HTMLDivElement;
     const toolbar = document.getElementById('toolbar') as HTMLDivElement;
@@ -1056,14 +1060,13 @@ async function loadPAGXData(data: Uint8Array, name: string, baseURL: string) {
     // opened file starts fresh instead of inheriting the previous file's loop toggle.
     playgroundState.pagxView.setLoop(true);
     gestureManager.resetTransform(playgroundState);
-    updateSize();
+    refreshUIAfterReparse();
     // Draw the first frame before showing canvas to avoid flashing old content
     playgroundState.pagxView.draw();
     hideDropZone();
     canvas.classList.remove('hidden');
     toolbar.classList.remove('hidden');
     navBtns.classList.add('hidden');
-    showPlaybackBar();
     document.title = 'PAGX Playground - ' + name;
     currentFileName = name;
 
@@ -1342,19 +1345,35 @@ function setupPlaybackControls(): void {
         });
     }
 
-    // Keyboard shortcut: Space for play/pause
+    // Keyboard shortcuts: Space toggles play/pause, ArrowLeft/ArrowRight step one frame.
+    // Guards are shared across shortcuts:
+    //   - text-entry targets (input/textarea/contentEditable) never trigger playback shortcuts;
+    //   - when the progress slider itself holds focus, ArrowLeft/Right must fall through to the
+    //     native range control (fine-grained scrub) rather than jumping a whole frame; Space
+    //     however still toggles playback so the user can pause without leaving the slider;
+    //   - no file loaded (canvas hidden) → do nothing so the shortcut can't be misused before
+    //     the drop-zone is dismissed.
     document.addEventListener('keydown', (e: KeyboardEvent) => {
-        if (e.code !== 'Space') return;
-        // Ignore only text entry fields; the range slider must still respond to Space.
+        const isPlayPause = e.code === 'Space';
+        const stepDirection = e.code === 'ArrowLeft' ? -1 : e.code === 'ArrowRight' ? 1 : 0;
+        if (!isPlayPause && stepDirection === 0) return;
         const target = e.target;
         const isTextInput =
             (target instanceof HTMLInputElement && target.type !== 'range') ||
-            target instanceof HTMLTextAreaElement;
+            target instanceof HTMLTextAreaElement ||
+            (target instanceof HTMLElement && target.isContentEditable);
         if (isTextInput) return;
+        // Range slider owns Arrow keys for scrub; only Space passes through to play/pause.
+        const isRangeSlider = target instanceof HTMLInputElement && target.type === 'range';
+        if (isRangeSlider && !isPlayPause) return;
         const canvas = document.getElementById('pagx-canvas');
         if (!canvas || canvas.classList.contains('hidden')) return;
         e.preventDefault();
-        togglePlayback();
+        if (isPlayPause) {
+            togglePlayback();
+        } else {
+            stepFrame(stepDirection);
+        }
     });
 
     // Update playback UI periodically. Also fire once on the play -> stop transition so the slider,
@@ -1585,6 +1604,12 @@ if (typeof window !== 'undefined') {
 
         // Encodes XML, reparses and redraws the view. Shared by the editor's Apply
         // and Save actions. Returns '' on success, otherwise an error message.
+        //
+        // Runs the same UI refresh as loadPAGXData's post-parse step so that an edit which
+        // changes the canvas dimensions (width/height attrs) or the animation duration (static
+        // ↔ animated) is fully reflected: canvas backing store is resized, the playback bar
+        // shows/hides, and the time/frame display picks up the new duration instead of showing
+        // the previous file's values.
         const applyXmlToView = (xmlText: string): string => {
             if (playgroundState.pagxView === null) {
                 return 'PAGXView not initialized';
@@ -1593,6 +1618,7 @@ if (typeof window !== 'undefined') {
                 const data = new TextEncoder().encode(xmlText);
                 playgroundState.pagxView.parsePAGX(data);
                 playgroundState.pagxView.buildLayers();
+                refreshUIAfterReparse();
                 playgroundState.pagxView.draw();
                 return '';
             } catch (e) {
diff --git a/playground/pagx-viewer/src/cpp/PAGXView.cpp b/playground/pagx-viewer/src/cpp/PAGXView.cpp
index 5f3437d46c..3b9402510b 100644
--- a/playground/pagx-viewer/src/cpp/PAGXView.cpp
+++ b/playground/pagx-viewer/src/cpp/PAGXView.cpp
@@ -511,13 +511,19 @@ int64_t PAGXView::durationMicros() const {
   return 0;
 }
 
-float PAGXView::currentFrameRate() const {
+float PAGXView::frameRate() const {
   if (defaultAnimation != nullptr) {
     return defaultAnimation->frameRate();
   }
   return 0.0f;
 }
 
+// Known limitation: seek only repositions the default (top-level) animation. Nested
+// auto-playing compositions rendered by `scene` are delta-driven via advanceAndApply() and have
+// no absolute-time entry point, so their frame lags behind the main timeline after a scrub:
+// the main animation jumps to `micros` while the nested compositions stay wherever their
+// accumulated delta left them. Acceptable for the MVP viewer; a future fix would need per-scene
+// seek support (or a full scene rebuild) rather than a workaround here.
 void PAGXView::setCurrentTimeMicros(int64_t micros) {
   if (defaultAnimation != nullptr) {
     defaultAnimation->setCurrentTime(micros);
diff --git a/playground/pagx-viewer/src/cpp/PAGXView.h b/playground/pagx-viewer/src/cpp/PAGXView.h
index 60e1492e4a..e04b2aa061 100644
--- a/playground/pagx-viewer/src/cpp/PAGXView.h
+++ b/playground/pagx-viewer/src/cpp/PAGXView.h
@@ -85,7 +85,7 @@ class PAGXView {
   bool isPlaying() const;
   int64_t currentTimeMicros() const;
   int64_t durationMicros() const;
-  float currentFrameRate() const;
+  float frameRate() const;
   void setCurrentTimeMicros(int64_t micros);
   void setLoop(bool loop);
   bool isLoop() const;
diff --git a/playground/pagx-viewer/src/cpp/binding.cpp b/playground/pagx-viewer/src/cpp/binding.cpp
index e701895834..c25afe31be 100644
--- a/playground/pagx-viewer/src/cpp/binding.cpp
+++ b/playground/pagx-viewer/src/cpp/binding.cpp
@@ -57,7 +57,7 @@ EMSCRIPTEN_BINDINGS(PAGXPlayground) {
       .function("_durationMicros", optional_override([](pagx::PAGXView& self) -> double {
                   return static_cast<double>(self.durationMicros());
                 }))
-      .function("_currentFrameRate", &pagx::PAGXView::currentFrameRate)
+      .function("_frameRate", &pagx::PAGXView::frameRate)
       .function("_setCurrentTimeMicros", optional_override([](pagx::PAGXView& self, double micros) {
                   self.setCurrentTimeMicros(static_cast<int64_t>(micros));
                 }))
diff --git a/playground/pagx-viewer/src/ts/pagx-view.ts b/playground/pagx-viewer/src/ts/pagx-view.ts
index 6412961ff4..573cef3af7 100644
--- a/playground/pagx-viewer/src/ts/pagx-view.ts
+++ b/playground/pagx-viewer/src/ts/pagx-view.ts
@@ -333,8 +333,8 @@ export class PAGXView {
   /**
    * Returns the frame rate of the animation. Returns 0 if no content is loaded.
    */
-  public currentFrameRate(): number {
-    return this.nativeView._currentFrameRate();
+  public frameRate(): number {
+    return this.nativeView._frameRate();
   }
 
   /**
diff --git a/playground/pagx-viewer/src/ts/types.ts b/playground/pagx-viewer/src/ts/types.ts
index 29df55e463..fd7fbd8ce9 100644
--- a/playground/pagx-viewer/src/ts/types.ts
+++ b/playground/pagx-viewer/src/ts/types.ts
@@ -158,7 +158,7 @@ export interface _PAGXView {
   /**
    * Returns the frame rate of the animation.
    */
-  _currentFrameRate(): number;
+  _frameRate(): number;
 
   /**
    * Sets the current playback time in microseconds.