@magicpixelart/cli 0.5.8 → 0.5.10

package/CHANGELOG.md

@@ -7,6 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.10] — 2026-08-26
+
+### Changed
+
+- **Watch header shows the working-set size**, not only the last successful
+  pull. Connecting 2,000+ game sprites no longer prints `Sprites: 469` when
+  `state.json` hasn't caught up yet (`2,147 in your game · 469 last pulled
+  from MagicPixel`).
+- **Watch prints live status** while a tick is in flight (`Checking
+  MagicPixel…`, `Comparing N sprites…`, download progress, `Checking your
+  game files…`) instead of sitting silent on the header until the tick
+  finishes. Idle ticks say `Waiting for edits…`.
+
+## [0.5.9] — 2026-08-26
+
+### Security
+
+- **Write-back ignores tampered `state.json`.** Sync/push resolve game paths
+  from the live connect index only. `sourceRel` must be a relative `.png`
+  with no `..` / absolute segments; connect globs cannot contain `..`. Pull
+  and push refuse to follow symlinks, and prune still cannot delete files
+  outside `outDir`. Cloud composite keys that still point at an indexed PNG
+  are aliased onto that file so a slug collision does not write a second copy
+  under `outDir` or re-adopt a duplicate.
+
+### Changed
+
+- **Working-set ingest cap is 10,000** (same as the game index), up from 500.
+  Hitting the cap now prints the real match count (`1847 PNGs match — ingesting
+  the first 10000`) on `connect`, `push`, and one-shot `sync`.
+
+- **Push skips unchanged game files.** Ingest's cloud composite sha is not the
+  original PNG. `connect` / `push` / `sync --watch` remember the on-disk sha256
+  (and mtime/size) and skip re-uploading until the game file actually changes —
+  so a second `connect '**'` resumes leftover files instead of rewriting the
+  whole working set. Hashing is parallel and cached by mtime+size. The game-tree
+  walk reads directories in parallel.
+
+- **Working set instead of bulk import.** `start` / `sync` / `push` no longer
+  copy every game PNG into the MagicPixel library. The CLI indexes sprites
+  locally; `magicpixel search <query>` finds them and `magicpixel connect
+  '<glob>'` adds a working set (`connect` in `magicpixel.json`). Sync writes
+  those sprites back to the original game path. New MagicPixel-only art still
+  lands in `outDir`.
+
+### Fixed
+
+- **First-run import survived a 546.** A persistent manifest-worker recycle
+  used to abort `start` / `sync` before local sprites were pushed. Pull still
+  retries 546s for ~30s; if it still fails, `push` runs anyway (ingest is a
+  different host) and `start` still prints watch instructions.
+
+- **Unity folders appear under Connected.** Game-tree PNGs in the working set
+  adopt as folder/doc/artboard (`sprites/hero/hero`) so they land in Connected,
+  not Files. Reused library folders get the Sync to Unity flag. Adopting an
+  artboard that already matches on disk is a no-op instead of a wall of
+  `cloud-changed` conflicts.
+
+- **Unity packages and hidden folders.** `start` treated a UPM package
+  (`Editor`/`Runtime`/`assets`, `.meta` files, no `package.json`) as "not a
+  project" and asked for JavaScript. Those layouts detect as Unity. The game
+  index walks the whole package (not only `Assets/`), including hidden content
+  dirs like `.SpineRaw_*`, and uses the on-disk `assets`/`Assets` casing for
+  `outDir`. `.git` / `.magicpixel` / Library / Packages / nested `MagicPixel`
+  folders stay skipped. A generic Node `assets/` folder without Unity `.meta`
+  files is not treated as a Unity project.
+
 ## [0.5.8] — 2026-08-26
 
 ### Added

package/README.md

@@ -16,13 +16,22 @@ Requires Node.js ≥ 18.
 
 ## Quickstart
 
-One command, inside your project folder (the one with `package.json`):
+One command, inside your game project — a JavaScript app (`package.json`), a
+Unity project or UPM package (`Assets`/`assets`, `Editor`/`Runtime`), Godot
+(`project.godot`), or GameMaker (`*.yyp`):
 
 ```bash
 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 your sprites, and tells you how to keep them fresh.
