@cardanvil/frame-kit 0.2.0 → 0.3.1

package/README.md

@@ -56,6 +56,7 @@ keeps the literal types.
 ```bash
 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 --help
 ```
@@ -73,6 +74,38 @@ reports everything; under GitHub Actions they become inline annotations.
 
 Exit codes: `0` clean, `1` one or more frames failed, `2` used wrongly.
 
+### `--watch`
+
+`build --watch` builds once, then rebuilds only the frames whose files changed,
+until you stop it. It is meant to be pointed at a folder Card Anvil is linked to,
+so saving a source file updates the preview without any manual step.
+
+```bash
+frame-kit build --out ~/CardAnvilFrames --watch
+```
+
+A failed rebuild leaves the previous bundle in place and prints the problem — the
+app keeps rendering the last good build rather than losing the frame mid-edit.
+Bundles are written atomically, so a watcher on the other side never reads a
+half-written file. `--watch` refuses to combine with `--json` or `--summary-md`,
+which describe a single run that has finished.
+
+Changes are debounced 200 ms, and a rebuild already in flight is allowed to
+finish before the next one starts: two builds writing one bundle would race.
+Output files, dotfiles, `node_modules`, `dist` and editor droppings are ignored,
+so a rebuild cannot trigger itself.
+
+Because bundles are byte-deterministic, saving a file that does not change the
+built output produces an identical bundle, and a consumer watching for content
+changes sees nothing happen — which is correct.
+
+⚠ **Frames are loaded through a long-lived Vite server**, and its SSR module
+cache is invalidated on each pass. Without that a rebuild would re-serve the
+module Vite loaded first, so an edited layout number would rebuild
+byte-identically and the watch would appear to do nothing. If you embed the
+build API yourself, call `invalidateFrameModules` between passes on a server you
+reuse.
+
 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.
@@ -129,8 +162,10 @@ package.
 
 A manifest carries a `contractVersion` of the form `MAJOR.MINOR`, independent of this package's
 version. A differing major is refused; a newer minor loads with a reduced-fidelity warning, because
-added fields are always optional. Packaging preserves everything the contract defines and drops
-everything it does not — keys outside the schema do not survive the round trip.
+added fields are always optional. A layout the loader does not recognise is dropped with a
+degraded note rather than failing the frame, so one new layout cannot cost an author every other
+one. Packaging preserves everything the contract defines and drops everything it does not — keys
+outside the schema do not survive the round trip.
 
 ## Licence
 

package/dist/cli/api.d.ts

@@ -1,5 +1,6 @@
 import { type Frame } from "../schema/frame.js";
 import { type DiscoveredFrame } from "./discover.js";
