pixelkiln 0.85.0 → 0.86.1

package/PROVIDERS.md

@@ -114,13 +114,13 @@ only the part that fits its existing still-image pipeline.
 
 | Decision | Scenario through PixelKiln |
 |---|---|
-| Best fit today | A controlled one-asset spike using a hosted model or project LoRA with a hard CU ceiling |
-| PixelKiln generator | `map` stills |
+| Best fit today | Large or illustrative art rendered big then reduced (render, Pixelate, cut out, refine), image-to-image edits of existing art, and a chain of models across styles, each with a hard CU ceiling. Poor for small native-size sprites. |
+| PixelKiln generator | `map` stills, with `styleImages` and `image-to-image` revisions as reference uploads, and `revision.fromStyle` to chain styles |
 | Output | One to four PNG candidates, 16–4096px; each model has its own bounds |
 | Cost model | Manifest `maxComputeUnits`, command budget, then free authoritative preflight before each paid request |
 | Recovery | Durable job and asset IDs refresh temporary signed original-file URLs |
 | Account lifecycle | Read-only connectivity check; no balance, list, adopt, salvage, tag, or purge yet |
-| Confidence | BFL Flux 2 Dev live-tested through quote, billing, single/two-output jobs, human selection, PNG download, and provider-backed restore; other model schemas remain unverified |
+| Confidence | BFL Flux 2 Dev live-tested through quote, billing, single/two-output jobs, human selection, PNG download, and provider-backed restore. Ten generation models, six tool models, reference-image edits, a three-style chain, and a game's landmarks and cover have each been run once; see the [Scenario page](./docs/SCENARIO.md). Other model schemas remain unverified. |
 
 Scenario model schemas differ. The current adapter sends prompt, width, height,
 output count, optional seed, and explicitly declared JSON parameters. Verify
@@ -134,8 +134,8 @@ background. That distinction matters more than raw canvas size.
 
 | Asset type | PixelLab | Retro Diffusion | ComfyUI | Scenario |
 |---|---|---|---|---|
