pixelkiln 0.19.0 → 0.20.1

package/PROVIDERS.md

@@ -85,7 +85,7 @@ prompt, size, batch, and optional seed inputs PixelKiln may replace.
 | PixelKiln generator | `map` stills and atomic `frames` sets |
 | Output | One PNG output node: 1–16 map candidates or 2–64 ordered still frames |
 | Revision input | `image-to-image`, `inpaint`, and user-authored `outpaint` graphs; hashed parent/mask uploads and source comparison are covered. The bundled img2img graph passed a three-strength live smoke but missed the requested winter treatment and lost alpha. |
-| Cost model | `0 free`; local compute and hosting are outside PixelKiln's estimate |
+| Cost model | No provider charge; local compute and hosting are outside PixelKiln's estimate |
 | Reproducibility | Workflow content is hashed; model files, custom-node versions, and runtime settings must still be managed outside PixelKiln |
 | Account lifecycle | Read-only connectivity check; no balance, remote object listing, tagging, or purge |
 | Confidence | Live map generation, four-candidate review, cache-only restore, and refinement on Apple MPS; deterministic coverage for frame submission, ordered review/fetch, shared-grid and palette gating, approval, and packing |

package/README.md

@@ -183,9 +183,10 @@ packaging layer.
 }
 ```
 
-Styles are namespaces. Adding a second style re-derives the same asset ids into
-a separate output directory and separate lock keys without clobbering the first
-set. Generator choice, reference-image bytes, dimensions, palette, seed, and
+Styles are namespaces. A variant can `extend` a base style while keeping its own
+output directory, so later parent fixes reach every child without copied config.
+Each style re-derives the same asset ids into separate lock keys. Generator
+choice, reference-image bytes, dimensions, palette, seed, and
 prompt settings participate in deterministic spec identity. A manifest may
 select another provider and pass namespaced `providerOptions`; see
 [Set up PixelLab](./docs/PIXELLAB.md),

package/dist/cli.js

@@ -1836,7 +1836,7 @@ var StyleImageSchema = z2.object({
   path: z2.string()
 });
 var HexColorSchema = z2.string().regex(/^#?[0-9a-f]{6}$/i, "expected a six-digit hex colour");
-var QualityProfileSchema = z2.object({
+var QualityProfileObjectSchema = z2.object({
   /** Output root for approved refined art, relative to the manifest. */
   outDir: z2.string().min(1),
   /** Closed final palette applied after native-grid recovery, without dithering. */
@@ -1851,7 +1851,8 @@ var QualityProfileSchema = z2.object({
   fixerPython: z2.string().min(1).optional(),
   /** Playback rate recorded for an ordered frame set. */
   fps: z2.number().int().min(1).max(60).optional()
-}).strict().refine(
+}).strict();
+var QualityProfileSchema = QualityProfileObjectSchema.refine(
   (profile) => new Set(profile.palette.map((color) => color.replace(/^#/, "").toLowerCase())).size === profile.palette.length,
   { message: "quality palette colors must be unique", path: ["palette"] }
 );
@@ -1880,7 +1881,7 @@ var RevisionSchema = z2.object({
     });
   }
 });
-var StyleSchema = z2.object({
+var StyleObjectSchema = z2.object({
   /** Generation backend for this style. Omit to inherit the manifest default. */
   provider: z2.string().min(1).optional(),
   // `map` is the default because it is 20-40x cheaper and correct for any
@@ -1995,7 +1996,8 @@ var StyleSchema = z2.object({
   tags: z2.array(z2.string()).default([]),
   /** Adapter-owned settings, keyed by provider id. */
   providerOptions: z2.record(z2.record(z2.unknown())).default({})
-}).strict().refine((s) => !(s.tileFeature && s.styleImages.length), {
+}).strict();
+var StyleSchema = StyleObjectSchema.refine((s) => !(s.tileFeature && s.styleImages.length), {
   message: "tileFeature and styleImages cannot be combined \u2014 a connectable set derives its own tile geometry, so remove one or the other",
   path: ["tileFeature"]
 }).superRefine((style, ctx) => {
@@ -2007,6 +2009,14 @@ var StyleSchema = z2.object({
     });
   }
 });
+var InheritedStyleSchema = StyleObjectSchema.partial().extend({
+  extends: z2.string().min(1),
+  /** Children own their destination; sharing a parent's output is never implicit. */
+  outDir: z2.string(),
+  /** A child may override only part of the inherited final-art policy. */
+  quality: QualityProfileObjectSchema.partial().optional()
+}).strict();
+var StyleInputSchema = z2.union([StyleSchema, InheritedStyleSchema]);
 var AssetSchema = z2.object({
   /** The subject. Style wrapping comes from the style's prefix/suffix. */
   prompt: z2.string(),
@@ -2095,6 +2105,13 @@ var ManifestSchema = z2.object({
   styles: z2.record(StyleSchema),
   assets: z2.record(AssetSchema)
 }).strict();
+var ManifestInputSchema = z2.object({
+  $schema: z2.string().optional(),
+  name: z2.string(),
+  provider: z2.string().min(1).default("pixellab"),
+  styles: z2.record(StyleInputSchema),
+  assets: z2.record(AssetSchema)
+}).strict();
 var LockEntrySchema = z2.object({
   styleId: z2.string(),
   assetId: z2.string(),
@@ -3670,9 +3687,24 @@ function resolveSpecOutputs(spec, lock, manifestDir) {
 async function loadManifest(manifestPath) {
   const abs = path6.resolve(manifestPath);
   if (!existsSync4(abs)) throw new Error(`No manifest at ${abs}`);
-  const parsed = ManifestSchema.safeParse(JSON.parse(await readFile3(abs, "utf8")));
+  const input = ManifestInputSchema.safeParse(JSON.parse(await readFile3(abs, "utf8")));
+  if (!input.success) {
+    const issues = formatManifestIssues(input.error.issues);
+    throw new Error(`Manifest at ${abs} is invalid:
+${issues}`);
+  }
+  let styles;
+  try {
+    styles = resolveStyleInheritance(input.data.styles);
+  } catch (error) {
+    throw new Error(
+      `Manifest at ${abs} is invalid:
+  ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  const parsed = ManifestSchema.safeParse({ ...input.data, styles });
   if (!parsed.success) {
-    const issues = parsed.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n");
+    const issues = formatManifestIssues(parsed.error.issues);
     throw new Error(`Manifest at ${abs} is invalid:
 ${issues}`);
   }