+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:
+
+```bash
+npx @magicpixelart/cli search hero
+npx @magicpixelart/cli connect 'assets/Sprites/**'
+```
+
+Connected sprites write back to their original game path. New MagicPixel-only art still lands in `outDir`.
 
 When it finishes:
 
@@ -101,7 +110,9 @@ No bundler config, no runtime, no extra package.
 | `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 new sprites) back to MagicPixel. |
+| `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. |
+| `search <query>` | Search indexed game PNGs (no network). |
 | `add <glob>` / `remove <glob>` | Manage `include` patterns. |
 | `list` | Print matching manifest as a table. |
 | `status` | Config, last sync, diff vs remote. |
@@ -135,10 +146,11 @@ 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. |
 | `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. |
-| `push`     | `boolean?` | `true`                  | Upload local PNG changes to MagicPixel on every `sync`. Set `false` for pull-only. |
+| `push`     | `boolean?` | `true`                  | Upload local PNG changes (outDir + `connect` working set) to MagicPixel on every `sync`. Set `false` for pull-only. |
 | `endpoint` | `string?`  | production URL          | Override the API base (testing only). Must be **HTTPS**. |
 
 State (`.magicpixel/state.json`) tracks `lastSync` (file mode `0600`). Add `.magicpixel/` to `.gitignore` (init offers to do this).

package/dist/api.js

@@ -84,9 +84,9 @@ export async function fetchManifestPage(opts) {
         url.searchParams.set('cursor', opts.cursor);
     if (opts.limit)
         url.searchParams.set('limit', String(opts.limit));
-    // Reuse the same transient-failure policy as asset downloads: 3 attempts,
-    // exponential backoff, honor Retry-After on 429/5xx. Network blips and
-    // brief edge restarts otherwise blow up the whole sync mid-pagination.
+    // 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 res = await safeFetch(url.href, { headers });
@@ -134,25 +134,27 @@ export async function fetchManifestPage(opts) {
         }
         const bodyText = await res.text();
         throw new ApiError(res.status, withRequestId(friendly(res.status, bodyText, 'manifest'), serverRequestId), serverRequestId, retryAfterMsFromResponse(res));
-    });
+    }, { max546Attempts: 7 });
 }
+const defaultRetrySleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
- * Run `fn` up to 3 times, backing off on network errors, 429, and 5xx.
+ * Run `fn` with exponential backoff on network errors, 429, and 5xx.
  * Non-retryable ApiErrors (4xx other than 429) bubble immediately.
  *
  * - `ApiError.retryAfterMs` (populated from a `Retry-After` header on 429/5xx)
  *   wins over the default exponential backoff for the *next* attempt.
  * - Network/transport failures are wrapped once with a friendly hint and the
  *   request-id of the most recent attempt.
+ *
+ * The 3rd argument may be a sleep function (tests) or an options bag.
  */
-export async function retryTransient(context, fn) {
-    // 5 attempts × (500ms, 1s, 2s, 4s) = ~7.5s of coverage. Enough to ride out
-    // a Supabase edge worker recycle (546) or a brief 5xx without surfacing to
-    // the user; short enough that a real outage still fails within one sync tick.
+export async function retryTransient(context, fn, opts = {}) {
+    const sleep = (typeof opts === 'function' ? opts : opts.sleep) ?? defaultRetrySleep;
     const maxAttempts = 5;
+    const max546Attempts = typeof opts === 'function' ? maxAttempts : (opts.max546Attempts ?? maxAttempts);
     let lastErr = null;
     let nextDelayMs = 0;
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    for (let attempt = 1;; attempt++) {
         try {
             return await fn();
         }
@@ -165,17 +167,15 @@ export async function retryTransient(context, fn) {
                 nextDelayMs = err.retryAfterMs ?? 0;
             }
             else {
-                // Network/transport failure — wrap once with the existing hint.
-                // Preserve the original error as `cause` so `--verbose` consumers
-                // and Node's default printer can still surface the underlying stack.
                 lastErr = new Error(`${context}: network error (${err.message}).\n` +
                     `  Fix: check your internet connection and that the MagicPixel API is reachable.`, { cause: err });
                 nextDelayMs = 0;
             }
-            if (attempt < maxAttempts) {
-                const backoffMs = 500 * 2 ** (attempt - 1);
-                await new Promise((r) => setTimeout(r, Math.max(nextDelayMs, backoffMs)));
-            }
+            const allowed = lastErr instanceof ApiError && lastErr.status === 546 ? max546Attempts : maxAttempts;
+            if (attempt >= allowed)
+                break;
+            const backoffMs = Math.min(500 * 2 ** (attempt - 1), 16_000);
+            await sleep(Math.max(nextDelayMs, backoffMs));
         }
     }
     throw lastErr ?? new Error(`${context}: unknown error`);

package/dist/commands/connect.js

@@ -0,0 +1,49 @@
+import kleur from 'kleur';
+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 } from '../util/gameScan.js';
+import { cmd } from '../util/invoke.js';
+import { runPush } from './push.js';
+/**
+ * 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.
+ */
+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);
+        await saveConfig(config);
+        console.log(kleur.green(`✓ added connect pattern: ${pattern}`));
+    }
+    else {
+        console.log(kleur.dim(`  connect pattern already present: ${pattern}`));
+    }
+    const kind = await detectProjectKind();
+    if (!isEngineKind(kind)) {
+        console.log(kleur.yellow('  This folder is not a Unity/Godot/GameMaker project — nothing to ingest from disk.'));
+        return;
+    }
+    const index = await indexGamePngs(kind, process.cwd(), config.outDir);
+    if (index.capped) {
+        console.log(kleur.yellow(`! ${GAME_INDEX_CAP_HINT}`));
+    }
+    const matched = matchConnectGlobs(index, config.connect);
+    if (matched.capped) {
+        console.log(kleur.yellow(`! ${connectCapMessage(matched.total, matched.entries.length)}`));
+    }
+    if (matched.entries.length === 0) {
+        console.log(kleur.yellow(`  No PNGs matched. Try \`${cmd('search')} <name>\` to see indexed paths.`));
+        return;
+    }
+    const n = matched.entries.length;
+    console.log(kleur.dim(`  ${n} sprite${n === 1 ? '' : 's'} in working set (of ${index.files.length} indexed` +
+        (matched.capped ? `, ${matched.total} matched` : '') +
+        `).`));
+    if (n >= 200) {
+        console.log(kleur.dim(`  Already-imported sprites are skipped; only new or changed files upload.`));
+    }
+    await runPush({ gameIndex: index });
+}

