@playcraft/cli 0.1.56-beta → 0.1.58-beta

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

@@ -198,6 +198,7 @@ var BridgeMethods = {
     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"
@@ -222,7 +223,8 @@ var BRIDGE_RPC_NAMES = [
   BridgeMethods.runtimeParameters.restart,
   BridgeMethods.runtimeParameters.status,
   BridgeMethods.runtimeParameters.dispose,
-  BridgeMethods.runtimeParameters.asset
+  BridgeMethods.runtimeParameters.asset,
+  BridgeMethods.runtimeParameters.refreshImages
 ];
 
 // ../iframe-bridge/src/configs/perspective.ts
@@ -637,6 +639,28 @@ 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");
@@ -738,6 +762,55 @@ function createParameterRuntime(options) {
   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();
@@ -752,6 +825,7 @@ function createParameterRuntime(options) {
     ...requireIdentity(),
     stage,
     canAcceptSnapshot: true,
+    ...options.loadImage ? { canRefreshImages: true, canReportMissingImages: true } : {},
     fields: clone(options.fields)
   });
   function requireIdentity() {
@@ -782,19 +856,22 @@ function createParameterRuntime(options) {
     const value = result();
     listeners.forEach((fn) => fn(value));
   }
-  function context(config, beforeConfig, draftRevision, fields, signal) {
+  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 { field, value } of images.values())
-          if (readPath(latest, field.effectivePath) !== value) throw new SupersededResourceError();
+        for (const [key, { field, value, sequence }] of images)
+          if (readPath(latest, field.effectivePath) !== value || (refreshGoals.get(key)?.sequence ?? 0) !== sequence)
+            throw new SupersededResourceError();
       }
     };
-    return {
+    const ctx = {
       config,
       beforeConfig,
       draftRevision,
@@ -810,21 +887,31 @@ function createParameterRuntime(options) {
         if (!options.loadImage)
           throw new ProtocolError("UNSUPPORTED", "Image resource transport is unavailable");
         const key = fingerprint([registered.documentId, registered.path]);
-        images.set(key, { field: registered, value });
+        const goal = refreshGoals.get(key);
+        images.set(key, { field: registered, value, sequence: goal?.sequence ?? 0 });
         assertCurrent();
         try {
-          const image = await options.loadImage(
+          const prepared = refresh?.prepared.get(key);
+          const response = prepared?.value === value ? prepared : await readImage(
             {
               ...requireIdentity(),
               draftRevision,
               documentId: registered.documentId,
               path: clone(registered.path),
-              value
+              value,
+              ...goal?.value === value ? {
+                resourceSequence: goal.sequence,
+                ...goal.contentHash !== null ? { expectedContentHash: goal.contentHash } : {}
+              } : {}
             },
             signal
           );
           assertCurrent();
-          resourceErrors.delete(key);
+          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();
@@ -838,6 +925,8 @@ function createParameterRuntime(options) {
         }
       }
     };
+    imageLoads.set(ctx, loaded);
+    return ctx;
   }
   function enqueue(work) {
     const signal = controller.signal;
@@ -860,6 +949,7 @@ function createParameterRuntime(options) {
         publish();
       }
     });
+    return queue;
   }
   function remember(kind, request) {
     const key = `${kind}:${request.draftRevision}`;
@@ -915,15 +1005,11 @@ function createParameterRuntime(options) {
     } else status = reload ? "requires-reload" : pending ? "pending-commit" : "applying";
     publish();
   }
-  async function applyTarget(documents, rev, commit, signal, retryResources = /* @__PURE__ */ new Set()) {
-    if (status === "error" && !recoverable) 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;
-      const resourceKey = fingerprint([field.documentId, field.path]);
-      if (resourceErrors.has(resourceKey) && !retryResources.has(resourceKey)) 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 } : {
@@ -934,13 +1020,29 @@ 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) => 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))
+      (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();
@@ -953,6 +1055,7 @@ 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]));
@@ -962,6 +1065,18 @@ function createParameterRuntime(options) {
       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;
     }
@@ -989,6 +1104,10 @@ 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();
@@ -1016,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) => {
@@ -1054,6 +1175,7 @@ function createParameterRuntime(options) {
             capabilityListeners.forEach((fn) => fn(capabilities()));
             await created.afterRender(ctx);
             ctx.assertCurrent();
+            commitImages(ctx);
             installed = clone(nextDocuments);
             if (resourceErrors.size) installedRevision = -1;
             error = void 0;
@@ -1099,11 +1221,222 @@ 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);
       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));
