@cardanvil/frame-kit 0.5.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,100 @@ 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
+frame-kit studio [--root <dir>] [--port <n>] [--frame <slug>] [--no-write]
+```
+
+A visual box editor, served from `dist/studio` and opened at
+<http://localhost:4620>. It loads frames through the same Vite SSR loader
+`validate` uses, so what it draws is the validated frame, and it reloads when a
+source file changes.
+
+The card name and type line are previewed in Beleren at the authored size and
+flagged when they overflow — one line each, with no wrapping, symbols or
+auto-shrink, so the app remains the authority on a full render.
+
+Working on the studio's own UI: `--dev` serves it from source with hot
+reloading, on the same port as the API, so one command covers both. It needs
+the UI's source, which only exists inside the frames workspace.
+
+Dragging a box rewrites the literal it came from, in place — nothing is
+reprinted, so comments and formatting survive. Editing needs `typescript`
+installed (an optional peer); without it the studio still runs read-only. Values
+that are not written as literals are reported as such rather than edited.
+
+### `@cardanvil/frame-kit/layout`
+
+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
+  the studio and the renderer cannot drift on two-colour splits, hybrid halves
+  or the coloured-artifact fallback.
+- `frameDetailsFor(shape)` — those details from a plain description of a card
+  (colours plus artifact / vehicle / land / enchantment / hybrid / devoid),
+  for callers with no Scryfall card to parse.
+- `placeAsset(path, config)` — where a piece of art is drawn. Most frame art is
+  full-sheet and centres, but crowns, nicknames and PT plates come from the
+  layout's own render config; centring those puts a legendary crown in the
+  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.
+
 ## Type it, then validate it
 
 Typing a config as `Frame` is weaker than the schema a loading app enforces. The clearest example:

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

@@ -9,6 +9,8 @@ import { PackagingError } from "./errors.js";
 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
 
@@ -17,6 +19,9 @@ Usage:
   frame-kit build --out <dir> [options]  check every frame, then pack each one
   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
 
@@ -35,6 +40,27 @@ 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)
+  --open                open the studio in your browser
+  --dev                 serve the studio's own UI from source, with hot
+                        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.
+
 A frame is any directory containing a frame.meta.json. One with "private": true
 is checked by validate but never built.
 `;
@@ -161,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);
 }
@@ -208,6 +290,12 @@ async function main(argv) {
     if (command === "schema") {
         return await runSchema(argv.slice(1));
     }
+    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/sourceWatcher.d.ts

@@ -0,0 +1,40 @@
+/**
+ * How long to wait for changes to stop before reacting.
+ *
+ * One save can produce several events — a write, a rename, an attribute
+ * change — and a tool upstream may rewrite a whole directory.
+ */
+export declare const DEBOUNCE_MS = 200;
+/** Whether a path is build output, editor debris, or inside a skipped dir. */
+export declare function isIgnored(file: string): boolean;
+export interface SourceWatcherOptions {
+    /** Absolute path the watch is rooted at. Only used for error messages. */
+    root: string;
+    /** Directories to watch recursively. Overlapping entries are fine. */
+    dirs: readonly string[];
+    /**
+     * Called with each batch of changed paths, debounced and never overlapping.
+     *
+     * Anything that arrives while a call is in flight is queued and delivered in
+     * the next batch, so a slow handler cannot drop a change.
+     */
+    onChange: (changed: readonly string[]) => void | Promise<void>;
+    /** Ignored on top of the built-in list — a build's own output directory, say. */
+    ignore?: (file: string) => boolean;
+    /** Defaults to `DEBOUNCE_MS`. */
+    debounceMs?: number;
+    /** Where an unwatchable directory or a throwing handler is reported. */
+    onError?: (message: string) => void;
+}
+export interface SourceWatcher {
+    close: () => void;
+}
+/**
+ * Watches directories and delivers debounced, non-overlapping change batches.
+ *
+ * Shared by `frame-kit build --watch` and `frame-kit studio`, which need the
+ * same three things and get them wrong in the same three ways otherwise:
+ * coalescing a burst of events from one save, never running two handlers at
+ * once, and surviving a handler that throws.
+ */
+export declare function startSourceWatcher(options: SourceWatcherOptions): SourceWatcher;