@playcraft/cli 0.1.55-beta → 0.1.56-beta

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

@@ -197,6 +197,7 @@ var BridgeMethods = {
     restart: "runtime.parameters.restart",
     status: "runtime.parameters.status",
     dispose: "runtime.parameters.dispose",
+    asset: "runtime.parameters.asset",
     capabilities: "runtime.parameters.capabilities",
     result: "runtime.parameters.result",
     resyncRequired: "runtime.parameters.resync-required"
@@ -220,7 +221,8 @@ var BRIDGE_RPC_NAMES = [
   BridgeMethods.runtimeParameters.patch,
   BridgeMethods.runtimeParameters.restart,
   BridgeMethods.runtimeParameters.status,
-  BridgeMethods.runtimeParameters.dispose
+  BridgeMethods.runtimeParameters.dispose,
+  BridgeMethods.runtimeParameters.asset
 ];
 
 // ../iframe-bridge/src/configs/perspective.ts
@@ -415,7 +417,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 +526,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 +637,22 @@ var identityKeys = [
   "configContractVersion",
   "locale"
 ];
+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,6 +730,8 @@ 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();
@@ -739,7 +772,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;
@@ -748,16 +783,59 @@ function createParameterRuntime(options) {
     listeners.forEach((fn) => fn(value));
   }
   function context(config, beforeConfig, draftRevision, fields, signal) {
+    const images = /* @__PURE__ */ new Map();
+    const assertCurrent = () => {
+      signal.throwIfAborted();
+      if (signal !== controller.signal || disposed)
+        throw new ProtocolError("STALE", "Application task expired");
+      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();
+      }
+    };
     return {
       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]);
+        images.set(key, { field: registered, value });
+        assertCurrent();
+        try {
+          const image = await options.loadImage(
+            {
+              ...requireIdentity(),
+              draftRevision,
+              documentId: registered.documentId,
+              path: clone(registered.path),
+              value
+            },
+            signal
+          );
+          assertCurrent();
+          resourceErrors.delete(key);
+          return image;
+        } catch (failure) {
+          assertCurrent();
+          if (failure instanceof ResourceLoadError)
+            resourceErrors.set(key, {
+              documentId: registered.documentId,
+              path: clone(registered.path),
+              error: failure.message
+            });
+          throw failure;
+        }
       }
     };
   }
@@ -769,10 +847,16 @@ 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();
       }
     });
@@ -795,12 +879,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 +915,15 @@ function createParameterRuntime(options) {
     } else status = reload ? "requires-reload" : pending ? "pending-commit" : "applying";
     publish();
   }
-  async function applyTarget(documents, rev, commit, signal) {
-    if (status === "error") return;
+  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");
     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;
       const value = readPath(documents[field.documentId], field.path);
       operations.push(
         value === void 0 ? { op: "remove", documentId: field.documentId, path: field.path } : {
@@ -838,13 +938,14 @@ function createParameterRuntime(options) {
     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) => 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);
     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 +953,16 @@ function createParameterRuntime(options) {
       ctx.assertCurrent();
       await adapter.afterRender(ctx);
       ctx.assertCurrent();
+      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;
+      }
       throw e;
     }
   }
@@ -888,6 +995,8 @@ function createParameterRuntime(options) {
       stage = "bootstrap-ready";
       status = "idle";
       error = void 0;
+      recoverable = false;
+      resourceErrors.clear();
       resultSequence = 0;
       for (const group of groups.values()) {
         group.appliedRevision = -1;
@@ -915,44 +1024,56 @@ 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();
+            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 +1085,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"
@@ -979,12 +1100,15 @@ function createParameterRuntime(options) {
       options.resolve(documents);
       target = documents;
       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));
       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 +1117,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) {
@@ -1025,6 +1159,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 +1235,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 +1242,27 @@ 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)
+        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);
+      return decodeImage(response.dataUrl, signal);
+    }
+  });
   const off = [
     bridge.on(names.hello, (value) => runtime.hello(value)),
     bridge.on(names.snapshot, (value) => runtime.snapshot(value)),
@@ -1116,6 +1306,7 @@ function connectPreviewRuntime(options) {
   };
 }
 export {
+  ResourceLoadError,
   connectPreviewRuntime,
   readWorkspacePreviewContext
 };

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

@@ -1,4 +1,4 @@
-import type { FieldCapability, RawDocuments } from './protocol.js';
+import type { FieldCapability, ImageResourceRequest, RawDocuments } from './protocol.js';
 export interface ApplyContext<C> {
     beforeConfig: C;
     config: C;
@@ -6,6 +6,7 @@ export interface ApplyContext<C> {
     fields: FieldCapability[];
     signal: AbortSignal;
     assertCurrent(): void;
+    loadImage(field: FieldCapability, value: string): Promise<HTMLImageElement>;
 }
 /** All callbacks must check cancellation before late asynchronous side effects. */
 export interface GameAdapter<C> {
@@ -23,4 +24,5 @@ export interface RuntimeOptions<C> {
         install(config: C): unknown;
     };
     createGame(context: ApplyContext<C>): Promise<GameAdapter<C>>;
+    loadImage?(request: ImageResourceRequest, signal: AbortSignal): Promise<HTMLImageElement>;
 }

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

@@ -1,5 +1,6 @@
 import type { RuntimeOptions } from './adapters.js';
 import type { SessionBinding } from './protocol.js';
+export { ResourceLoadError } from './protocol.js';
 /** Reads only the platform's explicit context; a game receives no platform credentials. */
 export declare function readWorkspacePreviewContext(expectedContractVersion: string): {
     binding: SessionBinding;

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

@@ -30,6 +30,7 @@ export interface FieldCapability {
     effectivePath: string[];
     groupId: string;
     mode: ApplyMode;
+    resource?: 'image';
 }
 export interface Capabilities extends Identity {
     stage: 'bootstrap-ready' | 'game-ready';
@@ -73,6 +74,40 @@ export interface ApplicationResult extends Identity {
     status: 'idle' | 'applying' | 'applied' | 'pending-commit' | 'requires-reload' | 'error';
     groups: GroupResult[];
     error?: string;
+    recoverable?: true;
+    resourceErrors?: Array<{
+        documentId: string;
+        path: string[];
+        error: string;
+    }>;
+}
+export interface ImageResourceRequest extends Identity {
+    draftRevision: number;
+    documentId: string;
+    path: string[];
+    value: string;
+}
+export type ImageResourceData = {
+    mimeType: string;
+    dataUrl: string;
+    contentHash?: string;
+};
+export type ImageResourceResponse = ImageResourceRequest & (({
+    status: 'ready';
+} & ImageResourceData) | {
+    status: 'failed';
+    error: string;
+} | {
+    status: 'stale';
+});
+export declare const MAX_IMAGE_RESOURCE_BYTES: number;
+/** Loading failures retain the last rendered image and allow another parameter patch. */
+export declare class ResourceLoadError extends Error {
+    constructor(message: string);
+}
+/** A newer value replaced this resource while it was being prepared. */
+export declare class SupersededResourceError extends Error {
+    constructor();
 }
 export declare class ProtocolError extends Error {
     readonly code: string;
@@ -88,6 +123,8 @@ export declare function assertIdentity(value: unknown): asserts value is Identit
 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 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;
 export declare function applyOperations(documents: RawDocuments, operations: Operation[]): RawDocuments;