@cardanvil/frame-kit 0.6.0 → 0.7.0

package/README.md

@@ -43,6 +43,30 @@ export const myFrame = {
 `as const satisfies Frame` is the idiom: `satisfies` checks the object against the contract, `as const`
 keeps the literal types.
 
+### The collector line
+
+What the collector box prints is data too: its `lines`, each a row of elements (`rarity`, `cardNumber`,
+`setCode`, `artist`, …) with their own spacing, sizing, fonts and alignment. `withCollectorInfoDefaults`
+fills in `defaultCollectorInfoLines` unless the bounds bring their own. Pass `retroCollectorInfoLines`
+for the Retro frame's centered artist and creator lines, or write your own:
+
+```ts
+const collectorBounds = {
+  x: 460,
+  y: 3880,
+  width: 2330,
+  height: 200,
+  fontSize: 58,
+  lines: [
+    { elements: [{ type: "artist", prefix: "Illus. " }], align: "center" },
+    {
+      elements: [{ type: "setCode", spacingAfter: 24 }, { type: "cardNumber" }],
+      align: "center",
+    },
+  ],
+} as const satisfies CollectorInfoBox;
+```
+
 ## Entry points
 
 | Import                           | What it gives you                                                                                                                                                                    |
@@ -58,6 +82,7 @@ frame-kit validate                # check every frame, write nothing
 frame-kit build --out dist        # check, then pack each one
 frame-kit build --out dist --watch  # …and repack whenever a source changes
 frame-kit schema meta             # a format as JSON Schema
+frame-kit trim --shared a.png b.png  # cut art down to what is visible
 frame-kit --help
 ```
 
@@ -129,6 +154,31 @@ Packaging needs Vite — it is what turns `import w from "./w.png"` into a file
 so it is an **optional** peer dependency, loaded only when packaging runs. The
 schemas above work under plain Node and in a browser without it.
 
+### `frame-kit trim`
+
+```bash
+frame-kit trim [--shared] [--out <dir>] [--dry-run] [--json] <png...>
+```
+
+Cuts PNGs down to their visible pixels and prints where each now sits on the
+sheet. Art is authored on the full sheet so it lines up by itself, but a
+renderer decodes, caches and composites every pixel of an image, transparent or
+not — a Saga banner is under 5% of its sheet, and trimmed it costs a twentieth
+as much on every card.
+
+`--shared` cuts every image given to one rectangle, the smallest holding all of
+their visible pixels, so images drawn together — a banner and the masks cut from
+it — keep one position. Put that position in the frame wherever a field asks for
+one, such as `saga.bannerOrigin`; only fields that take a position can use
+trimmed art.
+
+The pixels kept are byte-for-byte the originals, and the chunks that tell a
+decoder how to show them — colour profile, gamma — are carried over, so the art
+draws exactly as before. Each trimmed image also records its position in an
+`oFFs` chunk, so trimming it again reports where it sits on the sheet rather
+than in itself. Without `--out` each image replaces its original. Only 8-bit
+PNGs are trimmed: decoding 16 bits a channel would lose detail.
+
 ### `frame-kit studio`
 
 ```bash
@@ -155,7 +205,7 @@ that are not written as literals are reported as such rather than edited.
 
 ### `@cardanvil/frame-kit/layout`
 
-How a frame's art is chosen and placed, as pure functions:
+How a frame is drawn for one card, as pure functions:
 
 - `selectFrameLayers(details, options)` — the base frame and section overlays a
   set of `FrameDetails` selects. Split out of Card Anvil's `getFrameLayers`, so
@@ -170,6 +220,30 @@ How a frame's art is chosen and placed, as pure functions:
   middle of the card.
 - `resolveFrameAsset` / `resolveBaseFrame` — exact per-family lookup, and the
   base-frame fallback chain.
+- `frameCutoutMasks(input)` — the masks cut out of a face's frame body, in the
+  renderer's order: "No Border", the legendary crown's space, the extended-art
+  silhouette, the colorless nickname banner.
+- `ringMaskFor(masks, useFullBorder)` and `borderStateFor(input)` — the mask a
+  border color recolors through, and the border state that results:
+  `default`, `light`, `dark` or `none`.
+- `resolveBoxOverrides(boxes, state)` — a box set with each text box's
+  `overrides` merged in for one render's border state and template settings,
+  so everything that draws a frame agrees on what a condition matches.
+  `overrideMatches` tests a single rule, and
+  `resolveSecondFaceBoxOverrides` does the same for a `secondFaceBoxes` set.
+- `turnPlacement(sheet, rotation)` / `turnMatrix(sheet, rotation)` — where a
+  turned box set (one with a `rotation`) sits on the sheet, as a node's
+  position and rotation or as a matrix. `turnedSheetSize` is the sheet as such
+  a set measures it, `turnedBoundsOnSheet` one of its boxes back on the sheet
+  as printed, and `turnedVectorOnSheet` / `sheetVectorInTurned` a direction
+  taken one way or the other.
+- `templateSettingDefaults(frame)`, `mergeTemplateSettings` and
+  `layoutTemplateSettings(settings, layout)` — a frame's settings the way Card
+  Anvil stores them, and the values in effect for one layout.
+- `textOutlineFor(box)` / `textShadowFor(box)` — how a plain-text box is
+  outlined or shadowed.
+- `getReadableTextColor` and friends — the contrast rule that decides whether
+  a border color reads as light or dark.
 
 Card Anvil still owns the other half — reading a Scryfall card into
 `FrameDetails` — because that is where the Scryfall types live.

package/dist/authoring/collectorInfo.d.ts

@@ -0,0 +1,17 @@
+import { CollectorInfoLine } from "../schema/collectorInfo.js";
+/**
+ * Default collector info layout with two lines, left-aligned.
+ * Line 1: rarity | cardNumber | creatorName
+ * Line 2: setCode | separator | language | artistSymbol | artist
+ *
+ * `withCollectorInfoDefaults` gives these to collector info unless its bounds
+ * bring their own `lines`, and the renderer falls back to them for a collector
+ * box without any.
+ */
+export declare const defaultCollectorInfoLines: readonly CollectorInfoLine[];
+/**
+ * Retro collector info layout: just artist (top line) and creator name
+ * (bottom line), both centered in the box instead of flowing from its left
+ * edge like the default lines do.
+ */
+export declare const retroCollectorInfoLines: readonly CollectorInfoLine[];

package/dist/authoring/collectorInfo.js

@@ -0,0 +1,62 @@
+/**
+ * Default collector info layout with two lines, left-aligned.
+ * Line 1: rarity | cardNumber | creatorName
+ * Line 2: setCode | separator | language | artistSymbol | artist
+ *
+ * `withCollectorInfoDefaults` gives these to collector info unless its bounds
+ * bring their own `lines`, and the renderer falls back to them for a collector
+ * box without any.
+ */
+export const defaultCollectorInfoLines = [
+    {
+        elements: [
+            { type: "rarity", spacingAfter: 34 }, // Extra space before card number
+            { type: "cardNumber", spacingAfter: 40, letterSpacing: 8 }, // Extra space before creator name
+            { type: "creatorName", minXFromElement: "artistSymbol" },
+        ],
+        spacing: 10, // Space between elements
+    },
+    {
+        elements: [
+            { type: "setCode", spacingAfter: 24, letterSpacing: 6 }, // Extra space before language
+            {
+                type: "separator",
+                useManaFont: true,
+                manaSymbol: "•",
+                fontSizeMultiplierDot: 1.9,
+                fontSizeMultiplierStar: 1.4,
+                yOffsetDot: 5,
+                yOffsetStar: 20,
+                spacingAfter: 10,
+            },
+            { type: "language", spacingAfter: 38, letterSpacing: 4 }, // Extra space before artist symbol
+            {
+                type: "artistSymbol",
+                useManaFont: true,
+                manaSymbol: "a",
+                fontSizeMultiplier: 1.24,
+            },
+            { type: "artist", fontSizeMultiplier: 1.1, letterSpacing: 0 },
+        ],
+        spacing: 10,
+    },
+];
+/**
+ * Retro collector info layout: just artist (top line) and creator name
+ * (bottom line), both centered in the box instead of flowing from its left
+ * edge like the default lines do.
+ */
+export const retroCollectorInfoLines = [
+    {
+        elements: [{ type: "artist", prefix: "Illus. " }],
+        align: "center",
+        fontSizeMultiplier: 1.5,
+        fontFamily: "MPlantin",
+    },
+    {
+        elements: [{ type: "creatorName" }],
+        align: "center",
+        fontSizeMultiplier: 1.3,
+        fontFamily: "MPlantin",
+    },
+];

package/dist/authoring/index.d.ts

@@ -1,2 +1,4 @@
+export * from "./collectorInfo.js";
 export * from "./layoutDefaults.js";
 export * from "./omit.js";
+export * from "./opacityStops.js";

package/dist/authoring/index.js

@@ -1,2 +1,4 @@
+export * from "./collectorInfo.js";
 export * from "./layoutDefaults.js";
 export * from "./omit.js";
+export * from "./opacityStops.js";

package/dist/authoring/layoutDefaults.d.ts

@@ -1,6 +1,24 @@
-import { LayoutConfig, TemplateSettingsConfig, TextBox } from "../schema/frame.js";
+import { CollectorInfoBox, LayoutConfig, TemplateSettingsConfig, TextBoxOverride } from "../schema/frame.js";
+/**
+ * `overrides` for text printed on the frame's outer border ring — on most
+ * frames, the collector line. The text turns black once a light border color
+ * is picked, and gains a black outline when "No Border" cuts the ring away and
+ * leaves it over the art.
+ *
+ * `withCollectorInfoDefaults` gives these to collector info unless its bounds
+ * bring their own.
+ */
+export declare const onBorderTextOverrides: readonly TextBoxOverride[];
 /**
  * Applies default collector info bounds to a layout config if not specified.
+ *
+ * The collector info this fills in is taken to sit on the border ring, so it
+ * gets `onBorderTextOverrides` — unless `defaultCollectorInfoBounds` brings its
+ * own `overrides`, with `[]` for a collector line printed where the border
+ * settings never reach. It prints `defaultCollectorInfoLines` unless the bounds
+ * bring their own `lines` — `retroCollectorInfoLines`, or a layout of the
+ * frame's own. A collector box the layout defines itself is left exactly as
+ * written.
  */
-export declare function withCollectorInfoDefaults<T extends LayoutConfig>(config: T, defaultCollectorInfoBounds: TextBox): T;
+export declare function withCollectorInfoDefaults<T extends LayoutConfig>(config: T, defaultCollectorInfoBounds: CollectorInfoBox): T;
 export declare function withSettingsDefaults<T extends LayoutConfig>(config: T, defaultSettings: TemplateSettingsConfig): T;

package/dist/authoring/layoutDefaults.js

@@ -1,62 +1,97 @@
+import { defaultCollectorInfoLines } from "./collectorInfo.js";
+/**
+ * `overrides` for text printed on the frame's outer border ring — on most
+ * frames, the collector line. The text turns black once a light border color
+ * is picked, and gains a black outline when "No Border" cuts the ring away and
+ * leaves it over the art.
+ *
+ * `withCollectorInfoDefaults` gives these to collector info unless its bounds
+ * bring their own.
+ */
+export const onBorderTextOverrides = [
+    {
+        when: { border: "none" },
+        style: { outlineColor: "black", outlineWidth: 19 },
+    },
+    { when: { border: "light" }, style: { color: "black" } },
+];
 /**
  * Applies default collector info bounds to a layout config if not specified.
+ *
+ * The collector info this fills in is taken to sit on the border ring, so it
+ * gets `onBorderTextOverrides` — unless `defaultCollectorInfoBounds` brings its
+ * own `overrides`, with `[]` for a collector line printed where the border
+ * settings never reach. It prints `defaultCollectorInfoLines` unless the bounds
+ * bring their own `lines` — `retroCollectorInfoLines`, or a layout of the
+ * frame's own. A collector box the layout defines itself is left exactly as
+ * written.
  */
 export function withCollectorInfoDefaults(config, defaultCollectorInfoBounds) {
+    const collectorInfo = {
+        ...defaultCollectorInfoBounds,
+        overrides: defaultCollectorInfoBounds.overrides ?? onBorderTextOverrides,
+        lines: defaultCollectorInfoBounds.lines ?? defaultCollectorInfoLines,
+    };
     return {
         ...config,
         boxes: {
             ...config.boxes,
-            collectorInfo: config.boxes.collectorInfo ?? defaultCollectorInfoBounds,
+            collectorInfo: config.boxes.collectorInfo ?? collectorInfo,
         },
         tallBoxes: config.tallBoxes
             ? {
                 ...config.tallBoxes,
-                collectorInfo: config.tallBoxes.collectorInfo ?? defaultCollectorInfoBounds,
+                collectorInfo: config.tallBoxes.collectorInfo ?? collectorInfo,
+            }
+            : undefined,
+        // Planeswalkers with two abilities swap `boxes` for these (see
+        // renderCardToCanvas), which would otherwise drop collector info.
+        twoAbilityBoxes: config.twoAbilityBoxes
+            ? {
+                ...config.twoAbilityBoxes,
+                collectorInfo: config.twoAbilityBoxes.collectorInfo ?? collectorInfo,
             }
             : undefined,
         backBoxes: config.backBoxes
             ? {
                 ...config.backBoxes,
-                collectorInfo: config.backBoxes.collectorInfo ?? defaultCollectorInfoBounds,
+                collectorInfo: config.backBoxes.collectorInfo ?? collectorInfo,
             }
             : undefined,
         sagaFrontBoxes: config.sagaFrontBoxes
             ? {
                 ...config.sagaFrontBoxes,
-                collectorInfo: config.sagaFrontBoxes.collectorInfo ?? defaultCollectorInfoBounds,
+                collectorInfo: config.sagaFrontBoxes.collectorInfo ?? collectorInfo,
             }
             : undefined,
         sagaBackBoxes: config.sagaBackBoxes
             ? {
                 ...config.sagaBackBoxes,
-                collectorInfo: config.sagaBackBoxes.collectorInfo ?? defaultCollectorInfoBounds,
+                collectorInfo: config.sagaBackBoxes.collectorInfo ?? collectorInfo,
             }
             : undefined,
         creatureBoxes: config.creatureBoxes
             ? {
                 ...config.creatureBoxes,
-                collectorInfo: config.creatureBoxes.collectorInfo ?? defaultCollectorInfoBounds,
+                collectorInfo: config.creatureBoxes.collectorInfo ?? collectorInfo,
             }
             : undefined,
         backCreatureBoxes: config.backCreatureBoxes
             ? {
                 ...config.backCreatureBoxes,
-                collectorInfo: config.backCreatureBoxes.collectorInfo ??
-                    defaultCollectorInfoBounds,
+                collectorInfo: config.backCreatureBoxes.collectorInfo ?? collectorInfo,
             }
             : undefined,
         sagaFrontCreatureBoxes: config.sagaFrontCreatureBoxes
             ? {
                 ...config.sagaFrontCreatureBoxes,
-                collectorInfo: config.sagaFrontCreatureBoxes.collectorInfo ??
-                    defaultCollectorInfoBounds,
+                collectorInfo: config.sagaFrontCreatureBoxes.collectorInfo ?? collectorInfo,
             }
             : undefined,
         sagaBackCreatureBoxes: config.sagaBackCreatureBoxes
             ? {
                 ...config.sagaBackCreatureBoxes,
-                collectorInfo: config.sagaBackCreatureBoxes.collectorInfo ??
-                    defaultCollectorInfoBounds,
+                collectorInfo: config.sagaBackCreatureBoxes.collectorInfo ?? collectorInfo,
             }
             : undefined,
         // Saga layouts swap `boxes` for `flipsidePtBoxes` on face 0 when the
@@ -65,7 +100,7 @@ export function withCollectorInfoDefaults(config, defaultCollectorInfoBounds) {
         flipsidePtBoxes: config.flipsidePtBoxes
             ? {
                 ...config.flipsidePtBoxes,
-                collectorInfo: config.flipsidePtBoxes.collectorInfo ?? defaultCollectorInfoBounds,
+                collectorInfo: config.flipsidePtBoxes.collectorInfo ?? collectorInfo,
             }
             : undefined,
     };

package/dist/authoring/opacityStops.d.ts

@@ -0,0 +1,8 @@
+import type { OpacityStop } from "../schema/paint.js";
+/**
+ * Opacity stops sampled from `curve`, which maps 0–1 along a gradient to an
+ * opacity 0–1 — for writing a gradient's `opacity` from a formula. The stops
+ * are spaced evenly, `count` of them (at least two). A canvas draws straight
+ * lines between them, so a tight curve wants more.
+ */
+export declare function opacityStopsFrom(curve: (t: number) => number, count?: number): OpacityStop[];

package/dist/authoring/opacityStops.js

@@ -0,0 +1,17 @@
+const round = (value, places) => Number(value.toFixed(places));
+/**
+ * Opacity stops sampled from `curve`, which maps 0–1 along a gradient to an
+ * opacity 0–1 — for writing a gradient's `opacity` from a formula. The stops
+ * are spaced evenly, `count` of them (at least two). A canvas draws straight
+ * lines between them, so a tight curve wants more.
+ */
+export function opacityStopsFrom(curve, count = 24) {
+    const n = Math.max(2, Math.round(count));
+    return Array.from({ length: n }, (_, i) => {
+        const at = i / (n - 1);
+        return {
+            at: round(at, 6),
+            opacity: round(Math.min(1, Math.max(0, curve(at))), 4),
+        };
+    });
+}

package/dist/cli/index.d.ts

@@ -16,3 +16,4 @@ export { type FrameServer, loadFrameExport, startFrameServer, } from "./loadFram
 export { type Problem, Reporter, type Severity, formatProblem, inGitHubActions, } from "./report.js";
 export { SCHEMA_NAMES, SHIPPED_SCHEMAS, type SchemaName, schemaFilename, toJsonSchema, } from "./schema.js";
 export { stableStringify } from "./stableJson.js";
+export { type Pixels, type Rect, type TrimOptions, type TrimResult, type TrimmedImage, cropPixels, opaqueBounds, trimImages, unionBounds, } from "./trim.js";

package/dist/cli/index.js

@@ -16,3 +16,4 @@ export { loadFrameExport, startFrameServer, } from "./loadFrame.js";
 export { Reporter, formatProblem, inGitHubActions, } from "./report.js";
 export { SCHEMA_NAMES, SHIPPED_SCHEMAS, schemaFilename, toJsonSchema, } from "./schema.js";
 export { stableStringify } from "./stableJson.js";
+export { cropPixels, opaqueBounds, trimImages, unionBounds, } from "./trim.js";

package/dist/cli/loadFrame.js

@@ -32,7 +32,7 @@ async function importVite() {
  * loop would appear to run and do nothing.
  */
 export function invalidateFrameModules(frameServer) {
-    // Both supported Vite majors expose the SSR module graph here; the legacy
+    // Every supported Vite major exposes the SSR module graph here; the legacy
     // top-level accessor is deprecated.
     frameServer.server.environments.ssr.moduleGraph.invalidateAll();
 }

package/dist/cli/main.js

@@ -10,6 +10,7 @@ import { Reporter, inGitHubActions } from "./report.js";
 import { SCHEMA_NAMES, toJsonSchema } from "./schema.js";
 import { stableStringify } from "./stableJson.js";
 import { runStudio } from "./studio/serve.js";
+import { trimImages } from "./trim.js";
 import { watchFrames } from "./watch.js";
 const USAGE = `frame-kit — package Card Anvil frames
 
@@ -19,6 +20,8 @@ Usage:
   frame-kit schema <name> [--out <file>] print a format as JSON Schema
                                          (${SCHEMA_NAMES.join(" | ")})
   frame-kit studio [options]             open the visual box editor
+  frame-kit trim <png...> [options]      cut images down to their visible
+                                         pixels, and say where they sit
   frame-kit --help
   frame-kit --version
 
@@ -37,6 +40,12 @@ build only:
                         in the index
   --watch               rebuild a frame whenever its source changes
 
+trim only:
+  --shared              cut every image to one rectangle holding all of their
+                        visible pixels, so they keep one position on the sheet
+  --out <dir>           write trimmed images here instead of replacing them
+  --dry-run             say what would be cut, write nothing
+
 studio only:
   --port <n>            port to serve on (default: 4620)
   --host <h>            interface to bind (default: 127.0.0.1)
@@ -45,6 +54,10 @@ studio only:
                         reloading (only inside the frames workspace)
   --no-write            serve read-only; refuse every edit
 
+A trimmed image keeps its pixels exactly, and records where it sits on the
+sheet so a second trim still reports that position. Put the position in the
+frame where the field asks for one, such as a Saga's bannerOrigin.
+
 The studio edits the literals in your source when you drag a box, so run it on
 a clean working tree. It needs TypeScript installed to find them.
 
@@ -174,6 +187,62 @@ async function runBuild(root, only, values) {
     }
     return reporter.ok ? EXIT.ok : EXIT.failed;
 }
+function describeRect(rect) {
+    return `${String(rect.width)} × ${String(rect.height)} at (${String(rect.x)}, ${String(rect.y)})`;
+}
+async function runTrim(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            options: {
+                shared: { type: "boolean" },
+                out: { type: "string" },
+                "dry-run": { type: "boolean" },
+                json: { type: "boolean" },
+            },
+            allowPositionals: true,
+            strict: true,
+        });
+    }
+    catch (cause) {
+        console.error(`${cause instanceof Error ? cause.message : String(cause)}\n\n${USAGE}`);
+        return EXIT.usage;
+    }
+    const { values, positionals: files } = parsed;
+    if (files.length === 0) {
+        console.error(`trim needs at least one PNG.\n\n${USAGE}`);
+        return EXIT.usage;
+    }
+    const result = await trimImages(files, {
+        shared: values.shared === true,
+        ...(values.out !== undefined ? { outDir: values.out } : {}),
+        dryRun: values["dry-run"] === true,
+    });
+    if (values.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return EXIT.ok;
+    }
+    for (const image of result.images) {
+        const from = `${String(image.width)} × ${String(image.height)}`;
+        const what = image.kept
+            ? `${from} → ${describeRect(image.kept)}`
+            : `${from}, nothing visible, left as it is`;
+        const nothingToCut = image.kept?.width === image.width && image.kept.height === image.height;
+        const action = image.written
+            ? ""
+            : nothingToCut
+                ? "  (already trimmed)"
+                : values["dry-run"] && image.kept
+                    ? "  (dry run)"
+                    : "";
+        console.log(`${image.file}  ${what}${action}`);
+    }
+    if (result.shared) {
+        console.log(`\nEvery image was cut to ${describeRect(result.shared)} on the sheet.`);
+    }
+    return EXIT.ok;
+}
 function isSchemaName(name) {
     return SCHEMA_NAMES.includes(name);
 }
@@ -224,6 +293,9 @@ async function main(argv) {
     if (command === "studio") {
         return await runStudio(argv.slice(1));
     }
+    if (command === "trim") {
+        return await runTrim(argv.slice(1));
+    }
     if (command !== "validate" && command !== "build") {
         console.error(`Unknown command "${command}".\n\n${USAGE}`);
         return EXIT.usage;

package/dist/cli/studio/boxSets.js

@@ -1,4 +1,4 @@
-import { CardBoxesSchema, LayoutConfigSchema } from "../../schema/frame.js";
+import { CardBoxesSchema, LayoutConfigSchema, SecondFaceBoxesSchema, } from "../../schema/frame.js";
 import { FrameAssetsSchema, LayoutMasksSchema, } from "../../schema/frameAssets.js";
 /** Strips `.optional()` and friends to reach the schema that carries identity. */
 function unwrap(schema) {
@@ -23,12 +23,16 @@ function unwrap(schema) {
 }
 const KIND_BY_SCHEMA = new Map([
     [CardBoxesSchema, "boxes"],
+    // A second face's set is boxes like any other, only fewer of them.
+    [SecondFaceBoxesSchema, "boxes"],
     [FrameAssetsSchema, "assets"],
     [LayoutMasksSchema, "masks"],
 ]);
 /**
- * Whether a schema is a plain object of numbers — a layout's render knobs
- * (`planeswalkerConfig`, `sagaConfig`, `crownConfig`, `nicknameConfig`).
+ * Whether a schema is an object of numbers — a layout's render knobs
+ * (`planeswalkerConfig`, `sagaConfig`, `sectionConfig`, `crownConfig`,
+ * `nicknameConfig`, `powerToughnessRow`). A group may also hold objects, such
+ * as `planeswalkerConfig.abilityDivider`; the studio edits only its numbers.
  *
  * Recognised by shape rather than by name, so a knob group added to the
  * contract is editable in the studio without a change here. Records and enums
@@ -41,11 +45,10 @@ function isNumericObject(schema) {
         return false;
     }
     const fields = Object.values(node.shape);
-    return (fields.length > 0 &&
-        fields.every((field) => {
-            const inner = unwrap(field).inner.def;
-            return inner.type === "number" || inner.type === "boolean";
-        }));
+    const types = fields.map((field) => unwrap(field).inner.def.type);
+    const isKnob = (type) => type === "number" || type === "boolean";
+    return (types.some(isKnob) &&
+        types.every((type) => isKnob(type) || type === "object"));
 }
 /**
  * Every box / asset / mask / knob slot the frame contract defines, read off

package/dist/cli/studio/serve.js

@@ -117,7 +117,10 @@ async function startUiDevServer(srcDir, httpServer) {
     const server = await vite.createServer({
         root: srcDir,
         appType: "spa",
-        server: { middlewareMode: true, hmr: { server: httpServer } },
+        // `ws.server` is Vite 8's spelling (`hmr.server` is deprecated there, and
+        // Vite 7 has no `ws` options at all). Only the workspace runs --dev, and it
+        // pins Vite 8, so the published peer range never reaches this line.
+        server: { middlewareMode: true, ws: { server: httpServer } },
     });
     return {
         middlewares: (req, res) => {

package/dist/cli/trim.d.ts

@@ -0,0 +1,62 @@
+/** A rectangle in pixels. */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Decoded pixels, four bytes (RGBA) a pixel, row after row. */
+export interface Pixels {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+/**
+ * The smallest rectangle holding every pixel that is not fully transparent,
+ * or `undefined` when the image has none.
+ */
+export declare function opaqueBounds({ width, height, data, }: Pixels): Rect | undefined;
+/** The smallest rectangle holding all of `rects`, or `undefined` for none. */
+export declare function unionBounds(rects: readonly Rect[]): Rect | undefined;
+/** `pixels` cut down to `rect`, which must lie inside them. */
+export declare function cropPixels(pixels: Pixels, rect: Rect): Pixels;
+export interface TrimOptions {
+    /**
+     * Cut every image to one rectangle: the smallest holding all of their
+     * visible pixels. They must all be the same size, and they then share one
+     * position on the sheet — which is what images drawn together, such as a
+     * banner and the masks cut from it, need.
+     */
+    shared?: boolean;
+    /**
+     * Where trimmed images are written, under their own names. Without it each
+     * one replaces its original.
+     */
+    outDir?: string;
+    /** Work everything out but write nothing. */
+    dryRun?: boolean;
+}
+export interface TrimmedImage {
+    file: string;
+    /** Where it was written; `undefined` when nothing was. */
+    written: string | undefined;
+    /** Its size before trimming. */
+    width: number;
+    height: number;
+    /**
+     * The part kept, with `x` and `y` on the sheet. `undefined` when the image
+     * has no visible pixel, and is left as it was.
+     */
+    kept: Rect | undefined;
+}
+export interface TrimResult {
+    images: TrimmedImage[];
+    /** With `shared`: the one rectangle every image was cut to, on the sheet. */
+    shared: Rect | undefined;
+}
+/**
+ * Trims each PNG in `files` to its visible pixels, or with `shared` all of
+ * them to one rectangle, and reports where each now sits on its sheet. An
+ * image already as small as it can be is not rewritten.
+ */
+export declare function trimImages(files: readonly string[], options?: TrimOptions): Promise<TrimResult>;