@cardanvil/frame-kit 0.5.0 → 0.7.0

package/dist/cli/studio/session.d.ts

@@ -0,0 +1,73 @@
+import type { Frame } from "../../schema/frame.js";
+import { type DiscoveredFrame } from "../discover.js";
+import { type FrameServer } from "../loadFrame.js";
+import { type Problem } from "../report.js";
+import { type LayoutSlot } from "./boxSets.js";
+import { type SourceIndex } from "./edit/sourceIndex.js";
+import { type TypeScriptApi } from "./edit/ts.js";
+/** One box / asset / mask set present in a frame, addressed by logical path. */
+export interface FrameSlot extends LayoutSlot {
+    /** `null` for `config.layouts`, else the `alternateLayouts` key. */
+    readonly variant: string | null;
+    readonly layout: string;
+    readonly path: readonly string[];
+    /** Which `CardBoxes` members this set actually defines. */
+    readonly boxKeys?: readonly string[];
+}
+export interface FramePayload {
+    readonly slug: string;
+    readonly id: string;
+    readonly name: string;
+    /** Bumps on every successful reload, so the client can drop stale state. */
+    readonly revision: number;
+    readonly canvas: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** The validated frame, with asset URLs rewritten to studio endpoints. */
+    readonly frame: unknown;
+    readonly slots: readonly FrameSlot[];
+    /** Root-relative POSIX paths of every source file the frame was built from. */
+    readonly sourceFiles: readonly string[];
+    readonly problems: readonly Problem[];
+    /** True when this is the last good load and the newest one failed. */
+    readonly stale: boolean;
+    readonly staleProblems?: readonly Problem[];
+}
+export interface FrameSummary {
+    readonly slug: string;
+    readonly id: string;
+    readonly name: string;
+    readonly stale: boolean;
+}
+interface Entry {
+    payload: FramePayload;
+    /** The frame before URL rewriting — what edits are verified against. */
+    raw: Frame;
+    discovered: DiscoveredFrame;
+}
+export interface StudioSession {
+    readonly root: string;
+    readonly index: SourceIndex;
+    readonly api: TypeScriptApi;
+    readonly frameServer: FrameServer;
+    list: () => FrameSummary[];
+    get: (slug: string) => Entry | undefined;
+    /** Absolute source files worth watching, across every loaded frame. */
+    watchDirs: () => string[];
+    reload: (only?: readonly string[]) => Promise<string[]>;
+    close: () => Promise<void>;
+}
+/**
+ * Owns the Vite server, the loaded frames, and the last-good cache.
+ *
+ * A frame that fails to load keeps its previous payload — an author mid-save
+ * produces a syntax error on almost every keystroke, and blanking the canvas
+ * each time would make the studio unusable. `loadFrames` already routes every
+ * failure into the reporter instead of throwing, so a failed pass simply
+ * yields no frame for that slug.
+ */
+export declare function startSession(root: string, only?: readonly string[]): Promise<StudioSession>;
+/** Frames discoverable under `root`, for a startup message. */
+export declare function countFrames(root: string): Promise<number>;
+export {};

package/dist/cli/studio/session.js

