@magicpixelart/cli 0.5.13 → 0.5.20

package/CHANGELOG.md

@@ -7,6 +7,97 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## 0.5.20
+
+- `sync` no longer deletes a PNG that was edited in your project when the sprite
+  leaves the manifest — un-checking "Sync to Unity", trashing the document, or a
+  rename/previous-key sweep now keep the local edit and report it instead.
+
+## 0.5.19
+
+- `sync` no longer overwrites a PNG that changed both on disk and in MagicPixel. Such sprites are reported as conflicts, kept on disk, never pruned, and re-reported until you `push` them or delete the local file.
+- A full reconcile is promoted automatically every 15 minutes (and whenever the server reports it truncated its removal list), so sprites deleted permanently in MagicPixel stop lingering in the game project.
+
+## [0.5.18] — 2026-08-27
+
+### Fixed
+- Trashed documents (and documents converted into component masters) no longer
+  linger in the game project. The manifest now excludes them, and incremental
+  syncs receive an explicit `removed_keys` list so previously pulled sprites are
+  pruned on the next run. Sprites authored in Unity are still never touched.
+- Renaming a folder or toggling its "Sync to Unity" flag now invalidates the
+  manifest cache, so the CLI stops receiving a stale `304 Not Modified`.
+
+## [0.5.17] — 2026-08-27
+
+### Fixed
+- Watch-mode idle backoff now measures wall-clock seconds since the last change
+  instead of `ticks x interval`. Once the watcher had stepped down to 5s/10s
+  ticks the old estimate undercounted elapsed time, so the 5-minute step landed
+  well past 5 minutes.
+- Pushing a locally edited sprite counts as activity again: a run that only
+  pushes (an artist working entirely inside their engine) resets the hot window
+  to the fast interval instead of sliding to the 10s idle poll.
+
+### Changed
+- Idle incremental ticks no longer walk the whole output directory. The listing
+  is only needed by the full-sync orphan sweep and the rename fallback, so it is
+  now computed lazily — an unchanged (304) tick does no filesystem scan.
+
+## [0.5.16] — 2026-08-27
+
+### Changed
+- Manifest validators are persisted in `.magicpixel/state.json`, so a one-shot
+  `sync` (CI, cron, a manual run) gets the same idle `304 Not Modified` a
+  watcher already got on its second tick. Validators are keyed by endpoint plus
+  exact query, so a staging/self-hosted swap or an edited `connect`/`exclude`
+  glob can never be answered from a stale validator.
+
+## [0.5.15] — 2026-08-26
+
+### Changed
+- `sync --watch` sends conditional manifest requests (`If-None-Match`), so an
+  idle tick costs a `304` with no body instead of a full manifest render.
+  Validators are only used on incremental fetches — a full fetch, which prune
+  compares against, always reads the body.
+- Idle backoff is now a hot window: the configured interval applies for ~1 min
+  after the last change, then steps to 5s, then to 10s after ~5 min idle
+  (previously ~3 min / ~15 min).
+
+### Fixed
+- `safeFetch` no longer treated `304` as a malformed redirect. This made every
+  conditional asset download retry five times and then fail as a network error,
+  so unchanged PNGs were re-downloaded in full.
+
+
+## [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
@@ -16,10 +107,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   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

@@ -2,6 +2,52 @@ import { resolveEndpoint, getApiKey, CLI_VERSION } from './config.js';
 import { etagForSha256, MAX_ASSET_BYTES, readBodyWithLimit, safeFetch, validateEndpointUrl, } from './util/security.js';
 import { authHeaders } from './util/authHeaders.js';
 import { cmd } from './util/invoke.js';
