@magicpixelart/cli 0.5.12 → 0.5.14

package/CHANGELOG.md

@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.14] — 2026-08-26
+
+### Fixed
+
+- **Watch no longer re-downloads the whole game on catch-up.** Connect
+  originals almost never match MagicPixel's re-encoded composite hash, so
+  comparing those bytes queued ~every PNG (`492/3116…`) and would overwrite
+  the Unity files. Pull now skips a connected sprite unless the cloud
+  composite actually changed (or an editor save cleared the cached hash).
+  Ingest collision slugs (`ground-ice-snow-4`) alias onto the original PNG
+  instead of dumping copies into `Assets/MagicPixel`.
+- **`connect <folder>` actually narrows the default `**` working set.** Adding
+  a folder used to OR with `**` and keep every sprite. `connect '**'` restores
+  all sprites. Godot's `.godot/` import cache is not ingested.
+- **Editor saves of connected sprites still pull when the Unity flag is
+  missing.** A save nulls `artboard_index`; the next manifest often omits
+  `unity`. Watch writes those pixels back to the original game PNG. `lastSync`
+  advances past every row the fetch saw, including skipped drafts.
+- **Watch no longer sits silent on `Checking your game files…`.** After a
+  pull, the upload half hashes local PNGs; the status line now shows
+  `1,200 / 3,126` instead of a frozen timestamp. The game-tree walk is reused
+  for 30s so each 2s poll does not re-list thousands of folders.
+- **Ctrl+C drain message** says `Ctrl+C again` instead of `undefined`.
+- **Single-artboard downloads no longer composite in the edge worker.**
+  Unity ingest sheets (including 2048/4096 tiles) are served from storage
+  so a catch-up download does not 546 the isolate. The CLI writes those
+  bytes even when they differ from a cached composite hash.
+
+## [0.5.13] — 2026-08-26
+
+### Fixed
+
+- **Connect no longer hangs at `0 sprites · 1 folder`.** Full Unity games
+  (`ProjectSettings` present) scan `Assets/` only — listing Library and the
+  rest of the project root blocked the spinner before any sprite was found.
+  Directory reads stream so the path keeps updating (`Assets/Sprites`), and
+  nested walks no longer deadlock on the folder limiter.
+- **Push no longer aborts the rest of a connect on a 502.** Batches of 8
+  (down from 20) persist after each success. A gateway error splits the
+  batch instead of crashing; already-uploaded sprites are remembered so a
+  re-run skips them.
+- **`connect` copy.** Re-running `connect '**'` no longer prints
+  `connect pattern already present: **`. First-time connect says
+  `now syncing all sprites in your game`.
+
+### Changed
+
+- **Unity/Godot/GameMaker default to all game sprites.** `start` and `sync`
+  ingest the game tree without a separate `connect '**'`. Use `connect` only
+  to narrow folders. Daily command is `sync --watch`.
+
 ## [0.5.12] — 2026-08-26
 
 ### Fixed

package/README.md

@@ -24,14 +24,15 @@ Unity project or UPM package (`Assets`/`assets`, `Editor`/`Runtime`), Godot
 npx @magicpixelart/cli start
 ```
 
-That walks you through everything: detects your framework, writes `magicpixel.json`, prompts for your API key (paste it from [magicpixel.art/settings](https://magicpixel.art/settings) → API Keys), pulls flagged sprites, and indexes game PNGs locally. Nothing is imported into the library until you connect a working set:
+That walks you through everything: detects your engine or framework, writes `magicpixel.json`, prompts for your API key (paste it from [magicpixel.art/settings](https://magicpixel.art/settings) → API Keys), and syncs sprites both ways. Unity, Godot, and GameMaker default to all game PNGs.
+
+Then leave this running while you work:
 
 ```bash