package/dist/commands/doctor.js

@@ -4,7 +4,7 @@ import { readFile } from 'node:fs/promises';
 import { resolve, relative } from 'node:path';
 import { loadConfig, loadState, resolveEndpoint, defaultConfig } from '../config.js';
 import { describeKeySource, readKeyForDisplay } from '../util/credentials.js';
-import { detectProjectKind, hasPackageJson } from '../util/framework.js';
+import { detectProjectKind, hasPackageJson, isEngineKind } from '../util/framework.js';
 import { safeFetch } from '../util/security.js';
 import { authHeaders } from '../util/authHeaders.js';
 import { CLI_VERSION } from '../version.js';
@@ -104,6 +104,7 @@ export async function collectDoctorReport(opts = {}) {
                 emitIndex: config.emitIndex !== false,
                 include: config.include,
                 exclude: config.exclude,
+                connect: config.connect,
                 endpoint: config.endpoint ?? null,
             }
             : { found: false, error: configErr ?? 'unknown' },
@@ -178,13 +179,20 @@ export function renderDoctorReport(r) {
     push(`Platform:           ${r.platform}`);
     push(`cwd:                ${r.cwd}`);
     push();
-    push(`package.json:       ${r.hasPackageJson ? 'found' : kleur.yellow('missing')}`);
+    const pkgMissing = r.hasPackageJson
+        ? 'found'
+        : isEngineKind(r.framework)
+            ? kleur.dim('n/a (engine)')
+            : kleur.yellow('missing');
+    push(`package.json:       ${pkgMissing}`);
     push(`Framework detected: ${r.framework ?? kleur.dim('none')}`);
     if (r.config.found) {
         push(`magicpixel.json:    found`);
         push(`  outDir:           ${r.config.outDir}`);
         push(`  emitIndex:        ${r.config.emitIndex ? 'true' : 'false'}`);
         push(`  include:          ${r.config.include.join(', ')}`);
+        if (r.config.connect.length)
+            push(`  connect:          ${r.config.connect.join(', ')}`);
         if (r.config.exclude.length)
             push(`  exclude:          ${r.config.exclude.join(', ')}`);
         if (r.config.endpoint)

package/dist/commands/push.js

@@ -2,14 +2,9 @@
  * `magicpixel push` — disk → MagicPixel (the Unity → MagicPixel half of
  * two-way sync).
  *
- * Walks `outDir`, hashes every PNG, and sends the ones that changed (or are
- * brand new on disk) to `POST /api/public/integration/ingest`:
- *
- *   - known key + changed sha → write back into that artboard, using the sha
- *     the CLI last pulled as the conflict baseline. If the cloud moved on the
- *     server refuses with `conflict` and nothing is lost.
- *   - unknown key            → adopt: the server mirrors the disk folders into
- *     the library and appends/creates the document.
+ * Walks `outDir` plus the `connect` working set (original game PNGs), hashes
+ * every PNG, and sends the ones that changed (or are brand new on disk) to
+ * `POST /api/public/integration/ingest`.
  */
 import kleur from 'kleur';
 import ora from 'ora';
@@ -18,19 +13,26 @@ import { dirname } from 'node:path';
 import { relative, resolve } from 'node:path';
 import { loadConfig, loadState, saveState } from '../config.js';
 import { PUSH_BATCH_SIZE, pushSprites } from '../api.js';
-import { fileSha256 } from '../util/hash.js';
+import { hashFile } from '../util/hash.js';
+import { createLimit } from '../util/limit.js';
 import { assetDiskPathFromKey, walkOutDirPngs } from '../util/paths.js';
-import { planPush } from '../util/pushPlan.js';
+import { applyDiskFingerprints, indexSyncedBySourceRel, planPush, resolveSyncedKey } from '../util/pushPlan.js';
 import { cmd } from '../util/invoke.js';
-import { detectProjectKind } from '../util/framework.js';
-import { importNearbyGamePngs } from '../util/gameScan.js';
+import { detectProjectKind, isEngineKind } from '../util/framework.js';
+import { indexGamePngs, matchConnectGlobs, GAME_INDEX_CAP_HINT, connectCapMessage } from '../util/gameScan.js';
+import { collectSourceRelMap, remapAbsToCloudKeys } from '../util/syncPath.js';
+import { assertSafeIoPath } from '../util/security.js';
+/** Parallel hashing / path checks — enough to saturate disk, low enough to stay polite. */
+const PUSH_SCAN_CONCURRENCY = 8;
+/** Paths already verified this process; hashFile still refuses a later symlink swap. */
+const verifiedIoPaths = new Set();
 export async function pushCommand(opts = {}) {
     await runPush(opts);
 }
 /**
  * Scan local PNGs and upload new/changed ones into the MagicPixel library.
- * Used by `magicpixel push` and by `sync` (so connect/watch imports game
- * sprites without a second command).
+ * Used by `magicpixel push` and by `sync` (so a committed `connect` working
+ * set is ingested without a second command).
  */
 export async function runPush(opts = {}) {
     const config = await loadConfig();
@@ -42,28 +44,85 @@ export async function runPushWith(config, state, opts = {}) {
     const empty = { created: 0, updated: 0, unchanged: 0, conflict: 0, error: 0, imported: 0 };
     const spinner = quiet ? null : ora('Scanning local sprites…').start();
     const kind = await detectProjectKind();
-    const scan = await importNearbyGamePngs(config.outDir, kind);
-    const imported = scan.copied;
+    const index = opts.gameIndex
+        ?? (isEngineKind(kind)
+            ? await indexGamePngs(kind, process.cwd(), config.outDir)
+            : { files: [], capped: false });
+    const matched = matchConnectGlobs(index, config.connect ?? []);
+    const sourceByKey = collectSourceRelMap(matched.entries, state.synced);
     const disk = await walkOutDirPngs(config.outDir);
     const absByKey = new Map(disk.map((a) => [a.key, a.abs]));
+    const entryByKey = new Map(matched.entries.map((e) => [e.key, e]));
+    for (const e of matched.entries) {
+        absByKey.set(e.key, e.abs);
+    }
+    remapAbsToCloudKeys(absByKey, matched.entries, state.synced);
+    const entryBySourceRel = new Map(matched.entries.map((e) => [e.sourceRel, e]));
+    for (const [k, rel] of sourceByKey) {
+        const e = entryBySourceRel.get(rel);
+        if (e)
+            entryByKey.set(k, e);
+    }
     const candidates = [];
-    for (const asset of disk) {
-        const sha = await fileSha256(asset.abs);
-        if (!sha)
-            continue;
+    const cwdAbs = resolve(process.cwd());
+    let skippedUnsafe = 0;
+    const synced = state.synced ?? {};
+    const byRel = indexSyncedBySourceRel(synced);
+    const scan = createLimit(PUSH_SCAN_CONCURRENCY);
+    await Promise.all([...absByKey.entries()].map(([key, abs]) => scan(async () => {
+        try {
+            if (!verifiedIoPaths.has(abs)) {
+                await assertSafeIoPath(abs, cwdAbs);
+                verifiedIoPaths.add(abs);
+            }
+        }
+        catch {
+            skippedUnsafe++;
+            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 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)
+            return;
+        const segments = entry
+            ? entry.adoptRel.replace(/\.png$/i, '').split('/')
+            : key.split('/');
         candidates.push({
-            key: asset.key,
-            segments: asset.key.split('/'),
-            diskSha256: sha,
+            key,
+            segments,
+            diskSha256: hashed.sha256,
+            ...(sourceRel ? { sourceRel } : {}),
+            diskMtimeMs: hashed.mtimeMs,
+            diskSize: hashed.size,
         });
+    })));
+    const folderTreeKeys = new Set(matched.entries.map((e) => e.key));
+    for (const k of absByKey.keys()) {
+        if (sourceByKey.has(k))
+            folderTreeKeys.add(k);
     }
-    const actions = planPush(candidates, state.synced, { flatten: opts.flatten });
+    const actions = planPush(candidates, state.synced, { flatten: opts.flatten, folderTreeKeys });
     const skipped = actions.filter((a) => a.kind === 'skip' && a.reason !== 'legacy').length;
     const legacy = actions.filter((a) => a.kind === 'skip' && a.reason === 'legacy');
     const flattenBlocked = actions.filter((a) => a.kind === 'needs-flatten');
     const sendable = actions.filter((a) => a.kind === 'update' || a.kind === 'adopt');
     spinner?.succeed(`Local sprites: ${candidates.length} · to push ${sendable.length} · unchanged ${skipped}` +
-        (imported ? ` · imported ${imported}` : ''));
+        (matched.entries.length ? ` · connected ${matched.entries.length}` : ''));
+    if (index.capped && !quiet) {
+        console.log(kleur.yellow(`! ${GAME_INDEX_CAP_HINT}`));
+    }
+    if (matched.capped && !quiet) {
+        console.log(kleur.yellow(`! ${connectCapMessage(matched.total, matched.entries.length)}`));
+    }
+    if (skippedUnsafe > 0 && !quiet) {
+        console.log(kleur.yellow(`! skipped ${skippedUnsafe} path${skippedUnsafe === 1 ? '' : 's'} that were not regular files inside the project.`));
+    }
     if (legacy.length > 0 && !quiet) {
         console.log();
         console.log(kleur.yellow(`! ${legacy.length} sprite${legacy.length === 1 ? '' : 's'} came from a legacy single-image file — skipped.`));
@@ -78,9 +137,10 @@ export async function runPushWith(config, state, opts = {}) {
         console.log(kleur.dim('  Fix: re-run with --flatten to replace them with the flat disk image.'));
     }
     if (sendable.length === 0) {
+        await persistDiskFingerprints(state, candidates);
         if (!quiet)
             console.log(kleur.green('✓ nothing to push.'));
-        return { ...empty, imported, unchanged: skipped };
+        return { ...empty, imported: matched.entries.length, unchanged: skipped };
     }
     if (opts.dryRun) {
         if (!quiet) {
@@ -91,15 +151,17 @@ export async function runPushWith(config, state, opts = {}) {
             }
             console.log(kleur.dim('--dry-run: nothing sent.'));
         }
-        return { ...empty, imported };
+        return { ...empty, imported: matched.entries.length };
     }
     const outRoot = resolve(process.cwd(), config.outDir);
     const shaByKey = new Map(candidates.map((c) => [c.key, c.diskSha256]));
+    const fpByKey = new Map(candidates.map((c) => [c.key, c]));
     const sprites = [];
     for (const a of sendable) {
         const abs = absByKey.get(a.key);
         if (!abs)
             continue;
+        await assertSafeIoPath(abs, cwdAbs);
         const pngBase64 = (await readFile(abs)).toString('base64');
         const diskSha256 = shaByKey.get(a.key);
         if (a.kind === 'update') {
@@ -127,21 +189,31 @@ export async function runPushWith(config, state, opts = {}) {
             progress.text = `Pushing ${Math.min(i + batch.length, sprites.length)}/${sprites.length}…`;
     }
     const counts = { created: 0, updated: 0, unchanged: 0, conflict: 0, error: 0 };
-    const nextSynced = { ...(state.synced ?? {}) };
+    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')) {
-            await renameLocalSprite(config.outDir, r.key, stateKey);
+            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 } : {}),
             };
         }
     }
@@ -167,12 +239,19 @@ export async function runPushWith(config, state, opts = {}) {
         }
         if (counts.created > 0) {
             console.log(kleur.dim(`  ${counts.created} new sprite${counts.created === 1 ? '' : 's'} now live in your MagicPixel library ` +
-                `(folders mirrored from ${relative(process.cwd(), outRoot)}). Refresh the library to see them.`));
+                `(working set + ${relative(process.cwd(), outRoot)}). They appear in Connected as they import.`));
         }
     }
     if (failed)
         process.exitCode = 1;