+/**
+ * Manifest validators, so an idle poll costs a conditional GET (304, no body)
+ * instead of a full manifest render. Keyed by endpoint + exact query string: a
+ * different `since`/glob set — or a different server — is a different
+ * projection and must not reuse a validator.
+ *
+ * Bounded so a long-lived watcher walking many `since` values can't grow it
+ * without limit; eviction is FIFO and only costs one non-conditional GET.
+ *
+ * `sync` persists this map into state.json (see `manifestEtagsSnapshot` /
+ * `primeManifestEtags`) so one-shot runs — CI, cron, a manual `sync` — get the
+ * same 304 as a watcher's second tick.
+ */
+const manifestEtags = new Map();
+const MAX_MANIFEST_ETAGS = 32;
+function rememberManifestEtag(key, etag) {
+    manifestEtags.delete(key);
+    manifestEtags.set(key, etag);
+    while (manifestEtags.size > MAX_MANIFEST_ETAGS) {
+        const oldest = manifestEtags.keys().next().value;
+        if (oldest === undefined)
+            break;
+        manifestEtags.delete(oldest);
+    }
+}
+/**
+ * Seed validators persisted by an earlier run. Ignores non-string junk so a
+ * hand-edited state.json can't inject a bogus header value; a wrong-but-typed
+ * validator is harmless (the server just answers 200 with a body).
+ */
+export function primeManifestEtags(entries) {
+    if (!entries || typeof entries !== 'object' || Array.isArray(entries))
+        return;
+    for (const [key, etag] of Object.entries(entries)) {
+        if (typeof etag === 'string' && etag)
+            rememberManifestEtag(key, etag);
+    }
+}
+/** Snapshot of the current validators, for persisting into state.json. */
+export function manifestEtagsSnapshot() {
+    return Object.fromEntries(manifestEtags);
+}
+/** Test seam: drop cached manifest validators between cases. */
+export function __resetManifestEtagsForTesting() {
+    manifestEtags.clear();
+}
 /**
  * Last-seen project metadata from any manifest response this process made.
  * Populated as a side-effect of `fetchManifestPage`; read by `whoami`,
@@ -84,17 +130,32 @@ export async function fetchManifestPage(opts) {
         url.searchParams.set('cursor', opts.cursor);
     if (opts.limit)
         url.searchParams.set('limit', String(opts.limit));
+    // Conditional GET: an unchanged scope comes back as a 304 with no body.
+    // Only for un-paginated requests — the server doesn't validate cursor pages.
+    // Key includes the origin+path so a persisted validator can't be replayed
+    // against a different endpoint (self-hosted / staging swap).
+    const etagKey = opts.conditional && !opts.cursor ? `${url.origin}${url.pathname}${url.search}` : null;
+    const knownEtag = etagKey ? manifestEtags.get(etagKey) : undefined;
     // Reuse the same transient-failure policy as asset downloads, with extra
     // 546 attempts so first-run can ride out a worker recycle without stalling
     // every PNG download for ~30s.
     return retryTransient(`manifest`, async () => {
-        const { headers, requestId } = buildHeaders();
+        const { headers, requestId } = buildHeaders(knownEtag ? { 'If-None-Match': knownEtag } : undefined);
         const res = await safeFetch(url.href, { headers });
         const serverRequestId = res.headers.get('x-request-id') ?? requestId;
+        if (res.status === 304) {
+            const minCli = res.headers.get('x-magicpixel-min-cli-version');
+            if (minCli)
+                maybeWarnStaleCli(minCli);
+            return { items: [], nextCursor: null, count: 0 };
+        }
         if (res.status >= 200 && res.status < 300) {
             const minCli = res.headers.get('x-magicpixel-min-cli-version');
             if (minCli)
                 maybeWarnStaleCli(minCli);
+            const etag = res.headers.get('etag');
+            if (etagKey && etag)
+                rememberManifestEtag(etagKey, etag);
             const data = (await res.json());
             // Shape-guard the response. A malformed edge response (null,
             // {items: null}, nextCursor: 42, etc.) would otherwise either crash
@@ -214,18 +275,33 @@ function compareSemver(a, b) {
     }
     return 0;
 }
-export async function fetchAllManifest(config, since) {
+/** Full manifest walk, including the cloud's removal list. */
+export async function fetchManifestSnapshot(config, since) {
     const out = [];
+    const removed = new Set();
+    let removalsTruncated = false;
     let cursor;
+    // Conditional GETs only on incremental fetches. An incremental 304 means
+    // "nothing changed since `since`", which is indistinguishable from the empty
+    // incremental page callers already handle. A full fetch (`since` unset) is
+    // the cloud truth that prune compares against, so it always reads the body.
+    const conditional = !!since;
     // Cycle guard: caps total pages so a buggy server cursor can't hang the CLI.
     // At 500 entries/page this is 100k assets — well past any realistic project.
     const MAX_PAGES = 200;
     for (let page = 0; page < MAX_PAGES; page++) {
-        const res = await fetchManifestPage({ config, since, cursor, limit: 500 });
+        const res = await fetchManifestPage({ config, since, cursor, limit: 500, conditional });
         out.push(...res.items);
+        if (Array.isArray(res.removed_keys)) {
+            for (const k of res.removed_keys)
+                if (typeof k === 'string' && k)
+                    removed.add(k);
+        }
+        if (res.removals_truncated === true)
+            removalsTruncated = true;
         const nextCursor = res.nextCursor ?? undefined;
         if (!nextCursor)
-            return out;
+            return { entries: out, removedKeys: [...removed], removalsTruncated };
         // Detect a stuck cursor (server returns the same token it just received)
         // in O(1) round-trips instead of burning the full page budget.
         if (nextCursor === cursor) {
@@ -237,6 +313,10 @@ export async function fetchAllManifest(config, since) {
     throw new Error(`manifest: pagination exceeded ${MAX_PAGES} pages — possible server cursor loop.\n` +
         `  Fix: re-run with --full, or report at https://github.com/magicpixel/cli/issues.`);
 }
+/** Entries only — for read-only commands (`list`, `status`). */
+export async function fetchAllManifest(config, since) {
+    return (await fetchManifestSnapshot(config, since)).entries;
+}
 /**
  * Download a single asset by key. Returns null on 304 (not modified).
  * Shares the retryTransient policy with manifest fetches — including
@@ -280,15 +360,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 +388,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,26 +4,25 @@ 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) {
-    const g = glob.trim();
-    if (g === '**' || g === '**/*' || g === '**/**' || g === '**/*.png' || g === '**/**/*.png') {
-        return 'all sprites in your game';
-    }
-    return g;
+    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(`✓ now syncing ${describeWorkingSet(pattern)}`));
     }
@@ -49,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`;