@muxiuesd/dsh-pixel-studio 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 更新记录
 
+## 0.3.1
+
+- 修复选区导致画布跳动：拖出选框时不再重新适应视图 / 改变缩放，撤销历史也不会被清空（此前选区变化会连带重建渲染回调、重新加载作品）。
+- 修复「剪切」把内容从画布上抹掉：现在剪切 = 复制 + 抬起为浮动选区，像素仍显示在画布上并跟随选框，点「✓ 完成」才落到新位置，「✕ 取消」还原；`Delete` / 「清除」依旧立即抹除。
+- 新增剪贴板：`Ctrl/Cmd+C` 复制、`Ctrl/Cmd+X` 剪切、`Ctrl/Cmd+V` 粘贴到选区位置（无选区时贴到左上角）。
+- 拖拽期间忽略滚轮：拖动选框或画笔时，触控板滚动不会再缩放或平移画布。
+- 主按钮文字随底色自适应：深色底白字、浅色底深色字，切换浅色 / 深色主题时自动更新。
+- 选区浮动预览只合并被抬起的图层，不再把其他图层的像素复制进当前层。
+
+## 0.3.0
+
+- 新增矩形选区（工具 `M`）：在画布上拖出选框，拖动框内只移动选框，`Shift + 拖动`（或工具条「抓着像素」）带着像素一起移动，方向键微调 1 像素（`Shift` 10 像素），`Ctrl+A` 全选，`Esc` 取消。
+- 选区操作：水平 / 垂直镜像、填充（当前色）、删除，默认作用当前图层，工具条上的「多层」开关或按住 `Alt` 时作用于全部可见图层；每个操作一条撤销。
+- 选区时画布底部浮出工具条，顶栏显示 `选区 12×8 @ (4,3)`；蚂蚁线画在渲染层，不污染像素。
+- 撤销历史带上画布尺寸与选区状态，切换作品、改尺寸、撤销回放会自动清空选区。
+
 ## 0.2.0
 
 - 新增「打开图片」：把 PNG / JPEG / GIF / WebP / BMP 直接转成像素画，自动缩到 256 以内，可选自动提取配色（中位切分）/ 当前调色板 / PICO-8，可开 Floyd–Steinberg 抖动，导入前先看预览。

package/README.md

@@ -20,6 +20,7 @@ dsh plugin --profile web add /绝对路径/dsh-pixel
 
 - **画布**：整数倍缩放 `1×…64×`，滚轮以光标为锚点；空格/中键拖动平移，`F` 适应窗口；`4×` 以上显示格线（可关）。
 - **工具**：铅笔、橡皮、油漆桶（按合成后的颜色判断连通，视觉同色一次填满）、吸管；方形笔刷 `1–8` 像素。
+- **选区**（`M`）：拖出矩形选框；拖动框内只移框，`Shift + 拖动` 带像素一起走；镜像 / 填充 / 删除默认作用当前图层，「多层」或 `Alt` 作用全部可见层；方向键微调，`Ctrl+A` 全选，`Esc` 取消。
 - **图层**：最多 8 层，新建/复制/合并/上移/下移/删除/改名/显隐，全部可撤销。
 - **调色板**：最多 36 色，内置 PICO-8 等预设板；改某个槽位的颜色**不会改动已经画好的像素**（画布上的旧颜色会先由一个空闲槽位接手），也可以用系统取色器可视化取色。
 - **作品**：新建时填名字和尺寸（1–256），另有 11 个常用尺寸预设；自动保存。
@@ -32,6 +33,13 @@ dsh plugin --profile web add /绝对路径/dsh-pixel
 | 键 | 作用 |
 | --- | --- |
 | `B` / `E` / `G` / `I` | 铅笔 / 橡皮 / 油漆桶 / 吸管 |
+| `M` | 矩形选区 |
+| `Ctrl/Cmd+A` | 全选选区 |
+| `Esc` | 取消选区（浮动的内容回到原处） |
+| `Delete` / `Backspace` | 删除选区内像素 |
+| `Ctrl/Cmd+C` / `Ctrl/Cmd+X` / `Ctrl/Cmd+V` | 复制 / 剪切（内容留在画布上） / 粘贴 |
+| `Shift + H` / `Shift + V` / `Shift + F` | 选区水平镜像 / 垂直镜像 / 填充 |
+| 方向键（配合选区） | 微调选区 1 像素，`Shift` 为 10 像素 |
 | `[` `]` | 笔刷变小 / 变大 |
 | `H` | 格线开关 |
 | `F` | 适应窗口 |

package/client.js