+      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) {
@@ -1143,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;
     }
@@ -1249,7 +1589,7 @@ function connectPreviewRuntime(options) {
       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)
+      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") {
@@ -1260,7 +1600,12 @@ function connectPreviewRuntime(options) {
       if (response.status !== "ready")
         throw new ProtocolError("INVALID", "Invalid image resource response");
       assertImageResourceData(response);
-      return decodeImage(response.dataUrl, signal);
+      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 = [
@@ -1281,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);

package/templates/preview-runtime/v1/types/adapters.d.ts

@@ -24,5 +24,8 @@ export interface RuntimeOptions<C> {
         install(config: C): unknown;
     };
     createGame(context: ApplyContext<C>): Promise<GameAdapter<C>>;
-    loadImage?(request: ImageResourceRequest, signal: AbortSignal): Promise<HTMLImageElement>;
+    loadImage?(request: ImageResourceRequest, signal: AbortSignal): Promise<HTMLImageElement | {
+        image: HTMLImageElement;
+        contentHash?: string;
+    }>;
 }

package/templates/preview-runtime/v1/types/preview.d.ts

@@ -13,6 +13,7 @@ export declare function connectPreviewRuntime<C>(options: RuntimeOptions<C> & {
         hello(value: unknown): import("./protocol.js").Capabilities;
         snapshot(value: unknown): import("./protocol.js").Receipt;
         patch(value: unknown): import("./protocol.js").Receipt;
+        refreshImages(value: unknown): import("./protocol.js").ImageRefreshReceipt;
         restart(value: unknown): import("./protocol.js").Receipt;
         status(value: unknown): import("./protocol.js").ApplicationResult;
         subscribe(fn: (result: import("./protocol.js").ApplicationResult) => void): () => boolean;

package/templates/preview-runtime/v1/types/protocol.d.ts

@@ -36,6 +36,8 @@ export interface Capabilities extends Identity {
     stage: 'bootstrap-ready' | 'game-ready';
     canAcceptSnapshot: boolean;
     fields: FieldCapability[];
+    canRefreshImages?: true;
+    canReportMissingImages?: true;
 }
 export type Operation = {
     op: 'set';
@@ -61,6 +63,20 @@ export interface Receipt {
     accepted: true;
     receivedRevision: number;
 }
+export type ImageRefreshTarget = {
+    documentId: string;
+    path: string[];
+    /** Null reports a confirmed missing file; it does not clear the configured image. */
+    contentHash: string | null;
+};
+export interface ImageRefreshRequest extends Identity {
+    draftRevision: number;
+    resourceSequence: number;
+    images: ImageRefreshTarget[];
+}
+export interface ImageRefreshReceipt extends Receipt {
+    resourceSequence: number;
+}
 export interface GroupResult {
     groupId: string;
     appliedRevision: number;
@@ -86,6 +102,8 @@ export interface ImageResourceRequest extends Identity {
     documentId: string;
     path: string[];
     value: string;
+    resourceSequence?: number;
+    expectedContentHash?: string;
 }
 export type ImageResourceData = {
     mimeType: string;
@@ -124,6 +142,7 @@ export declare function sameIdentity(a: Identity, b: unknown): b is Identity;
 export declare function assertBinding(expected: SessionBinding, actual: Hello): void;
 export declare function assertDocuments(value: unknown): asserts value is RawDocuments;
 export declare function assertImageResourceRequest(value: unknown): asserts value is ImageResourceRequest;
+export declare function assertImageRefresh(value: unknown): asserts value is ImageRefreshRequest;
 export declare function assertImageResourceData(value: unknown): asserts value is ImageResourceData;
 export declare function assertSnapshot(value: unknown): asserts value is SnapshotRequest;
 export declare function assertPatch(value: unknown): asserts value is PatchRequest;

package/templates/preview-runtime/v1/types/runtime.d.ts

@@ -1,9 +1,10 @@
 import type { RuntimeOptions } from './adapters.js';
-import type { ApplicationResult, Capabilities, Receipt } from './protocol.js';
+import type { ApplicationResult, Capabilities, ImageRefreshReceipt, Receipt } from './protocol.js';
 export declare function createParameterRuntime<C>(options: RuntimeOptions<C>): {
     hello(value: unknown): Capabilities;
     snapshot(value: unknown): Receipt;
     patch(value: unknown): Receipt;
+    refreshImages(value: unknown): ImageRefreshReceipt;
     restart(value: unknown): Receipt;
     status(value: unknown): ApplicationResult;
     subscribe(fn: (result: ApplicationResult) => void): () => boolean;