@@ -0,0 +1,154 @@
+import path from "node:path";
+import { walkAssets } from "../../manifest/walk.js";
+import { setAtPath } from "../../manifest/walk.js";
+import { DEFAULT_CANVAS_HEIGHT, DEFAULT_CANVAS_WIDTH, } from "../../schema/frame.js";
+import { FrameSchema } from "../../schema/frame.js";
+import { loadFrames } from "../api.js";
+import { discoverFrames, relativePosix, } from "../discover.js";
+import { invalidateFrameModules, startFrameServer, } from "../loadFrame.js";
+import { Reporter } from "../report.js";
+import { layoutSlots } from "./boxSets.js";
+import { createSourceIndex } from "./edit/sourceIndex.js";
+import { isUnderRoot, normalizeFile, } from "./edit/sourceIndex.js";
+import { loadTypeScript } from "./edit/ts.js";
+/** Every box/asset/mask set a loaded frame actually defines. */
+function slotsFor(frame) {
+    const slots = layoutSlots();
+    const found = [];
+    const collect = (container, variant, prefix) => {
+        for (const [layout, config] of Object.entries(container ?? {})) {
+            if (!config || typeof config !== "object") {
+                continue;
+            }
+            const record = config;
+            for (const slot of slots) {
+                const value = record[slot.key];
+                if (!value || typeof value !== "object") {
+                    continue;
+                }
+                found.push({
+                    ...slot,
+                    variant,
+                    layout,
+                    path: [...prefix, layout, slot.key],
+                    ...(slot.kind === "boxes" ? { boxKeys: Object.keys(value) } : {}),
+                });
+            }
+        }
+    };
+    const config = frame.config;
+    collect(config.layouts, null, ["config", "layouts"]);
+    for (const [variant, layouts] of Object.entries(config.alternateLayouts ?? {})) {
+        collect(layouts, variant, ["config", "alternateLayouts", variant]);
+    }
+    return found;
+}
+/**
+ * Rewrites every asset URL to the studio's own endpoint.
+ *
+ * Driven by `walkAssets` rather than a field list, so an asset field added to
+ * the contract is served without touching this.
+ */
+function rewriteAssets(frame) {
+    const plain = JSON.parse(JSON.stringify(frame));
+    for (const occurrence of walkAssets(FrameSchema, plain)) {
+        setAtPath(plain, occurrence.path, `/api/asset?u=${encodeURIComponent(occurrence.url)}`);
+    }
+    return plain;
+}
+/**
+ * Owns the Vite server, the loaded frames, and the last-good cache.
+ *
+ * A frame that fails to load keeps its previous payload — an author mid-save
+ * produces a syntax error on almost every keystroke, and blanking the canvas
+ * each time would make the studio unusable. `loadFrames` already routes every
+ * failure into the reporter instead of throwing, so a failed pass simply
+ * yields no frame for that slug.
+ */
+export async function startSession(root, only = []) {
+    const resolvedRoot = path.resolve(root);
+    const frameServer = await startFrameServer(resolvedRoot);
+    const api = await loadTypeScript();
+    const index = createSourceIndex(api);
+    const cache = new Map();
+    let revision = 0;
+    async function reload(slugs) {
+        invalidateFrameModules(frameServer);
+        const reporter = new Reporter();
+        const wanted = slugs ?? only;
+        const loaded = await loadFrames({ root: resolvedRoot, ...(wanted.length > 0 ? { only: wanted } : {}) }, reporter, frameServer);
+        const seen = new Set();
+        const sourceFiles = [
+            ...frameServer.server.environments.ssr.moduleGraph.fileToModulesMap.keys(),
+        ]
+            .filter((file) => isUnderRoot(file, resolvedRoot) && /\.[cm]?tsx?$/.test(file))
+            .map((file) => relativePosix(resolvedRoot, file))
+            .sort();
+        for (const item of loaded) {
+            const { discovered, frame } = item;
+            seen.add(discovered.slug);
+            revision += 1;
+            const canvas = frame.config.canvas ?? {
+                width: DEFAULT_CANVAS_WIDTH,
+                height: DEFAULT_CANVAS_HEIGHT,
+            };
+            cache.set(discovered.slug, {
+                raw: frame,
+                discovered,
+                payload: {
+                    slug: discovered.slug,
+                    id: discovered.meta.id,
+                    name: frame.name,
+                    revision,
+                    canvas,
+                    frame: rewriteAssets(frame),
+                    slots: slotsFor(frame),
+                    sourceFiles,
+                    problems: reporter.problems.filter((problem) => problem.frame === discovered.slug),
+                    stale: false,
+                },
+            });
+        }
+        // Anything asked for that did not come back kept its last good payload.
+        for (const [slug, entry] of cache) {
+            if (seen.has(slug) || (wanted.length > 0 && !wanted.includes(slug))) {
+                continue;
+            }
+            const problems = reporter.problems.filter((problem) => problem.frame === slug || problem.frame === undefined);
+            cache.set(slug, {
+                ...entry,
+                payload: { ...entry.payload, stale: true, staleProblems: problems },
+            });
+        }
+        return [...seen];
+    }
+    await reload();
+    return {
+        root: resolvedRoot,
+        index,
+        api,
+        frameServer,
+        list: () => [...cache.values()]
+            .map((entry) => ({
+            slug: entry.payload.slug,
+            id: entry.payload.id,
+            name: entry.payload.name,
+            stale: entry.payload.stale,
+        }))
+            .sort((a, b) => a.slug.localeCompare(b.slug)),
+        get: (slug) => cache.get(slug),
+        watchDirs: () => {
+            const dirs = new Set([resolvedRoot]);
+            for (const entry of cache.values()) {
+                dirs.add(normalizeFile(entry.discovered.dir));
+            }
+            return [...dirs];
+        },
+        reload,
+        close: () => frameServer.close(),
+    };
+}
+/** Frames discoverable under `root`, for a startup message. */
+export async function countFrames(root) {
+    return (await discoverFrames(path.resolve(root), new Reporter())).length;
+}

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>;

package/dist/cli/trim.js