-    return { ...counts, imported };
+    return { ...counts, imported: matched.entries.length };
+}
+/** 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);
+    if (!changed)
+        return;
+    await saveState({ ...state, synced: next });
 }
 function conflictHint(reason) {
     switch (reason) {
@@ -191,7 +270,7 @@ function conflictHint(reason) {
 /**
  * Move a pushed sprite (and its `.meta` sidecar) to the disk path matching the
  * key the cloud assigned. Best effort: a failed move only means the next sync
- * re-downloads the sprite under its cloud name.
+ * re-downloads the sprite under its cloud name. Never used for sourceRel files.
  */
 async function renameLocalSprite(outDir, fromKey, toKey) {
     const from = assetDiskPathFromKey(outDir, fromKey);

package/dist/commands/search.js

@@ -0,0 +1,45 @@
+import kleur from 'kleur';
+import { loadConfig } from '../config.js';
+import { detectProjectKind, isEngineKind } from '../util/framework.js';
+import { indexGamePngs, searchGameIndex, GAME_INDEX_CAP_HINT } from '../util/gameScan.js';
+import { cmd } from '../util/invoke.js';
+const PRINT_CAP = 50;
+/**
+ * Substring search over the local game PNG index. No network.
+ */
+export async function searchCommand(query) {
+    const q = query.trim();
+    if (!q) {
+        console.log(kleur.yellow('  Pass a search string, e.g. `magicpixel search hero`.'));
+        return;
+    }
+    const kind = await detectProjectKind();
+    if (!isEngineKind(kind)) {
+        console.log(kleur.yellow('  Game-sprite search is for Unity, Godot, and GameMaker projects.'));
+        return;
+    }
+    let outDir = '';
+    try {
+        outDir = (await loadConfig()).outDir;
+    }
+    catch {
+        // Config is optional for search — skip MagicPixel outDir when missing.
+    }
+    const index = await indexGamePngs(kind, process.cwd(), outDir);
+    if (index.capped) {
+        console.log(kleur.yellow(`! ${GAME_INDEX_CAP_HINT}`));
+    }
+    const hits = searchGameIndex(index, q);
+    if (hits.length === 0) {
+        console.log(kleur.dim(`  No indexed PNGs matching "${q}" (${index.files.length} scanned).`));
+        return;
+    }
+    const shown = hits.slice(0, PRINT_CAP);
+    console.log(kleur.dim(`  ${hits.length} match${hits.length === 1 ? '' : 'es'} (of ${index.files.length} indexed). Connect with \`${cmd('connect')} '<glob>'\`.`));
+    for (const h of shown) {
+        console.log(`  ${h.sourceRel}  ${kleur.dim(`→ ${h.key}`)}`);
+    }
+    if (hits.length > shown.length) {
+        console.log(kleur.dim(`  …and ${hits.length - shown.length} more. Narrow the query.`));
+    }
+}

package/dist/commands/start.js

@@ -19,15 +19,19 @@ import { cmd } from '../util/invoke.js';
  */
 export async function startCommand(opts = {}) {
     console.log(kleur.bold('🪄  MagicPixel — first-run setup'));
-    console.log(kleur.dim('  This connects your game project so existing sprites show up in MagicPixel.'));
+    console.log(kleur.dim('  This links your game project. Sprites are indexed locally; nothing is imported until you connect a working set.'));
     console.log();
     const kind = await detectProjectKind();
-    // Engine projects have no package.json requirement. JS projects still need one.
+    // Engine projects (including Unity UPM packages) have no package.json
+    // requirement. JS projects still need one.
     if (!hasPackageJson() && !isEngineKind(kind)) {
-        console.log(kleur.yellow('  MagicPixel needs a JavaScript project (package.json) to sync into.\n' +
-            '  Run this inside your project folder — the one with package.json.'));
+        console.log(kleur.yellow('  MagicPixel needs a game project to sync into.\n' +
+            '  Run this inside your Unity, Godot, GameMaker, or JavaScript folder\n' +
+            '  (Unity package, project with Assets/, or a folder with package.json).'));
         return;
     }
+    if (kind)
+        console.log(kleur.dim(`  Detected: ${kind}`));
     // 2. Run init non-interactively unless config already exists AND is valid.
     // A broken `magicpixel.json` (hand-edited / truncated) used to slip past
     // the existsSync check here and then explode deep inside `syncCommand`.
@@ -68,10 +72,21 @@ export async function startCommand(opts = {}) {
     // 5. First sync. syncCommand sets `process.exitCode = 1` on download
     //    failures without throwing — snapshot around the call so we don't
     //    print a misleading green "you're set up" over a half-failed run.
+    //    Manifest 546s throw after still importing local sprites; catch so
+    //    the watch instructions below aren't swallowed.
     console.log();
-    console.log(kleur.bold('Step: import + sync'));
+    console.log(kleur.bold('Step: sync'));
     const exitBefore = process.exitCode ?? 0;
-    await syncCommand({ full: true });
+    try {
+        await syncCommand({ full: true });
+    }
+    catch (e) {
+        const err = e;
+        console.error(kleur.red(err.message ?? String(e)));
+        process.exitCode = 1;
+        const { reportCliError } = await import('../util/telemetry.js');
+        await reportCliError(err, { command: 'start' });
+    }
     const firstSyncFailed = (process.exitCode ?? 0) > exitBefore;
     // 6. Tell the user how to run the watch loop. If `init` couldn't patch
     //    package.json (non-standard layout, write-protected, etc.) the
@@ -94,6 +109,9 @@ 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();
     if (await hasDevScript()) {
         const watchCmd = hasWatch ? 'npm run magicpixel:watch' : `${cmd('sync')} --watch`;
         console.log(kleur.dim('  Tip: run your dev server and the watcher together with'));