-npx @magicpixelart/cli search hero
-npx @magicpixelart/cli connect 'assets/Sprites/**'
+npx @magicpixelart/cli sync --watch
 ```
 
-Connected sprites write back to their original game path. New MagicPixel-only art still lands in `outDir`.
+After `npm i -D @magicpixelart/cli` you can type `magicpixel sync --watch`. Connected sprites write back to their original game path. New MagicPixel-only art still lands in `outDir`. To sync only some folders: `npx @magicpixelart/cli connect 'assets/Sprites/**'`.
 
 When it finishes:
 
@@ -109,9 +110,9 @@ No bundler config, no runtime, no extra package.
 | `logout` | Remove the stored API key. |
 | `doctor` | Print a one-screen diagnostic — paste it to your AI agent when something breaks. |
 | `repair [--dry-run] [-y]` | Self-heal a broken sync: validate key → quarantine `state.json` → prune empty dirs → full re-sync. |
-| `sync [...flags]` | Fetch manifest, diff against disk, download changed assets, prune orphans. |
-| `push [--dry-run] [--flatten]` | Upload local PNG edits (and the `connect` working set) back to MagicPixel. |
-| `connect <glob>` | Add a game-sprite glob to the working set and ingest matching PNGs. |
+| `sync [...flags]` | Two-way: pull MagicPixel edits and push changed game sprites. |
+| `push [--dry-run] [--flatten]` | Upload local PNG edits (and connected game sprites) back to MagicPixel. |
+| `connect <glob>` | Limit which game folders sync (default is all sprites on Unity/Godot/GameMaker). |
 | `search <query>` | Search indexed game PNGs (no network). |
 | `add <glob>` / `remove <glob>` | Manage `include` patterns. |
 | `list` | Print matching manifest as a table. |
@@ -146,7 +147,7 @@ Sync is built to be cheap: a no-op run is one small manifest request, zero PNG b
 | `outDir`   | `string`   | framework-dependent     | Where PNGs (and `index.ts`) are written.         |
 | `include`  | `string[]` | `["**/*"]`              | Globs (picomatch) matched against `folder/slug`. |
 | `exclude`  | `string[]` | `[]`                    | Globs to exclude.                                |
-| `connect`  | `string[]` | `[]`                    | Working-set globs of game PNGs to adopt into Connected. Empty = index only. |
+| `connect`  | `string[]` | `["**"]` on engines | Game PNG globs to keep in Connected. Empty on JS projects. |
 | `emitIndex`| `boolean`  | `true`                  | Emit `<outDir>/index.ts` with typed asset map.   |
 | `unityPpu` | `number?`  | `32`                    | Unity only: pixels-per-unit in generated `.meta`. |
 | `unitySyncAll` | `boolean?` | `false`             | Unity only: sync every artboard, not just those flagged in the editor. |

package/dist/api.js

@@ -280,15 +280,15 @@ export function retryAfterMsFromResponse(res) {
     }
     return 0;
 }
-/** Max sprites the server accepts per request (mirrors MAX_SPRITES_PER_REQUEST). */
-export const PUSH_BATCH_SIZE = 20;
+/** CLI send size. The server allows 20; smaller batches survive Worker 502s. */
+export const PUSH_BATCH_SIZE = 8;
 const DEFAULT_INGEST_ENDPOINT = 'https://magicpixel.art/api/public/integration/ingest';
 export function resolveIngestEndpoint() {
     const override = process.env.MAGICPIXEL_INGEST_ENDPOINT?.trim();
     return override ? validateEndpointUrl(override) : DEFAULT_INGEST_ENDPOINT;
 }
 /** Post one batch of sprites. Shares the transient-retry policy with pulls. */
-export async function pushSprites(sprites) {
+export async function pushSprites(sprites, retryOpts) {
     const url = resolveIngestEndpoint();
     return retryTransient('push', async () => {
         const { headers, requestId } = buildHeaders({ 'Content-Type': 'application/json' });
@@ -308,5 +308,41 @@ export async function pushSprites(sprites) {
         }
         const bodyText = await res.text();
         throw new ApiError(res.status, withRequestId(friendly(res.status, bodyText, 'push'), serverRequestId), serverRequestId, retryAfterMsFromResponse(res));
-    });
+    }, retryOpts);
+}
+function isTransientPushError(e) {
+    return e instanceof ApiError && (e.status >= 500 || e.status === 429);
+}
+/**
+ * Push a batch, splitting in half on persistent 502/5xx so one fat request
+ * cannot abort the rest of a connect/sync.
+ */
+export async function pushSpritesAdaptive(sprites, retryOpts) {
+    if (sprites.length === 0)
+        return [];
+    try {
+        return await pushSprites(sprites, retryOpts);
+    }
+    catch (e) {
+        if (!isTransientPushError(e))
+            throw e;
+        if (sprites.length === 1) {
+            return [{ key: sprites[0].key, status: 'error', message: e.message }];
+        }
+        const mid = Math.ceil(sprites.length / 2);
+        const left = await pushSpritesAdaptive(sprites.slice(0, mid), retryOpts);
+        try {
+            const right = await pushSpritesAdaptive(sprites.slice(mid), retryOpts);
+            return [...left, ...right];
+        }
+        catch (rightErr) {
+            // Left half already landed — don't drop those results when the rest fails.
+            const right = sprites.slice(mid).map((s) => ({
+                key: s.key,
+                status: 'error',
+                message: rightErr.message,
+            }));
+            return [...left, ...right];
+        }
+    }
 }

package/dist/commands/connect.js

@@ -4,23 +4,27 @@ import { loadConfig, saveConfig } from '../config.js';
 import { assertSafeGlob } from '../util/security.js';
 import { detectProjectKind, isEngineKind } from '../util/framework.js';
 import { indexGamePngs, matchConnectGlobs, GAME_INDEX_CAP_HINT, connectCapMessage, countingSpritesText } from '../util/gameScan.js';
+import { isAllSpritesGlob, nextConnectGlobs } from '../util/engineConnect.js';
 import { cmd } from '../util/invoke.js';
 import { runPush } from './push.js';
+/** Plain-language label for a connect glob (`**` is not meaningful to players). */
+export function describeWorkingSet(glob) {
+    return isAllSpritesGlob(glob) ? 'all sprites in your game' : glob.trim();
+}
 /**
- * Add a working-set glob and ingest matching game PNGs into Connected.
- * Sync writes edits back to the original files — not a copy under outDir.
+ * Add or narrow a working-set glob, then ingest matching game PNGs.
+ * A specific folder replaces the default `**`. Sync writes edits back to
+ * the original files — not a copy under outDir.
  */
 export async function connectCommand(glob) {
     const pattern = assertSafeGlob(glob);
     const config = await loadConfig();
-    const already = config.connect.includes(pattern);
-    if (!already) {
-        config.connect.push(pattern);
+    const next = nextConnectGlobs(config.connect, pattern);
+    const changed = next.length !== config.connect.length || next.some((g, i) => g !== config.connect[i]);
+    if (changed) {
+        config.connect = next;
         await saveConfig(config);
-        console.log(kleur.green(`✓ added connect pattern: ${pattern}`));
-    }
-    else {
-        console.log(kleur.dim(`  connect pattern already present: ${pattern}`));
+        console.log(kleur.green(`✓ now syncing ${describeWorkingSet(pattern)}`));
     }
     const kind = await detectProjectKind();
     if (!isEngineKind(kind)) {
@@ -44,7 +48,7 @@ export async function connectCommand(glob) {
         return;
     }
     const n = matched.entries.length;
-    console.log(kleur.dim(`  ${n} sprite${n === 1 ? '' : 's'} in working set (of ${index.files.length} indexed` +
+    console.log(kleur.dim(`  ${n} sprite${n === 1 ? '' : 's'} to sync (of ${index.files.length} in your game` +
         (matched.capped ? `, ${matched.total} matched` : '') +
         `).`));
     if (n >= 200) {

package/dist/commands/init.js

@@ -9,6 +9,7 @@ import { detectProjectKind, suggestOutDir, hasPackageJson, isStaticOutDir, suppo
 import { assertSafeOutDir } from '../util/security.js';
 import { atomicWrite } from '../util/atomicWrite.js';
 import { cmd } from '../util/invoke.js';
+import { DEFAULT_ENGINE_CONNECT } from '../util/engineConnect.js';
 const WATCH_SCRIPT_NAME = 'magicpixel:watch';
 const WATCH_SCRIPT_CMD = 'magicpixel sync --watch';
 export async function initCommand(opts) {
@@ -23,6 +24,8 @@ export async function initCommand(opts) {
     const kind = await detectProjectKind();
     const suggestedOutDir = suggestOutDir(kind);
     config.outDir = suggestedOutDir;
+    if (isEngineKind(kind))
+        config.connect = [...DEFAULT_ENGINE_CONNECT];
     const pkgExists = hasPackageJson();
     const pkgPath = resolve(process.cwd(), 'package.json');
     let addWatchScript = pkgExists && !isEngineKind(kind);

package/dist/commands/push.js

@@ -9,10 +9,10 @@
 import kleur from 'kleur';
 import ora from 'ora';
 import { mkdir, readFile, rename } from 'node:fs/promises';
-import { dirname } from 'node:path';
-import { relative, resolve } from 'node:path';
+import { dirname, relative, resolve } from 'node:path';
 import { loadConfig, loadState, saveState } from '../config.js';
-import { PUSH_BATCH_SIZE, pushSprites } from '../api.js';
+import { ensureEngineConnect } from '../util/engineConnect.js';
+import { PUSH_BATCH_SIZE, pushSpritesAdaptive } from '../api.js';
 import { hashFile } from '../util/hash.js';
 import { createLimit } from '../util/limit.js';
 import { assetDiskPathFromKey, walkOutDirPngs } from '../util/paths.js';
@@ -35,7 +35,7 @@ export async function pushCommand(opts = {}) {
  * set is ingested without a second command).
  */
 export async function runPush(opts = {}) {
-    const config = await loadConfig();
+    const config = await ensureEngineConnect(await loadConfig(), process.cwd(), !opts.dryRun);
     const state = await loadState();
     return runPushWith(config, state, opts);
 }
@@ -68,10 +68,22 @@ export async function runPushWith(config, state, opts = {}) {
     const candidates = [];
     const cwdAbs = resolve(process.cwd());
     let skippedUnsafe = 0;
-    const synced = state.synced ?? {};
-    const byRel = indexSyncedBySourceRel(synced);
+    const knownSynced = state.synced ?? {};
+    const byRel = indexSyncedBySourceRel(knownSynced);
     const scan = createLimit(PUSH_SCAN_CONCURRENCY);
-    await Promise.all([...absByKey.entries()].map(([key, abs]) => scan(async () => {
+    const toHash = [...absByKey.entries()];
+    let hashed = 0;
+    const reportHash = () => {
+        hashed++;
+        const n = hashed.toLocaleString('en-US');
+        const t = toHash.length.toLocaleString('en-US');
+        if (spinner)
+            spinner.text = `Checking your game files…  ${n} / ${t}`;
+        else if (opts.onStatus && (hashed === 1 || hashed === toHash.length || hashed % 25 === 0)) {
+            opts.onStatus(`Checking your game files…  ${n} / ${t}`);
+        }
+    };
+    await Promise.all(toHash.map(([key, abs]) => scan(async () => {
         try {
             if (!verifiedIoPaths.has(abs)) {
                 await assertSafeIoPath(abs, cwdAbs);
@@ -80,29 +92,33 @@ export async function runPushWith(config, state, opts = {}) {
         }
         catch {
             skippedUnsafe++;
+            reportHash();
             return;
         }
         const entry = entryByKey.get(key);
         const sourceRel = entry?.sourceRel ?? sourceByKey.get(key);
-        const stateKey = resolveSyncedKey({ key, sourceRel }, synced, byRel);
-        const known = stateKey ? synced[stateKey] : undefined;
+        const stateKey = resolveSyncedKey({ key, sourceRel }, knownSynced, byRel);
+        const known = stateKey ? knownSynced[stateKey] : undefined;
         const hint = known?.diskSha256 && known.diskMtimeMs != null && known.diskSize != null
             ? { sha256: known.diskSha256, mtimeMs: known.diskMtimeMs, size: known.diskSize }
             : undefined;
-        const hashed = await hashFile(abs, hint);
-        if (!hashed)
+        const hashedFile = await hashFile(abs, hint);
+        if (!hashedFile) {
+            reportHash();
             return;
+        }
         const segments = entry
             ? entry.adoptRel.replace(/\.png$/i, '').split('/')
             : key.split('/');
         candidates.push({
             key,
             segments,
-            diskSha256: hashed.sha256,
+            diskSha256: hashedFile.sha256,
             ...(sourceRel ? { sourceRel } : {}),
-            diskMtimeMs: hashed.mtimeMs,
-            diskSize: hashed.size,
+            diskMtimeMs: hashedFile.mtimeMs,
+            diskSize: hashedFile.size,
         });
+        reportHash();
     })));
     const folderTreeKeys = new Set(matched.entries.map((e) => e.key));
     for (const k of absByKey.keys()) {
@@ -183,43 +199,37 @@ export async function runPushWith(config, state, opts = {}) {
     }
     const progress = quiet ? null : ora(`Pushing 0/${sprites.length}…`).start();
     const results = [];
-    for (let i = 0; i < sprites.length; i += PUSH_BATCH_SIZE) {
-        const batch = sprites.slice(i, i + PUSH_BATCH_SIZE);
-        const batchResults = await pushSprites(batch);
-        results.push(...batchResults);
-        if (progress)
-            progress.text = `Pushing ${Math.min(i + batch.length, sprites.length)}/${sprites.length}…`;
+    let synced = { ...(state.synced ?? {}) };
+    try {
+        for (let i = 0; i < sprites.length; i += PUSH_BATCH_SIZE) {
+            const batch = sprites.slice(i, i + PUSH_BATCH_SIZE);
+            const batchResults = await pushSpritesAdaptive(batch);
+            results.push(...batchResults);
+            synced = await commitPushResults({
+                synced,
+                batchResults,
+                candidates,
+                sourceByKey,
+                shaByKey,
+                fpByKey,
+                outDir: config.outDir,
+            });
+            await saveState({ ...state, synced });
+            if (progress)
+                progress.text = `Pushing ${Math.min(i + batch.length, sprites.length)}/${sprites.length}…`;
+        }
+    }
+    catch (e) {
+        progress?.fail(`Push stopped after ${results.length}/${sprites.length}. ${e.message}`);
+        if (results.length > 0)
+            await saveState({ ...state, synced });
+        throw e;
     }
     const counts = { created: 0, updated: 0, unchanged: 0, conflict: 0, error: 0 };
-    const failedKeys = new Set(results.filter((r) => r.status === 'conflict' || r.status === 'error').map((r) => r.key));
-    const fingerprinted = applyDiskFingerprints(state.synced ?? {}, candidates.filter((c) => !failedKeys.has(c.key)));
-    const nextSynced = { ...fingerprinted.next };
     for (const r of results) {
-        counts[r.status] = (counts[r.status] ?? 0) + 1;
-        const stateKey = r.cloudKey && r.cloudKey !== r.key ? r.cloudKey : r.key;
-        const sourceRel = sourceByKey.get(r.key) ?? sourceByKey.get(stateKey);
-        if (stateKey !== r.key && (r.status === 'created' || r.status === 'updated')) {
-            if (!sourceRel)
-                await renameLocalSprite(config.outDir, r.key, stateKey);
-        }
-        if ((r.status === 'created' || r.status === 'updated' || r.status === 'unchanged') && r.assetId && r.sha256) {
-            if (stateKey !== r.key)
-                delete nextSynced[r.key];
-            const diskSha256 = shaByKey.get(r.key) ?? shaByKey.get(stateKey) ?? nextSynced[stateKey]?.diskSha256;
-            const fp = fpByKey.get(r.key) ?? fpByKey.get(stateKey);
-            nextSynced[stateKey] = {
-                assetId: r.assetId,
-                layerIdx: typeof r.layerIdx === 'number' ? r.layerIdx : (nextSynced[stateKey]?.layerIdx ?? 0),
-                sha256: r.sha256,
-                layers: 1,
-                ...(diskSha256 ? { diskSha256 } : {}),
-                ...(fp?.diskMtimeMs != null ? { diskMtimeMs: fp.diskMtimeMs } : {}),
-                ...(fp?.diskSize != null ? { diskSize: fp.diskSize } : {}),
-                ...(sourceRel ? { sourceRel } : {}),
-            };
-        }
+        if (r.status in counts)
+            counts[r.status]++;
     }
-    await saveState({ ...state, synced: nextSynced });
     const failed = counts.conflict + counts.error;
     const summary = `created ${counts.created}, updated ${counts.updated}, unchanged ${counts.unchanged}` +
         (counts.conflict ? `, conflicts ${counts.conflict}` : '') +
@@ -248,6 +258,38 @@ export async function runPushWith(config, state, opts = {}) {
         process.exitCode = 1;
     return { ...counts, imported: matched.entries.length };
 }
+async function commitPushResults(opts) {
+    const { batchResults, candidates, sourceByKey, shaByKey, fpByKey, outDir } = opts;
+    const failedKeys = new Set(batchResults.filter((r) => r.status === 'conflict' || r.status === 'error').map((r) => r.key));
+    const batchKeys = new Set(batchResults.map((r) => r.key));
+    const fingerprinted = applyDiskFingerprints(opts.synced, candidates.filter((c) => batchKeys.has(c.key) && !failedKeys.has(c.key)));
+    const nextSynced = { ...fingerprinted.next };
+    for (const r of batchResults) {
+        const stateKey = r.cloudKey && r.cloudKey !== r.key ? r.cloudKey : r.key;
+        const sourceRel = sourceByKey.get(r.key) ?? sourceByKey.get(stateKey);
+        if (stateKey !== r.key && (r.status === 'created' || r.status === 'updated')) {
+            if (!sourceRel)
+                await renameLocalSprite(outDir, r.key, stateKey);
+        }
+        if ((r.status === 'created' || r.status === 'updated' || r.status === 'unchanged') && r.assetId && r.sha256) {
+            if (stateKey !== r.key)
+                delete nextSynced[r.key];
+            const diskSha256 = shaByKey.get(r.key) ?? shaByKey.get(stateKey) ?? nextSynced[stateKey]?.diskSha256;
+            const fp = fpByKey.get(r.key) ?? fpByKey.get(stateKey);
+            nextSynced[stateKey] = {
+                assetId: r.assetId,
+                layerIdx: typeof r.layerIdx === 'number' ? r.layerIdx : (nextSynced[stateKey]?.layerIdx ?? 0),
+                sha256: r.sha256,
+                layers: 1,
+                ...(diskSha256 ? { diskSha256 } : {}),
+                ...(fp?.diskMtimeMs != null ? { diskMtimeMs: fp.diskMtimeMs } : {}),
+                ...(fp?.diskSize != null ? { diskSize: fp.diskSize } : {}),
+                ...(sourceRel ? { sourceRel } : {}),
+            };
+        }
+    }
+    return nextSynced;
+}
 /** Persist disk sha256 onto existing synced rows so the next scan can skip. */
 async function persistDiskFingerprints(state, candidates) {
     const { next, changed } = applyDiskFingerprints(state.synced ?? {}, candidates);

package/dist/commands/start.js

@@ -19,7 +19,7 @@ import { cmd } from '../util/invoke.js';
  */
 export async function startCommand(opts = {}) {
     console.log(kleur.bold('🪄  MagicPixel — first-run setup'));
-    console.log(kleur.dim('  This links your game project. Sprites are indexed locally; nothing is imported until you connect a working set.'));
+    console.log(kleur.dim('  This links your game project and syncs sprites both ways.'));
     console.log();
     const kind = await detectProjectKind();
     // Engine projects (including Unity UPM packages) have no package.json
@@ -109,8 +109,7 @@ export async function startCommand(opts = {}) {
         console.log(`  ${kleur.green('▶')} ${kleur.bold(`${cmd('sync')} --watch`)}   ${kleur.dim('# keeps sprites fresh while you edit them in MagicPixel')}`);
     }
     console.log();
-    console.log(kleur.dim(`  Find sprites with \`${cmd('search')} hero\`, then \`${cmd('connect')} 'assets/Sprites/**'\` to add a working set.`));
-    console.log(kleur.dim('  Connected sprites write back to their original game path. New MagicPixel art lands in outDir.'));
+    console.log(kleur.dim('  Game sprites write back to their original path. New MagicPixel art lands in outDir.'));
     console.log();
     if (await hasDevScript()) {
         const watchCmd = hasWatch ? 'npm run magicpixel:watch' : `${cmd('sync')} --watch`;

package/dist/commands/sync.js

@@ -1,10 +1,10 @@
 import kleur from 'kleur';
 import ora from 'ora';
-import { createHash } from 'node:crypto';
 import { mkdir, unlink, readdir, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
 import { loadConfig, loadState, saveState } from '../config.js';
+import { ensureEngineConnect } from '../util/engineConnect.js';
 import { fetchAllManifest, fetchAssetBytes, ApiError, getLastProjectInfo } from '../api.js';
 import { fileSha256 } from '../util/hash.js';
 import { pruneEmptyDirs, walkOutDirPngs } from '../util/paths.js';
@@ -13,9 +13,9 @@ import { emitTypedIndex, ensureAgentsDoc, scanDiskAssets } from '../util/emitInd
 import { assertPathInsideRoot, assertSafeIoPath } from '../util/security.js';
 import { detectProjectKind, isEngineKind } from '../util/framework.js';
 import { indexGamePngs, matchConnectGlobs, GAME_INDEX_CAP_HINT, connectCapMessage, countingSpritesText } from '../util/gameScan.js';
-import { collectSourceRelMap, isPathInside, syncDiskPathFromKey } from '../util/syncPath.js';
+import { aliasCollisionKeys, collectSourceRelMap, isPathInside, syncDiskPathFromKey } from '../util/syncPath.js';
 import { DEFAULT_UNITY_PPU, writeMissingUnityMetas } from '../util/unityMeta.js';
-import { filterUnityManifest } from '../util/unityFilter.js';
+import { applyUnityPullPolicy, isWorkingSetEntry, workingSetPullKeys } from '../util/unityFilter.js';
 import { selectFullSyncOrphans } from '../util/prunePolicy.js';
 import { runTmpJanitor } from '../util/tmpJanitor.js';
 import { friendlyFsError } from '../util/errors.js';
@@ -24,6 +24,7 @@ import { formatBytes } from '../util/format.js';
 import { computePreviousKeyOrphans } from '../util/previousKeyOrphans.js';
 import { cmd } from '../util/invoke.js';
 import { formatWatchSpriteLine } from '../util/watchCopy.js';
+import { shouldPullEntry } from '../util/pullDecision.js';
 import { runPush } from './push.js';
 export async function syncCommand(opts) {
     // Sweep any leaked `<file>.<pid>.<hex>.tmp` files left behind by a prior
@@ -32,10 +33,16 @@ export async function syncCommand(opts) {
     // never race a concurrent in-flight write. See util/tmpJanitor.ts.
     try {
         const cfg = await loadConfig();
-        await runTmpJanitor(cfg.outDir);
+        try {
+            await runTmpJanitor(cfg.outDir);
+        }
+        catch {
+            /* janitor is best-effort — never let it block a sync */
+        }
+        await ensureEngineConnect(cfg, process.cwd(), !opts.dryRun);
     }
     catch {
-        /* janitor is best-effort — never let it block a sync */
+        /* missing/invalid config is reported by runOnce / watchLoop */
     }
     if (opts.watch) {
         await watchLoop(opts);
@@ -105,6 +112,11 @@ async function watchLoop(opts) {
     // tick counts (90 / 300) which made the slowdown timing scale with intervalSec.
     const IDLE_SOFT_BACKOFF_SECONDS = 180;
     const IDLE_HARD_BACKOFF_SECONDS = 900;
+    // Re-walk the game tree on this cadence so new PNGs are ingested without
+    // listing thousands of folders on every 2s tick.
+    const GAME_INDEX_TTL_MS = 30_000;
+    let gameIndexCache = header.gameIndex;
+    let gameIndexAt = Date.now();
     // Cancellable idle sleep — `onStopSignal` calls `wakeStop()` so the next
     // tick exits immediately instead of waiting out the full backoff (which can
     // be 60s at the error ceiling). Initialised to a no-op so the first
@@ -119,9 +131,11 @@ async function watchLoop(opts) {
         stopping = true;
         wakeStop();
         process.stdout.write('\x1b[2K\r');
+        const sig = signal === 'SIGTERM' ? 'SIGTERM' : 'SIGINT';
         if (inFlight) {
-            console.log(kleur.dim(`Still finishing this check… (${signal} again to stop now)`));
-            process.once(signal, () => process.exit(signal === 'SIGINT' ? 130 : 143));
+            const again = sig === 'SIGINT' ? 'Ctrl+C' : 'SIGTERM';
+            console.log(kleur.dim(`Still finishing this check… (${again} again to stop now)`));
+            process.once(sig, () => process.exit(sig === 'SIGINT' ? 130 : 143));
         }
         else {
             if (!opts.quiet)
@@ -143,7 +157,18 @@ async function watchLoop(opts) {
         };
         try {
             onStatus('Checking MagicPixel…');
-            const r = await runOnce({ ...opts, watch: false }, { watchMode: true, onStatus, gameIndex: header.gameIndex });
+            const reuseIndex = gameIndexCache && Date.now() - gameIndexAt < GAME_INDEX_TTL_MS
+                ? gameIndexCache
+                : undefined;
+            const r = await runOnce({ ...opts, watch: false }, {
+                watchMode: true,
+                onStatus,
+                gameIndex: reuseIndex,
+                onGameIndex: (idx) => {
+                    gameIndexCache = idx;
+                    gameIndexAt = Date.now();
+                },
+            });
             // Reset backoff on any successful tick. Resume message fires once when
             // we recover from an auth pause — `getApiKey()` re-reads
             // .magicpixel/credentials on every call, so a `magicpixel login` in
@@ -242,7 +267,6 @@ async function watchLoop(opts) {
             }
         }
         finally {
-            header.gameIndex = undefined;
             inFlight = false;
         }
     };
@@ -371,8 +395,12 @@ async function runOnce(opts, runOpts = {}) {
     if (!spinner)
         onStatus?.(since ? 'Checking MagicPixel for edits…' : 'Fetching your sprites from MagicPixel…');
     let manifest;
+    // Capture before the Unity filter drops rows — lastSync must not jump past
+    // an editor save whose `unity` flag was omitted on this tick.
+    let observedUpdatedAt = null;
     try {
         manifest = await fetchAllManifest(config, since);
+        observedUpdatedAt = maxIsoTimestamp(manifest.map((e) => e.updated_at));
         const projectInfo = getLastProjectInfo();
         const projectSuffix = projectInfo && verbose
             ? kleur.dim(` · project: ${projectInfo.name ?? projectInfo.id.slice(0, 8)}`)
@@ -413,14 +441,19 @@ async function runOnce(opts, runOpts = {}) {
                 onProgress: (p) => {
                     const n = p.pngs.toLocaleString('en-US');
                     const f = p.folders.toLocaleString('en-US');
-                    onStatus?.(p.folders > 0
-                        ? `Looking through your game sprites…  ${n} sprites · ${f} folders`
-                        : `Looking through your game sprites…  ${n}`);
+                    onStatus?.(p.current
+                        ? `Looking through your game sprites…  ${n} sprites · ${f} folders  ·  ${p.current}`
+                        : p.folders > 0
+                            ? `Looking through your game sprites…  ${n} sprites · ${f} folders`
+                            : `Looking through your game sprites…  ${n}`);
                 },
             })
             : { files: [], capped: false });
+    if (!runOpts.gameIndex)
+        runOpts.onGameIndex?.(gameIndex);
     const connected = matchConnectGlobs(gameIndex, config.connect ?? []);
     const sourceByKey = collectSourceRelMap(connected.entries, state.synced);
+    aliasCollisionKeys(sourceByKey, manifest.map((e) => e.key));
     if (verbose && gameIndex.capped) {
         console.log(kleur.yellow(`! ${GAME_INDEX_CAP_HINT}`));
     }
@@ -432,6 +465,7 @@ async function runOnce(opts, runOpts = {}) {
             (connected.capped ? ` of ${connected.total} matched` : '')));
     }
     const pathForKey = (key) => syncDiskPathFromKey(config.outDir, key, sourceByKey);
+    const workingSet = workingSetPullKeys(sourceByKey, state.synced);
     // Files whose artboard is no longer flagged for Unity. Deleted even in
     // incremental mode: un-checking the box in the editor must actually remove
     // the sprite from the game project, not leave a stale copy behind.
@@ -442,14 +476,25 @@ async function runOnce(opts, runOpts = {}) {
     // response must never delete art from someone's game project.
     const unknownFlagPaths = new Set();
     if (projectKind === 'Unity') {
-        const filtered = filterUnityManifest(manifest, { syncAll: config.unitySyncAll });
+        const filtered = applyUnityPullPolicy(manifest, {
+            syncAll: config.unitySyncAll,
+            alwaysPull: (entry) => isWorkingSetEntry(entry, workingSet),
+        });
         if (filtered.unknown.length > 0) {
-            console.log(kleur.yellow(`! ${filtered.unknown.length} artboard${filtered.unknown.length === 1 ? '' : 's'} came back without a "Sync to Unity" flag — skipped (existing files kept).`));
-            console.log(kleur.dim(`  Fix: re-run \`${cmd('sync')}\` in a moment, or upgrade with \`npm i -D @magicpixelart/cli@latest\`.`));
+            const n = filtered.unknown.length;
+            const msg = `${n} artboard${n === 1 ? '' : 's'} came back without a "Sync to Unity" flag — skipped (existing files kept).`;
+            if (verbose) {
+                console.log(kleur.yellow(`! ${msg}`));
+                console.log(kleur.dim(`  Fix: re-run \`${cmd('sync')}\` in a moment, or upgrade with \`npm i -D @magicpixelart/cli@latest\`.`));
+            }
+            else {
+                onStatus?.(msg);
+            }
         }
         const unknownSet = new Set(filtered.unknown);
+        const pullSet = new Set(filtered.entries);
         for (const entry of manifest) {
-            if (filtered.entries.includes(entry))
+            if (pullSet.has(entry))
                 continue;
             const p = pathForKey(entry.key);
             if (unknownSet.has(entry)) {
@@ -480,7 +525,11 @@ async function runOnce(opts, runOpts = {}) {
                 bytesSaved: 0,
                 renamed: [],
             };
-            await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode);
+            if (observedUpdatedAt) {
+                const lastSync = state.lastSync && state.lastSync > observedUpdatedAt ? state.lastSync : observedUpdatedAt;
+                await saveState({ ...state, lastSync });
+            }
+            await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode, onStatus);
             return empty;
         }
         const skipped = manifest.length - filtered.entries.length;
@@ -524,10 +573,54 @@ async function runOnce(opts, runOpts = {}) {
     const toDownload = [];
     let bytesSaved = 0;
     let unchanged = 0;
+    const synced = state.synced ?? {};
+    const cloudShaByAssetId = new Map();
+    for (const s of Object.values(synced)) {
+        if (!s.assetId || !s.sha256)
+            continue;
+        const prev = cloudShaByAssetId.get(s.assetId);
+        if (prev && prev !== s.sha256)
+            cloudShaByAssetId.set(s.assetId, 'ambiguous');
+        else if (!prev)
+            cloudShaByAssetId.set(s.assetId, s.sha256);
+    }
+    const previousCloudSha = (entry) => {
+        const direct = synced[entry.key]?.sha256;
+        if (direct)
+            return direct;
+        for (const k of entry.previous_keys ?? []) {
+            const sha = synced[k]?.sha256;
+            if (sha)
+                return sha;
+        }
+        if (entry.asset_id) {
+            const sha = cloudShaByAssetId.get(entry.asset_id);
+            if (sha && sha !== 'ambiguous')
+                return sha;
+        }
+        return undefined;
+    };
     await Promise.all(manifest.map((entry) => diffLimit(async () => {
+        const previousCloudSha256 = previousCloudSha(entry);
+        const inWorkingSet = isWorkingSetEntry(entry, workingSet);
+        // Unchanged cloud composite: skip hashing the original PNG (it almost
+        // never matches) unless the file is gone and we need to restore it.
+        if (entry.sha256 && previousCloudSha256 === entry.sha256 && existsSync(pathFor(entry))) {
+            shaByEntryId.set(entry.id, null);
+            unchanged++;
+            if (entry.size_bytes)
+                bytesSaved += entry.size_bytes;
+            return;
+        }
         const localSha = await fileSha256(pathFor(entry));
         shaByEntryId.set(entry.id, localSha);
-        if (entry.sha256 && localSha && entry.sha256 === localSha) {
+        const pull = shouldPullEntry({
+            cloudSha256: entry.sha256,
+            localSha256: localSha,
+            previousCloudSha256,
+            inWorkingSet,
+        });
+        if (!pull) {
             unchanged++;
             if (entry.size_bytes)
                 bytesSaved += entry.size_bytes;
@@ -766,14 +859,9 @@ async function runOnce(opts, runOpts = {}) {
                     result.bytesSaved += entry.size_bytes;
             }
             else {
-                if (entry.sha256) {
-                    const actual = createHash('sha256').update(bytes).digest('hex');
-                    if (actual !== entry.sha256) {
-                        throw new Error(`sha256 mismatch (expected ${entry.sha256.slice(0, 12)}…, got ${actual.slice(0, 12)}…)`);
-                    }
-                }
-                // Wrap any of mkdir/writeFile so the user sees a friendly
-                // multi-line diagnostic instead of a raw `EACCES: permission denied`.
+                // Do not require bytes to match `entry.sha256`. Single-artboard
+                // downloads serve storage_path (so 2048/4096 Unity tiles do not
+                // 546 the isolate); that PNG can differ from a cached composite hash.
                 //
                 // NOTE: Asset PNGs deliberately use a direct writeFile rather than
                 // atomicWrite. Vite's chokidar watcher only suppresses atomic-rename
@@ -976,7 +1064,7 @@ async function runOnce(opts, runOpts = {}) {
         // rows whose `updated_at` lived in the gap between the manifest snapshot
         // and the next poll (notably when only metadata changed — e.g. artboard
         // renames — and the row updated between fetch start and save).
-        const maxUpdatedAt = maxIsoTimestamp(manifest.map((e) => e.updated_at));
+        const maxUpdatedAt = observedUpdatedAt ?? maxIsoTimestamp(manifest.map((e) => e.updated_at));
         if (maxUpdatedAt) {
             // Take the later of: newest row we saw, or the prior cursor. Never
             // rewind — an incremental sync that returned 0 rows must keep the
@@ -1048,16 +1136,16 @@ async function runOnce(opts, runOpts = {}) {
             printRenames(renamed, { withHints: true });
     }
     onStatus?.('Checking your game files…');
-    await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode);
+    await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode, onStatus);
     if (result.failed)
         process.exitCode = 1;
     return result;
 }
-async function maybePushLocalSprites(pushEnabled, verbose, gameIndex, announceErrors = verbose) {
+async function maybePushLocalSprites(pushEnabled, verbose, gameIndex, announceErrors = verbose, onStatus) {
     if (pushEnabled === false)
         return null;
     try {
-        return await runPush({ quiet: !verbose, gameIndex });
+        return await runPush({ quiet: !verbose, gameIndex, onStatus });
     }
     catch (e) {
         if (announceErrors) {

package/dist/index.js

@@ -83,7 +83,7 @@ program
     .action(wrap("repair", async (opts) => repairCommand(opts)));
 program
     .command('sync')
-    .description('Download changed assets from MagicPixel')
+    .description('Two-way sync: pull MagicPixel edits, push your game sprites')
     .option('--no-prune', 'Keep local files not in the manifest (pruning is now on by default)')
     .option('--dry-run', 'Print the plan without writing files')
     .option('--full', 'Ignore lastSync state; re-fetch the full manifest')
@@ -101,7 +101,7 @@ program
     .action(wrap("push", async (opts) => pushCommand(opts)));
 program
     .command('connect <glob>')
-    .description('Add a game-sprite glob to the working set and ingest matching PNGs')
+    .description('Limit which game folders sync (default is all sprites)')
     .addHelpText('after', '\nExamples:\n  $ magicpixel connect \'assets/Sprites/Hero/**\'\n  $ magicpixel connect Runtime/UI/hud.png\n')
     .action(wrap("connect", async (glob) => connectCommand(glob)));
 program

package/dist/util/engineConnect.js

@@ -0,0 +1,32 @@
+import { saveConfig } from '../config.js';
+import { detectProjectKind, isEngineKind } from './framework.js';
+export const DEFAULT_ENGINE_CONNECT = ['**'];
+const ALL_SPRITES_GLOBS = new Set(['**', '**/*', '**/**', '**/*.png', '**/**/*.png']);
+export function isAllSpritesGlob(glob) {
+    return ALL_SPRITES_GLOBS.has(glob.trim());
+}
+/**
+ * Next `connect` list after the user adds a glob.
+ * A specific folder replaces a default `**` (narrowing). `**` restores all
+ * sprites. Other globs accumulate. Stray `**` left over from an earlier
+ * default is dropped when narrowing so OR-matching cannot keep everything.
+ */
+export function nextConnectGlobs(current, pattern) {
+    if (isAllSpritesGlob(pattern))
+        return [...DEFAULT_ENGINE_CONNECT];
+    const withoutAll = current.filter((g) => !isAllSpritesGlob(g));
+    if (withoutAll.includes(pattern))
+        return withoutAll;
+    return [...withoutAll, pattern];
+}
+export async function ensureEngineConnect(config, cwd = process.cwd(), persist = true) {
+    if (config.connect.length > 0)
+        return config;
+    const kind = await detectProjectKind(cwd);
+    if (!isEngineKind(kind))
+        return config;
+    const next = { ...config, connect: [...DEFAULT_ENGINE_CONNECT] };
+    if (persist)
+        await saveConfig(next, cwd);
+    return next;
+}

package/dist/util/gameScan.js

@@ -4,7 +4,7 @@
  * globs select a working set; sync writes back to those original paths.
  */
 import { existsSync } from 'node:fs';
-import { readdir } from 'node:fs/promises';
+import { opendir } from 'node:fs/promises';
 import { relative, resolve } from 'node:path';
 import { isEngineKind, resolveChildDir } from './framework.js';
 import { assertPathInsideRoot, sanitizeSourceRel } from './security.js';
@@ -36,6 +36,7 @@ export const GAME_SCAN_SKIP_HIDDEN = new Set([
     '.git',
     '.svn',
     '.hg',
+    '.godot',
     '.magicpixel',
     '.vs',
     '.vscode',
@@ -52,8 +53,12 @@ export const MAX_GAME_INDEX = 10_000;
 export const MAX_GAME_CONNECT = MAX_GAME_INDEX;
 export const GAME_INDEX_CAP_HINT = `Game index hit ${MAX_GAME_INDEX} PNGs — later files aren't searchable or connectable.`;
 export function connectCapMessage(total, ingested) {
-    return (`${total} PNGs match the working set — ingesting the first ${ingested} (cap ${MAX_GAME_CONNECT}). ` +
-        `Narrow the glob, or add another connect pattern for the rest.`);
+    return (`${total} sprites match — syncing the first ${ingested} (cap ${MAX_GAME_CONNECT}). ` +
+        `Connect a smaller folder if you don't need all of them.`);
+}
+/** True for a full Unity game project (not an embedded UPM package). */
+function isUnityGameProject(cwd, assetRoot) {
+    return Boolean(assetRoot && existsSync(resolve(cwd, 'ProjectSettings')));
 }
 export function gameScanRoot(kind) {
     switch (kind) {
@@ -101,34 +106,69 @@ function toEntry(abs, cwdAbs, assetRoot) {
 function fmtCount(n, noun) {
     return `${n.toLocaleString('en-US')} ${noun}${n === 1 ? '' : 's'}`;
 }
+function shortPath(rel) {
+    const n = rel.replace(/\\/g, '/');
+    if (!n || n === '.')
+        return '';
+    return n.length <= 48 ? n : `…${n.slice(-47)}`;
+}
 /** Spinner / status copy while walking the game tree. */
 export function countingSpritesText(progress = 0) {
     const pngs = typeof progress === 'number' ? progress : progress.pngs;
     const folders = typeof progress === 'number' ? 0 : progress.folders;
-    if (pngs === 0 && folders === 0)
+    const current = typeof progress === 'number' ? undefined : progress.current;
+    if (pngs === 0 && folders === 0 && !current)
         return 'Counting sprites in your game…';
     const spriteBit = fmtCount(pngs, 'sprite');
+    const parts = [spriteBit];
     if (folders > 0)
-        return `Counting sprites in your game…  ${spriteBit} · ${fmtCount(folders, 'folder')}`;
-    return `Counting sprites in your game…  ${spriteBit}`;
+        parts.push(fmtCount(folders, 'folder'));
+    const where = current ? shortPath(current) : '';
+    if (where)
+        parts.push(where);
+    return `Counting sprites in your game…  ${parts.join(' · ')}`;
 }
 function bindScanProgress(onProgress) {
     if (!onProgress)
         return () => { };
     let lastAt = 0;
-    let lastPngs = -1;
-    let lastFolders = -1;
-    return (pngs, folders) => {
-        if (pngs === lastPngs && folders === lastFolders)
-            return;
+    let pending = null;
+    let timer = null;
+    const flush = (p) => {
+        pending = null;
+        lastAt = Date.now();
+        onProgress(p);
+    };
+    const visit = (pngs, folders, current) => {
+        const next = { pngs, folders, current };
         const now = Date.now();
-        if (lastPngs < 0 || now - lastAt >= 80) {
-            lastAt = now;
-            lastPngs = pngs;
-            lastFolders = folders;
-            onProgress({ pngs, folders });
+        if (lastAt === 0 || now - lastAt >= 80) {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            flush(next);
+            return;
+        }
+        pending = next;
+        if (!timer) {
+            timer = setTimeout(() => {
+                timer = null;
+                if (pending)
+                    flush(pending);
+            }, 80 - (now - lastAt));
+            timer.unref();
+        }
+    };
+    visit.flush = () => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
         }
+        if (pending)
+            flush(pending);
     };
+    return visit;
 }
 function samePath(a, b) {
     return a.replace(/\\/g, '/').toLowerCase() === b.replace(/\\/g, '/').toLowerCase();
@@ -148,7 +188,12 @@ export async function indexGamePngs(kind, cwd = process.cwd(), outDir = '', opts
     const stats = { folders: 0 };
     const io = createLimit(SCAN_WALK_CONCURRENCY);
     const report = bindScanProgress(opts.onProgress);
-    await walkPngs(scanRoot, scanRoot, destNorm, found, MAX_GAME_INDEX + 1, io, report, stats, assetRoot);
+    // Full Unity games: walk Assets/ only. Listing the project root waits on
+    // Library/Packages/cloud placeholders and looks hung at "1 folder".
+    const startAt = isUnityGameProject(cwd, assetRoot) ? assetRoot : scanRoot;
+    const preferFirst = startAt === scanRoot ? assetRoot : null;
+    await walkPngs(startAt, scanRoot, destNorm, found, MAX_GAME_INDEX + 1, io, report, stats, preferFirst);
+    report.flush?.();
     opts.onProgress?.({ pngs: found.length, folders: stats.folders });
     found.sort((a, b) => a.localeCompare(b));
     const capped = found.length > MAX_GAME_INDEX;
@@ -178,58 +223,74 @@ export function searchGameIndex(index, query) {
         return [];
     return index.files.filter((e) => e.sourceRel.toLowerCase().includes(q) || e.key.includes(q) || e.adoptRel.toLowerCase().includes(q));
 }
-async function walkPngs(dir, root, destNorm, out, limit, io, onVisit, stats, preferFirst) {
-    if (out.length >= limit)
-        return;
-    // Count the folder *before* readdir so a huge listing still shows movement.
-    stats.folders++;
-    onVisit(out.length, stats.folders);
-    let entries;
+function folderLabel(dir, root) {
+    return relative(root, dir).replace(/\\/g, '/') || '.';
+}
+/**
+ * List one directory. The limiter wraps *only* this listing so a parent does
+ * not hold a slot while waiting on children (that deadlocks wide Unity trees).
+ */
+async function listDir(dir, root, destNorm, out, limit, onVisit, stats, preferFirst, current) {
+    const preferred = [];
+    const other = [];
+    let dh;
     try {
-        entries = await readdir(dir, { withFileTypes: true });
+        dh = await opendir(dir);
     }
     catch {
-        return;
+        return { preferred, other };
     }
-    entries.sort((a, b) => a.name.localeCompare(b.name));
-    const preferred = [];
-    const other = [];
-    for (const ent of entries) {
-        if (out.length >= limit)
-            return;
-        if (ent.isSymbolicLink())
-            continue;
-        const full = resolve(dir, ent.name);
-        try {
-            assertPathInsideRoot(full, root, 'scan');
-        }
-        catch {
-            continue;
-        }
-        if (ent.isDirectory()) {
-            if (shouldSkipDir(ent.name))
+    let lastBeat = Date.now();
+    try {
+        for await (const ent of dh) {
+            if (out.length >= limit)
+                break;
+            const now = Date.now();
+            if (now - lastBeat >= 80) {
+                lastBeat = now;
+                onVisit(out.length, stats.folders, current);
+            }
+            if (shouldSkipDir(ent.name) || ent.isSymbolicLink())
                 continue;
-            if (destNorm && full.replace(/\\/g, '/').toLowerCase() === destNorm)
+            const full = resolve(dir, ent.name);
+            try {
+                assertPathInsideRoot(full, root, 'scan');
+            }
+            catch {
                 continue;
-            if (preferFirst && samePath(full, preferFirst))
-                preferred.push(full);
-            else
-                other.push(full);
-        }
-        else if (ent.isFile() && ent.name.toLowerCase().endsWith('.png')) {
-            out.push(full);
-            onVisit(out.length, stats.folders);
+            }
+            if (ent.isDirectory()) {
+                if (destNorm && full.replace(/\\/g, '/').toLowerCase() === destNorm)
+                    continue;
+                if (preferFirst && samePath(full, preferFirst))
+                    preferred.push(full);
+                else
+                    other.push(full);
+            }
+            else if (ent.isFile() && ent.name.toLowerCase().endsWith('.png')) {
+                out.push(full);
+                onVisit(out.length, stats.folders, current);
+            }
         }
     }
+    catch {
+        /* unreadable mid-listing */
+    }
+    return { preferred, other };
+}
+async function walkPngs(dir, root, destNorm, out, limit, io, onVisit, stats, preferFirst) {
+    if (out.length >= limit)
+        return;
+    stats.folders++;
+    const current = folderLabel(dir, root);
+    onVisit(out.length, stats.folders, current);
+    const { preferred, other } = await io(() => listDir(dir, root, destNorm, out, limit, onVisit, stats, preferFirst, current));
     if (out.length >= limit)
         return;
-    // Engine asset tree first (Unity `Assets/`) so sprite counts appear before
-    // sibling folders like Builds/Editor. Nested walks keep preferFirst so a
-    // misplaced `Assets` dir is still prioritized if we ever see it.
     for (const d of preferred) {
         await walkPngs(d, root, destNorm, out, limit, io, onVisit, stats, null);
     }
     if (other.length === 0 || out.length >= limit)
         return;
-    await Promise.all(other.map((d) => io(() => walkPngs(d, root, destNorm, out, limit, io, onVisit, stats, null))));
+    await Promise.all(other.map((d) => walkPngs(d, root, destNorm, out, limit, io, onVisit, stats, null)));
 }

package/dist/util/pullDecision.js

@@ -0,0 +1,30 @@
+/**
+ * Whether a manifest entry should be written to disk.
+ *
+ * Connected game PNGs are usually *not* the same bytes as MagicPixel's
+ * re-encoded composite. Comparing those hashes would re-download the whole
+ * library on every catch-up and overwrite the originals. Pull only when the
+ * cloud composite actually changed since we last recorded it, or when there
+ * is no local file to protect.
+ */
+export function shouldPullEntry(opts) {
+    const cloud = opts.cloudSha256 ?? null;
+    const local = opts.localSha256;
+    const prev = opts.previousCloudSha256;
+    // Missing on disk → restore from cloud (MagicPixel-only art and deletions).
+    if (!local)
+        return true;
+    if (cloud && cloud === local)
+        return false;
+    // Cloud composite unchanged since last pull/push — keep the original PNG.
+    if (cloud && prev && cloud === prev)
+        return false;
+    if (opts.inWorkingSet) {
+        // Never recorded a cloud hash: disk is the source of truth (connect/ingest).
+        if (!prev)
+            return false;
+        // Editor save often nulls the cached hash; treat that as a cloud change.
+        return true;
+    }
+    return true;
+}

package/dist/util/syncPath.js

@@ -37,6 +37,37 @@ export function collectSourceRelMap(connected, synced) {
     }
     return map;
 }
+/**
+ * Ingest appends `-2`, `-3`, … to the *document* slug when the library already
+ * has that name. The live connect index still uses the unsuffixed key, so a
+ * catch-up pull would treat `ground-ice-snow-4/…` as new MagicPixel art and
+ * dump thousands of copies into outDir. Alias those keys onto the original
+ * PNG when the unsuffixed key is already in the working set.
+ */
+export function stripDocCollisionSuffix(key) {
+    const parts = key.split('/');
+    if (parts.length < 2)
+        return key;
+    const docIdx = parts.length - 2;
+    const stripped = parts[docIdx].replace(/-(\d+)$/, '');
+    if (stripped === parts[docIdx])
+        return key;
+    const next = parts.slice();
+    next[docIdx] = stripped;
+    return next.join('/');
+}
+export function aliasCollisionKeys(sourceByKey, manifestKeys) {
+    for (const key of manifestKeys) {
+        if (sourceByKey.has(key))
+            continue;
+        const base = stripDocCollisionSuffix(key);
+        if (base === key)
+            continue;
+        const rel = sourceByKey.get(base);
+        if (rel)
+            sourceByKey.set(key, rel);
+    }
+}
 /**
  * When the cloud assigned a different composite key than the index key,
  * push under the cloud key so we update instead of adopting a duplicate.

package/dist/util/unityFilter.js

@@ -1,5 +1,5 @@
 /**
- * Per-artboard Unity sync opt-in (strict).
+ * Per-artboard Unity sync opt-in (strict), with a working-set override.
  *
  * In the editor, each artboard has a "Sync to Unity" checkbox (and library
  * folders have a folder-level switch that cascades). A project may hold 100
@@ -9,8 +9,14 @@
  * Strict opt-in: `unity === true` syncs, anything else does not. A missing
  * flag means the server didn't say (older edge deploy, or a budget-starved
  * manifest backfill) — those entries are excluded and reported via
- * `unknownFlags` so the caller can warn instead of silently syncing the whole
+ * `unknown` so the caller can warn instead of silently syncing the whole
  * library into someone's game project.
+ *
+ * Exception: sprites already in the game (connect working set / previously
+ * synced keys) always pull. An editor save nulls `artboard_index` and the
+ * next manifest often omits `unity` (or rebuilds it as false because the
+ * layer JSON dropped `syncToUnity`). Those saves must still write back to
+ * the original PNG.
  */
 export function filterUnityManifest(manifest, opts = {}) {
     if (opts.syncAll)
@@ -23,3 +29,49 @@ export function filterUnityManifest(manifest, opts = {}) {
         unknown,
     };
 }
+/** Keys we already write to on disk — connect globs plus those sprites' cloud aliases. */
+export function workingSetPullKeys(sourceByKey, synced) {
+    const keys = new Set(sourceByKey.keys());
+    const assetIds = new Set();
+    if (synced) {
+        for (const [key, sprite] of Object.entries(synced)) {
+            if (!keys.has(key))
+                continue;
+            if (sprite.assetId)
+                assetIds.add(sprite.assetId);
+        }
+    }
+    return { keys, assetIds };
+}
+export function isWorkingSetEntry(entry, pull) {
+    if (entry.key && pull.keys.has(entry.key))
+        return true;
+    if (entry.previous_keys?.some((k) => pull.keys.has(k)))
+        return true;
+    if (entry.asset_id && pull.assetIds.has(entry.asset_id)) {
+        // Same document as a connected sprite. Post-save fallback (flag omitted)
+        // must still pull; explicitly unflagged sibling artboards must not dump
+        // into outDir.
+        return entry.unity !== false;
+    }
+    return false;
+}
+/**
+ * Flagged artboards, plus any working-set sprite whose Unity flag is missing
+ * or false after an editor save / index rebuild.
+ */
+export function applyUnityPullPolicy(manifest, opts = {}) {
+    const filtered = filterUnityManifest(manifest, { syncAll: opts.syncAll });
+    if (opts.syncAll || !opts.alwaysPull)
+        return filtered;
+    const already = new Set(filtered.entries);
+    const extra = manifest.filter((e) => !already.has(e) && opts.alwaysPull(e));
+    if (extra.length === 0)
+        return filtered;
+    const extraSet = new Set(extra);
+    return {
+        entries: filtered.entries.concat(extra),
+        unknown: filtered.unknown.filter((e) => !extraSet.has(e)),
+        noneFlagged: false,
+    };
+}

package/dist/util/watchCopy.js

@@ -16,6 +16,6 @@ export function formatWatchSpriteLine(c) {
         return `   Sprites:  ${fmt(set)} in your game  ·  ${fmt(pulled)} last pulled from MagicPixel`;
     }
     if (set > 0)
-        return `   Sprites:  ${fmt(set)} in your working set`;
+        return `   Sprites:  ${fmt(set)} in your game`;
     return `   Sprites:  ${fmt(pulled)}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magicpixelart/cli",
-  "version": "0.5.12",
+  "version": "0.5.14",
   "description": "Sync MagicPixel pixel-art assets to your local project.",
   "type": "module",
   "bin": {