@@ -3723,6 +3755,61 @@ ${unknownReferences.map((i) => `  ${i}`).join("\n")}`);
   }
   return { manifest: parsed.data, root: path6.dirname(abs), path: abs };
 }
+function formatManifestIssues(issues) {
+  return issues.flatMap((issue) => {
+    if (issue.code === "invalid_union") {
+      return issue.unionErrors.flatMap((error) => formatManifestIssues(error.issues).split("\n"));
+    }
+    return [`  ${issue.path.join(".")}: ${issue.message}`];
+  }).join("\n");
+}
+function resolveStyleInheritance(styles) {
+  const resolved = /* @__PURE__ */ new Map();
+  const visit = (styleId, chain) => {
+    const cached = resolved.get(styleId);
+    if (cached) return cached;
+    const cycleStart = chain.indexOf(styleId);
+    if (cycleStart >= 0) {
+      throw new Error(
+        `styles.${styleId}.extends: inheritance cycle ${[...chain.slice(cycleStart), styleId].join(" -> ")}`
+      );
+    }
+    const style = styles[styleId];
+    if (!style) throw new Error(`styles.${styleId}: unknown style`);
+    if (!("extends" in style)) {
+      resolved.set(styleId, style);
+      return style;
+    }
+    const parentId = style.extends;
+    if (!Object.hasOwn(styles, parentId)) {
+      throw new Error(`styles.${styleId}.extends: unknown style "${parentId}"`);
+    }
+    const parent = visit(parentId, [...chain, styleId]);
+    const { extends: _parent, ...child } = style;
+    const merged = {
+      ...parent,
+      ...child,
+      quality: child.quality == null ? parent.quality : { ...parent.quality ?? {}, ...child.quality },
+      providerOptions: mergeProviderOptions(parent.providerOptions, child.providerOptions)
+    };
+    const parsed = StyleSchema.safeParse(merged);
+    if (!parsed.success) {
+      const issues = parsed.error.issues.map((issue) => `styles.${styleId}.${issue.path.join(".")}: ${issue.message}`).join("; ");
+      throw new Error(issues);
+    }
+    resolved.set(styleId, parsed.data);
+    return parsed.data;
+  };
+  return Object.fromEntries(Object.keys(styles).map((styleId) => [styleId, visit(styleId, [])]));
+}
+function mergeProviderOptions(parent, child) {
+  if (!child) return parent;
+  const merged = { ...parent };
+  for (const [provider, options] of Object.entries(child)) {
+    merged[provider] = { ...parent[provider] ?? {}, ...options };
+  }
+  return merged;
+}
 async function resolveSpecs(loaded, filter) {
   const { manifest, root } = loaded;
   const providerOverride = filter?.provider;
@@ -6899,7 +6986,10 @@ function renderSheet(groups) {
   .loop { display:flex; align-items:flex-start; gap:12px; margin-bottom:12px; }
   .loop img { image-rendering:pixelated; border:2px solid var(--accent); padding:7px;
     background:var(--panel-deep); max-width:min(var(--preview),calc(100vw - 62px)); height:auto; }
-  .loop-copy { color:var(--dim); font-size:11px; max-width:32ch; }
+  .loop-copy { color:var(--dim); font-size:11px; max-width:32ch; display:flex;
+    flex-direction:column; gap:8px; }
+  .loop-copy p { margin:0; }
+  .loop-copy button { align-self:flex-start; padding:5px 9px; font-size:10.5px; }
   .cand { border:2px solid var(--line-strong); border-radius:0; padding:7px; background:var(--panel-deep);
     cursor:pointer; display:flex; flex:0 0 auto; flex-direction:column; align-items:center; gap:5px;
     position:relative; max-width:100%; }
@@ -7003,15 +7093,49 @@ GROUPS.forEach((g, gi) => {
     preview.alt = 'Animated frame-set preview';
     const copy = document.createElement('div');
     copy.className = 'loop-copy';
-    copy.textContent = g.frameUrls.length + ' ordered frames \xB7 ' + (g.fps || 12) +
+    const copyText = document.createElement('p');
+    copyText.textContent = g.frameUrls.length + ' ordered frames \xB7 ' + (g.fps || 12) +
       ' fps. Accepting keeps every frame; one bad frame means leave the set unchosen.';
+    const playback = document.createElement('button');
+    playback.type = 'button';
+    let userPaused = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    let loopVisible = true;
+    let pageVisible = !document.hidden;
+    let loopTimer = null;
+    let loopIndex = 0;
+    const stopLoop = () => {
+      if (loopTimer !== null) window.clearInterval(loopTimer);
+      loopTimer = null;
+    };
+    const syncLoop = () => {
+      stopLoop();
+      playback.textContent = userPaused ? 'Play preview' : 'Pause preview';
+      playback.setAttribute('aria-pressed', String(userPaused));
+      if (!userPaused && loopVisible && pageVisible) {
+        loopTimer = window.setInterval(() => {
+          loopIndex = (loopIndex + 1) % g.frameUrls.length;
+          preview.src = g.frameUrls[loopIndex];
+        }, Math.max(16, Math.round(1000 / (g.fps || 12))));
+      }
+    };
+    playback.addEventListener('click', () => {
+      userPaused = !userPaused;
+      syncLoop();
+    });
+    copy.append(copyText, playback);
     loop.append(preview, copy);
     review.insertBefore(loop, frames);
-    let loopIndex = 0;
-    setInterval(() => {
-      loopIndex = (loopIndex + 1) % g.frameUrls.length;
-      preview.src = g.frameUrls[loopIndex];
-    }, Math.max(16, Math.round(1000 / (g.fps || 12))));
+    document.addEventListener('visibilitychange', () => {
+      pageVisible = !document.hidden;
+      syncLoop();
+    });
+    syncLoop();
+    if ('IntersectionObserver' in window) {
+      new IntersectionObserver((entries) => {
+        loopVisible = entries[0]?.isIntersecting ?? false;
+        syncLoop();
+      }).observe(loop);
+    }
   }
   g.frameUrls.forEach((url, i) => {
     const c = document.createElement('button');