pixelkiln 0.30.0 → 0.32.0

package/dist/index.d.cts

@@ -8312,8 +8312,14 @@ interface GenerateJob {
     id: string;
     project: string | null;
     keys: string[];
-    /** `resume` skips submission: poll, review, and fetch existing work at no cost; `refresh` re-pulls changed objects. */
-    mode: "generate" | "resume" | "refresh";
+    /**
+     * `resume` skips submission: poll, review, and fetch existing work at no
+     * cost; `refresh` re-pulls changed objects; `restore` puts the recorded
+     * bytes back on disk from the cache or the provider, as `pixelkiln restore`.
+     */
+    mode: "generate" | "resume" | "refresh" | "restore";
+    /** The job may replace a locally modified or untracked file, as `--force` does. */
+    force: boolean;
     phase: GeneratePhase;
     startedAt: string;
     finishedAt: string | null;
@@ -8377,36 +8383,46 @@ interface GalleryGenerateHandlers {
 declare const GenerateRequestSchema: z.ZodEffects<z.ZodObject<{
     project: z.ZodOptional<z.ZodString>;
     keys: z.ZodArray<z.ZodString, "many">;
-    /** Regenerate work that is up to date, as `gen --force` does. */
+    /**
+     * Regenerate work that is up to date, as `gen --force` does, and let the
+     * fetch replace a locally modified or untracked file. With `restore`, put
+     * the recorded bytes back over a modified file.
+     */
     force: z.ZodOptional<z.ZodBoolean>;
     /** Advance in-flight, review, or selected work without submitting anything. */
     resume: z.ZodOptional<z.ZodBoolean>;
     /** Re-download downloaded outputs and replace files whose object changed upstream. */
     refresh: z.ZodOptional<z.ZodBoolean>;
+    /** Put recorded outputs back on disk from the cache or the provider, without generating. */
+    restore: z.ZodOptional<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     keys: string[];
     resume?: boolean | undefined;
     force?: boolean | undefined;
     project?: string | undefined;
     refresh?: boolean | undefined;
+    restore?: boolean | undefined;
 }, {
     keys: string[];
     resume?: boolean | undefined;
     force?: boolean | undefined;
     project?: string | undefined;
     refresh?: boolean | undefined;
+    restore?: boolean | undefined;
 }>, {
     keys: string[];
     resume?: boolean | undefined;
     force?: boolean | undefined;
     project?: string | undefined;
     refresh?: boolean | undefined;
+    restore?: boolean | undefined;
 }, {
     keys: string[];
     resume?: boolean | undefined;
     force?: boolean | undefined;
     project?: string | undefined;
     refresh?: boolean | undefined;
+    restore?: boolean | undefined;
 }>;
 declare class GenerateRequestError extends Error {
     readonly status: number;

package/dist/index.d.ts

@@ -8312,8 +8312,14 @@ interface GenerateJob {
     id: string;
     project: string | null;
     keys: string[];
-    /** `resume` skips submission: poll, review, and fetch existing work at no cost; `refresh` re-pulls changed objects. */
-    mode: "generate" | "resume" | "refresh";
+    /**
+     * `resume` skips submission: poll, review, and fetch existing work at no
+     * cost; `refresh` re-pulls changed objects; `restore` puts the recorded
+     * bytes back on disk from the cache or the provider, as `pixelkiln restore`.
+     */
+    mode: "generate" | "resume" | "refresh" | "restore";
+    /** The job may replace a locally modified or untracked file, as `--force` does. */
+    force: boolean;
     phase: GeneratePhase;
     startedAt: string;
     finishedAt: string | null;
@@ -8377,36 +8383,46 @@ interface GalleryGenerateHandlers {
 declare const GenerateRequestSchema: z.ZodEffects<z.ZodObject<{
     project: z.ZodOptional<z.ZodString>;
     keys: z.ZodArray<z.ZodString, "many">;
-    /** Regenerate work that is up to date, as `gen --force` does. */
+    /**
+     * Regenerate work that is up to date, as `gen --force` does, and let the
+     * fetch replace a locally modified or untracked file. With `restore`, put
+     * the recorded bytes back over a modified file.
+     */
     force: z.ZodOptional<z.ZodBoolean>;
     /** Advance in-flight, review, or selected work without submitting anything. */
     resume: z.ZodOptional<z.ZodBoolean>;
     /** Re-download downloaded outputs and replace files whose object changed upstream. */
     refresh: z.ZodOptional<z.ZodBoolean>;
+    /** Put recorded outputs back on disk from the cache or the provider, without generating. */
+    restore: z.ZodOptional<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     keys: string[];
     resume?: boolean | undefined;
     force?: boolean | undefined;
     project?: string | undefined;
     refresh?: boolean | undefined;
+    restore?: boolean | undefined;
 }, {
     keys: string[];
     resume?: boolean | undefined;
     force?: boolean | undefined;
     project?: string | undefined;
     refresh?: boolean | undefined;
+    restore?: boolean | undefined;
 }>, {
     keys: string[];
     resume?: boolean | undefined;
     force?: boolean | undefined;
     project?: string | undefined;
     refresh?: boolean | undefined;
+    restore?: boolean | undefined;
 }, {
     keys: string[];
     resume?: boolean | undefined;
     force?: boolean | undefined;
     project?: string | undefined;
     refresh?: boolean | undefined;
+    restore?: boolean | undefined;
 }>;
 declare class GenerateRequestError extends Error {
     readonly status: number;

package/dist/index.js

@@ -7770,7 +7770,7 @@ async function poll(provider, lock, lockPath, opts = {}) {
 }
 
 // src/pipeline/fetch.ts
-import { existsSync as existsSync13 } from "fs";
+import { existsSync as existsSync13, readFileSync as readFileSync3 } from "fs";
 import { mkdir as mkdir4, readFile as readFile11, rename as rename4, rm as rm6, writeFile as writeFile4 } from "fs/promises";
 import path16 from "path";
 async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
@@ -7787,7 +7787,12 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
     if (opts.refresh) return e.outputs.length > 0 && Boolean(e.sourceUrls?.length || e.sourceUrl);
     if (!opts.repair) return false;
     const spec = specByKey.get(key);
-    return e.outputs.length === 0 || !spec || e.outputs.some((output) => !existsSync13(resolveOutputPath(output.path, spec.root)));
+    if (e.outputs.length === 0 || !spec) return true;
+    return e.outputs.some((output) => {
+      const file = resolveOutputPath(output.path, spec.root);
+      if (!existsSync13(file)) return true;
+      return Boolean(opts.force) && sha256(readFileSync3(file)) !== output.sha256;
+    });
   });
   const concurrency = Math.min(Math.max(1, opts.concurrency ?? 8), Math.max(1, pending.length));
   let cursor = 0;
@@ -10556,6 +10561,7 @@ function renderGallery(snapshot, opts = {}) {
   .sheet.editor-host { width:min(1400px, 96vw); grid-template-rows:auto 1fr; }
   .sheet.editor-host .rbar b { font:650 12.5px/1.4 var(--mono); color:var(--text); }
   .sheet.editor-host .rbar .acts { margin-left:auto; display:flex; gap:8px; align-items:center; }
+  .sheet.editor-host .rbar .chip { color:var(--dim); font-size:12.5px; display:inline-flex; align-items:center; gap:5px; margin-right:6px; }
   .sheet.editor-host .rbar .st { display:inline-flex; align-items:center; gap:6px; font:650 11.5px/1 var(--mono); }
   .sheet.editor-host .rbar .msg { color:var(--bad); font-size:12.5px; }
   .sheet.editor-host .stage { position:relative; min-height:0; }
@@ -10603,6 +10609,8 @@ function renderGallery(snapshot, opts = {}) {
   .tray > button { padding:5px 11px; font-size:12.5px; }
   @media (max-width: 900px) { .sheet.review-host, .sheet.compare-host, .sheet.editor-host { width:100vw; } }
   .drawer .gen { display:flex; gap:8px; flex-wrap:wrap; margin-top:12px; }
+  .drawer .readonly-hint { margin-top:10px; font-size:12.5px; line-height:1.5; }
+  .drawer .readonly-hint code { font:12px var(--mono); color:var(--text); }
   .pair { display:grid; grid-template-columns:1fr 1fr; gap:8px; margin:8px 0 10px; }
   .pair figure { margin:0; border:1px solid var(--line); background:var(--panel-deep); background-image:var(--checker);
     background-size:12px 12px; background-position:0 0,6px 6px; display:grid; place-items:center; padding:8px; min-height:96px; }
@@ -10812,7 +10820,7 @@ function renderJobs() {
     const row = el('div', 'job');
     const ph = el('span', 'ph');
     ph.append(el('i', 'dot ' + PHASE_TONE[job.phase]), document.createTextNode(job.phase));
-    const what = (job.mode === 'refresh' ? 'pull upstream for ' : job.mode === 'resume' ? 'resume ' : 'generate ') + job.keys.length + (job.keys.length === 1 ? ' asset' : ' assets') +
+    const what = (job.mode === 'refresh' ? 'pull upstream for ' : job.mode === 'restore' ? 'restore ' : job.mode === 'resume' ? 'resume ' : 'generate ') + job.keys.length + (job.keys.length === 1 ? ' asset' : ' assets') +
       (job.project ? ' in ' + job.project : '');
     const last = el('span', 'last', what + (job.messages.length ? ' \u2014 ' + job.messages[job.messages.length - 1].trim() : ''));
     last.title = job.keys.join('\\n');
@@ -10937,13 +10945,16 @@ function budgetLine() {
 
 // The confirm step: what will be sent, what it is estimated to cost, and what
 // this session may still spend. Mirrors gen's "Spend \u2026 on N asset(s)?" prompt.
-function generateDialog(items, { project = null, force = false, resume = false, refresh = false } = {}) {
+function generateDialog(items, { project = null, force = false, resume = false, refresh = false, restore = false } = {}) {
   const host = $('dialog-host');
   host.textContent = '';
   const wrap = el('div', 'dialog');
   const form = el('form');
   const noun = items.length + (items.length === 1 ? ' asset' : ' assets');
+  const free = resume || refresh || restore;
+  const replacing = items.filter((i) => i.state === 'orphaned' && i.outputs.every((o) => o.exists) || i.state === 'untracked');
   form.append(el('h3', null, refresh ? 'Pull upstream changes for ' + noun
+    : restore ? 'Restore ' + noun
     : resume ? 'Resume ' + noun
     : (force ? 'Regenerate ' : 'Generate ') + noun));
   const table = el('table');
@@ -10953,9 +10964,9 @@ function generateDialog(items, { project = null, force = false, resume = false,
   for (const item of items) {
     const tr = el('tr');
     tr.append(el('td', 'mono', item.key), el('td', null, item.state), el('td', 'n', item.candidates ?? '\u2014'),
-      el('td', 'n', resume || refresh ? 'no cost' : fmtCost(item.costUnit, item.estimatedCost ?? 0)));
+      el('td', 'n', free ? 'no cost' : fmtCost(item.costUnit, item.estimatedCost ?? 0)));
     table.append(tr);
-    if (!resume && !refresh) {
+    if (!free) {
       const g = byProvider.get(item.provider) || { cost: 0, unit: item.costUnit };
       g.cost += item.estimatedCost ?? 0; byProvider.set(item.provider, g);
     }
@@ -10964,6 +10975,9 @@ function generateDialog(items, { project = null, force = false, resume = false,
   const sum = el('div', 'sum');
   if (refresh) {
     sum.append(el('div', null, 'Re-downloads each object from the provider and replaces the local file only when the object changed upstream \u2014 for example after editing it in the provider\u2019s own editor. Unchanged objects are left alone; a file you changed locally is refused. Nothing is submitted.'));
+  } else if (restore) {
+    sum.append(el('div', null, 'Puts the recorded bytes back on disk from the local cache or the provider object. Nothing is generated or submitted.'));
+    if (force && replacing.length) sum.append(el('div', 'warn', 'The file on disk was changed after PixelKiln wrote it. Restoring discards that change. To keep it instead, cancel and use Edit by hand or Edit in browser first: the edit is copied beside the generated file, and the record stays intact.'));
   } else if (resume) {
     sum.append(el('div', null, 'Polls, reviews, and downloads existing provider work. Nothing is submitted.'));
   } else {
@@ -10976,12 +10990,13 @@ function generateDialog(items, { project = null, force = false, resume = false,
       if (left !== null && g.cost > left) line.className = 'warn';
       sum.append(line);
     }
-    if (force) sum.append(el('div', 'warn', 'Regenerating replaces the current art. The previous file is replaced when the new result is fetched; the provider objects it came from are not deleted.'));
+    if (force && replacing.length) sum.append(el('div', 'warn', (replacing.length === 1 ? 'This file' : replacing.length + ' of these files') + ' changed on disk after PixelKiln wrote it (or was never recorded). Generating replaces it and that change is lost. To keep it, cancel and use Edit by hand or Edit in browser first.'));
+    else if (force) sum.append(el('div', 'warn', 'Regenerating replaces the current art. The previous file is replaced when the new result is fetched; the provider objects it came from are not deleted.'));
     sum.append(el('div', null, 'Candidate sets land in review; you choose from them here before anything is downloaded.'));
   }
   form.append(sum);
   const actions = el('div', 'actions');
-  const go = el('button', 'primary', refresh ? 'Pull changes' : resume ? 'Resume' : 'Generate');
+  const go = el('button', 'primary', refresh ? 'Pull changes' : restore ? (force && replacing.length ? 'Restore and discard my change' : 'Restore') : resume ? 'Resume' : force && replacing.length ? 'Generate and replace' : 'Generate');
   go.type = 'submit';
   const cancel = el('button', null, 'Cancel'); cancel.type = 'button'; cancel.onclick = () => { host.textContent = ''; };
   const msg = el('span', 'msg');
@@ -10996,6 +11011,7 @@ function generateDialog(items, { project = null, force = false, resume = false,
       if (force) body.force = true;
       if (resume) body.resume = true;
       if (refresh) body.refresh = true;
+      if (restore) body.restore = true;
       const job = await postGenerate(body);
       host.textContent = '';
       GEN.jobs.unshift(job);
@@ -11084,11 +11100,16 @@ function openEditorSheet(item) {
   const status = el('span', 'st');
   const acts = el('div', 'acts');
   const msg = el('span', 'msg');
+  const compare = el('label', 'chip'); compare.hidden = true;
+  compare.title = 'The generated art on a locked layer at 50%, for comparison; never part of the saved file';
+  const compareBox = el('input'); compareBox.type = 'checkbox'; compareBox.checked = true;
+  compareBox.onchange = () => showReference(compareBox.checked);
+  compare.append(compareBox, document.createTextNode(' show generated'));
   const save = el('button', 'primary', 'Save to project'); save.type = 'button';
   save.onclick = () => requestEditorSave(false);
   const saveClose = el('button', null, 'Save & close'); saveClose.type = 'button';
   saveClose.onclick = () => requestEditorSave(true);
-  acts.append(msg, save, saveClose);
+  acts.append(msg, compare, save, saveClose);
   bar.append(close, title, status, acts);
   const stage = el('div', 'stage');
   const frame = el('iframe');
@@ -11101,7 +11122,7 @@ function openEditorSheet(item) {
   stage.append(frame, loading);
   panel.append(bar, stage);
   host.append(scrim, panel);
-  SHEET = { item, frame, loading, status, msg, save, saveClose, dirty: false, opened: false, ready: null, pending: null, requests: 0, source: src, sentProject: false, roles: null };
+  SHEET = { item, frame, loading, status, msg, save, saveClose, compare, dirty: false, opened: false, ready: null, pending: null, requests: 0, source: src, sentProject: false, sentReference: false, reference: false, roles: null };
   sheetStatus('cool', 'loading');
   sheetButtons();
   close.focus({ preventScroll: true });
@@ -11121,7 +11142,11 @@ async function sendOpen() {
     sheetStatus('bad', 'unsupported');
     return;
   }
+  // When an edit is being opened, the generated art rides along as a
+  // reference layer: what the editor shows through at 50% for comparison.
+  const referenceFiles = sources.fromEdit && SHEET.ready.version >= 4 && item.outputs.every((o) => o.exists && o.url) ? item.outputs : null;
   const pngs = [];
+  const reference = [];
   let pxo = null;
   try {
     for (const file of sources.files) {
@@ -11133,6 +11158,10 @@ async function sendOpen() {
       const p = await fetch(projectUrl, { cache: 'no-store' });
       if (p.ok) pxo = await p.arrayBuffer();
     }
+    for (const file of referenceFiles || []) {
+      const res = await fetch(file.url, { cache: 'no-store' });
+      if (res.ok) reference.push({ role: file.role || null, png: await res.arrayBuffer() });
+    }
   } catch (err) {
     if (SHEET) { SHEET.msg.textContent = 'Could not load the image: ' + err.message; sheetStatus('bad', 'failed'); }
     return;
@@ -11157,9 +11186,18 @@ async function sendOpen() {
     transfer.push(message.png);
   }
   if (pxo) { message.pxo = pxo; transfer.push(pxo); }
+  if (reference.length === (referenceFiles || []).length && reference.length) {
+    message.reference = reference;
+    for (const r of reference) transfer.push(r.png);
+  }
+  SHEET.sentReference = !!message.reference;
   SHEET.frame.contentWindow.postMessage(message, location.origin, transfer);
   sheetStatus('cool', 'opening');
 }
+function showReference(visible) {
+  if (!SHEET || !SHEET.opened || !SHEET.reference) return;
+  SHEET.frame.contentWindow.postMessage({ type: 'pixelkiln:reference', visible }, location.origin);
+}
 function requestEditorSave(close) {
   if (!SHEET || !SHEET.opened || SHEET.pending) return;
   const request = 'save-' + (++SHEET.requests);
@@ -11183,10 +11221,13 @@ async function onEditorMessage(m) {
     case 'pixelkiln:opened':
       SHEET.opened = true;
       SHEET.loading.remove();
+      SHEET.reference = !!m.reference;
+      SHEET.compare.hidden = !SHEET.reference;
       if (m.source === 'pxo') sheetStatus('ok', 'editing the edit file' + (m.frames > 1 ? 's' : '') + ' with ' + (m.layers === 1 ? 'the layer' : m.layers + ' layers') + (m.frames > 1 ? ' and ' + m.frames + ' ' + memberNoun(SHEET.item, m.frames) : '') + ' restored');
       else if (SHEET.sentProject) sheetStatus('warn', 'editing the flattened edit file' + (m.frames > 1 ? 's' : '') + '; the layer file could not be opened');
       else if (m.source === 'frames') sheetStatus('ok', (SHEET.item.edits.length ? 'editing the edit files' : 'editing a copy of the generated ' + memberNoun(SHEET.item, m.frames)) + ' as ' + m.frames + ' frames' + (isFrameSet(SHEET.item) ? '' : ', one per ' + memberNoun(SHEET.item, 1)));
       else sheetStatus('ok', SHEET.item.edit && SHEET.item.edit.exists ? 'editing the edit file' : 'editing a copy of the generated art');
+      if (SHEET.reference) SHEET.status.append(document.createTextNode(' \xB7 generated art shown through at 50%'));
       sheetButtons();
       break;
     case 'pixelkiln:dirty':
@@ -11629,6 +11670,13 @@ function generateActions(item) {
   };
   if (item.state === 'missing' || item.state === 'stale' || item.state === 'failed') add('Generate' + cost, 'primary', {});
   else if (item.state === 'ok') add('Regenerate' + cost, null, { force: true });
+  else if (item.state === 'orphaned' && item.outputs.every((o) => o.exists)) {
+    // The file changed after download. Putting the recorded bytes back and
+    // regenerating both discard that change, so both say so and ask.
+    add('Restore recorded bytes \xB7 no cost', null, { restore: true, force: true });
+    add('Regenerate' + cost, null, { force: true });
+  } else if (item.state === 'orphaned') add('Restore \xB7 no cost', 'primary', { restore: true });
+  else if (item.state === 'untracked') add('Generate' + cost + ' \xB7 replaces the file', null, { force: true });
   if (item.state === 'in-flight' || item.state === 'recoverable') {
     // A job already parked this asset in review: go straight to its sheet.
     const holder = GEN.jobs.find((job) => job.phase === 'review' && job.project === item.project && job.review.includes(item.key));
@@ -12319,6 +12367,15 @@ function renderDrawer() {
   if (ui.notice && ui.notice.id === item.id) body.append(el('div', 'notice', ui.notice.text));
   body.append(stateNode(item.state, item.reason));
   if (GENERATION) body.append(generateActions(item));
+  // Writes are opt-in flags on the command line; say so where the buttons would be.
+  if ((!EDITABLE || !GENERATION) && item.declared) {
+    const missing = [];
+    if (!EDITABLE) missing.push('--edit to change its prompt, size, and tags or open it in the browser editor');
+    if (!GENERATION) missing.push('--budget <n> to generate or regenerate it from here');
+    const hint = el('div', 'state-dim readonly-hint');
+    hint.append(document.createTextNode('This gallery is read-only. Restart it with '), el('code', null, 'pixelkiln gallery'), document.createTextNode(' plus ' + missing.join(', and ') + '.'));
+    body.append(hint);
+  }
   if (canEdit && ui.editing === item.id) body.append(editForm(item));
   // Plan already quotes the error as the reason for a failed entry; only a
   // stale or superseded failure needs its own line.
@@ -12629,8 +12686,8 @@ var pin_default = {
   pixelorama: "v1.2.2",
   godot: "4.7.2",
   extensionsApi: 9,
-  protocol: 3,
-  release: "editor-pixelorama-v1.2.2-pk.14",
+  protocol: 4,
+  release: "editor-pixelorama-v1.2.2-pk.18",
   files: {
     "index.apple-touch-icon.png": {
       sha256: "ee5434873e0fed91e9a888c3ea5a8b79beac25999308be7a6eb41bf4ce640d27",
@@ -12645,7 +12702,7 @@ var pin_default = {
       bytes: 7298
     },
     "index.html": {
-      sha256: "2974146c89f4df9f796e840947c334aaf3e4fa3dd18bcd7e08db2eabfd0f086e",
+      sha256: "d9adf06036660c4b76ef5386e872bc03dc0d5b0628fd6ac660d480893ee1f47a",
       bytes: 5442
     },
     "index.icon.png": {
@@ -12657,8 +12714,8 @@ var pin_default = {
       bytes: 279815
     },
     "index.pck": {
-      sha256: "736bd383c82fdadf31cc894caf08490b99c5df572aa20db683972c35c7a0465b",
-      bytes: 6429628
+      sha256: "a41d9c3a39aa99ea5ee49ddcedfeb8b092006aa75c0de67139f13297c17f42e4",
+      bytes: 6431692
     },
     "index.png": {
       sha256: "6e3ca3eb4a99e4c07bdd89ebc873b440ec0ffd66ce1955160da9e7ed80d538d7",
@@ -13207,13 +13264,21 @@ import { z as z10 } from "zod";
 var GenerateRequestSchema = z10.object({
   project: z10.string().min(1).optional(),
   keys: z10.array(z10.string().min(1)).min(1).max(500),
-  /** Regenerate work that is up to date, as `gen --force` does. */
+  /**
+   * Regenerate work that is up to date, as `gen --force` does, and let the
+   * fetch replace a locally modified or untracked file. With `restore`, put
+   * the recorded bytes back over a modified file.
+   */
   force: z10.boolean().optional(),
   /** Advance in-flight, review, or selected work without submitting anything. */
   resume: z10.boolean().optional(),
   /** Re-download downloaded outputs and replace files whose object changed upstream. */
-  refresh: z10.boolean().optional()
-}).strict().refine((request) => !(request.resume && request.refresh), { message: "resume and refresh are exclusive" });
+  refresh: z10.boolean().optional(),
+  /** Put recorded outputs back on disk from the cache or the provider, without generating. */
+  restore: z10.boolean().optional()
+}).strict().refine((request) => [request.resume, request.refresh, request.restore].filter(Boolean).length <= 1, {
+  message: "resume, refresh, and restore are exclusive"
+});
 var GenerateRequestError = class extends Error {
   constructor(message6, status = 400) {
     super(message6);
@@ -13301,7 +13366,9 @@ function createGenerateHandlers(opts) {
     for (const [providerId, providerSpecs] of groupByRecordedProvider(specs, ctx.lock)) {
       const provider = opts.providerFor(job.project ?? void 0, providerId);
       const res = await fetchAssets(provider, providerSpecs, ctx.lock, ctx.lockPath, {
-        onProgress: (line) => say(job, line)
+        onProgress: (line) => say(job, line),
+        // A forced regeneration replaces whatever is on disk, as `gen --force`.
+        force: job.force
       });
       job.counts.downloaded += res.downloaded;
       if (res.downloaded || res.failed) {
@@ -13316,12 +13383,32 @@ function createGenerateHandlers(opts) {
       job.finishedAt = now().toISOString();
     }
   }
+  async function restore(job, ctx, specs) {
+    job.phase = "fetching";
+    for (const [providerId, providerSpecs] of groupByRecordedProvider(specs, ctx.lock)) {
+      const provider = opts.providerFor(job.project ?? void 0, providerId);
+      const res = await fetchAssets(provider, providerSpecs, ctx.lock, ctx.lockPath, {
+        onProgress: (line) => say(job, line),
+        repair: true,
+        force: job.force
+      });
+      job.counts.downloaded += res.downloaded;
+      say(job, `${providerId}: restored ${res.downloaded}, skipped ${res.skipped}, failed ${res.failed}`);
+      if (res.failed) throw new Error(`${res.failed} file(s) could not be restored`);
+    }
+    job.phase = "done";
+    job.finishedAt = now().toISOString();
+  }
   async function run(job, ctx, specs, groups) {
     try {
       if (job.mode === "refresh") {
         await refresh(job, ctx, specs);
         return;
       }
+      if (job.mode === "restore") {
+        await restore(job, ctx, specs);
+        return;
+      }
       if (job.mode === "generate") {
         job.phase = "submitting";
         for (const group of groups) {
@@ -13384,8 +13471,16 @@ function createGenerateHandlers(opts) {
         const holder = busy.get(`${request.project ?? ""}:${key}`);
         if (holder) throw new GenerateRequestError(`"${key}" is already being worked on by job ${holder}`, 409);
       }
+      if (request.restore) {
+        for (const key of request.keys) {
+          const entry = ctx.lock.entries[key];
+          if (!entry || entry.status !== "downloaded" || !entry.outputs.length) {
+            throw new GenerateRequestError(`"${key}" has no downloaded output recorded to restore`);
+          }
+        }
+      }
       let groups = [];
-      if (!request.resume && !request.refresh) {
+      if (!request.resume && !request.refresh && !request.restore) {
         const plan = await buildPlan(specs, ctx.lock, { force: request.force });
         if (!plan.actionable.length) {
           const reasons = plan.items.map((item) => `${item.key}: ${item.state} \u2014 ${item.reason}`).slice(0, 5);
@@ -13405,7 +13500,8 @@ function createGenerateHandlers(opts) {
         id: randomBytes2(8).toString("hex"),
         project: request.project ?? null,
         keys: request.keys,
-        mode: request.refresh ? "refresh" : request.resume ? "resume" : "generate",
+        mode: request.refresh ? "refresh" : request.resume ? "resume" : request.restore ? "restore" : "generate",
+        force: Boolean(request.force),
         phase: "queued",
         startedAt: now().toISOString(),
         finishedAt: null,
@@ -13417,7 +13513,7 @@ function createGenerateHandlers(opts) {
       };
       jobs.set(job.id, job);
       contexts.set(job.id, ctx);
-      say(job, request.refresh ? `checking ${request.keys.length} asset(s) upstream at no cost` : request.resume ? `resuming ${request.keys.length} asset(s) at no cost` : `generating ${groups.reduce((n, g) => n + g.actionable.length, 0)} asset(s): ` + groups.map((g) => `${g.provider} ${formatCost(g.costUnit, g.cost)}`).join("; "));
+      say(job, request.refresh ? `checking ${request.keys.length} asset(s) upstream at no cost` : request.restore ? `restoring ${request.keys.length} asset(s) at no cost${request.force ? " (replacing modified files)" : ""}` : request.resume ? `resuming ${request.keys.length} asset(s) at no cost` : `generating ${groups.reduce((n, g) => n + g.actionable.length, 0)} asset(s): ` + groups.map((g) => `${g.provider} ${formatCost(g.costUnit, g.cost)}`).join("; "));
       void run(job, ctx, specs, groups);
       return job;
     },