@playcraft/cli 0.1.55-beta → 0.1.57-beta

package/templates/preview-runtime/v1/runtime.mjs

@@ -197,6 +197,8 @@ var BridgeMethods = {
     restart: "runtime.parameters.restart",
     status: "runtime.parameters.status",
     dispose: "runtime.parameters.dispose",
+    asset: "runtime.parameters.asset",
+    refreshImages: "runtime.parameters.refresh-images",
     capabilities: "runtime.parameters.capabilities",
     result: "runtime.parameters.result",
     resyncRequired: "runtime.parameters.resync-required"
@@ -220,7 +222,9 @@ var BRIDGE_RPC_NAMES = [
   BridgeMethods.runtimeParameters.patch,
   BridgeMethods.runtimeParameters.restart,
   BridgeMethods.runtimeParameters.status,
-  BridgeMethods.runtimeParameters.dispose
+  BridgeMethods.runtimeParameters.dispose,
+  BridgeMethods.runtimeParameters.asset,
+  BridgeMethods.runtimeParameters.refreshImages
 ];
 
 // ../iframe-bridge/src/configs/perspective.ts
@@ -415,7 +419,7 @@ function safeReply(bridge, message) {
   try {
     bridge.postMessage(message);
   } catch (err) {
-    if (err instanceof PlaycraftBridgeError && err.code === BridgeErrorCodes.PEER_UNAVAILABLE) {
+    if (err instanceof PlaycraftBridgeError && (err.code === BridgeErrorCodes.PEER_UNAVAILABLE || err.code === BridgeErrorCodes.DESTROYED)) {
       return;
     }
     throw err;
@@ -524,6 +528,19 @@ var Bridge = class {
 };
 
 // ../preview-runtime/src/protocol.ts
+var MAX_IMAGE_RESOURCE_BYTES = 32 * 1024 * 1024;
+var ResourceLoadError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ResourceLoadError";
+  }
+};
+var SupersededResourceError = class extends Error {
+  constructor() {
+    super("A newer image value replaced this resource request");
+    this.name = "SupersededResourceError";
+  }
+};
 var ProtocolError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -622,6 +639,44 @@ var identityKeys = [
   "configContractVersion",
   "locale"
 ];
+function assertImageRefresh(value) {
+  assertIdentity(value);
+  const request = value;
+  exactKeys(value, [
+    ...identityKeys,
+    "draftRevision",
+    "resourceSequence",
+    "images"
+  ]);
+  if (!revision(request.draftRevision) || !revision(request.resourceSequence) || request.resourceSequence === 0 || !Array.isArray(request.images) || !request.images.length || request.images.length > 64)
+    throw new ProtocolError("INVALID", "Invalid image refresh sequence or target count");
+  const seen = /* @__PURE__ */ new Set();
+  for (const image of request.images) {
+    if (!record(image) || !string(image.documentId) || forbidden.has(image.documentId) || !Array.isArray(image.path) || !image.path.length || image.path.length > 32 || image.path.some((part) => !string(part) || forbidden.has(part)) || image.contentHash !== null && (typeof image.contentHash !== "string" || !/^[a-f0-9]{64}$/.test(image.contentHash)))
+      throw new ProtocolError("INVALID", "Invalid image refresh target");
+    exactKeys(image, ["documentId", "path", "contentHash"]);
+    const key = fingerprint([image.documentId, image.path]);
+    if (seen.has(key)) throw new ProtocolError("INVALID", "Duplicate image refresh target");
+    seen.add(key);
+  }
+  limit(value, 64 * 1024);
+}
+function assertImageResourceData(value) {
+  if (!record(value) || typeof value.mimeType !== "string" || typeof value.dataUrl !== "string")
+    throw new ProtocolError("INVALID", "Invalid image resource response");
+  const allowed = ["image/png", "image/jpeg", "image/webp", "image/gif", "image/avif", "image/bmp"];
+  if (!allowed.includes(value.mimeType))
+    throw new ProtocolError("INVALID", "Unsupported image resource type");
+  const prefix = `data:${value.mimeType};base64,`;
+  const data = value.dataUrl.startsWith(prefix) ? value.dataUrl.slice(prefix.length) : "";
+  if (!data || data.length % 4 !== 0 || data.length > Math.ceil(MAX_IMAGE_RESOURCE_BYTES / 3) * 4 || !/^[A-Za-z0-9+/]+={0,2}$/.test(data))
+    throw new ProtocolError("LIMIT", "Invalid or oversized image resource data");
+  const bytes = data.length / 4 * 3 - (data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0);
+  if (bytes > MAX_IMAGE_RESOURCE_BYTES)
+    throw new ProtocolError("LIMIT", "Image resource exceeds the byte limit");
+  if (value.contentHash !== void 0 && !/^[a-f0-9]{64}$/.test(String(value.contentHash)))
+    throw new ProtocolError("INVALID", "Invalid image content fingerprint");
+}
 function assertSnapshot(value) {
   assertIdentity(value);
   exactKeys(value, [
@@ -699,12 +754,63 @@ function createParameterRuntime(options) {
   let error;
   let disposed = false;
   let cleanupFailure;
+  let recoverable = false;
+  const resourceErrors = /* @__PURE__ */ new Map();
   let resultSequence = 0;
   const retiredSessions = /* @__PURE__ */ new Set();
   const groups = /* @__PURE__ */ new Map();
   const receipts = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Set();
   const capabilityListeners = /* @__PURE__ */ new Set();
+  const installedImages = /* @__PURE__ */ new Map();
+  const imageReads = /* @__PURE__ */ new Map();
+  const imageLoads = /* @__PURE__ */ new WeakMap();
+  const refreshGoals = /* @__PURE__ */ new Map();
+  const refreshWork = /* @__PURE__ */ new Set();
+  const refreshReceipts = /* @__PURE__ */ new Map();
+  let resourceSequence = 0;
+  const imageKey = (field) => fingerprint([field.documentId, field.path]);
+  async function readImage(request, signal) {
+    signal.throwIfAborted();
+    const key = imageKey(request);
+    const read = new AbortController();
+    const cancel = () => read.abort(signal.reason);
+    signal.addEventListener("abort", cancel, { once: true });
+    const active = imageReads.get(key) ?? /* @__PURE__ */ new Set();
+    active.add(read);
+    imageReads.set(key, active);
+    let off = () => {
+    };
+    try {
+      return await Promise.race([
+        options.loadImage(request, read.signal),
+        new Promise((_, reject) => {
+          const cancelled = () => reject(read.signal.reason);
+          read.signal.addEventListener("abort", cancelled, { once: true });
+          off = () => read.signal.removeEventListener("abort", cancelled);
+          if (read.signal.aborted) cancelled();
+        })
+      ]);
+    } finally {
+      off();
+      signal.removeEventListener("abort", cancel);
+      active.delete(read);
+      if (!active.size && imageReads.get(key) === active) imageReads.delete(key);
+    }
+  }
+  function cancelRefreshes() {
+    for (const goal of refreshGoals.values()) goal.controller.abort(new SupersededResourceError());
+    refreshGoals.clear();
+  }
+  function commitImages(ctx) {
+    for (const [key, image] of imageLoads.get(ctx) ?? []) {
+      installedImages.set(key, image);
+      resourceErrors.delete(key);
+    }
+    for (const field of ctx.fields)
+      if (field.resource === "image" && readPath(ctx.config, field.effectivePath) === "")
+        installedImages.delete(imageKey(field));
+  }
   async function release(game) {
     try {
       await game?.dispose();
@@ -719,6 +825,7 @@ function createParameterRuntime(options) {
     ...requireIdentity(),
     stage,
     canAcceptSnapshot: true,
+    ...options.loadImage ? { canRefreshImages: true, canReportMissingImages: true } : {},
     fields: clone(options.fields)
   });
   function requireIdentity() {
@@ -739,7 +846,9 @@ function createParameterRuntime(options) {
     appliedRevision,
     status,
     groups: clone([...groups.values()]),
-    ...error ? { error } : {}
+    ...error ? { error } : {},
+    ...recoverable ? { recoverable: true } : {},
+    ...resourceErrors.size ? { resourceErrors: clone([...resourceErrors.values()]) } : {}
   });
   function publish() {
     if (!identity || disposed) return;
@@ -747,19 +856,77 @@ function createParameterRuntime(options) {
     const value = result();
     listeners.forEach((fn) => fn(value));
   }
-  function context(config, beforeConfig, draftRevision, fields, signal) {
-    return {
+  function context(config, beforeConfig, draftRevision, fields, signal, refresh) {
+    const images = /* @__PURE__ */ new Map();
+    const loaded = /* @__PURE__ */ new Map();
+    const assertCurrent = () => {
+      signal.throwIfAborted();
+      if (signal !== controller.signal || disposed)
+        throw new ProtocolError("STALE", "Application task expired");
+      refresh?.assertCurrent();
+      if (images.size && target) {
+        const latest = options.resolve(target);
+        for (const [key, { field, value, sequence }] of images)
+          if (readPath(latest, field.effectivePath) !== value || (refreshGoals.get(key)?.sequence ?? 0) !== sequence)
+            throw new SupersededResourceError();
+      }
+    };
+    const ctx = {
       config,
       beforeConfig,
       draftRevision,
       fields,
       signal,
-      assertCurrent() {
-        signal.throwIfAborted();
-        if (signal !== controller.signal || disposed)
-          throw new ProtocolError("STALE", "Application task expired");
+      assertCurrent,
+      async loadImage(field, value) {
+        const registered = options.fields.find(
+          (item) => item.resource === "image" && item.documentId === field.documentId && fingerprint(item.path) === fingerprint(field.path)
+        );
+        if (!registered || typeof value !== "string" || !value)
+          throw new ProtocolError("UNSUPPORTED", "Unregistered image resource field");
+        if (!options.loadImage)
+          throw new ProtocolError("UNSUPPORTED", "Image resource transport is unavailable");
+        const key = fingerprint([registered.documentId, registered.path]);
+        const goal = refreshGoals.get(key);
+        images.set(key, { field: registered, value, sequence: goal?.sequence ?? 0 });
+        assertCurrent();
+        try {
+          const prepared = refresh?.prepared.get(key);
+          const response = prepared?.value === value ? prepared : await readImage(
+            {
+              ...requireIdentity(),
+              draftRevision,
+              documentId: registered.documentId,
+              path: clone(registered.path),
+              value,
+              ...goal?.value === value ? {
+                resourceSequence: goal.sequence,
+                ...goal.contentHash !== null ? { expectedContentHash: goal.contentHash } : {}
+              } : {}
+            },
+            signal
+          );
+          assertCurrent();
+          const image = "image" in response ? response.image : response;
+          const contentHash = "image" in response ? response.contentHash : void 0;
+          if (goal?.value === value && goal.contentHash !== null && contentHash !== goal.contentHash)
+            throw new ResourceLoadError("Image resource content changed during refresh");
+          loaded.set(key, { value, image, ...contentHash ? { contentHash } : {} });
+          return image;
+        } catch (failure) {
+          assertCurrent();
+          if (failure instanceof ResourceLoadError)
+            resourceErrors.set(key, {
+              documentId: registered.documentId,
+              path: clone(registered.path),
+              error: failure.message
+            });
+          throw failure;
+        }
       }
     };
+    imageLoads.set(ctx, loaded);
+    return ctx;
   }
   function enqueue(work) {
     const signal = controller.signal;
@@ -769,13 +936,20 @@ function createParameterRuntime(options) {
         await work(signal);
       } catch (e) {
         if (signal.aborted) return;
+        if (e instanceof SupersededResourceError) return;
         status = "error";
-        installedRevision = appliedRevision = -1;
+        recoverable = e instanceof ResourceLoadError;
+        if (!recoverable) installedRevision = appliedRevision = -1;
         error = e instanceof Error ? e.message : String(e);
-        for (const group of groups.values()) group.status = "unknown";
+        for (const group of groups.values())
+          if (!recoverable || options.fields.some(
+            (field) => field.groupId === group.groupId && resourceErrors.has(fingerprint([field.documentId, field.path]))
+          ))
+            group.status = "unknown";
         publish();
       }
     });
+    return queue;
   }
   function remember(kind, request) {
     const key = `${kind}:${request.draftRevision}`;
@@ -795,12 +969,26 @@ function createParameterRuntime(options) {
     return receipt;
   }
   function updateState(rev, changed) {
+    const previousGroups = new Map(groups);
     for (const field of changed)
       groups.set(field.groupId, {
         groupId: field.groupId,
         appliedRevision: rev,
         status: "applied"
       });
+    if (resourceErrors.size) {
+      status = "error";
+      recoverable = true;
+      if (changed.length) installedRevision = appliedRevision = -1;
+      error = [...resourceErrors.values()].map((item) => item.error).join("; ");
+      for (const field of options.fields)
+        if (resourceErrors.has(fingerprint([field.documentId, field.path])))
+          groups.set(field.groupId, { ...previousGroups.get(field.groupId), status: "unknown" });
+      publish();
+      return;
+    }
+    recoverable = false;
+    error = void 0;
     let pending = false, reload = false;
     for (const field of options.fields) {
       if (fingerprint(readPath(installed?.[field.documentId], field.path)) !== fingerprint(readPath(target?.[field.documentId], field.path))) {
@@ -817,13 +1005,11 @@ function createParameterRuntime(options) {
     } else status = reload ? "requires-reload" : pending ? "pending-commit" : "applying";
     publish();
   }
-  async function applyTarget(documents, rev, commit, signal) {
-    if (status === "error") return;
-    if (!adapter || !installed)
-      throw new ProtocolError("STATE", "Initial snapshot must create the game first");
+  function candidateFor(documents, commit, retryResources) {
     const operations = [];
     for (const field of options.fields) {
       if (field.mode !== "live" && !(commit && field.mode === "restart-scene")) continue;
+      if (resourceErrors.has(imageKey(field)) && !retryResources.has(imageKey(field))) continue;
       const value = readPath(documents[field.documentId], field.path);
       operations.push(
         value === void 0 ? { op: "remove", documentId: field.documentId, path: field.path } : {
@@ -834,17 +1020,34 @@ function createParameterRuntime(options) {
         }
       );
     }
-    const candidate = applyOperations(installed, operations);
+    return applyOperations(installed, operations);
+  }
+  async function applyTarget(documents, rev, commit, signal, retryResources = /* @__PURE__ */ new Set(), refresh, rereadImages = /* @__PURE__ */ new Set()) {
+    if (status === "error" && !recoverable) return;
+    if (!adapter || !installed)
+      throw new ProtocolError("STATE", "Initial snapshot must create the game first");
+    const candidate = candidateFor(documents, commit, retryResources);
     const before = options.source.get();
     const config = freeze(options.resolve(freeze(clone(candidate))));
     const changed = options.fields.filter(
-      (field) => fingerprint(readPath(before, field.effectivePath)) !== fingerprint(readPath(config, field.effectivePath))
+      (field) => rereadImages.has(imageKey(field)) || refresh?.prepared.has(imageKey(field)) || resourceErrors.has(fingerprint([field.documentId, field.path])) && retryResources.has(fingerprint([field.documentId, field.path])) && (field.mode === "live" || commit && field.mode === "restart-scene") || fingerprint(readPath(before, field.effectivePath)) !== fingerprint(readPath(config, field.effectivePath))
+    );
+    const ctx = context(
+      config,
+      before,
+      rev,
+      changed,
+      signal,
+      refresh ? {
+        prepared: refresh.prepared,
+        assertCurrent: () => refresh.assertCurrent(config)
+      } : void 0
     );
-    const ctx = context(config, before, rev, changed, signal);
     ctx.assertCurrent();
     status = "applying";
     publish();
     options.source.install(config);
+    const previousInstalledRevision = installedRevision;
     installedRevision = fingerprint(candidate) === fingerprint(documents) ? rev : -1;
     try {
       if (changed.some((field) => field.mode === "restart-scene")) await adapter.restartScene(ctx);
@@ -852,10 +1055,29 @@ function createParameterRuntime(options) {
       ctx.assertCurrent();
       await adapter.afterRender(ctx);
       ctx.assertCurrent();
+      commitImages(ctx);
+      for (const field of changed)
+        if (field.resource === "image" && readPath(config, field.effectivePath) === "")
+          resourceErrors.delete(fingerprint([field.documentId, field.path]));
       installed = candidate;
       updateState(rev, changed);
     } catch (e) {
-      if (!signal.aborted) options.source.install(before);
+      if (!signal.aborted) {
+        options.source.install(before);
+        installedRevision = previousInstalledRevision;
+        if (e instanceof ResourceLoadError)
+          for (const field of changed) {
+            if (field.resource !== "image") continue;
+            const key = imageKey(field);
+            installedImages.delete(key);
+            if (!resourceErrors.has(key))
+              resourceErrors.set(key, {
+                documentId: field.documentId,
+                path: clone(field.path),
+                error: e.message
+              });
+          }
+      }
       throw e;
     }
   }
@@ -882,12 +1104,18 @@ function createParameterRuntime(options) {
         cleanupFailure = e;
       });
       identity = freeze({ ...clone(value), runtimeInstanceId });
+      cancelRefreshes();
+      installedImages.clear();
+      refreshReceipts.clear();
+      resourceSequence = 0;
       target = installed = void 0;
       receivedRevision = installedRevision = appliedRevision = -1;
       receipts.clear();
       stage = "bootstrap-ready";
       status = "idle";
       error = void 0;
+      recoverable = false;
+      resourceErrors.clear();
       resultSequence = 0;
       for (const group of groups.values()) {
         group.appliedRevision = -1;
@@ -907,6 +1135,8 @@ function createParameterRuntime(options) {
       const rev = value.draftRevision;
       const documents = freeze(clone(value.documents));
       options.resolve(documents);
+      cancelRefreshes();
+      installedImages.clear();
       target = documents;
       const receipt = accept("snapshot", value);
       enqueue(async (signal) => {
@@ -915,44 +1145,57 @@ function createParameterRuntime(options) {
             "RECOVERY",
             "Previous game cleanup failed; reload the preview frame"
           );
-        const before = options.source.get();
-        const config = freeze(options.resolve(documents));
-        const ctx = context(config, before, rev, clone(options.fields), signal);
-        ctx.assertCurrent();
         status = "applying";
         publish();
         const previousAdapter = adapter;
         adapter = void 0;
         stage = "bootstrap-ready";
         await release(previousAdapter);
-        ctx.assertCurrent();
-        options.source.install(config);
-        installedRevision = rev;
-        let created;
-        try {
-          created = await options.createGame(ctx);
-          if (signal.aborted) {
-            await release(created);
-            return;
-          }
-          ctx.assertCurrent();
-          adapter = created;
-          stage = "game-ready";
-          capabilityListeners.forEach((fn) => fn(capabilities()));
-          await created.afterRender(ctx);
+        let nextDocuments = documents;
+        let nextRevision = rev;
+        for (; ; ) {
+          const before = options.source.get();
+          resourceErrors.clear();
+          recoverable = false;
+          const config = freeze(options.resolve(nextDocuments));
+          const ctx = context(config, before, nextRevision, clone(options.fields), signal);
           ctx.assertCurrent();
-          installed = clone(documents);
-          error = void 0;
-          updateState(rev, options.fields);
-        } catch (e) {
-          if (!signal.aborted) {
-            adapter = void 0;
-            stage = "bootstrap-ready";
-            options.source.install(before);
+          options.source.install(config);
+          installedRevision = nextRevision;
+          let created;
+          try {
+            created = await options.createGame(ctx);
+            if (signal.aborted) {
+              await release(created);
+              return;
+            }
+            ctx.assertCurrent();
+            adapter = created;
+            stage = "game-ready";
             capabilityListeners.forEach((fn) => fn(capabilities()));
+            await created.afterRender(ctx);
+            ctx.assertCurrent();
+            commitImages(ctx);
+            installed = clone(nextDocuments);
+            if (resourceErrors.size) installedRevision = -1;
+            error = void 0;
+            updateState(nextRevision, options.fields);
+            return;
+          } catch (e) {
+            if (!signal.aborted) {
+              adapter = void 0;
+              stage = "bootstrap-ready";
+              options.source.install(before);
+              capabilityListeners.forEach((fn) => fn(capabilities()));
+            }
+            await release(created);
+            if (e instanceof SupersededResourceError && !signal.aborted && target) {
+              nextDocuments = freeze(clone(target));
+              nextRevision = receivedRevision;
+              continue;
+            }
+            throw e;
           }
-          await release(created);
-          throw e;
         }
       });
       return receipt;
@@ -964,7 +1207,7 @@ function createParameterRuntime(options) {
       if (previous) return previous;
       if (!target || value.baseDraftRevision !== receivedRevision)
         throw new ProtocolError("RESYNC", "Patch base does not match received revision");
-      if (status === "error")
+      if (status === "error" && !recoverable)
         throw new ProtocolError(
           "RECOVERY",
           "Application state is unknown; send a recovery snapshot"
@@ -978,13 +1221,227 @@ function createParameterRuntime(options) {
       const rev = value.draftRevision, commit = value.phase === "commit";
       options.resolve(documents);
       target = documents;
+      const latestConfig = options.resolve(documents);
+      const rereadImages = /* @__PURE__ */ new Set();
+      for (const [key, goal] of refreshGoals)
+        if (readPath(latestConfig, goal.field.effectivePath) !== goal.value || fingerprint(readPath(documents[goal.field.documentId], goal.field.path)) !== fingerprint(goal.raw)) {
+          const image = installedImages.get(key);
+          if (goal.contentHash !== null && (goal.applying || image?.value !== goal.value || image.contentHash !== goal.contentHash))
+            rereadImages.add(key);
+          goal.controller.abort(new SupersededResourceError());
+          refreshGoals.delete(key);
+        }
       const receipt = accept("patch", value);
-      enqueue((signal) => applyTarget(documents, rev, commit, signal));
+      const retryResources = new Set(
+        value.operations.length ? value.operations.map((operation) => fingerprint([operation.documentId, operation.path])) : options.fields.filter((field) => field.resource === "image").map((field) => fingerprint([field.documentId, field.path]))
+      );
+      enqueue(
+        (signal) => applyTarget(documents, rev, commit, signal, retryResources, void 0, rereadImages)
+      );
+      return receipt;
+    },
+    refreshImages(value) {
+      assertImageRefresh(value);
+      check(value);
+      const request = freeze(clone(value));
+      const previous = refreshReceipts.get(request.resourceSequence);
+      if (previous) {
+        if (previous.fingerprint !== fingerprint(request))
+          throw new ProtocolError("CONFLICT", "Image refresh sequence already accepted");
+        return previous.receipt;
+      }
+      if (request.resourceSequence <= resourceSequence || request.draftRevision !== receivedRevision || !target)
+        throw new ProtocolError("STALE", "Image refresh must name the current target and sequence");
+      if (!adapter || !installed || !options.loadImage || status === "error" && !recoverable)
+        throw new ProtocolError("STATE", "Image refresh requires an available game");
+      if (refreshWork.size >= 64)
+        throw new ProtocolError("LIMIT", "Too many pending image refresh requests");
+      const config = options.resolve(target);
+      const uncertain = /* @__PURE__ */ new Set();
+      const goals = request.images.map((image) => {
+        const field = options.fields.find(
+          (field2) => imageKey(field2) === imageKey(image) && field2.resource === "image" && field2.mode === "live"
+        );
+        const current = field && readPath(config, field.effectivePath);
+        if (!field || typeof current !== "string" || !current)
+          throw new ProtocolError("UNSUPPORTED", "Image refresh requires a live nonempty image");
+        if (refreshGoals.get(imageKey(field))?.applying) uncertain.add(imageKey(field));
+        return {
+          field,
+          value: current,
+          raw: clone(readPath(target[field.documentId], field.path)),
+          contentHash: image.contentHash,
+          sequence: request.resourceSequence,
+          controller: new AbortController()
+        };
+      });
+      const receipt = {
+        accepted: true,
+        receivedRevision,
+        resourceSequence: request.resourceSequence
+      };
+      resourceSequence = request.resourceSequence;
+      refreshReceipts.set(resourceSequence, { fingerprint: fingerprint(request), receipt });
+      if (refreshReceipts.size > 256) refreshReceipts.delete(refreshReceipts.keys().next().value);
+      for (const goal of goals) {
+        for (const read of imageReads.get(imageKey(goal.field)) ?? [])
+          read.abort(new SupersededResourceError());
+        refreshGoals.get(imageKey(goal.field))?.controller.abort(new SupersededResourceError());
+        refreshGoals.set(imageKey(goal.field), goal);
+      }
+      const active = goals.filter((goal) => {
+        if (goal.contentHash === null) return false;
+        const image = installedImages.get(imageKey(goal.field));
+        return uncertain.has(imageKey(goal.field)) || resourceErrors.has(imageKey(goal.field)) || image?.value !== goal.value || image.contentHash !== goal.contentHash;
+      });
+      const sessionSignal = controller.signal;
+      const assertSession = () => {
+        sessionSignal.throwIfAborted();
+        if (disposed || sessionSignal !== controller.signal || !target)
+          throw new SupersededResourceError();
+      };
+      const isCurrent = (goal) => {
+        assertSession();
+        const latest = options.resolve(target);
+        return !goal.controller.signal.aborted && refreshGoals.get(imageKey(goal.field)) === goal && readPath(latest, goal.field.effectivePath) === goal.value;
+      };
+      const assertGoal = (goal) => {
+        if (!isCurrent(goal)) throw new SupersededResourceError();
+      };
+      const missing = goals.filter((goal) => goal.contentHash === null);
+      for (const goal of missing)
+        resourceErrors.set(imageKey(goal.field), {
+          documentId: goal.field.documentId,
+          path: clone(goal.field.path),
+          error: "Image resource file is missing"
+        });
+      if (missing.length)
+        void enqueue(async () => {
+          assertSession();
+          if (missing.some(isCurrent)) updateState(receivedRevision, []);
+        });
+      if (!active.length) return receipt;
+      const work = (async () => {
+        const prepared = /* @__PURE__ */ new Map();
+        const cancel = () => goals.forEach((goal) => goal.controller.abort(sessionSignal.reason));
+        sessionSignal.addEventListener("abort", cancel, { once: true });
+        try {
+          await Promise.all(
+            active.map(async (goal) => {
+              try {
+                assertGoal(goal);
+                const response = await readImage(
+                  {
+                    ...requireIdentity(),
+                    draftRevision: request.draftRevision,
+                    documentId: goal.field.documentId,
+                    path: clone(goal.field.path),
+                    value: goal.value,
+                    resourceSequence: goal.sequence,
+                    expectedContentHash: goal.contentHash
+                  },
+                  goal.controller.signal
+                );
+                assertGoal(goal);
+                if (!("image" in response) || response.contentHash !== goal.contentHash)
+                  throw new ResourceLoadError("Image resource content changed during refresh");
+                prepared.set(imageKey(goal.field), {
+                  value: goal.value,
+                  image: response.image,
+                  contentHash: response.contentHash
+                });
+              } catch (failure) {
+                if (!isCurrent(goal)) return;
+                if (failure instanceof ResourceLoadError)
+                  resourceErrors.set(imageKey(goal.field), {
+                    documentId: goal.field.documentId,
+                    path: clone(goal.field.path),
+                    error: failure.message
+                  });
+                throw failure;
+              }
+            })
+          );
+          for (let attempt = 0; attempt < 32; attempt++) {
+            let rebase = false;
+            await enqueue(async (signal) => {
+              assertSession();
+              const current = active.filter(
+                (goal) => prepared.has(imageKey(goal.field)) && isCurrent(goal)
+              );
+              if (!current.length) return;
+              const selected = new Map(
+                current.map((goal) => [imageKey(goal.field), prepared.get(imageKey(goal.field))])
+              );
+              const retry = new Set(selected.keys());
+              const documents = clone(target);
+              const rev = receivedRevision;
+              try {
+                current.forEach((goal) => {
+                  goal.applying = true;
+                });
+                await applyTarget(documents, rev, false, signal, retry, {
+                  prepared: selected,
+                  assertCurrent(config2) {
+                    assertSession();
+                    if (current.some((goal) => !isCurrent(goal))) {
+                      rebase = true;
+                      throw new SupersededResourceError();
+                    }
+                    const latest = options.resolve(candidateFor(target, false, retry));
+                    if (fingerprint(latest) !== fingerprint(config2)) {
+                      rebase = true;
+                      throw new SupersededResourceError();
+                    }
+                  }
+                });
+              } catch (failure) {
+                if (rebase && failure instanceof SupersededResourceError) return;
+                throw failure;
+              } finally {
+                current.forEach((goal) => {
+                  goal.applying = false;
+                });
+              }
+            });
+            if (!rebase) return;
+          }
+          throw new ResourceLoadError("Image refresh was interrupted by parameter changes; retry");
+        } catch (failure) {
+          if (!sessionSignal.aborted && !(failure instanceof SupersededResourceError)) {
+            try {
+              assertSession();
+            } catch {
+              return;
+            }
+            if (failure instanceof ResourceLoadError) {
+              for (const goal of active.filter(isCurrent))
+                if (!resourceErrors.has(imageKey(goal.field)))
+                  resourceErrors.set(imageKey(goal.field), {
+                    documentId: goal.field.documentId,
+                    path: clone(goal.field.path),
+                    error: failure.message
+                  });
+            }
+            await enqueue(async () => {
+              throw failure;
+            });
+          }
+        } finally {
+          goals.forEach((goal) => goal.controller.abort(new SupersededResourceError()));
+          active.forEach((goal) => {
+            goal.applying = false;
+          });
+          sessionSignal.removeEventListener("abort", cancel);
+        }
+      })();
+      refreshWork.add(work);
+      void work.finally(() => refreshWork.delete(work));
       return receipt;
     },
     restart(value) {
       check(value);
-      if (status === "error")
+      if (status === "error" && !recoverable)
         throw new ProtocolError(
           "RECOVERY",
           "Application state is unknown; send a recovery snapshot"
@@ -993,7 +1450,17 @@ function createParameterRuntime(options) {
       if (rev !== receivedRevision || !target)
         throw new ProtocolError("STALE", "Restart must name the current target");
       const documents = clone(target);
-      enqueue((signal) => applyTarget(documents, rev, true, signal));
+      enqueue(
+        (signal) => applyTarget(
+          documents,
+          rev,
+          true,
+          signal,
+          new Set(
+            options.fields.filter((field) => field.resource === "image").map((field) => fingerprint([field.documentId, field.path]))
+          )
+        )
+      );
       return { accepted: true, receivedRevision };
     },
     status(value) {
@@ -1009,15 +1476,22 @@ function createParameterRuntime(options) {
       return () => capabilityListeners.delete(fn);
     },
     async settled() {
-      await queue;
+      for (; ; ) {
+        const current = queue;
+        await Promise.all([...refreshWork]);
+        await queue;
+        if (!refreshWork.size && current === queue) return;
+      }
     },
     async dispose() {
       if (disposed) return;
       disposed = true;
       controller.abort();
+      cancelRefreshes();
       listeners.clear();
       capabilityListeners.clear();
       await queue;
+      await Promise.all([...refreshWork]);
       await adapter?.dispose();
       adapter = void 0;
     }
@@ -1025,6 +1499,42 @@ function createParameterRuntime(options) {
 }
 
 // ../preview-runtime/src/preview.ts
+function decodeImage(dataUrl, signal) {
+  return new Promise((resolve, reject) => {
+    signal.throwIfAborted();
+    const image = new Image();
+    const timer = setTimeout(
+      () => finish(new ResourceLoadError("Image decoding timed out")),
+      15e3
+    );
+    const cleanup = () => {
+      clearTimeout(timer);
+      image.onload = image.onerror = null;
+      signal.removeEventListener("abort", cancel);
+    };
+    const finish = (error) => {
+      if (!error && (!Number.isSafeInteger(image.naturalWidth) || !Number.isSafeInteger(image.naturalHeight) || image.naturalWidth <= 0 || image.naturalHeight <= 0 || image.naturalWidth * image.naturalHeight > 32 * 1024 * 1024))
+        error = new ResourceLoadError("Image dimensions exceed the pixel limit");
+      cleanup();
+      if (error) {
+        image.src = "";
+        reject(error);
+      } else resolve(image);
+    };
+    const cancel = () => finish(signal.reason);
+    signal.addEventListener("abort", cancel, { once: true });
+    image.onerror = () => finish(new ResourceLoadError("Image decoding failed"));
+    image.onload = () => {
+      if (typeof image.decode !== "function") finish();
+    };
+    image.src = dataUrl;
+    if (typeof image.decode === "function")
+      void image.decode().then(
+        () => finish(),
+        () => finish(new ResourceLoadError("Image decoding failed"))
+      );
+  });
+}
 function readWorkspacePreviewContext(expectedContractVersion) {
   try {
     const mark = "playcraft-preview-storage:";
@@ -1065,7 +1575,6 @@ function connectPreviewRuntime(options) {
   const origin = new URL(options.parentOrigin).origin;
   if (origin === "null" || options.parentOrigin !== origin)
     throw new ProtocolError("ORIGIN", "An exact parent origin is required");
-  const runtime = createParameterRuntime(options);
   const bridge = new Bridge({
     peer: () => window.parent,
     targetOrigin: origin,
@@ -1073,6 +1582,32 @@ function connectPreviewRuntime(options) {
     strictSource: true
   });
   const names = BridgeMethods.runtimeParameters;
+  const runtime = createParameterRuntime({
+    ...options,
+    async loadImage(request, signal) {
+      const value = await bridge.emit(names.asset, request, { timeout: 16e3, signal });
+      if (!sameIdentity(request, value))
+        throw new ProtocolError("STALE", "Image response belongs to a different runtime");
+      const response = value;
+      if (response.draftRevision !== request.draftRevision || response.documentId !== request.documentId || fingerprint(response.path) !== fingerprint(request.path) || response.value !== request.value || response.resourceSequence !== request.resourceSequence || response.expectedContentHash !== request.expectedContentHash)
+        throw new ProtocolError("STALE", "Image response does not match its request");
+      if (response.status === "stale") throw new SupersededResourceError();
+      if (response.status === "failed") {
+        if (typeof response.error !== "string")
+          throw new ProtocolError("INVALID", "Invalid image failure response");
+        throw new ResourceLoadError(response.error);
+      }
+      if (response.status !== "ready")
+        throw new ProtocolError("INVALID", "Invalid image resource response");
+      assertImageResourceData(response);
+      if (request.expectedContentHash !== void 0 && response.contentHash !== request.expectedContentHash)
+        throw new ResourceLoadError("Image resource content changed during refresh");
+      return {
+        image: await decodeImage(response.dataUrl, signal),
+        contentHash: response.contentHash
+      };
+    }
+  });
   const off = [
     bridge.on(names.hello, (value) => runtime.hello(value)),
     bridge.on(names.snapshot, (value) => runtime.snapshot(value)),
@@ -1091,6 +1626,7 @@ function connectPreviewRuntime(options) {
       }
     }),
     bridge.on(names.restart, (value) => runtime.restart(value)),
+    bridge.on(names.refreshImages, (value) => runtime.refreshImages(value)),
     bridge.on(names.status, (value) => runtime.status(value)),
     bridge.on(names.dispose, async (value) => {
       runtime.status(value);
@@ -1116,6 +1652,7 @@ function connectPreviewRuntime(options) {
   };
 }
 export {
+  ResourceLoadError,
   connectPreviewRuntime,
   readWorkspacePreviewContext
 };