+import { type FrameServer } from "./loadFrame.js";
 import { Reporter } from "./report.js";
 export interface LoadedFrame {
     discovered: DiscoveredFrame;
@@ -24,7 +25,12 @@ export interface LoadOptions {
  * Shared by `validate` and `build` so the two can never disagree about whether
  * a frame is sound.
  */
-export declare function loadFrames(options: LoadOptions, reporter: Reporter): Promise<LoadedFrame[]>;
+export declare function loadFrames(options: LoadOptions, reporter: Reporter, 
+/**
+ * A server to reuse. When supplied the caller owns its lifetime and this
+ * function will not close it — watch mode keeps one alive across rebuilds.
+ */
+existingServer?: FrameServer): Promise<LoadedFrame[]>;
 export interface ValidateResult {
     reporter: Reporter;
     /** The frames that loaded cleanly. Fewer than were found, if some failed. */

package/dist/cli/api.js

@@ -19,7 +19,12 @@ function toPlain(frame) {
  * Shared by `validate` and `build` so the two can never disagree about whether
  * a frame is sound.
  */
-export async function loadFrames(options, reporter) {
+export async function loadFrames(options, reporter, 
+/**
+ * A server to reuse. When supplied the caller owns its lifetime and this
+ * function will not close it — watch mode keeps one alive across rebuilds.
+ */
+existingServer) {
     const root = path.resolve(options.root);
     const discovered = await discoverFrames(root, reporter);
     const only = new Set(options.only ?? []);
@@ -40,10 +45,9 @@ export async function loadFrames(options, reporter) {
         }
         return [];
     }
-    let frameServer;
+    const frameServer = existingServer ?? (await startFrameServer(root));
     const loaded = [];
     try {
-        frameServer = await startFrameServer(root);
         for (const frame of wanted) {
             const result = await loadOne(frameServer, root, frame, reporter);
             if (result) {
@@ -52,7 +56,9 @@ export async function loadFrames(options, reporter) {
         }
     }
     finally {
-        await frameServer?.close();
+        if (!existingServer) {
+            await frameServer.close();
+        }
     }
     return loaded;
 }

package/dist/cli/atomic.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Writes `file` so that a reader never sees a partial one.
+ *
+ * Watch mode means something else is reading this directory while it is being
+ * written — Card Anvil re-reads a bundle the moment it changes. Writing in
+ * place would hand it a truncated zip whenever the timing was unlucky, so
+ * every output is written to a temp file and renamed into position, which is
+ * atomic on every platform this runs on — see {@link renameWhenFree} for the
+ * one thing Windows asks for in return.
+ */
+export declare function writeFileAtomic(file: string, data: string | Uint8Array): Promise<void>;
+/** Streams to `file` atomically. Returns the number of bytes written. */
+export declare function writeStreamAtomic(file: string, stream: NodeJS.ReadableStream): Promise<number>;
+/** Copies to `dest` atomically. */
+export declare function copyFileAtomic(source: string, dest: string): Promise<void>;

package/dist/cli/atomic.js

@@ -0,0 +1,114 @@
+import { createWriteStream } from "node:fs";
+import { copyFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { setTimeout as delay } from "node:timers/promises";
+/**
+ * A temp name beside the destination.
+ *
+ * Beside, not in the system temp directory: `rename` is only atomic within one
+ * filesystem, and an author's output directory is frequently on a different
+ * volume from /tmp.
+ */
+function tempFor(file) {
+    return path.join(path.dirname(file), `.${path.basename(file)}.${String(process.pid)}.tmp`);
+}
+async function discard(temp) {
+    await rm(temp, { force: true });
+}
+/**
+ * What Windows reports when something else has the destination open.
+ *
+ * `EBUSY` and `EACCES` for the same situation on network shares and some
+ * antivirus filters.
+ */
+const HELD_OPEN = new Set(["EPERM", "EACCES", "EBUSY"]);
+/** Backoff between rename attempts. */
+const RETRY_DELAYS_MS = [10, 20, 40, 80, 160, 320, 640, 1000];
+const TOTAL_WAIT_MS = RETRY_DELAYS_MS.reduce((a, b) => a + b, 0);
+/**
+ * Renames, waiting out anything that has the destination open.
+ *
+ * POSIX lets a file be replaced while it is being read. Windows does not: a
+ * rename onto a path some process holds open fails outright. A linked folder
+ * exists precisely to be read — Card Anvil re-reads a bundle whenever it
+ * changes — so a rebuild that lands mid-read hits this, and so do antivirus
+ * and search indexers, which open files briefly on their own schedule.
+ *
+ * Waiting is the whole fix: whatever holds the file is finishing a read that
+ * takes milliseconds. A real permission problem still fails, two seconds later.
+ */
+async function renameWhenFree(temp, file) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            await rename(temp, file);
+            return;
+        }
+        catch (cause) {
+            const code = cause.code ?? "";
+            if (!HELD_OPEN.has(code)) {
+                throw cause;
+            }
+            const wait = RETRY_DELAYS_MS[attempt];
+            if (wait === undefined) {
+                // `EPERM: operation not permitted, rename` says nothing about what to
+                // do. Whatever is holding the file is the thing to go and close.
+                throw new Error(`could not replace ${path.basename(file)}: something still has it open after ${String(TOTAL_WAIT_MS)}ms (${code}). On Windows a file cannot be replaced while another process holds it — close whatever is reading it, or point the build somewhere else.`, { cause });
+            }
+            await delay(wait);
+        }
+    }
+}
+/**
+ * Writes `file` so that a reader never sees a partial one.
+ *
+ * Watch mode means something else is reading this directory while it is being
+ * written — Card Anvil re-reads a bundle the moment it changes. Writing in
+ * place would hand it a truncated zip whenever the timing was unlucky, so
+ * every output is written to a temp file and renamed into position, which is
+ * atomic on every platform this runs on — see {@link renameWhenFree} for the
+ * one thing Windows asks for in return.
+ */
+export async function writeFileAtomic(file, data) {
+    const temp = tempFor(file);
+    try {
+        await writeFile(temp, data);
+        await renameWhenFree(temp, file);
+    }
+    catch (cause) {
+        await discard(temp);
+        throw cause;
+    }
+}
+/** Streams to `file` atomically. Returns the number of bytes written. */
+export async function writeStreamAtomic(file, 
+// The broad interface rather than node:stream's Readable, because yazl types
+// its output stream this way.
+stream) {
+    const temp = tempFor(file);
+    let bytes = 0;
+    stream.on("data", (chunk) => {
+        bytes += chunk.length;
+    });
+    try {
+        await pipeline(stream, createWriteStream(temp));
+        await renameWhenFree(temp, file);
+        return bytes;
+    }
+    catch (cause) {
+        await discard(temp);
+        throw cause;
+    }
+}
+/** Copies to `dest` atomically. */
+export async function copyFileAtomic(source, dest) {
+    const temp = tempFor(dest);
+    try {
+        await copyFile(source, temp);
+        await renameWhenFree(temp, dest);
+    }
+    catch (cause) {
+        await discard(temp);
+        throw cause;
+    }
+}

package/dist/cli/build.d.ts

@@ -1,6 +1,7 @@
 import { type FrameManifest } from "../manifest/index.js";
 import { type LoadOptions, type LoadedFrame } from "./api.js";
 import { type FrameIndex, type IndexedFrame, type ReleaseSource } from "./frameIndex.js";
+import type { FrameServer } from "./loadFrame.js";
 import type { Reporter } from "./report.js";
 export interface BuildOptions extends LoadOptions {
     /** Directory bundles and the index are written to. Created if missing. */
@@ -33,4 +34,6 @@ export interface BuildResult {
  * Frames that fail to load are reported and skipped rather than aborting the
  * run, so one bad frame does not hide the state of the others.
  */
-export declare function buildFrames(options: BuildOptions, reporter: Reporter): Promise<BuildResult>;
+export declare function buildFrames(options: BuildOptions, reporter: Reporter, 
+/** A server to reuse. Passed straight to loadFrames; see its note. */
+existingServer?: FrameServer): Promise<BuildResult>;

package/dist/cli/build.js

@@ -1,8 +1,9 @@
-import { copyFile, mkdir, stat, writeFile } from "node:fs/promises";
+import { mkdir, stat } from "node:fs/promises";
 import path from "node:path";
 import { FrameManifestSchema, frameToManifest, manifestToFrame, } from "../manifest/index.js";
 import { DEFAULT_CANVAS_HEIGHT, DEFAULT_CANVAS_WIDTH, } from "../schema/frame.js";
 import { loadFrames } from "./api.js";
+import { copyFileAtomic, writeFileAtomic } from "./atomic.js";
 import { describeBytes, writeBundle } from "./bundle.js";
 import { PackagingError } from "./errors.js";
 import { FRAME_INDEX_FILENAME, buildIndex, downloadBase, } from "./frameIndex.js";
@@ -20,12 +21,14 @@ const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
  * Frames that fail to load are reported and skipped rather than aborting the
  * run, so one bad frame does not hide the state of the others.
  */
-export async function buildFrames(options, reporter) {
+export async function buildFrames(options, reporter, 
+/** A server to reuse. Passed straight to loadFrames; see its note. */
+existingServer) {
     if (!VERSION_PATTERN.test(options.version)) {
         throw new PackagingError(`"${options.version}" is not a version. Expected MAJOR.MINOR.PATCH, ` +
             `optionally with a pre-release suffix.`);
     }
-    const loaded = await loadFrames(options, reporter);
+    const loaded = await loadFrames(options, reporter, existingServer);
     const outDir = path.resolve(options.outDir);
     await mkdir(outDir, { recursive: true });
     const built = [];
@@ -46,7 +49,7 @@ export async function buildFrames(options, reporter) {
         ...(options.source === undefined ? {} : { source: options.source }),
         frames: built.map((frame) => frame.entry),
     });
-    await writeFile(path.join(outDir, FRAME_INDEX_FILENAME), stableStringify(index), "utf8");
+    await writeFileAtomic(path.join(outDir, FRAME_INDEX_FILENAME), stableStringify(index));
     return { frames: built, index };
 }
 async function buildOne(loaded, outDir, options, reporter) {
@@ -65,6 +68,7 @@ async function buildOne(loaded, outDir, options, reporter) {
                 ? {}
                 : { generator: options.generator }),
             author: loaded.discovered.meta.author,
+            license: loaded.discovered.meta.license,
             resolveAsset: (url) => {
                 const asset = byUrl.get(url);
                 if (asset === undefined) {
@@ -179,7 +183,7 @@ async function indexEntry(loaded, manifest, bundle, fileByPath, outDir, options)
         throw new PackagingError(`the preview image is not among the packaged assets — this is a bug in frame-kit`);
     }
     const previewName = `${slug}-${options.version}.preview${path.extname(previewSource).toLowerCase()}`;
-    await copyFile(previewSource, path.join(outDir, previewName));
+    await copyFileAtomic(previewSource, path.join(outDir, previewName));
     const [previewHash, previewStats, size, bundleHash] = await Promise.all([
         hashFile(previewSource),
         stat(previewSource),

package/dist/cli/bundle.js

@@ -1,6 +1,5 @@
-import { createWriteStream } from "node:fs";
-import { pipeline } from "node:stream/promises";
 import yazl from "yazl";
+import { writeStreamAtomic } from "./atomic.js";
 import { PackagingError } from "./errors.js";
 import { stableStringify } from "./stableJson.js";
 /** The earliest instant a DOS timestamp can express. */
@@ -41,11 +40,10 @@ export async function writeBundle(outFile, manifest, source) {
         });
     }
     zip.end();
-    let bytes = 0;
-    zip.outputStream.on("data", (chunk) => {
-        bytes += chunk.length;
-    });
-    await pipeline(zip.outputStream, createWriteStream(outFile));
+    // Written to a temp file and renamed: watch mode means Card Anvil may be
+    // reading this directory while it is being written, and a partial zip is
+    // indistinguishable from a corrupt one.
+    const bytes = await writeStreamAtomic(outFile, zip.outputStream);
     if (bytes > MAX_BUNDLE_BYTES) {
         throw new PackagingError(`${outFile} is ${describeBytes(bytes)}, over GitHub's 2 GiB limit for a ` +
             `release asset. Split the frame, or use smaller art.`);

package/dist/cli/loadFrame.d.ts

@@ -1,4 +1,14 @@
 import type { ViteDevServer } from "vite";
+/**
+ * Drops the SSR module graph so the next load re-reads from disk.
+ *
+ * Watch mode reuses one server across rebuilds, because starting one costs a
+ * second or two and a fresh dependency cache. Without this, ssrLoadModule
+ * serves the module it loaded the first time, and a rebuild produces
+ * byte-identical output no matter what the author just changed — the watch
+ * loop would appear to run and do nothing.
+ */
+export declare function invalidateFrameModules(frameServer: FrameServer): void;
 export interface FrameServer {
     readonly server: ViteDevServer;
     /** Absolute project root every asset URL is relative to. */

package/dist/cli/loadFrame.js

@@ -22,6 +22,20 @@ async function importVite() {
             "  pnpm add -D vite\n");
     }
 }
+/**
+ * Drops the SSR module graph so the next load re-reads from disk.
+ *
+ * Watch mode reuses one server across rebuilds, because starting one costs a
+ * second or two and a fresh dependency cache. Without this, ssrLoadModule
+ * serves the module it loaded the first time, and a rebuild produces
+ * byte-identical output no matter what the author just changed — the watch
+ * loop would appear to run and do nothing.
+ */
+export function invalidateFrameModules(frameServer) {
+    // Both supported Vite majors expose the SSR module graph here; the legacy
+    // top-level accessor is deprecated.
+    frameServer.server.environments.ssr.moduleGraph.invalidateAll();
+}
 /**
  * Starts one Vite server for a whole packaging run.
  *

package/dist/cli/main.js

@@ -9,6 +9,7 @@ import { PackagingError } from "./errors.js";
 import { Reporter, inGitHubActions } from "./report.js";
 import { SCHEMA_NAMES, toJsonSchema } from "./schema.js";
 import { stableStringify } from "./stableJson.js";
+import { watchFrames } from "./watch.js";
 const USAGE = `frame-kit — package Card Anvil frames
 
 Usage:
@@ -32,6 +33,7 @@ build only:
   --repository <o/n>    the GitHub repository the release belongs to
   --tag <vX.Y.Z>        the release tag; with --repository, puts download URLs
                         in the index
+  --watch               rebuild a frame whenever its source changes
 
 A frame is any directory containing a frame.meta.json.
 `;
@@ -100,6 +102,22 @@ async function runBuild(root, only, values) {
         return EXIT.usage;
     }
     const version = values.version ?? (await repositoryVersion(root));
+    if (values.watch) {
+        // Both are one-shot shapes meant for CI, and neither means anything for a
+        // process that never finishes.
+        if (values.json || values["summary-md"] !== undefined) {
+            console.error("--watch cannot be combined with --json or --summary-md.");
+            return EXIT.usage;
+        }
+        await watchFrames({
+            root,
+            only,
+            outDir: values.out,
+            version,
+            generator: `@cardanvil/frame-kit@${await packageVersion()}`,
+        });
+        return EXIT.ok;
+    }
     const reporter = new Reporter();
     const { frames: built } = await buildFrames({
         root,
@@ -198,6 +216,7 @@ async function main(argv) {
                 version: { type: "string" },
                 repository: { type: "string" },
                 tag: { type: "string" },
+                watch: { type: "boolean" },
             },
             strict: true,
         }));

package/dist/cli/watch.d.ts

@@ -0,0 +1,21 @@
+import { type BuildOptions } from "./build.js";
+export interface WatchOptions extends BuildOptions {
+    /** Called after every rebuild so the CLI can report it. */
+    onBuild?: (summary: string) => void;
+}
+/**
+ * Rebuilds frames as their sources change, until the process is interrupted.
+ *
+ * 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`.
+ */
+export declare function watchFrames(options: WatchOptions): Promise<void>;
+/**
+ * Which frames a set of changed paths affects.
+ *
+ * `undefined` means "rebuild everything" — a descriptor appeared or vanished,
+ * or something outside every frame directory changed (a shared module, a
+ * workspace file), and we cannot know what depends on it.
+ */
+export declare function slugsFor(root: string, changed: readonly string[], only: readonly string[] | undefined): Promise<string[] | undefined>;

package/dist/cli/watch.js

@@ -0,0 +1,164 @@
+import { watch } from "node:fs";
+import path from "node:path";
+import { buildFrames } from "./build.js";
+import { discoverFrames, relativePosix } from "./discover.js";
+import { invalidateFrameModules, startFrameServer } from "./loadFrame.js";
+import { Reporter, formatProblem } from "./report.js";
+/** Directories never worth watching. Mirrors discovery's own skip list. */
+const SKIP_DIRS = new Set([
+    "node_modules",
+    "dist",
+    ".git",
+    ".pnpm-store",
+    "__fixtures__",
+]);
+/** Files a rebuild produces, or an editor leaves lying around. */
+const IGNORED_FILE = /(\.cardframe|frame-index\.json|\.preview\.[a-z]+|~|\.swp|\.tmp)$/i;
+/**
+ * How long to wait for changes to stop before rebuilding.
+ *
+ * One save can produce several events — a write, a rename, an attribute
+ * change — and a tool upstream may rewrite a whole directory.
+ */
+const DEBOUNCE_MS = 200;
+function isIgnored(file) {
+    const segments = file.split(path.sep);
+    return (segments.some((segment) => SKIP_DIRS.has(segment) || segment.startsWith(".")) || IGNORED_FILE.test(file));
+}
+const plural = (n) => `${String(n)} frame${n === 1 ? "" : "s"}`;
+/**
+ * Rebuilds frames as their sources change, until the process is interrupted.
+ *
+ * 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`.
+ */
+export async function watchFrames(options) {
+    const root = path.resolve(options.root);
+    const outDir = path.resolve(options.outDir);
+    const report = options.onBuild ??
+        ((summary) => {
+            console.log(summary);
+        });
+    const frameServer = await startFrameServer(root);
+    const watchers = [];
+    const pending = new Set();
+    let timer;
+    let building = false;
+    function runBuild(only) {
+        invalidateFrameModules(frameServer);
+        const reporter = new Reporter();
+        const started = Date.now();
+        return buildFrames({ ...options, ...(only === undefined ? {} : { only }) }, reporter, frameServer).then(({ frames }) => {
+            for (const problem of reporter.problems) {
+                console.error(`${problem.severity}: ${formatProblem(problem)}`);
+            }
+            report(`${plural(frames.length)} rebuilt in ${String(Date.now() - started)}ms`);
+        });
+    }
+    async function drain() {
+        if (building) {
+            // Two builds would race on the same output file. Whatever arrived is
+            // already in `pending`, and the loop below will pick it up.
+            return;
+        }
+        building = true;
+        try {
+            // Keyed off `pending` rather than a flag: anything that arrived during a
+            // build is still queued when it finishes.
+            while (pending.size > 0) {
+                const changed = [...pending];
+                pending.clear();
+                const slugs = await slugsFor(root, changed, options.only);
+                if (slugs?.length === 0) {
+                    continue; // nothing we build was touched
+                }
+                await runBuild(slugs);
+            }
+        }
+        catch (cause) {
+            // A failed rebuild must not end the session: the author is mid-edit and
+            // the next save is probably the fix.
+            console.error(cause instanceof Error ? cause.message : String(cause));
+        }
+        finally {
+            building = false;
+        }
+    }
+    function onChange(file) {
+        if (isIgnored(file) || file.startsWith(outDir)) {
+            return;
+        }
+        pending.add(file);
+        if (timer) {
+            clearTimeout(timer);
+        }
+        timer = setTimeout(() => void drain(), DEBOUNCE_MS);
+    }
+    function watchDir(dir) {
+        try {
+            watchers.push(watch(dir, { recursive: true }, (_event, name) => {
+                if (name !== null) {
+                    onChange(path.join(dir, name));
+                }
+            }));
+        }
+        catch {
+            console.error(`Could not watch ${relativePosix(root, dir)}. Recursive watching is ` +
+                `not supported on this filesystem; rebuild with \`frame-kit build\`.`);
+        }
+    }
+    try {
+        await runBuild(undefined);
+        // Each frame's own directory, plus the root, so a frame added or removed
+        // while watching is noticed.
+        for (const frame of await discoverFrames(root, new Reporter())) {
+            watchDir(frame.dir);
+        }
+        watchDir(root);
+        report("Watching for changes. Press Ctrl+C to stop.");
+        await new Promise((resolve) => {
+            const stop = () => {
+                resolve();
+            };
+            process.once("SIGINT", stop);
+            process.once("SIGTERM", stop);
+        });
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+        for (const watcher of watchers) {
+            watcher.close();
+        }
+        await frameServer.close();
+    }
+}
+/**
+ * Which frames a set of changed paths affects.
+ *
+ * `undefined` means "rebuild everything" — a descriptor appeared or vanished,
+ * or something outside every frame directory changed (a shared module, a
+ * workspace file), and we cannot know what depends on it.
+ */
+export async function slugsFor(root, changed, only) {
+    if (changed.some((file) => path.basename(file) === "frame.meta.json")) {
+        return undefined;
+    }
+    const discovered = await discoverFrames(root, new Reporter());
+    const wanted = new Set(only ?? []);
+    const slugs = new Set();
+    for (const file of changed) {
+        const owner = discovered
+            .filter((frame) => file.startsWith(frame.dir + path.sep))
+            .sort((a, b) => b.dir.length - a.dir.length)[0];
+        if (!owner) {
+            return undefined; // outside every frame — something shared changed
+        }
+        if (wanted.size === 0 || wanted.has(owner.slug)) {
+            slugs.add(owner.slug);
+        }
+    }
+    return [...slugs];
+}

package/dist/manifest/contract.d.ts

@@ -11,7 +11,7 @@ import { z } from "zod";
  *   because parsing strips unknown keys; they should warn that the frame may
  *   render with reduced fidelity.
  */
-export declare const CONTRACT_VERSION = "1.0";
+export declare const CONTRACT_VERSION = "1.1";
 /** The only manifest kind any loader understands today. */
 export declare const DECLARATIVE_KIND = "declarative";
 export declare const AssetEntrySchema: z.ZodObject<{
@@ -30,6 +30,7 @@ export declare const FrameManifestSchema: z.ZodObject<{
         name: z.ZodString;
         url: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    license: z.ZodOptional<z.ZodString>;
     frame: z.ZodObject<{
         name: z.ZodString;
         description: z.ZodString;

package/dist/manifest/contract.js

@@ -12,7 +12,7 @@ import { FrameSchema } from "../schema/frame.js";
  *   because parsing strips unknown keys; they should warn that the frame may
  *   render with reduced fidelity.
  */
-export const CONTRACT_VERSION = "1.0";
+export const CONTRACT_VERSION = "1.1";
 /** The only manifest kind any loader understands today. */
 export const DECLARATIVE_KIND = "declarative";
 export const AssetEntrySchema = z.object({
@@ -36,6 +36,14 @@ export const FrameManifestSchema = z.object({
     version: z.string(),
     generator: z.string().optional(),
     author: z.object({ name: z.string(), url: z.string().optional() }).optional(),
+    /**
+     * How the frame's art is licensed, as declared in its descriptor.
+     *
+     * Optional because contract 1.0 bundles predate it. Added in 1.1 so an
+     * installed frame carries its licence with it — before this it existed only
+     * in the release index, which an installed bundle does not travel with.
+     */
+    license: z.string().optional(),
     /** The frame itself, with every asset URL rewritten to a relative path. */
     frame: FrameSchema,
     /** Integrity index for the packaged files. Loaders may ignore it. */

package/dist/manifest/deserialize.d.ts

@@ -7,8 +7,9 @@ export interface ManifestToFrameOptions {
      */
     resolveUrl: (path: string) => string;
     /**
-     * Called when the manifest targets a newer minor contract than this build.
-     * The frame still loads; some fields may be ignored.
+     * Called when the frame loads but not in full fidelity — it targets a newer
+     * minor contract than this build, or it configures layouts this build does
+     * not know about. Called once per reason.
      */
     onDegraded?: (reason: string) => void;
 }

package/dist/manifest/deserialize.js

@@ -1,12 +1,82 @@
 import { FrameSchema } from "../schema/frame.js";
+import { layouts } from "../schema/layout.js";
 import { FrameManifestSchema, assertDeclarative, isContractCompatible, } from "./contract.js";
 import { setAtPath, walkAssets } from "./walk.js";
+const KNOWN_LAYOUTS = new Set(layouts);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Filters one layout map, recording every key it had to drop. */
+function pruneLayoutMap(value, dropped) {
+    if (!isRecord(value)) {
+        return value;
+    }
+    const unknown = Object.keys(value).filter((key) => !KNOWN_LAYOUTS.has(key));
+    if (unknown.length === 0) {
+        return value;
+    }
+    dropped.push(...unknown);
+    return Object.fromEntries(Object.entries(value).filter(([key]) => KNOWN_LAYOUTS.has(key)));
+}
+/** Filters every variant's layout map under `config.alternateLayouts`. */
+function pruneAlternateLayouts(value, dropped) {
+    if (!isRecord(value)) {
+        return value;
+    }
+    const next = {};
+    let changed = false;
+    for (const [variant, map] of Object.entries(value)) {
+        const pruned = pruneLayoutMap(map, dropped);
+        changed ||= pruned !== map;
+        next[variant] = pruned;
+    }
+    return changed ? next : value;
+}
+/**
+ * Strips layout keys this build does not recognise, before the manifest is
+ * parsed.
+ *
+ * `config.layouts` is a `partialRecord` over a closed enum, so an unknown key
+ * is a hard error rather than a stripped one — the one place a minor contract
+ * bump can still reject a whole frame outright, which is exactly what the
+ * degrade policy exists to prevent. Dropping the key costs that one layout and
+ * keeps the rest of the frame.
+ *
+ * Returns the manifest untouched when there is nothing to drop, so the ordinary
+ * case does not pay for a copy.
+ */
+function dropUnknownLayouts(manifest, onDegraded) {
+    if (!isRecord(manifest) || !isRecord(manifest.frame)) {
+        return manifest;
+    }
+    const frame = manifest.frame;
+    const config = frame.config;
+    if (!isRecord(config)) {
+        return manifest;
+    }
+    const dropped = [];
+    const prunedLayouts = pruneLayoutMap(config.layouts, dropped);
+    const prunedAlternates = pruneAlternateLayouts(config.alternateLayouts, dropped);
+    if (dropped.length === 0) {
+        return manifest;
+    }
+    const names = [...new Set(dropped)].sort();
+    onDegraded?.(`ignoring ${String(names.length)} unknown layout(s) this build does not support: ${names.join(", ")}`);
+    const nextConfig = {
+        ...config,
+        layouts: prunedLayouts,
+    };
+    if (prunedAlternates !== undefined) {
+        nextConfig.alternateLayouts = prunedAlternates;
+    }
+    return { ...manifest, frame: { ...frame, config: nextConfig } };
+}
 /**
  * Validates a manifest and rebuilds a loadable {@link Frame} from it, turning
  * every package-relative asset path back into a URL.
  */
 export function manifestToFrame(manifest, options) {
-    const parsed = FrameManifestSchema.parse(manifest);
+    const parsed = FrameManifestSchema.parse(dropUnknownLayouts(manifest, options.onDegraded));
     const compatibility = isContractCompatible(parsed.contractVersion);
     if (!compatibility.ok) {
         throw new Error(compatibility.reason ?? "incompatible contract version");

package/dist/manifest/serialize.d.ts

@@ -15,6 +15,7 @@ export interface FrameToManifestOptions {
         name: string;
         url?: string;
     };
+    license?: string;
     /**
      * Maps a build-time asset URL to its packaged location.
      *

package/dist/manifest/serialize.js

@@ -37,6 +37,7 @@ export function frameToManifest(frame, options) {
             ? {}
             : { generator: options.generator }),
         ...(options.author === undefined ? {} : { author: options.author }),
+        ...(options.license === undefined ? {} : { license: options.license }),
         frame: rewritten,
         // Sorted so the manifest is byte-stable across builds and diffs cleanly.
         assets: [...assetsByPath.values()].sort((a, b) => a.path.localeCompare(b.path)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardanvil/frame-kit",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "The contract Card Anvil frames are authored against: schemas, types, authoring helpers, and the distributable manifest format.",
   "license": "MIT",
   "type": "module",