pixelkiln 0.19.0 → 0.20.0

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;