pixelkiln 0.62.0 → 0.63.0

package/dist/index.js

@@ -193,6 +193,14 @@ var CharacterAnimationSchema = z.object({
   template: z.string().min(1).optional(),
   /** Direction to animate. */
   direction: CharacterDirectionSchema.default("south"),
+  /**
+   * Shorthand for one loop in several directions, instead of `direction`.
+   * Expanded when the manifest loads into one loop per named direction
+   * (`<id>.<direction>`) plus a mirror for each direction whose flip is
+   * not named, exactly as if each had been written out. See
+   * `src/loop-directions.ts`.
+   */
+  directions: z.array(CharacterDirectionSchema).min(1).optional(),
   /** Frames to generate without a template (v3). Even, 4 to 16. */
   frames: z.number().int().min(4).max(16).optional(),
   /** Playback rate recorded with the frames; PixelLab does not store one. */
@@ -221,6 +229,13 @@ var CharacterAnimationSchema = z.object({
   /** v3 text loops only: let PixelLab expand the action into a fuller motion description first. */
   enhancePrompt: z.boolean().optional()
 }).strict().superRefine((animation, context) => {
+  if (animation.directions !== void 0) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "directions is expanded when the manifest loads; validate the loaded manifest, not the raw file",
+      path: ["directions"]
+    });
+  }
   if (animation.frames !== void 0 && animation.frames % 2 !== 0) {
     context.addIssue({ code: z.ZodIssueCode.custom, message: "frames must be even", path: ["frames"] });
   }
@@ -6992,6 +7007,91 @@ import { readFile as readFile3 } from "fs/promises";
 import { existsSync as existsSync4 } from "fs";
 import path5 from "path";
 
+// src/loop-directions.ts
+var SINGLE_OUTPUT_FIELDS = ["file", "cell", "remoteId", "source", "sourceByStyle", "outputRole"];
+var MIRROR_FIELDS = ["category", "tags", "styles"];
+function loopDirectionId(shorthandId, direction) {
+  return `${shorthandId}.${direction}`;
+}
+function expandLoopDirections(raw) {
+  const families = {};
+  const issues = [];
+  if (!isObject2(raw) || !isObject2(raw.assets)) return { raw, families, issues };
+  const assets = raw.assets;
+  if (!Object.values(assets).some((asset) => isObject2(asset) && isObject2(asset.animation) && "directions" in asset.animation)) {
+    return { raw, families, issues };
+  }
+  const expanded = {};
+  const claimed = new Set(Object.keys(assets));
+  for (const [id, asset] of Object.entries(assets)) {
+    if (!isObject2(asset) || !isObject2(asset.animation) || !("directions" in asset.animation)) {
+      expanded[id] = asset;
+      continue;
+    }
+    const where = `assets.${id}.animation.directions`;
+    const { directions: rawDirections, ...animation } = asset.animation;
+    const parsed = CharacterDirectionSchema.array().min(1).safeParse(rawDirections);
+    if (!parsed.success) {
+      issues.push(`${where}: expected a non-empty list of directions (${CharacterDirectionSchema.options.join(", ")})`);
+      continue;
+    }
+    const directions = parsed.data;
+    const duplicate = directions.find((direction, index) => directions.indexOf(direction) !== index);
+    if (duplicate) {
+      issues.push(`${where}: "${duplicate}" is listed twice`);
+      continue;
+    }
+    if ("direction" in animation) {
+      issues.push(`assets.${id}.animation: direction and directions are mutually exclusive; directions names every loop to make`);
+      continue;
+    }
+    const single = SINGLE_OUTPUT_FIELDS.filter((field) => field in asset);
+    if (single.length) {
+      issues.push(
+        `assets.${id}: ${single.join(", ")} name${single.length === 1 ? "s" : ""} one output, but directions makes ${directions.length} loops; declare the loops explicitly to set ${single.length === 1 ? "it" : "them"} per direction`
+      );
+      continue;
+    }
+    const loops = directions.map((direction) => ({ id: loopDirectionId(id, direction), direction }));
+    const named = new Set(directions);
+    const mirrors = [];
+    for (const { id: loopId, direction } of loops) {
+      const flipped = MIRRORED_DIRECTION[direction];
+      if (flipped === direction || named.has(flipped)) continue;
+      named.add(flipped);
+      mirrors.push({ id: loopDirectionId(id, flipped), of: loopId });
+    }
+    const ids = [...loops.map((loop) => loop.id), ...mirrors.map((mirror) => mirror.id)];
+    const collision = ids.find((expandedId) => claimed.has(expandedId));
+    if (collision) {
+      issues.push(`${where}: expands to "${collision}", which is already declared`);
+      continue;
+    }
+    for (const expandedId of ids) claimed.add(expandedId);
+    for (const loop of loops) {
+      expanded[loop.id] = { ...asset, animation: { ...animation, direction: loop.direction } };
+    }
+    for (const mirror of mirrors) {
+      const inherited = {};
+      for (const field of MIRROR_FIELDS) if (field in asset) inherited[field] = asset[field];
+      expanded[mirror.id] = { mirror: mirror.of, ...inherited };
+    }
+    families[id] = ids;
+  }
+  return { raw: { ...raw, assets: expanded }, families, issues };
+}
+function expandAssetFilter(ids, families) {
+  if (!families) return [...ids];
+  return [...new Set(ids.flatMap((id) => families[id] ?? [id]))];
+}
+function loopShorthandOf(assetId, families) {
+  if (!families) return void 0;
+  return Object.keys(families).find((id) => families[id].includes(assetId));
+}
+function isObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // src/outputs.ts
 import { existsSync as existsSync3 } from "fs";
 import path4 from "path";
@@ -7310,7 +7410,12 @@ function frameSetFps(entry) {
 async function loadManifest(manifestPath) {
   const abs = path5.resolve(manifestPath);
   if (!existsSync4(abs)) throw new ProjectError(`No manifest at ${abs}`);
-  const input = ManifestInputSchema.safeParse(JSON.parse(await readFile3(abs, "utf8")));
+  const expansion = expandLoopDirections(JSON.parse(await readFile3(abs, "utf8")));
+  if (expansion.issues.length) {
+    throw new ProjectError(`Manifest at ${abs} is invalid:
+${expansion.issues.map((i) => `  ${i}`).join("\n")}`);
+  }
+  const input = ManifestInputSchema.safeParse(expansion.raw);
   if (!input.success) {
     const issues = formatManifestIssues(input.error.issues);
     throw new ProjectError(`Manifest at ${abs} is invalid:
@@ -7395,7 +7500,8 @@ ${issues}`);
     throw new ProjectError(`Manifest at ${abs} is invalid:
 ${unknownReferences.map((i) => `  ${i}`).join("\n")}`);
   }
-  return { manifest: parsed.data, root: path5.dirname(abs), path: abs };
+  const loopFamilies = Object.keys(expansion.families).length ? { loopFamilies: expansion.families } : {};
+  return { manifest: parsed.data, root: path5.dirname(abs), path: abs, ...loopFamilies };
 }
 function parentAssetId(asset) {
   return asset?.revision?.from ?? asset?.state?.of ?? asset?.animation?.of;
@@ -7479,12 +7585,13 @@ async function resolveSpecs(loaded, filter) {
       );
     }
   }
-  for (const unknownAsset of filter?.assets ?? []) {
+  const assetFilter = expandAssetFilter(filter?.assets ?? [], loaded.loopFamilies);
+  for (const unknownAsset of assetFilter) {
     if (!manifest.assets[unknownAsset]) {
       throw new UsageError(`Unknown asset "${unknownAsset}".`);
     }
   }
-  const requestedAssetIds = new Set(filter?.assets?.length ? filter.assets : Object.keys(manifest.assets));
+  const requestedAssetIds = new Set(assetFilter.length ? assetFilter : Object.keys(manifest.assets));
   const resolutionAssetIds = new Set(requestedAssetIds);
   for (const assetId of [...requestedAssetIds]) {
     let current = parentAssetId(manifest.assets[assetId]);
@@ -14208,11 +14315,21 @@ function assetStyles(raw, asset) {
   const own = Array.isArray(asset.styles) ? asset.styles : [];
   return own.length ? own : Object.keys(raw.styles ?? {});
 }
+function declaredAssets(raw) {
+  const expanded = expandLoopDirections(raw).raw;
+  return new Set(Object.keys(expanded.assets ?? {}));
+}
+function undeclaredAsset(raw, assetId) {
+  const shorthand = loopShorthandOf(assetId, expandLoopDirections(raw).families);
+  return new ManifestEditError(
+    shorthand ? `asset "${assetId}" is expanded from "${shorthand}"'s animation.directions; edit "${shorthand}" (it applies to every direction), or write this direction out as its own asset to change it alone` : `asset "${assetId}" is not declared by the manifest`
+  );
+}
 function applyEdit(raw, edit) {
   raw.assets ??= {};
   if (edit.action === "set-source" || edit.action === "clear-source") {
     const asset2 = Object.hasOwn(raw.assets, edit.assetId) ? raw.assets[edit.assetId] : void 0;
-    if (!asset2) throw new ManifestEditError(`asset "${edit.assetId}" is not declared by the manifest`);
+    if (!asset2) throw undeclaredAsset(raw, edit.assetId);
     if (!raw.styles || !Object.hasOwn(raw.styles, edit.styleId)) {
       throw new ManifestEditError(`unknown style "${edit.styleId}"`);
     }
@@ -14264,7 +14381,7 @@ function applyEdit(raw, edit) {
     return;
   }
   if (edit.action === "add-asset") {
-    if (Object.hasOwn(raw.assets, edit.assetId)) {
+    if (declaredAssets(raw).has(edit.assetId)) {
       throw new ManifestEditError(`asset "${edit.assetId}" already exists`);
     }
     const { styles, tags, ...rest } = edit.asset;
@@ -14278,20 +14395,20 @@ function applyEdit(raw, edit) {
       }
       asset2.styles = styles;
     }
-    if (edit.asset.revision && !Object.hasOwn(raw.assets, edit.asset.revision.from)) {
+    if (edit.asset.revision && !declaredAssets(raw).has(edit.asset.revision.from)) {
       throw new ManifestEditError(`revision parent "${edit.asset.revision.from}" is not declared by the manifest`);
     }
-    if (edit.asset.state && !Object.hasOwn(raw.assets, edit.asset.state.of)) {
+    if (edit.asset.state && !declaredAssets(raw).has(edit.asset.state.of)) {
       throw new ManifestEditError(`state parent "${edit.asset.state.of}" is not declared by the manifest`);
     }
-    if (edit.asset.animation && !Object.hasOwn(raw.assets, edit.asset.animation.of)) {
+    if (edit.asset.animation && !declaredAssets(raw).has(edit.asset.animation.of)) {
       throw new ManifestEditError(`animation parent "${edit.asset.animation.of}" is not declared by the manifest`);
     }
     raw.assets[edit.assetId] = asset2;
     return;
   }
   const asset = Object.hasOwn(raw.assets, edit.assetId) ? raw.assets[edit.assetId] : void 0;
-  if (!asset) throw new ManifestEditError(`asset "${edit.assetId}" is not declared by the manifest`);
+  if (!asset) throw undeclaredAsset(raw, edit.assetId);
   const { patch } = edit;
   if (patch.prompt !== void 0) asset.prompt = patch.prompt;
   if (patch.promptForStyle) {
@@ -14905,6 +15022,7 @@ async function describeQuality(media, root, inspection) {
 }
 async function buildGallerySnapshot(opts) {
   const { loaded, specs, lock } = opts;
+  const filter = opts.filter?.assets?.length ? { ...opts.filter, assets: expandAssetFilter(opts.filter.assets, loaded.loopFamilies) } : opts.filter;
   const root = loaded.root;
   const media = /* @__PURE__ */ new Map();
   const plan = await buildPlan(specs, lock);
@@ -15049,7 +15167,7 @@ async function buildGallerySnapshot(opts) {
   for (const [key, entry] of Object.entries(lock.entries)) {
     if (shown.has(key)) continue;
     if (isDeclared(loaded, entry.styleId, entry.assetId)) continue;
-    if (!matchesFilter(opts.filter, entry.styleId, entry.assetId)) continue;
+    if (!matchesFilter(filter, entry.styleId, entry.assetId)) continue;
     const outputs = await Promise.all(
       entry.outputs.map(
         (output) => describeOutput(media, root, resolveOutputPath(output.path, root), output)
@@ -15215,7 +15333,7 @@ async function buildWorkspaceGallerySnapshot(opts) {
     try {
       const loaded = await loadManifest(manifestPath);
       const styleFilter = filter.styles.filter((id) => loaded.manifest.styles[id]);
-      const assetFilter = filter.assets.filter((id) => loaded.manifest.assets[id]);
+      const assetFilter = expandAssetFilter(filter.assets, loaded.loopFamilies).filter((id) => loaded.manifest.assets[id]);
       const excluded = filter.styles.length > 0 && styleFilter.length === 0 || filter.assets.length > 0 && assetFilter.length === 0;
       const lock = await loadLock(lockPath);
       let projectItems = [];