@umicat/phaser-sdk 1.0.2 → 1.0.4

package/dist/editor/EditorBridge.js

@@ -43,6 +43,16 @@ export function setupEditorBridge(game) {
             return;
         handleMessage(game, data);
     });
+    // Boot-time edit flag (2026-06-11). When the host remounts the iframe
+    // while edit mode is on (post-save / post-agent-turn rebuild), it appends
+    // `umicatEdit=1` to the iframe URL. Enter edit IMMEDIATELY at game
+    // construction so scenes pause before their first update. Without this
+    // the game visibly plays for a second or two after every rebuild: the
+    // host's `enter` postMessage can't arrive any earlier because main.ts
+    // awaits font fetches before createUmicatGame installs this listener.
+    if (typeof window !== 'undefined' && /[?&]umicatEdit=1/.test(window.location.search)) {
+        enterEdit(game);
+    }
 }
 function handleMessage(game, msg) {
     switch (msg.type) {
@@ -134,6 +144,15 @@ function enterEdit(game) {
     restoreCanvasAfterEditor(game);
     setEditorActive(game, true);
     pauseActiveNonEditor(game);
+    // Continuous pause enforcement (2026-06-11) — the bounded 3s re-attempt
+    // loop below misses scenes that finish booting later than 3s after
+    // enter (slow CDN fetch of scene assets, etc.), and even within the
+    // window a scene can run for up to 100ms before the next tick pauses
+    // it. A PRE_STEP hook pauses any newly-active non-editor scene BEFORE
+    // its first update, for as long as edit mode is on. pauseActiveNonEditor
+    // skips already-paused scenes, so the per-frame cost is a short loop
+    // over the scene list.
+    installPauseEnforcement(game);
     // P1 infinite canvas — expand the Phaser canvas to fill its container
     // (host's iframe). Without this, the editor surface stays locked to
     // the game's intrinsic aspect ratio (720×1280 portrait, etc.) with
@@ -199,6 +218,33 @@ function enterEdit(game) {
     };
     setTimeout(reattempt, 100);
 }
+const PAUSE_ENFORCER_FLAG = '__umicatEditorPauseEnforcer';
+/**
+ * While edit mode is active, pause any non-editor scene before each game
+ * step. Catches scenes that boot AFTER enterEdit (iframe rebuild path) no
+ * matter how late — the game never visibly plays under the editor.
+ * Self-disarms via the active check; uninstalled on exitEdit.
+ */
+function installPauseEnforcement(game) {
+    const bag = game;
+    if (bag[PAUSE_ENFORCER_FLAG])
+        return;
+    const handler = () => {
+        if (!getEditorState(game).active)
+            return;
+        pauseActiveNonEditor(game);
+    };
+    game.events.on(Phaser.Core.Events.PRE_STEP, handler);
+    bag[PAUSE_ENFORCER_FLAG] = handler;
+}
+function uninstallPauseEnforcement(game) {
+    const bag = game;
+    const handler = bag[PAUSE_ENFORCER_FLAG];
+    if (!handler)
+        return;
+    game.events.off(Phaser.Core.Events.PRE_STEP, handler);
+    delete bag[PAUSE_ENFORCER_FLAG];
+}
 function pauseActiveNonEditor(game) {
     // P1 infinite canvas (2026-05-17) — use `setActive(false)` instead of
     // `pause()` so scenes STOP updating (game logic frozen) but KEEP
@@ -250,6 +296,9 @@ function exitEdit(game) {
     if (!getEditorState(game).active)
         return;
     setEditorActive(game, false);
+    // Active is false now so the enforcer self-disables, but remove the
+    // hook too — no point paying the per-frame check during play.
+    uninstallPauseEnforcement(game);
     setSelection(game, null);
     // Allow next enter to re-post the snapshot (scene file may have changed).
     delete game[SNAPSHOT_POSTED_FLAG];

package/dist/editor/EditorOverlayScene.d.ts

@@ -89,6 +89,8 @@ export declare class EditorOverlayScene extends Phaser.Scene {
     private panStartScreen;
     private panStartScroll;
     private wheelHandler?;
+    private snapCandidates;
+    private snapGuides;
     constructor();
     init(data: EditorOverlayInitData): void;
     create(): void;
@@ -268,6 +270,16 @@ export declare class EditorOverlayScene extends Phaser.Scene {
      * normal editTilemap dispatch (which mutates the live runtime).
      */
     private commitTilemapResize;
+    /** Candidate alignment lines: world-bounds edges/centers + every OTHER entity's. */
+    private buildSnapCandidates;
+    /**
+     * Snap a candidate position against the cached lines. Returns the
+     * adjusted position (or null when nothing is within threshold) and
+     * records the matched guide lines for update() to draw.
+     */
+    private applySnap;
+    /** Pink alignment guide lines across the visible viewport while snapped. */
+    private drawSnapGuides;
     /**
      * Selected rect entity's bounds + 8 handle positions in world coords.
      * Returns null when the selection isn't a rect, in HUD mode, or when the

package/dist/editor/EditorOverlayScene.js

@@ -72,6 +72,12 @@ export class EditorOverlayScene extends Phaser.Scene {
         this.spaceHeld = false;
         this.panStartScreen = null;
         this.panStartScroll = null;
+        // Snap-to-align (2026-06-11) — Figma-style magnetic alignment while
+        // dragging an entity. Candidates (world-bounds edges/centers + every
+        // other entity's edges/centers) are cached once at drag start; guides
+        // are the alignment lines currently snapped to, drawn in update().
+        this.snapCandidates = null;
+        this.snapGuides = { xs: [], ys: [] };
         this.handleShortcut = (e) => {
             // Don't swallow keys when the user is typing in a real form control —
             // shouldn't happen inside the iframe, but be defensive.
@@ -303,6 +309,9 @@ export class EditorOverlayScene extends Phaser.Scene {
         else {
             const target = hit;
             startDrag(this.game, entityId, { x: px, y: py }, { x: target.x, y: target.y });
+            // Cache snap candidates once per drag — other entities don't move
+            // while we drag this one, so a per-move registry walk would be waste.
+            this.buildSnapCandidates(entityId);
         }
     }
     handlePointerMove(pointer) {
@@ -377,8 +386,23 @@ export class EditorOverlayScene extends Phaser.Scene {
             go.__lastDragDy = dy;
         }
         else {
-            go.x = drag.startEntity.x + dx;
-            go.y = drag.startEntity.y + dy;
+            let nx = drag.startEntity.x + dx;
+            let ny = drag.startEntity.y + dy;
+            // Snap-to-align — Cmd/Ctrl held disables it (Figma convention:
+            // precision placement override).
+            const ev = pointer.event;
+            if (ev?.metaKey || ev?.ctrlKey) {
+                this.snapGuides = { xs: [], ys: [] };
+            }
+            else {
+                const snapped = this.applySnap(go, nx, ny);
+                if (snapped) {
+                    nx = snapped.x;
+                    ny = snapped.y;
+                }
+            }
+            go.x = nx;
+            go.y = ny;
         }
     }
     handlePointerUp(pointer) {
@@ -410,11 +434,22 @@ export class EditorOverlayScene extends Phaser.Scene {
         const drag = getDrag(this.game);
         if (!drag)
             return;
+        // Snap state is per-drag.
+        this.snapCandidates = null;
+        this.snapGuides = { xs: [], ys: [] };
         const { x: px, y: py } = this.pointerCoords(pointer);
         const dx = px - drag.startWorld.x;
         const dy = py - drag.startWorld.y;
         const before = drag.startEntity;
-        const after = { x: drag.startEntity.x + dx, y: drag.startEntity.y + dy };
+        let after = { x: drag.startEntity.x + dx, y: drag.startEntity.y + dy };
+        // World mode: report the GameObject's ACTUAL final position, not the
+        // raw pointer delta — snapping may have adjusted it during the drag,
+        // and the raw-delta value would make the entity "un-snap" on save.
+        if (getEditorMode(this.game) !== 'hud') {
+            const go = this.findEntityRegistry()?.byId(drag.entityId);
+            if (go)
+                after = { x: go.x, y: go.y };
+        }
         // Reset the per-drag delta accumulator on the GO if HUD mode left one.
         if (getEditorMode(this.game) === 'hud') {
             const reg = this.findEntityRegistry();
@@ -1389,6 +1424,101 @@ export class EditorOverlayScene extends Phaser.Scene {
             window.parent.postMessage(message, '*');
         }
     }
+    // --- Snap-to-align (2026-06-11) -------------------------------------------
+    //
+    // Figma-style magnetic alignment while dragging. The dragged entity's
+    // left/center/right (and top/center/bottom) lines are tested against the
+    // cached candidate lines; when one comes within ~8 screen px the position
+    // snaps to it and a pink guide line renders across the viewport. X and Y
+    // snap independently. Cmd/Ctrl held during the drag bypasses snapping.
+    /** Candidate alignment lines: world-bounds edges/centers + every OTHER entity's. */
+    buildSnapCandidates(draggedId) {
+        if (getEditorMode(this.game) === 'hud') {
+            this.snapCandidates = null;
+            return;
+        }
+        const xs = [];
+        const ys = [];
+        if (this.worldBounds) {
+            const wb = this.worldBounds;
+            xs.push(wb.x, wb.x + wb.width / 2, wb.x + wb.width);
+            ys.push(wb.y, wb.y + wb.height / 2, wb.y + wb.height);
+        }
+        const registry = this.findEntityRegistry();
+        if (registry) {
+            for (const go of registry.all()) {
+                if (go.getData('entityId') === draggedId)
+                    continue;
+                const b = computeBounds(go);
+                if (!b || (b.width === 0 && b.height === 0))
+                    continue;
+                xs.push(b.x, b.x + b.width / 2, b.x + b.width);
+                ys.push(b.y, b.y + b.height / 2, b.y + b.height);
+            }
+        }
+        this.snapCandidates = { xs, ys };
+        this.snapGuides = { xs: [], ys: [] };
+    }
+    /**
+     * Snap a candidate position against the cached lines. Returns the
+     * adjusted position (or null when nothing is within threshold) and
+     * records the matched guide lines for update() to draw.
+     */
+    applySnap(go, rawX, rawY) {
+        this.snapGuides = { xs: [], ys: [] };
+        const cands = this.snapCandidates;
+        if (!cands)
+            return null;
+        const b = computeBounds(go);
+        if (!b)
+            return null;
+        const pos = go;
+        // Bounds offset relative to the GO's transform position is constant
+        // during the drag — derive once from the current frame's bounds.
+        const offL = b.x - pos.x;
+        const offT = b.y - pos.y;
+        const cam = this.findActiveEditorCamera();
+        const zoom = cam?.zoom ?? 1;
+        const threshold = 8 / zoom; // 8 screen px regardless of zoom
+        const snapAxis = (raw, off, size, lines) => {
+            const edges = [raw + off, raw + off + size / 2, raw + off + size];
+            let best = null;
+            for (const line of lines) {
+                for (const e of edges) {
+                    const d = Math.abs(e - line);
+                    if (d <= threshold && (!best || d < best.d)) {
+                        best = { pos: raw + (line - e), guide: line, d };
+                    }
+                }
+            }
+            return best ? { pos: best.pos, guide: best.guide } : null;
+        };
+        const sx = snapAxis(rawX, offL, b.width, cands.xs);
+        const sy = snapAxis(rawY, offT, b.height, cands.ys);
+        if (sx)
+            this.snapGuides.xs.push(sx.guide);
+        if (sy)
+            this.snapGuides.ys.push(sy.guide);
+        if (!sx && !sy)
+            return null;
+        return { x: sx?.pos ?? rawX, y: sy?.pos ?? rawY };
+    }
+    /** Pink alignment guide lines across the visible viewport while snapped. */
+    drawSnapGuides() {
+        if (this.snapGuides.xs.length === 0 && this.snapGuides.ys.length === 0)
+            return;
+        const cam = this.findActiveEditorCamera();
+        if (!cam)
+            return;
+        const view = cam.worldView;
+        this.graphics.lineStyle(1 / cam.zoom, 0xff2d78, 0.9);
+        for (const x of this.snapGuides.xs) {
+            this.graphics.lineBetween(x, view.y, x, view.y + view.height);
+        }
+        for (const y of this.snapGuides.ys) {
+            this.graphics.lineBetween(view.x, y, view.x + view.width, y);
+        }
+    }
     // --- Rect-entity resize-handle drag (2026-06-10) --------------------------
     //
     // Same 8-handle affordance as the tilemap resize above, generalized to
@@ -1707,6 +1837,8 @@ export class EditorOverlayScene extends Phaser.Scene {
         // Rect-entity resize handles — render whenever a rect entity is
         // selected (2026-06-10).
         this.drawEntityResizeOverlay();
+        // Snap-to-align guide lines — render while a drag is snapped (2026-06-11).
+        this.drawSnapGuides();
     }
     /**
      * Render the 8 resize handles (when paint mode is active) and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umicat/phaser-sdk",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Umicat Phaser 3 SDK — game infrastructure for the Umicat platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",