@@ -0,0 +1,251 @@
+/**
+ * Trimming: cutting full-sheet art down to the part of it that draws.
+ *
+ * Frame art is authored on the full 3264 × 4440 sheet so that it lines up by
+ * itself, but much of it covers a sliver of that: a Saga banner is under 5% of
+ * its sheet. A renderer decodes, caches and composites every pixel of an image,
+ * transparent or not, so the empty rest costs memory and time on every card.
+ * Trimmed, the image keeps only that sliver, and the frame records where it
+ * sits on the sheet.
+ *
+ * Nothing about how the art looks changes: the pixels kept are byte-for-byte
+ * the same, and the chunks that tell a decoder how to show them (colour
+ * profile, gamma) are carried over. A trimmed image also records its own
+ * position in an `oFFs` chunk, so trimming it again still reports where it
+ * sits on the sheet rather than in itself.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { PNG } from "pngjs";
+import { PackagingError } from "./errors.js";
+/**
+ * The smallest rectangle holding every pixel that is not fully transparent,
+ * or `undefined` when the image has none.
+ */
+export function opaqueBounds({ width, height, data, }) {
+    let left = width;
+    let right = -1;
+    let top = height;
+    let bottom = -1;
+    for (let y = 0; y < height; y++) {
+        const row = y * width * 4;
+        for (let x = 0; x < width; x++) {
+            if (data[row + x * 4 + 3] !== 0) {
+                left = Math.min(left, x);
+                right = Math.max(right, x);
+                top = Math.min(top, y);
+                bottom = y;
+            }
+        }
+    }
+    return right < 0
+        ? undefined
+        : { x: left, y: top, width: right - left + 1, height: bottom - top + 1 };
+}
+/** The smallest rectangle holding all of `rects`, or `undefined` for none. */
+export function unionBounds(rects) {
+    if (rects.length === 0) {
+        return undefined;
+    }
+    const left = Math.min(...rects.map((r) => r.x));
+    const top = Math.min(...rects.map((r) => r.y));
+    const right = Math.max(...rects.map((r) => r.x + r.width));
+    const bottom = Math.max(...rects.map((r) => r.y + r.height));
+    return { x: left, y: top, width: right - left, height: bottom - top };
+}
+/** `pixels` cut down to `rect`, which must lie inside them. */
+export function cropPixels(pixels, rect) {
+    const data = new Uint8Array(rect.width * rect.height * 4);
+    for (let y = 0; y < rect.height; y++) {
+        const from = ((rect.y + y) * pixels.width + rect.x) * 4;
+        data.set(pixels.data.subarray(from, from + rect.width * 4), y * rect.width * 4);
+    }
+    return { width: rect.width, height: rect.height, data };
+}
+const PNG_SIGNATURE = Buffer.from([
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+/** Splits a PNG file into its chunks, without decoding any. */
+function readChunks(file) {
+    const chunks = [];
+    let offset = PNG_SIGNATURE.length;
+    while (offset + 12 <= file.length) {
+        const length = file.readUInt32BE(offset);
+        const end = offset + 12 + length;
+        chunks.push({
+            type: file.toString("latin1", offset + 4, offset + 8),
+            bytes: file.subarray(offset, end),
+            data: file.subarray(offset + 8, offset + 8 + length),
+        });
+        offset = end;
+    }
+    return chunks;
+}
+/**
+ * Chunks that change how a decoder shows the pixels — colour profile, gamma,
+ * chromaticities, significant bits, colour space — plus the pixel density.
+ * The encoder writes none of them, and a browser drawing the art honours
+ * every one, so each is copied from the original.
+ */
+const KEPT_CHUNKS = new Set([
+    "cHRM",
+    "cICP",
+    "gAMA",
+    "iCCP",
+    "mDCV",
+    "cLLI",
+    "sBIT",
+    "sRGB",
+    "pHYs",
+]);
+/** Where an image sits on its sheet, from an `oFFs` chunk in pixels. */
+function readOffset(chunks) {
+    const offs = chunks.find((chunk) => chunk.type === "oFFs");
+    // Unit 0 is pixels; a micrometre offset is someone else's and is ignored.
+    if (offs?.data.length === 9 && offs.data[8] === 0) {
+        return { x: offs.data.readInt32BE(0), y: offs.data.readInt32BE(4) };
+    }
+    return { x: 0, y: 0 };
+}
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+        c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    return c >>> 0;
+});
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (const byte of bytes) {
+        crc = (CRC_TABLE[(crc ^ byte) & 0xff] ?? 0) ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const typeAndData = Buffer.concat([Buffer.from(type, "latin1"), data]);
+    const out = Buffer.alloc(12 + data.length);
+    out.writeUInt32BE(data.length, 0);
+    typeAndData.copy(out, 4);
+    out.writeUInt32BE(crc32(typeAndData), 8 + data.length);
+    return out;
+}
+function offsetChunk(x, y) {
+    const data = Buffer.alloc(9);
+    data.writeInt32BE(x, 0);
+    data.writeInt32BE(y, 4);
+    data.writeUInt8(0, 8);
+    return chunk("oFFs", data);
+}
+/**
+ * Encodes `pixels` as an RGBA PNG carrying `original`'s display chunks and an
+ * `oFFs` chunk at `at`. All of them go straight after the header, which is
+ * before any palette or image data, as the format requires.
+ */
+function encode(pixels, original, at) {
+    const png = new PNG({ width: pixels.width, height: pixels.height });
+    png.data = Buffer.from(pixels.data.buffer, pixels.data.byteOffset, pixels.data.byteLength);
+    const encoded = PNG.sync.write(png, { colorType: 6 });
+    const [header, ...rest] = readChunks(encoded);
+    if (!header) {
+        throw new Error("the PNG encoder wrote no header");
+    }
+    return Buffer.concat([
+        PNG_SIGNATURE,
+        header.bytes,
+        ...original.filter((c) => KEPT_CHUNKS.has(c.type)).map((c) => c.bytes),
+        offsetChunk(at.x, at.y),
+        ...rest.map((c) => c.bytes),
+    ]);
+}
+async function readSource(file) {
+    const bytes = await readFile(file);
+    if (!bytes.subarray(0, 8).equals(PNG_SIGNATURE)) {
+        throw new PackagingError(`${file} is not a PNG. Only PNGs have transparency to trim.`);
+    }
+    const chunks = readChunks(bytes);
+    // Decoding scales 16 bits down to 8, so writing it back would lose detail.
+    const header = chunks[0];
+    if (header?.type === "IHDR" && header.data[8] === 16) {
+        throw new PackagingError(`${file} has 16 bits a channel. Trimming keeps pixels exactly, which ` +
+            "it can only do for 8-bit images.");
+    }
+    const png = PNG.sync.read(bytes);
+    const pixels = { width: png.width, height: png.height, data: png.data };
+    return {
+        file,
+        bytes,
+        chunks,
+        pixels,
+        offset: readOffset(chunks),
+        bounds: opaqueBounds(pixels),
+    };
+}
+/**
+ * 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 async function trimImages(files, options = {}) {
+    const sources = await Promise.all(files.map((file) => readSource(file)));
+    let shared;
+    if (options.shared) {
+        const [first] = sources;
+        const mismatched = sources.find((s) => first &&
+            (s.pixels.width !== first.pixels.width ||
+                s.pixels.height !== first.pixels.height ||
+                s.offset.x !== first.offset.x ||
+                s.offset.y !== first.offset.y));
+        if (first && mismatched) {
+            throw new PackagingError(`--shared needs images of one size at one place on the sheet, but ` +
+                `${mismatched.file} is ${String(mismatched.pixels.width)} × ` +
+                `${String(mismatched.pixels.height)} at ` +
+                `(${String(mismatched.offset.x)}, ${String(mismatched.offset.y)}) ` +
+                `and ${first.file} is ${String(first.pixels.width)} × ` +
+                `${String(first.pixels.height)} at ` +
+                `(${String(first.offset.x)}, ${String(first.offset.y)}).`);
+        }
+        shared = unionBounds(sources.flatMap((s) => (s.bounds ? [s.bounds] : [])));
+    }
+    const images = await Promise.all(sources.map(async (source) => {
+        const crop = options.shared ? shared : source.bounds;
+        const { width, height } = source.pixels;
+        const onSheet = crop && {
+            ...crop,
+            x: source.offset.x + crop.x,
+            y: source.offset.y + crop.y,
+        };
+        const unchanged = !crop ||
+            (crop.x === 0 &&
+                crop.y === 0 &&
+                crop.width === width &&
+                crop.height === height);
+        if (unchanged || options.dryRun) {
+            return {
+                file: source.file,
+                written: undefined,
+                width,
+                height,
+                kept: onSheet,
+            };
+        }
+        const target = options.outDir
+            ? path.join(options.outDir, path.basename(source.file))
+            : source.file;
+        await writeFile(target, encode(cropPixels(source.pixels, crop), source.chunks, onSheet ?? crop));
+        return {
+            file: source.file,
+            written: target,
+            width,
+            height,
+            kept: onSheet,
+        };
+    }));
+    return {
+        images,
+        shared: shared && {
+            ...shared,
+            x: (sources[0]?.offset.x ?? 0) + shared.x,
+            y: (sources[0]?.offset.y ?? 0) + shared.y,
+        },
+    };
+}

package/dist/cli/watch.d.ts

@@ -9,6 +9,9 @@ export interface WatchOptions extends BuildOptions {
  * One Vite server stays alive for the whole session — starting one costs a
  * second or two — and its module graph is dropped before each rebuild so an
  * edit is actually seen. See `invalidateFrameModules`.
+ *
+ * Debouncing, ignore rules and the non-overlapping drain live in
+ * `startSourceWatcher`, shared with `frame-kit studio`.
  */
 export declare function watchFrames(options: WatchOptions): Promise<void>;
 /**