@@ -83,6 +83,7 @@ window.__ModuleLoader__.load({
             { id: 'eraser', label: '橡皮', key: 'E', icon: 'eraser' },
             { id: 'bucket', label: '油漆桶', key: 'G', icon: 'bucket' },
             { id: 'picker', label: '吸管', key: 'I', icon: 'picker' },
+            { id: 'select', label: '选区', key: 'M', icon: 'select' },
         ];
 
         /* ------------------------------------------------------------------ */
@@ -402,6 +403,177 @@ window.__ModuleLoader__.load({
             return next;
         }
 
+        /* ------------------------------------------------------------------ */
+        /* selection                                                          */
+        /* ------------------------------------------------------------------ */
+
+        const MIN_SELECTION = 1;
+
+        /** Normalised rectangle spanning two grid cells (both inclusive). */
+        function selectionBetween(a, b) {
+            return {
+                x: Math.min(a.x, b.x),
+                y: Math.min(a.y, b.y),
+                w: Math.abs(a.x - b.x) + 1,
+                h: Math.abs(a.y - b.y) + 1,
+            };
+        }
+
+        /** Keeps a rectangle inside the canvas, shrinking it at the far edges. */
+        function clampRectangle(rect, width, height) {
+            const x = clamp(Math.round(rect.x), 0, Math.max(0, width - MIN_SELECTION));
+            const y = clamp(Math.round(rect.y), 0, Math.max(0, height - MIN_SELECTION));
+            const w = clamp(Math.round(rect.w), MIN_SELECTION, Math.max(MIN_SELECTION, width - x));
+            const h = clamp(Math.round(rect.h), MIN_SELECTION, Math.max(MIN_SELECTION, height - y));
+            return { x, y, w, h };
+        }
+
+        /** Slides a rectangle to (x, y) without changing its size or leaving the canvas. */
+        function moveRectangle(rect, x, y, width, height) {
+            return {
+                x: clamp(Math.round(x), 0, Math.max(0, width - rect.w)),
+                y: clamp(Math.round(y), 0, Math.max(0, height - rect.h)),
+                w: rect.w,
+                h: rect.h,
+            };
+        }
+
+        function pointInRectangle(rect, cell) {
+            return cell.x >= rect.x && cell.x < rect.x + rect.w && cell.y >= rect.y && cell.y < rect.y + rect.h;
+        }
+
+        /** Copies the selected characters out of one layer, padding short rows. */
+        function readRegion(rows, rect) {
+            const region = [];
+            for (let y = 0; y < rect.h; y += 1) {
+                const line = rows[rect.y + y] || '';
+                region.push(line.slice(rect.x, rect.x + rect.w).padEnd(rect.w, '.'));
+            }
+            return region;
+        }
+
+        /** Writes characters back into one layer, leaving every other cell untouched. */
+        function writeRegion(rows, region, x, y) {
+            const next = rows.slice();
+            for (let row = 0; row < region.length; row += 1) {
+                const target = y + row;
+                if (target < 0 || target >= next.length) continue;
+                const chars = (next[target] || '').split('');
+                for (let column = 0; column < region[row].length; column += 1) {
+                    const at = x + column;
+                    if (at >= 0 && at < chars.length) chars[at] = region[row][column] || '.';
+                }
+                next[target] = chars.join('');
+            }
+            return next;
+        }
+
+        function blankRegion(rect) {
+            const region = [];
+            for (let y = 0; y < rect.h; y += 1) region.push('.'.repeat(rect.w));
+            return region;
+        }
+
+        function fillRows(rows, rect, ch) {
+            const region = [];
+            for (let y = 0; y < rect.h; y += 1) region.push(ch.repeat(rect.w));
+            return writeRegion(rows, region, rect.x, rect.y);
+        }
+
+        function emptyRows(rows, rect) {
+            return writeRegion(rows, blankRegion(rect), rect.x, rect.y);
+        }
+
+        /** Mirrors the selected characters inside the box. */
+        function mirrorRows(rows, rect, horizontal) {
+            const region = readRegion(rows, rect);
+            const flipped = horizontal
+                ? region.map((line) => line.split('').reverse().join(''))
+                : region.slice().reverse();
+            return writeRegion(rows, flipped, rect.x, rect.y);
+        }
+
+        /** Top-most visible character in every cell of the rectangle, for the move preview. */
+        function mergedRegion(layers, rect) {
+            const region = blankRegion(rect);
+            layers.forEach((layer) => {
+                if (layer.visible === false) return;
+                for (let y = 0; y < rect.h; y += 1) {
+                    const line = layer.rows[rect.y + y] || '';
+                    const chars = region[y].split('');
+                    for (let x = 0; x < rect.w; x += 1) {
+                        const ch = line[rect.x + x];
+                        if (ch && ch !== '.') chars[x] = ch;
+                    }
+                    region[y] = chars.join('');
+                }
+            });
+            return region;
+        }
+
+        /** Stacks regions bottom-first; transparent cells let the lower region show through. */
+        function overlayRegions(regions) {
+            const height = regions.length === 0 ? 0 : regions[0].length;
+            const width = height === 0 ? 0 : regions[0][0].length;
+            const out = [];
+            for (let y = 0; y < height; y += 1) {
+                const chars = new Array(width).fill('.');
+                regions.forEach((region) => {
+                    const line = region[y] || '';
+                    for (let x = 0; x < width; x += 1) {
+                        const ch = line[x];
+                        if (ch && ch !== '.') chars[x] = ch;
+                    }
+                });
+                out.push(chars.join(''));
+            }
+            return out;
+        }
+
+        /* solid fills ------------------------------------------------------ */
+        /* Text that sits on a solid colour has to flip with that colour: white on
+         * dark fills, near-black on light ones. The fill often comes from a theme
+         * token, so the readable ink is resolved at runtime instead of guessed in
+         * CSS (a light theme can map "brand" to a bright yellow). */
+        function parseRgbColor(value) {
+            if (typeof value !== 'string') return null;
+            const match = value.match(/rgba?\(([^)]+)\)/i);
+            if (!match) return null;
+            const parts = match[1].split(/[,\s/]+/).filter(Boolean).map(Number);
+            if (parts.length < 3 || parts.slice(0, 3).some((part) => !Number.isFinite(part))) return null;
+            return { r: parts[0], g: parts[1], b: parts[2] };
+        }
+
+        function readableOn(color) {
+            const rgb = parseRgbColor(color);
+            if (!rgb) return '#ffffff';
+            const channel = (value) => {
+                const unit = clamp(value, 0, 255) / 255;
+                return unit <= 0.03928 ? unit / 12.92 : ((unit + 0.055) / 1.055) ** 2.4;
+            };
+            const luminance = 0.2126 * channel(rgb.r) + 0.7152 * channel(rgb.g) + 0.0722 * channel(rgb.b);
+            return luminance > 0.5 ? '#101216' : '#ffffff';
+        }
+
+        function resolveBrandInk(host) {
+            if (typeof document === 'undefined' || typeof window === 'undefined') return '#ffffff';
+            const parent = (host && typeof host.appendChild === 'function') ? host : document.body;
+            if (!parent || typeof parent.appendChild !== 'function') return '#ffffff';
+            if (typeof window.getComputedStyle !== 'function') return '#ffffff';
+            let probe = null;
+            try {
+                probe = document.createElement('span');
+                probe.style.cssText = 'position:absolute;left:-9999px;top:0;width:0;height:0;'
+                    + 'background:var(--dsw-alias-brand-primary, #4b7bec)';
+                parent.appendChild(probe);
+                return readableOn(window.getComputedStyle(probe).backgroundColor);
+            } catch (error) {
+                return '#ffffff';
+            } finally {
+                if (probe && typeof probe.remove === 'function') probe.remove();
+            }
+        }
+
         /* ------------------------------------------------------------------ */
         /* image import                                                       */
         /* ------------------------------------------------------------------ */
@@ -703,6 +875,14 @@ window.__ModuleLoader__.load({
                     }),
                     h('path', { d: 'M13.2 10.4c1 1.2 1.5 2 1.5 2.6a1.5 1.5 0 0 1-3 0c0-.6.5-1.4 1.5-2.6z', fill: 'currentColor' }));
             }