-| Isolated house, building, mountain, or landmark | Start with `map`: arbitrary dimensions up to 400×400 and a measured one-generation cost. Live benchmark outputs had opaque backgrounds, so plan for cleanup. Use `1dir` only when references or candidate variety justify 20–40 generations and a square canvas. | Start with `rd_plus__topdown_asset`, `rd_plus__isometric_asset`, or `rd_tile__scene_object`, depending on perspective. `rd_tile__scene_object` is intended for 64–384px objects placed on tile maps. | Choose a checkpoint or LoRA trained for the intended perspective, then keep background removal or segmentation in the workflow. For the tested Pixel Art XL stack, target 48–128px native components even though the adapter accepts larger working canvases. | The live BFL smoke produced a readable 512px keep, but it was opaque and used 19,619 colors. Use that profile for concepts or refinement input, not a finished limited-palette asset. A project-specific model may improve consistency but needs its own smoke. |
-| Full scenic background | Use `pixflux` with `noBackground: false` when an exact palette matters, or `map` for a simple scene; both top out at 400×400. `imagePro` reaches 792 wide or 688 tall for a flat 40 generations. | `rd_plus__environment` targets one-point-perspective scenes; `rd_plus__topdown_map` targets 3/4 top-down maps. These styles support up to 384×384. | Use composition controls only to establish the scene. Recover and review native components, then compose them at 1× with one grid and palette. A large model canvas is not a large native pixel-art canvas. | The BFL profile accepts canvases up to 2048px, but no Scenario scenic brief has passed the shared benchmark. Treat that as model-canvas capacity, not native pixel resolution. Start with one 512px concept before raising size or steps. |
+| Isolated house, building, mountain, or landmark | Start with `map`: arbitrary dimensions up to 400×400 and a measured one-generation cost. Live benchmark outputs had opaque backgrounds, so plan for cleanup. Use `1dir` only when references or candidate variety justify 20–40 generations and a square canvas. | Start with `rd_plus__topdown_asset`, `rd_plus__isometric_asset`, or `rd_tile__scene_object`, depending on perspective. `rd_tile__scene_object` is intended for 64–384px objects placed on tile maps. | Choose a checkpoint or LoRA trained for the intended perspective, then keep background removal or segmentation in the workflow. For the tested Pixel Art XL stack, target 48–128px native components even though the adapter accepts larger working canvases. | Raw model output is opaque and anti-aliased (the BFL smoke keep used 19,619 colors), but a chain of render at four times the size, Pixelate to the target grid, Birefnet, and `refine` took a 960 px render of an alpine lodge to a 240×208 native grid at high confidence with 63 colors, for 18 CU (a 1 CU render can be nearly as good). Details and the Pixelate grid caveat are in [Set up Scenario](./docs/SCENARIO.md#large-and-illustrative-art-render-big-pixelate-refine). One sample per subject. |
+| Full scenic background | Use `pixflux` with `noBackground: false` when an exact palette matters, or `map` for a simple scene; both top out at 400×400. `imagePro` reaches 792 wide or 688 tall for a flat 40 generations. | `rd_plus__environment` targets one-point-perspective scenes; `rd_plus__topdown_map` targets 3/4 top-down maps. These styles support up to 384×384. | Use composition controls only to establish the scene. Recover and review native components, then compose them at 1× with one grid and palette. A large model canvas is not a large native pixel-art canvas. | GPT Image 2 at four times the target size, then Pixelate, turned a course-cover brief into a convincing pixel scene with 31 colors and legible title text. It has not been put through the shared benchmark. A large model canvas is not native pixel resolution: pixelate to the grid you need and check it with `refine`. |
 | Style consistency across a set | `1dir` accepts a style reference and returns size-dependent candidates, but it is more expensive and capped at the square-object range. | RD Pro accepts up to nine references and has stronger prompt following, but its common styles top out at 256×256 and cost $0.18 per image. Environment-specific RD Plus styles trade references for a larger 384px canvas. | LoRAs, reference adapters, ControlNet, and shared latent settings can live in the committed workflow. Reproducibility also depends on external model and custom-node versions. | Scenario's project models and LoRAs are the main reason to use it for a set. PixelKiln can pin the model ID and parameters, but its first live run covers only the public BFL profile. |
 | Very large final scene | Generate reusable objects, terrain, and background layers separately; assemble them deterministically and integer-upscale the result. | Use the same layered approach. The API has a 512px overall ceiling, but the useful environment and scene-object styles currently cap at 384px. | The graph can tile, upscale, or composite beyond hosted-provider limits, but memory and seam quality become workflow concerns. Prefer reusable layers unless the scene truly needs one render. | Scenario can request a larger raster from a compatible model, but the same rule applies: generate reusable layers at their useful native detail, compose at 1×, and integer-upscale only the final scene. |
 

package/dist/cli.js

@@ -777,6 +777,7 @@ function specHash(spec, styleImageHashes, providerOptionIdentity = spec.provider
       revision: spec.revision ? {
         mode: spec.revision.mode,
         from: spec.revision.sourceAssetId,
+        fromStyle: spec.revision.sourceStyleId,
         sourceSha256: spec.revision.sourceSha256,
         maskSha256: spec.revision.maskSha256,
         strength: spec.revision.strength,
@@ -1126,8 +1127,16 @@ var RevisionDitheringSchema = z.enum(["none", "2x2", "4x4", "8x8"]);
 var RevisionSchema = z.object({
   /** What kind of controlled change the provider workflow performs. */
   mode: RevisionModeSchema,
-  /** Parent asset id in the same style. */
+  /** Parent asset id. It lives in this asset's own style unless `fromStyle` names another. */
   from: z.string().min(1),
+  /**
+   * The style the parent lives in, when it is not this asset's own. The
+   * parent is generated by that style's provider and model, and this
+   * revision starts from its output file, so a chain (generate with one
+   * model, clean up with another) is declared instead of restated by hand.
+   * Styles may depend on one another but not in a cycle.
+   */
+  fromStyle: z.string().min(1).optional(),
   /** Manifest-relative black/white PNG. Required only for masked inpainting. */
   mask: z.string().min(1).optional(),
   /** Provider-neutral edit strength. The active adapter must bind it explicitly. */
@@ -1988,6 +1997,7 @@ var LockEntrySchema = z.object({
   revision: z.object({
     mode: RevisionModeSchema,
     sourceAssetId: z.string().min(1),
+    sourceStyleId: z.string().min(1).optional(),
     sourceSha256: z.string().regex(/^[0-9a-f]{64}$/),
     maskSha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
     strength: z.number().min(0).max(1).optional(),
@@ -4405,7 +4415,7 @@ async function inspectRevision(spec, lock, seen) {
   if (!dependency.ready) {
     return {
       ready: false,
-      reason: `revision source ${spec.styleId}/${revision.sourceAssetId} is not ready: ${dependency.reason}`
+      reason: `revision source ${revision.sourceStyleId ?? spec.styleId}/${revision.sourceAssetId} is not ready: ${dependency.reason}`
     };
   }
   if (revision.sourceMembers) {
@@ -10836,13 +10846,24 @@ ${issues}`);
       }
     }
     if (asset.revision) {
-      if (!parsed.data.assets[asset.revision.from]) {
+      const parent = parsed.data.assets[asset.revision.from];
+      if (!parent) {
         unknownReferences.push(
           `assets.${assetId}.revision.from: unknown asset "${asset.revision.from}"`
         );
       } else if (asset.revision.from === assetId) {
         unknownReferences.push(`assets.${assetId}.revision.from: an asset cannot revise itself`);
       }
+      const fromStyle = asset.revision.fromStyle;
+      if (fromStyle) {
+        if (!styleIds.has(fromStyle)) {
+          unknownReferences.push(`assets.${assetId}.revision.fromStyle: unknown style "${fromStyle}"`);
+        } else if (parent && parent.styles.length && !parent.styles.includes(fromStyle)) {
+          unknownReferences.push(
+            `assets.${assetId}.revision.fromStyle: "${asset.revision.from}" is not in style "${fromStyle}"`
+          );
+        }
+      }
     }
     for (const shape of ["state", "animation"]) {
       const of = asset[shape]?.of;
@@ -10958,7 +10979,7 @@ async function resolveSpecs(loaded, filter) {
     return provider;
   };
   const specs = [];
-  const styleIds = Object.keys(manifest.styles).filter(
+  const requestedStyleIds = Object.keys(manifest.styles).filter(
     (id) => !filter?.styles?.length || filter.styles.includes(id)
   );
   for (const unknownStyle of filter?.styles ?? []) {
@@ -10983,6 +11004,39 @@ async function resolveSpecs(loaded, filter) {
       current = parentAssetId(manifest.assets[current]);
     }
   }
+  const styleDependencies = /* @__PURE__ */ new Map();
+  for (const styleId of Object.keys(manifest.styles)) {
+    const needed = /* @__PURE__ */ new Set();
+    for (const assetId of resolutionAssetIds) {
+      const asset = manifest.assets[assetId];
+      if (asset?.styles.length && !asset.styles.includes(styleId)) continue;
+      const fromStyle = asset?.revision?.fromStyle;
+      if (fromStyle && fromStyle !== styleId) needed.add(fromStyle);
+    }
+    styleDependencies.set(styleId, needed);
+  }
+  const styleIds = [];
+  const emitStyles = new Set(requestedStyleIds);
+  {
+    const placed = /* @__PURE__ */ new Set();
+    const visiting = [];
+    const place = (styleId) => {
+      if (placed.has(styleId)) return;
+      const cycleStart = visiting.indexOf(styleId);
+      if (cycleStart >= 0) {
+        throw new Error(
+          `Styles revise each other in a cycle: ${[...visiting.slice(cycleStart), styleId].join(" -> ")}. revision.fromStyle must form a chain, not a loop.`
+        );
+      }
+      visiting.push(styleId);
+      for (const dependency of styleDependencies.get(styleId) ?? []) place(dependency);
+      visiting.pop();
+      placed.add(styleId);
+      styleIds.push(styleId);
+    };
+    for (const styleId of requestedStyleIds) place(styleId);
+  }
+  const styleFinalizers = /* @__PURE__ */ new Map();
   const styleImageCache = /* @__PURE__ */ new Map();
   async function loadStyleImage(rel, what = "Style image") {
     const abs = path14.resolve(root, rel);
@@ -11370,7 +11424,8 @@ async function resolveSpecs(loaded, filter) {
             `Provider "${activeProvider.id}" does not support ${asset.revision.mode} revisions`
           );
         }
-        const sourceSpec = await finalize(asset.revision.from);
+        const sourceStyleId = asset.revision.fromStyle && asset.revision.fromStyle !== styleId ? asset.revision.fromStyle : void 0;
+        const sourceSpec = sourceStyleId ? await styleFinalizers.get(sourceStyleId)(asset.revision.from) : await finalize(asset.revision.from);
         const sourceStem = sourceSpec.quality?.outFile ?? (sourceSpec.source ? path14.resolve(root, sourceSpec.source) : sourceSpec.outFile);
         const sourceMembers = await revisionSourceMembers(sourceStem, `revision source ${asset.revision.from}`);
         const sourceFile = sourceMembers?.[0]?.file ?? sourceStem;
@@ -11392,6 +11447,7 @@ async function resolveSpecs(loaded, filter) {
         resolved.revision = {
           mode: asset.revision.mode,
           sourceAssetId: asset.revision.from,
+          ...sourceStyleId ? { sourceStyleId } : {},
           sourceFile,
           sourceSha256: sourceImage?.hash ?? null,
           sourceWidth: sourceImage?.width ?? null,
@@ -11513,6 +11569,8 @@ async function resolveSpecs(loaded, filter) {
       finalized.add(assetId);
       return resolved;
     };
+    styleFinalizers.set(styleId, finalize);
+    if (!emitStyles.has(styleId)) continue;
     for (const assetId of Object.keys(manifest.assets)) {
       if (!requestedAssetIds.has(assetId) || !styleSpecs.has(assetId)) continue;
       specs.push(await finalize(assetId));
@@ -15913,7 +15971,7 @@ async function buildGallerySnapshot(opts) {
       recordedSpecHash: entry?.specHash ?? null,
       currentSpecHash: spec.specHash,
       revision: entry?.revision ?? null,
-      revisionParentKey: spec.revision ? lockKey(spec.styleId, spec.revision.sourceAssetId) : entry?.revision ? lockKey(spec.styleId, entry.revision.sourceAssetId) : null,
+      revisionParentKey: spec.revision ? lockKey(spec.revision.sourceStyleId ?? spec.styleId, spec.revision.sourceAssetId) : entry?.revision ? lockKey(entry.revision.sourceStyleId ?? spec.styleId, entry.revision.sourceAssetId) : null,
       mirrorOfKey: spec.mirror ? lockKey(spec.styleId, spec.mirror.sourceAssetId) : entry?.mirror ? lockKey(spec.styleId, entry.mirror.sourceAssetId) : null,
       skeleton: spec.revision?.mode === "animate-skeleton" && spec.revision.keypointsFile ? {
         keypointsFile: portableOutputPath(spec.revision.keypointsFile, root),
@@ -15983,7 +16041,7 @@ async function buildGallerySnapshot(opts) {
       recordedSpecHash: entry.specHash,
       currentSpecHash: null,
       revision: entry.revision,
-      revisionParentKey: entry.revision ? lockKey(entry.styleId, entry.revision.sourceAssetId) : null,
+      revisionParentKey: entry.revision ? lockKey(entry.revision.sourceStyleId ?? entry.styleId, entry.revision.sourceAssetId) : null,
       mirrorOfKey: entry.mirror ? lockKey(entry.styleId, entry.mirror.sourceAssetId) : null,
       skeleton: null,
       character: describeCharacter(void 0, entry),
@@ -16919,6 +16977,7 @@ async function submit(provider, loaded, items, lock, lockPath, opts = {}) {
       revision: spec.revision ? {
         mode: spec.revision.mode,
         sourceAssetId: spec.revision.sourceAssetId,
+        ...spec.revision.sourceStyleId ? { sourceStyleId: spec.revision.sourceStyleId } : {},
         sourceSha256: spec.revision.sourceSha256,
         ...spec.revision.maskSha256 ? { maskSha256: spec.revision.maskSha256 } : {},
         ...spec.revision.strength == null ? {} : { strength: spec.revision.strength },