+            if (name === 'select') {
+                return h('svg', common,
+                    h('rect', {
+                        x: 2.5, y: 2.5, width: 11, height: 11, rx: 1,
+                        fill: 'none', stroke: 'currentColor', strokeWidth: 1.4, strokeDasharray: '3 2',
+                    }),
+                    h('path', { d: 'M8 1.2v2.2M8 12.6v2.2M1.2 8h2.2M12.6 8h2.2', fill: 'none', stroke: 'currentColor', strokeWidth: 1.4, strokeLinecap: 'round' }));
+            }
             return h('svg', common,
                 h('path', {
                     d: 'M9.9 2.6a3.4 3.4 0 1 0 3.5 3.4c0-.6-.2-1.2-.5-1.7l1.6-1.6-1.1-1.1-1.6 1.6a3.4 3.4 0 0 0-1.9-.6z',
@@ -867,6 +1047,35 @@ window.__ModuleLoader__.load({
 .pxs-status { font-size: 11px; color: var(--dsw-alias-label-secondary, #9aa1ad); min-width: 54px; text-align: right; }
 .pxs-status[data-state="dirty"] { color: var(--dsw-alias-state-warn-primary, #e0a33a); }
 .pxs-status[data-state="error"] { color: var(--dsw-alias-state-error-primary, #e0574f); }
+.pxs-select-status {
+  min-width: 0; text-align: left; font-variant-numeric: tabular-nums;
+  color: var(--dsw-alias-brand-primary, #7aa2f7);
+}
+.pxs-selection-bar {
+  position: absolute; left: 10px; right: 10px; bottom: 10px; z-index: 3;
+  display: flex; flex-direction: column; gap: 5px;
+  padding: 6px 8px; border-radius: 9px;
+  background: var(--dsw-alias-bg-overlay, rgba(38, 42, 51, .9));
+  border: 1px solid var(--dsw-alias-border-l2, rgba(255, 255, 255, .2));
+  box-shadow: 0 6px 20px rgba(0, 0, 0, .28);
+  backdrop-filter: blur(6px);
+}
+.pxs-selection-row {
+  display: flex; flex-wrap: wrap; align-items: center; gap: 4px;
+}
+.pxs-selection-bar .pxs-btn { height: 24px; padding: 0 8px; font-size: 11px; }
+.pxs-selection-divider {
+  width: 1px; height: 16px; margin: 0 4px;
+  background: var(--dsw-alias-border-l1, rgba(255, 255, 255, .16));
+}
+.pxs-selection-hint {
+  font-size: 10px; line-height: 1.5;
+  color: var(--dsw-alias-label-tertiary, rgba(255, 255, 255, .55));
+}
+.pxs-selection-label {
+  font-size: 11px; margin-right: auto; color: var(--dsw-alias-label-secondary, #9aa1ad);
+  font-variant-numeric: tabular-nums; white-space: nowrap;
+}
 .pxs-notice {
     font-size: 11px;
     color: var(--dsw-alias-state-success-primary, #3fa45b);
@@ -914,7 +1123,7 @@ window.__ModuleLoader__.load({
 .pxs-dialog-actions { display: flex; justify-content: flex-end; gap: 8px; }
 .pxs-btn-primary {
     background: var(--dsw-alias-brand-primary, #4b7bec); border-color: transparent;
-    color: #fff;
+    color: var(--pxs-on-brand, #fff);
 }
 .pxs-native-color {
     width: 40px; height: 28px; padding: 0; border: 1px solid var(--dsw-alias-border-l2, rgba(255, 255, 255, .18));
@@ -1007,6 +1216,12 @@ window.__ModuleLoader__.load({
         /* editor                                                             */
         /* ------------------------------------------------------------------ */
 
+        /**
+         * In-memory clipboard for the selection tool. Intentionally not persisted:
+         * a page reload should never paste stale pixels into another drawing.
+         */
+        let clipRegion = null;
+
         function PixelStudio(props) {
             const sessionId = props && typeof props.sessionId === 'string' ? props.sessionId : '';
             const [docs, setDocs] = useState([]);
@@ -1032,6 +1247,25 @@ window.__ModuleLoader__.load({
             const [editing, setEditing] = useState(null);
             const [importDialog, setImportDialog] = useState(null);
             const [resizeDialog, setResizeDialog] = useState(null);
+            const [selection, setSelection] = useState(null);
+            const [grabMode, setGrabMode] = useState(false);
+            const [allLayersMode, setAllLayersMode] = useState(false);
+            const [brandInk, setBrandInk] = useState(() => resolveBrandInk());
+            const rootRef = useRef(null);
+
+            useEffect(() => {
+                const sync = () => setBrandInk(resolveBrandInk(rootRef.current));
+                sync();
+                if (typeof MutationObserver !== 'function' || typeof document === 'undefined') return undefined;
+                if (!document.documentElement) return undefined;
+                const observer = new MutationObserver(sync);
+                const targets = [document.documentElement, document.body].filter(Boolean);
+                targets.forEach((target) => observer.observe(target, {
+                    attributes: true,
+                    attributeFilter: ['class', 'style', 'data-theme', 'data-ds-theme', 'data-color-scheme'],
+                }));
+                return () => observer.disconnect();
+            }, []);
 
             const stageRef = useRef(null);
             const canvasRef = useRef(null);
@@ -1063,10 +1297,21 @@ window.__ModuleLoader__.load({
             // before the callback is created, so it must not close over the binding.
             const saveAsRef = useRef(null);
             const fileRef = useRef(null);
+            /** Live rectangle, read by the pointer handlers and the paint loop. */
+            const selectionRef = useRef(null);
+            /** In-flight selection drag: { mode, pointerId, start, origin }. */
+            const selectDragRef = useRef(null);
+            /** Indirection for the keyboard effect, which is registered before these callbacks exist. */
+            const selectApiRef = useRef({});
+            const grabRef = useRef(false);
+            const allLayersRef = useRef(false);
 
             if (gridRef.current !== showGrid) gridRef.current = showGrid;
             sizeRef.current = { left: leftWidth, right: rightWidth };
             if (editingRef.current !== editing) editingRef.current = editing;
+            if (grabRef.current !== grabMode) grabRef.current = grabMode;
+            if (allLayersRef.current !== allLayersMode) allLayersRef.current = allLayersMode;
+            selectionRef.current = selection;
 
             docRef.current = doc;
             toolRef.current = tool;
@@ -1126,6 +1371,10 @@ window.__ModuleLoader__.load({
 
             const paint = useCallback(() => {
                 frameRef.current = 0;
+                // Read through the ref so paints do not depend on the selection state
+                // identity: a changing callback here would cascade into fitToView →
+                // openDoc → the mount effect, reloading the document on every selection.
+                const selection = selectionRef.current;
                 const canvas = canvasRef.current;
                 const stage = stageRef.current;
                 const current = docRef.current;
@@ -1200,6 +1449,43 @@ window.__ModuleLoader__.load({
                     context.restore();
                 }
 
+                if (selection) {
+                    const boxX = Math.round(pan.x + selection.x * scale);
+                    const boxY = Math.round(pan.y + selection.y * scale);
+                    const boxW = Math.max(1, Math.round(selection.w * scale));
+                    const boxH = Math.max(1, Math.round(selection.h * scale));
+                    const floating = selection.float;
+                    if (floating && floating.region) {
+                        // Floating content preview, drawn over the cells it was lifted from.
+                        for (let row = 0; row < floating.region.length; row += 1) {
+                            const line = floating.region[row];
+                            for (let column = 0; column < line.length; column += 1) {
+                                const ch = line[column];
+                                if (!ch || ch === '.') continue;
+                                const color = current.palette[indexFor(ch)];
+                                if (!color) continue;
+                                context.fillStyle = color;
+                                context.fillRect(
+                                    Math.round(pan.x + (selection.x + column) * scale),
+                                    Math.round(pan.y + (selection.y + row) * scale),
+                                    Math.ceil(scale),
+                                    Math.ceil(scale),
+                                );
+                            }
+                        }
+                    }
+                    // Marching ants: one dark and one offset light dashed border.
+                    context.save();
+                    context.lineWidth = 1;
+                    context.setLineDash([4, 4]);
+                    context.strokeStyle = 'rgba(0,0,0,0.8)';
+                    context.strokeRect(boxX + 0.5, boxY + 0.5, boxW - 1, boxH - 1);
+                    context.lineDashOffset = 4;
+                    context.strokeStyle = 'rgba(255,255,255,0.95)';
+                    context.strokeRect(boxX + 0.5, boxY + 0.5, boxW - 1, boxH - 1);
+                    context.restore();
+                }
+
                 context.strokeStyle = 'rgba(255,255,255,0.22)';
                 context.lineWidth = 1;
                 context.strokeRect(Math.round(pan.x) + 0.5, Math.round(pan.y) + 0.5, Math.round(docWidth), Math.round(docHeight));
@@ -1247,6 +1533,8 @@ window.__ModuleLoader__.load({
 
             const openDoc = useCallback(async (id) => {
                 const data = await callApi({ op: 'get', id });
+                const previous = docRef.current;
+                const switched = !previous || previous.id !== data.doc.id;
                 setDoc(data.doc);
                 docRef.current = data.doc;
                 setLayerIndex(0);
@@ -1254,6 +1542,12 @@ window.__ModuleLoader__.load({
                 setEditing(null);
                 editingRef.current = null;
                 historyRef.current = { undo: [], redo: [] };
+                if (switched) {
+                    // Selection coordinates belong to the document that was open;
+                    // a late-arriving reload of the same document must not wipe it.
+                    selectionRef.current = null;
+                    setSelection(null);
+                }
                 setStatus('clean');
                 window.requestAnimationFrame(() => fitToView());
             }, [fitToView]);
@@ -1358,6 +1652,8 @@ window.__ModuleLoader__.load({
                 if (!snapshot) return;
                 const current = docRef.current;
                 history.redo.push(snapshotOf(current));
+                selectionRef.current = null;
+                setSelection(null);
                 applyHistory(snapshot);
             }, [applyHistory]);
 
@@ -1367,6 +1663,8 @@ window.__ModuleLoader__.load({
                 if (!snapshot) return;
                 const current = docRef.current;
                 history.undo.push(snapshotOf(current));
+                selectionRef.current = null;
+                setSelection(null);
                 applyHistory(snapshot);
             }, [applyHistory]);
 
@@ -1430,6 +1728,272 @@ window.__ModuleLoader__.load({
                 }
             }, []);
 
+            const pushHistory = useCallback(() => {
+                const current = docRef.current;
+                if (!current) return;
+                const history = historyRef.current;
+                history.undo.push(snapshotOf(current));
+                if (history.undo.length > HISTORY_LIMIT) history.undo.shift();
+                history.redo = [];
+            }, []);
+
+            const selectionTargets = useCallback((allLayers) => {
+                const current = docRef.current;
+                if (!current) return [];
+                if (allLayers) {
+                    return current.layers
+                        .map((layer, index) => ({ layer, index }))
+                        .filter((entry) => entry.layer && entry.layer.visible !== false);
+                }
+                const layer = current.layers[layerRef.current];
+                return layer ? [{ layer, index: layerRef.current }] : [];
+            }, []);
+
+            const setSelectionRect = useCallback((rect) => {
+                selectionRef.current = rect;
+                setSelection(rect);
+                requestPaint();
+            }, [requestPaint]);
+
+            const selectAll = useCallback(() => {
+                const current = docRef.current;
+                if (!current) return;
+                setTool('select');
+                setSelectionRect({ x: 0, y: 0, w: current.w, h: current.h, float: null });
+                requestPaint();
+            }, [requestPaint, setSelectionRect]);
+
+            const putBackLifted = useCallback((current, active) => {
+                const float = active.float;
+                if (!float) return current;
+                const layers = current.layers.map((layer, index) => {
+                    const item = float.targets.find((entry) => entry.index === index);
+                    if (!item) return layer;
+                    return {
+                        ...layer,
+                        rows: writeRegion(layer.rows, item.region, float.origin.x, float.origin.y),
+                    };
+                });
+                return { ...current, layers };
+            }, []);
+
+            const cancelSelection = useCallback(() => {
+                const current = docRef.current;
+                const active = selectionRef.current;
+                selectionRef.current = null;
+                setSelection(null);
+                if (current && active && active.float) {
+                    const next = putBackLifted(current, active);
+                    docRef.current = next;
+                    setDoc(next);
+                    scheduleSave();
+                }
+                requestPaint();
+            }, [putBackLifted, requestPaint, scheduleSave]);
+
+            /** Lifts the selected pixels out of their layers; false when nothing could be lifted. */
+            const liftSelection = useCallback((allLayers) => {
+                const current = docRef.current;
+                const active = selectionRef.current;
+                if (!current || !active || active.float) return false;
+                const rect = clampRectangle(active, current.w, current.h);
+                const targets = selectionTargets(allLayers);
+                if (targets.length === 0) return false;
+                pushHistory();
+                const items = targets.map((entry) => ({ index: entry.index, region: readRegion(entry.layer.rows, rect) }));
+                const layers = current.layers.map((layer, index) => {
+                    const item = items.find((entry) => entry.index === index);
+                    return item ? { ...layer, rows: emptyRows(layer.rows, rect) } : layer;
+                });
+                const next = { ...current, layers };
+                docRef.current = next;
+                setDoc(next);
+                setSelectionRect({
+                    ...rect,
+                    float: {
+                        // Only the lifted layers, so pixels of untouched layers are not
+                        // copied into the destination when the selection is dropped.
+                        region: overlayRegions(items.map((item) => item.region)),
+                        origin: { x: rect.x, y: rect.y },
+                        targets: items,
+                    },
+                });
+                setStatus('dirty');
+                return true;
+            }, [pushHistory, selectionTargets, setSelectionRect]);
+
+            /** Drops the lifted pixels at the rectangle's current position. */
+            const dropSelection = useCallback(() => {
+                const current = docRef.current;
+                const active = selectionRef.current;
+                if (!current || !active || !active.float) return;
+                const rect = clampRectangle(active, current.w, current.h);
+                const float = active.float;
+                const layers = current.layers.map((layer, index) => {
+                    const item = float.targets.find((entry) => entry.index === index);
+                    return item ? { ...layer, rows: writeRegion(layer.rows, item.region, rect.x, rect.y) } : layer;
+                });
+                const next = { ...current, layers };
+                docRef.current = next;
+                setDoc(next);
+                setSelectionRect({ ...rect, float: null });
+                setStatus('dirty');
+                scheduleSave();
+            }, [scheduleSave, setSelectionRect]);
+
+            const applySelectionEdit = useCallback((mode, allLayers) => {
+                const current = docRef.current;
+                const active = selectionRef.current;
+                if (!current || !active) return;
+                let base = current;
+                if (active.float) {
+                    const floating = clampRectangle(active, base.w, base.h);
+                    if (mode === 'delete') {
+                        // The lift already pushed its own history entry, so dropping the float
+                        // without writing it back is exactly "these pixels are gone".
+                        setSelectionRect({ ...floating, float: null });
+                        setStatus('dirty');
+                        scheduleSave();
+                        return;
+                    }
+                    const float = active.float;
+                    const committed = base.layers.map((layer, index) => {
+                        const item = float.targets.find((entry) => entry.index === index);
+                        if (!item) return layer;
+                        return { ...layer, rows: writeRegion(layer.rows, item.region, floating.x, floating.y) };
+                    });
+                    base = { ...base, layers: committed };
+                    docRef.current = base;
+                    setDoc(base);
+                }
+                const rect = clampRectangle(active, base.w, base.h);
+                const targets = selectionTargets(allLayers);
+                if (targets.length === 0) return;
+                // A committed float already pushed its own undo entry during the lift.
+                if (!active.float) pushHistory();
+                const layers = base.layers.map((layer, index) => {
+                    const target = targets.find((entry) => entry.index === index);
+                    if (!target) return layer;
+                    let rows = layer.rows;
+                    if (mode === 'mirror-h') rows = mirrorRows(rows, rect, true);
+                    else if (mode === 'mirror-v') rows = mirrorRows(rows, rect, false);
+                    else if (mode === 'fill') rows = fillRows(rows, rect, charFor(colorRef.current));
+                    else if (mode === 'delete') rows = emptyRows(rows, rect);
+                    return { ...layer, rows };
+                });
+                const next = { ...base, layers };
+                docRef.current = next;
+                setDoc(next);
+                setSelectionRect({ ...rect, float: null });
+                setStatus('dirty');
+                scheduleSave();
+            }, [pushHistory, scheduleSave, selectionTargets, setSelectionRect]);
+
+            /** Arrow-key nudging: 1 cell, 10 with Shift; carries lifted pixels along. */
+            const nudgeSelection = useCallback((dx, dy) => {
+                const current = docRef.current;
+                const active = selectionRef.current;
+                if (!current || !active) return;
+                const rect = moveRectangle(active, active.x + dx, active.y + dy, current.w, current.h);
+                setSelectionRect({ ...rect, float: active.float });
+            }, [setSelectionRect]);
+
+            /** Copy what the selection shows (floating pixels win) into the clipboard. */
+            const copySelection = useCallback(() => {
+                const current = docRef.current;
+                const active = selectionRef.current;
+                if (!current || !active) return false;
+                const rect = clampRectangle(active, current.w, current.h);
+                clipRegion = {
+                    w: rect.w,
+                    h: rect.h,
+                    rows: active.float
+                        ? active.float.region.map((row) => row.slice())
+                        : mergedRegion(current.layers, rect),
+                };
+                setNotice(`已复制 ${rect.w}×${rect.h}`);
+                return true;
+            }, []);
+
+            /**
+             * Cut keeps the pixels on the canvas: the content is copied and lifted into the
+             * floating selection, so it stays visible and can be dragged to its new home.
+             * Only 「完成」 (or dropping elsewhere) actually removes it from where it was.
+             */
+            const cutSelection = useCallback(() => {
+                const copied = copySelection();
+                if (!copied) return;
+                const lifted = liftSelection(allLayersRef.current);
+                setNotice(lifted
+                    ? '已剪切 · 内容还留在画布上，拖动选框然后点「完成」落地'
+                    : '已剪切 · 内容已在剪贴板里');
+            }, [copySelection, liftSelection]);
+
+            const finishSelection = useCallback(() => {
+                const active = selectionRef.current;
+                if (!active) return;
+                if (active.float) dropSelection();
+                selectionRef.current = null;
+                setSelection(null);
+                requestPaint();
+                scheduleSave();
+            }, [dropSelection, requestPaint, scheduleSave]);
+
+            const pasteClipboard = useCallback(() => {
+                const clipboard = clipRegion;
+                if (!clipboard) return;
+                const active = selectionRef.current;
+                // A floating selection is committed where it stands before pasting, otherwise
+                // the paste would silently throw the moved pixels back to their old home.
+                if (active && active.float) dropSelection();
+                const base = docRef.current;
+                if (!base) return;
+                const width = Math.min(clipboard.w, base.w);
+                const height = Math.min(clipboard.h, base.h);
+                const origin = active ? clampRectangle(active, base.w, base.h) : { x: 0, y: 0 };
+                const x = clamp(origin.x, 0, base.w - width);
+                const y = clamp(origin.y, 0, base.h - height);
+                const region = clipboard.rows
+                    .slice(0, height)
+                    .map((row) => row.padEnd(clipboard.w, '.').slice(0, width));
+                pushHistory();
+                const layers = base.layers.map((layer, index) => (index === layerRef.current
+                    ? { ...layer, rows: writeRegion(layer.rows, region, x, y) }
+                    : layer));
+                const next = { ...base, layers };
+                docRef.current = next;
+                setDoc(next);
+                setSelectionRect({ x, y, w: width, h: height, float: null });
+                setStatus('dirty');
+                scheduleSave();
+                setNotice(`已粘贴 ${width}×${height} @ (${x},${y})`);
+            }, [dropSelection, pushHistory, scheduleSave, setSelectionRect]);
+
+            const mirrorSelection = useCallback((horizontal) => {
+                applySelectionEdit(horizontal ? 'mirror-h' : 'mirror-v', allLayersRef.current);
+            }, [applySelectionEdit]);
+
+            const fillSelection = useCallback(() => {
+                applySelectionEdit('fill', allLayersRef.current);
+            }, [applySelectionEdit]);
+
+            // Exposed to the keyboard effect, which is registered before these callbacks exist.
+            selectApiRef.current = {
+                selectAll,
+                cancel: cancelSelection,
+                apply: applySelectionEdit,
+                nudge: nudgeSelection,
+                drop: dropSelection,
+                lift: liftSelection,
+                copy: copySelection,
+                cut: cutSelection,
+                paste: pasteClipboard,
+                mirror: mirrorSelection,
+                fill: fillSelection,
+                finish: finishSelection,
+                allLayers: allLayersRef.current,
+            };
+
             const onPointerDown = useCallback((event) => {
                 if (!docRef.current) return;
                 const wantsPan = event.button === 1 || spaceRef.current || event.altKey;
@@ -1450,6 +2014,46 @@ window.__ModuleLoader__.load({
                 if (!cell) return;
                 const current = docRef.current;
 
+                if (toolRef.current === 'select') {
+                    event.preventDefault();
+                    const anchor = {
+                        x: clamp(cell.x, 0, Math.max(0, current.w - 1)),
+                        y: clamp(cell.y, 0, Math.max(0, current.h - 1)),
+                    };
+                    const active = selectionRef.current;
+                    const inside = active ? pointInRectangle(active, cell) : false;
+                    const carry = event.shiftKey || grabRef.current;
+                    event.currentTarget.setPointerCapture(event.pointerId);
+                    if (inside && carry && (active.float || liftSelection(allLayersRef.current))) {
+                        selectDragRef.current = {
+                            mode: 'grab',
+                            pointerId: event.pointerId,
+                            start: anchor,
+                            origin: { x: active.x, y: active.y },
+                        };
+                    } else if (inside) {
+                        // Plain drag slides the frame; the pixels stay where they are.
+                        selectDragRef.current = {
+                            mode: 'move',
+                            pointerId: event.pointerId,
+                            start: anchor,
+                            origin: { x: active.x, y: active.y },
+                        };
+                    } else {
+                        setSelectionRect({
+                            ...clampRectangle({ x: anchor.x, y: anchor.y, w: 1, h: 1 }, current.w, current.h),
+                            float: null,
+                        });
+                        selectDragRef.current = {
+                            mode: 'create',
+                            pointerId: event.pointerId,
+                            start: anchor,
+                        };
+                    }
+                    requestPaint();
+                    return;
+                }
+
                 if (toolRef.current === 'picker') {
                     pickColorAt(cell);
                     return;
@@ -1488,6 +2092,35 @@ window.__ModuleLoader__.load({
                     requestPaint();
                     return;
                 }
+                const selectDrag = selectDragRef.current;
+                if (selectDrag && selectDrag.pointerId === event.pointerId) {
+                    const current = docRef.current;
+                    const cell = cellFromEvent(event);
+                    if (!current || !cell) return;
+                    const anchor = {
+                        x: clamp(cell.x, 0, Math.max(0, current.w - 1)),
+                        y: clamp(cell.y, 0, Math.max(0, current.h - 1)),
+                    };
+                    if (selectDrag.mode === 'create') {
+                        setSelectionRect({
+                            ...clampRectangle(selectionBetween(selectDrag.start, anchor), current.w, current.h),
+                            float: null,
+                        });
+                    } else {
+                        const active = selectionRef.current;
+                        if (!active) return;
+                        const rect = moveRectangle(
+                            { x: 0, y: 0, w: active.w, h: active.h },
+                            selectDrag.origin.x + (anchor.x - selectDrag.start.x),
+                            selectDrag.origin.y + (anchor.y - selectDrag.start.y),
+                            current.w,
+                            current.h,
+                        );
+                        setSelectionRect({ ...rect, float: active.float });
+                    }
+                    requestPaint();
+                    return;
+                }
                 const stroke = strokeRef.current;
                 if (!stroke || stroke.pointerId !== event.pointerId) return;
                 const cell = cellFromEvent(event);
@@ -1498,6 +2131,18 @@ window.__ModuleLoader__.load({
             }, [cellFromEvent, requestPaint, strokeAt]);
 
             const onPointerUp = useCallback((event) => {
+                const selectDrag = selectDragRef.current;
+                if (selectDrag && selectDrag.pointerId === event.pointerId) {
+                    selectDragRef.current = null;
+                    if (selectDrag.mode === 'grab') dropSelection();
+                    const active = selectionRef.current;
+                    if (active && (active.w < 1 || active.h < 1)) {
+                        selectionRef.current = null;
+                        setSelection(null);
+                    }
+                    requestPaint();
+                    return;
+                }
                 if (panDrawRef.current && panDrawRef.current.pointerId === event.pointerId) {
                     panDrawRef.current = null;
                     requestPaint();
@@ -1521,6 +2166,9 @@ window.__ModuleLoader__.load({
                 const onWheel = (event) => {
                     if (!docRef.current) return;
                     event.preventDefault();
+                    // A drag owns the pointer: a trackpad that fires wheel events
+                    // mid-drag must not shove or rescale the canvas under the cursor.
+                    if (selectDragRef.current || strokeRef.current || panDrawRef.current) return;
                     if (event.shiftKey) {
                         panRef.current = {
                             x: panRef.current.x - event.deltaY,
@@ -1570,6 +2218,11 @@ window.__ModuleLoader__.load({
                         return;
                     }
                     const meta = event.metaKey || event.ctrlKey;
+                    if (meta && event.key.toLowerCase() === 'a') {
+                        event.preventDefault();
+                        selectApiRef.current.selectAll();
+                        return;
+                    }
                     if (meta && event.key.toLowerCase() === 'z') {
                         event.preventDefault();
                         if (event.shiftKey) redo();
@@ -1591,12 +2244,62 @@ window.__ModuleLoader__.load({
                         void saveNow();
                         return;
                     }
-                    if (meta) return;
+                    if (meta) {
+                        const combo = event.key.toLowerCase();
+                        const wantsSelection = selectionRef.current !== null;
+                        if ((combo === 'c' || combo === 'x') && wantsSelection) {
+                            event.preventDefault();
+                            if (combo === 'c') selectApiRef.current.copy();
+                            else selectApiRef.current.cut();
+                            return;
+                        }
+                        if (combo === 'v' && clipRegion !== null) {
+                            event.preventDefault();
+                            selectApiRef.current.paste();
+                            return;
+                        }
+                        return;
+                    }
                     const key = event.key.toLowerCase();
+                    if (key === 'escape') {
+                        selectApiRef.current.cancel();
+                        return;
+                    }
+                    if (selectionRef.current) {
+                        if (key === 'delete' || key === 'backspace') {
+                            event.preventDefault();
+                            selectApiRef.current.apply('delete', selectApiRef.current.allLayers);
+                            return;
+                        }
+                        if (key.indexOf('arrow') === 0) {
+                            event.preventDefault();
+                            const step = event.shiftKey ? 10 : 1;
+                            const dx = key === 'arrowleft' ? -step : key === 'arrowright' ? step : 0;
+                            const dy = key === 'arrowup' ? -step : key === 'arrowdown' ? step : 0;
+                            selectApiRef.current.nudge(dx, dy);
+                            return;
+                        }
+                        if (event.shiftKey && key === 'h') {
+                            event.preventDefault();
+                            selectApiRef.current.apply('mirror-h', selectApiRef.current.allLayers);
+                            return;
+                        }
+                        if (event.shiftKey && key === 'v') {
+                            event.preventDefault();
+                            selectApiRef.current.apply('mirror-v', selectApiRef.current.allLayers);
+                            return;
+                        }
+                        if (event.shiftKey && key === 'f') {
+                            event.preventDefault();
+                            selectApiRef.current.apply('fill', selectApiRef.current.allLayers);
+                            return;
+                        }
+                    }
                     if (key === 'b') setTool('pencil');
                     else if (key === 'e') setTool('eraser');
                     else if (key === 'g') setTool('bucket');
                     else if (key === 'i') setTool('picker');
+                    else if (key === 'm') setTool('select');
                     else if (key === 'f') fitToView();
                     else if (key === 'h') {
                         const next = !gridRef.current;
@@ -1943,6 +2646,9 @@ window.__ModuleLoader__.load({
                 history.undo.push(snapshotOf(current));
                 if (history.undo.length > HISTORY_LIMIT) history.undo.shift();
                 history.redo = [];
+                // A selection in canvas coordinates would be meaningless after a resize.
+                selectionRef.current = null;
+                setSelection(null);
                 const layers = current.layers.map((layer) => ({
                     ...layer,
                     rows: resizeRows(layer.rows, current.w, current.h, width, height, dialog.anchor),
@@ -1962,15 +2668,6 @@ window.__ModuleLoader__.load({
             /* palette actions                                                */
             /* -------------------------------------------------------------- */
 
-            const pushHistory = useCallback(() => {
-                const current = docRef.current;
-                if (!current) return;
-                const history = historyRef.current;
-                history.undo.push(snapshotOf(current));
-                if (history.undo.length > HISTORY_LIMIT) history.undo.shift();
-                history.redo = [];
-            }, []);
-
             const updatePalette = useCallback((palette, options = {}) => {
                 const current = docRef.current;
                 if (!current) return;
@@ -2377,6 +3074,10 @@ window.__ModuleLoader__.load({
                     : status === 'error' ? '保存失败'
                         : '已保存';
 
+            const selectionText = selection
+                ? `选区 ${selection.w}×${selection.h} @ (${selection.x},${selection.y})${selection.float ? ' · 浮动' : ''}${allLayersMode ? ' · 全部图层' : ''}`
+                : '';
+
             const currentLayer = doc ? doc.layers[layerIndex] : null;
 
             const swatchNodes = doc ? doc.palette.map((color, index) => h('button', {
@@ -2525,6 +3226,7 @@ window.__ModuleLoader__.load({
                     title: '删除当前作品',
                 }, '删除'),
                 h('span', { className: 'pxs-status', 'data-state': status }, statusText),
+                selection ? h('span', { className: 'pxs-status pxs-select-status', title: '选区：拖动移框，Shift+拖动带内容，方向键微调，Esc 取消' }, selectionText) : null,
                 notice ? h('span', { className: 'pxs-notice', title: notice }, notice) : null);
 
             const errorNode = error ? h('div', { className: 'pxs-error' },
@@ -2666,7 +3368,10 @@ window.__ModuleLoader__.load({
                     h('div', null, h('kbd', null, 'G'), '填充  ', h('kbd', null, 'I'), '吸管'),
                     h('div', null, h('kbd', null, '滚轮'), '缩放  ', h('kbd', null, '空格'), '+ 拖动'),
                     h('div', null, h('kbd', null, 'F'), '适应窗口  ', h('kbd', null, '[ ]'), '笔刷'),
-                    h('div', null, h('kbd', null, 'H'), '格线开/关  ', h('kbd', null, 'Ctrl+S'), '保存')));
+                    h('div', null, h('kbd', null, 'H'), '格线开/关  ', h('kbd', null, 'Ctrl+S'), '保存'),
+                    h('div', null, h('kbd', null, 'M'), '选区  ', h('kbd', null, 'Ctrl+A'), '全选'),
+                    h('div', null, h('kbd', null, 'Shift'), '+ 拖动', ' 移内容'),
+                    h('div', null, h('kbd', null, 'Del'), '删除  ', h('kbd', null, 'Esc'), '取消')));
 
             const leftPanel = h('div', { className: 'pxs-panel pxs-panel-left' },
                 toolsSection, brushSection, layerSection, canvasSection, keysSection);
@@ -2678,7 +3383,10 @@ window.__ModuleLoader__.load({
                 onPointerMove,
                 onPointerUp,
                 onPointerCancel: onPointerUp,
-                onContextMenu: (event) => event.preventDefault(),
+                onContextMenu: (event) => {
+                    event.preventDefault();
+                    if (selectionRef.current) selectApiRef.current.cancel();
+                },
                 onDragStart: (event) => event.preventDefault(),
             });
 
@@ -2694,8 +3402,74 @@ window.__ModuleLoader__.load({
 
             const loadingNode = loading ? h('div', { className: 'pxs-empty' }, h('p', null, '加载作品中…')) : null;
 
+            const selectionBar = selection ? h('div', { className: 'pxs-selection-bar' },
+                h('div', { className: 'pxs-selection-row' },
+                    h('span', { className: 'pxs-selection-label' },
+                        `${selection.w}×${selection.h} @ ${selection.x},${selection.y}`),
+                    h('button', {
+                        className: 'pxs-btn',
+                        onClick: () => selectApiRef.current.cut(),
+                        title: '剪切选区内容到剪贴板 (Ctrl+X)',
+                    }, '✂ 剪切'),
+                    h('button', {
+                        className: 'pxs-btn',
+                        onClick: () => selectApiRef.current.copy(),
+                        title: '复制选区内容到剪贴板 (Ctrl+C)',
+                    }, '⧉ 复制'),
+                    h('button', {
+                        className: 'pxs-btn',
+                        onClick: () => selectApiRef.current.paste(),
+                        title: '把剪贴板内容粘贴到选区左上角 (Ctrl+V)',
+                    }, '⇩ 粘贴'),
+                    h('span', { className: 'pxs-selection-divider' }),
+                    h('button', {
+                        className: 'pxs-btn',
+                        onClick: () => selectApiRef.current.fill(),
+                        title: '用当前颜色填充选区 (Shift+F)',
+                    }, '▣ 填充'),
+                    h('button', {
+                        className: 'pxs-btn',
+                        onClick: () => selectApiRef.current.apply('delete', allLayersRef.current),
+                        title: '清空选区内容 (Delete)',
+                    }, '⌫ 清除'),
+                    h('button', {
+                        className: 'pxs-btn',
+                        onClick: () => selectApiRef.current.mirror(true),
+                        title: '选区内容水平镜像 (Shift+H)',
+                    }, '⇆ 镜像'),
+                    h('button', {
+                        className: 'pxs-btn',
+                        onClick: () => selectApiRef.current.mirror(false),
+                        title: '选区内容垂直镜像 (Shift+V)',
+                    }, '⇅ 镜像'),
+                    h('span', { className: 'pxs-selection-divider' }),
+                    h('button', {
+                        className: 'pxs-btn',
+                        'data-active': grabMode,
+                        title: '开启后，拖动选区会搬走像素（等同 Shift+拖动）',
+                        onClick: () => setGrabMode((value) => !value),
+                    }, grabMode ? '✓ 搬内容' : '搬内容'),
+                    h('button', {
+                        className: 'pxs-btn',
+                        'data-active': allLayersMode,
+                        title: '填充 / 清除 / 镜像作用于所有可见图层，而不只是当前图层',
+                        onClick: () => setAllLayersMode((value) => !value),
+                    }, allLayersMode ? '✓ 多层' : '多层'),
+                    h('button', {
+                        className: 'pxs-btn pxs-btn-primary',
+                        onClick: () => selectApiRef.current.finish(),
+                        title: '把浮动的内容落到当前位置并结束选区',
+                    }, '✓ 完成'),
+                    h('button', {
+                        className: 'pxs-btn',
+                        onClick: () => selectApiRef.current.cancel(),
+                        title: '放弃这次选区；浮动的内容回到原处 (Esc)',
+                    }, '✕ 取消')),
+                h('div', { className: 'pxs-selection-hint' },
+                    '拖动 = 移动选框　·　Shift + 拖动 = 搬走像素　·　剪切 = 内容留在画布上跟随选框　·　方向键 = 微调（Shift 10px）　·　Esc = 取消还原')) : null;
+
             const stageNode = h('div', { className: 'pxs-stage', ref: stageRef },
-                canvasNode, emptyNode, loadingNode);
+                canvasNode, emptyNode, loadingNode, selectionBar);
 
             const colorSection = h('div', { className: 'pxs-section' },
                 h('p', { className: 'pxs-title' }, '当前颜色'),
@@ -3148,7 +3922,7 @@ window.__ModuleLoader__.load({
                         onClick: confirmResize,
                     }, '应用')))) : null;
 
-            return h('div', { className: 'pxs-root' },
+            return h('div', { className: 'pxs-root', ref: rootRef, style: { '--pxs-on-brand': brandInk } },
                 h('style', null, CSS),
                 barNode,
                 errorNode,
@@ -3235,6 +4009,23 @@ window.__ModuleLoader__.load({
             }
         }
 
+        // Test hook: tools/select-test.cjs drives the pure selection helpers.
+        if (window.__PXS_TEST__) {
+            window.__PXS_TEST__.selection = {
+                selectionBetween,
+                clampRectangle,
+                moveRectangle,
+                pointInRectangle,
+                readRegion,
+                writeRegion,
+                blankRegion,
+                fillRows,
+                emptyRows,
+                mirrorRows,
+                mergedRegion,
+            };
+        }
+
         return {
             inject: ['slots'],
             apply(ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muxiuesd/dsh-pixel-studio",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "在 DSH 里画像素画：三栏编辑器（左工具 / 中画布 / 右调色板），滚轮缩放，图层、调色板、导出 PNG 都在会话页签里。",
   "type": "module",
   "main": "./index.js",