orca-gallery-panel 0.0.0-stage → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaime Errázuriz Werth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,205 @@
-# Temporary Holding Version
+# Orca Gallery Panel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/jerrazuw/orca-gallery-panel/actions/workflows/ci.yml/badge.svg)](https://github.com/jerrazuw/orca-gallery-panel/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Background images for [Orca](https://orca.dev), the agent IDE.** Orca has no setting for a
+wallpaper or background image, so this plugin adds a side panel that shows a rotating gallery of
+your own pictures while your agents work: wallpapers, photos, art, mood boards.
+
+You point it at a folder, it packs the images into an Orca panel plugin, and the panel shuffles
+through them with a slideshow, a blurred background, an optional Ken Burns zoom and controls you
+can change without leaving Orca.
+
+![The gallery panel in Orca's dark and light themes, with the display settings menu open](docs/screenshot.png)
+
+## Features
+
+- **Slideshow**: shuffles your images and changes them on an interval you choose. Every image
+  shows once before any repeats, and the same one never appears twice in a row.
+- **Controls** on hover: previous, pause/resume, next, a position counter, interval, display
+  settings and fit/fill.
+- **Settings in the panel**: click the clock to type the seconds between images (`0` stops the
+  automatic change), or the sliders to turn on a blurred background, a slow Ken Burns zoom or
+  the image's name. Changes last until Orca reloads the panel, because Orca gives panels no
+  storage; the defaults come from your build settings.
+- **Blurred background**: an image that doesn't fill the panel sits on a blurred copy of itself
+  instead of empty bars.
+- **Several galleries**, each in its own panel, from one config file.
+- **Watch mode**: `--watch` rebuilds whenever you add or remove images, and Orca reloads the
+  panel, so a new photo shows up without touching the terminal.
+- **Keyboard**: `←` / `→` to navigate, `Space` to pause, `F` to switch between fit and fill.
+- **Matches Orca's theme**, light or dark, using the design tokens Orca gives every panel.
+- **Any common format**: PNG, JPEG, GIF, WebP, AVIF and TIFF. Animated GIF and WebP stay
+  animated, and EXIF rotation is applied.
+- **English and Spanish**, picked from the system language.
+- **Accessible**: labeled buttons, visible focus, and no fade if you have reduced motion turned on.
+- **Private**: the plugin asks Orca for no permissions and makes no network requests.
+
+## Quick start
+
+Requires [Node.js](https://nodejs.org) 22.18 or later and Orca 1.4.160 or later.
+
+```bash
+mkdir ~/orca-gallery && cd ~/orca-gallery
+npx orca-gallery-panel ~/Pictures/wallpapers --title "Wallpapers"
+```
+
+The plugin is written to `dist/` in the current folder. In Orca, go to
+**Settings → Plugins → Development**, click **Add path** and enter the full path to `dist/`
+(here `~/orca-gallery/dist`). Then open the panel from the right sidebar.
+
+The examples below use `npm run build`, which is how the command runs from a clone of this
+repository. With `npx`, replace `npm run build --` with `npx orca-gallery-panel` and run it from
+the same folder each time, so it finds your `gallery.config.json` and rebuilds the same `dist/`.
+
+To work from a clone instead (also the way to try the bundled samples with
+`npm run build -- examples/images`):
+
+```bash
+git clone https://github.com/jerrazuw/orca-gallery-panel.git
+cd orca-gallery-panel
+npm install
+npm run build -- ~/Pictures/wallpapers --title "Wallpapers"
+```
+
+### Saving your settings
+
+Instead of repeating options on every build, copy the example config and edit it:
+
+```bash
+cp gallery.config.example.json gallery.config.json
+```
+
+```json
+{
+  "$schema": "./gallery.config.schema.json",
+  "folder": "~/Pictures/wallpapers",
+  "title": "Wallpapers",
+  "interval": 60
+}
+```
+
+From then on, `npm run build` is enough. `gallery.config.json` is ignored by git, so your paths
+stay on your machine. The `$schema` line gives you autocomplete and validation in editors that
+support JSON Schema. Options passed on the command line still override the file for that build,
+and `--config <file>` reads a different one.
+
+### Updating your images
+
+Add or remove files in your folder and run `npm run build` again. A plugin loaded from
+**Development** reloads on its own.
+
+Or leave `npm run build -- --watch` running: it rebuilds whenever an image in your folders or
+the config file changes, and a burst of changes (copying 20 photos at once) triggers a single
+rebuild.
+
+If you installed it with **Install plugin → Local folder** instead, Orca keeps a copy, so you
+need to install it again after each build.
+
+## Options
+
+| Option                  | Config key  | Default   | Description                                       |
+| ----------------------- | ----------- | --------- | ------------------------------------------------- |
+| `[folder]`              | `folder`    | `images`  | Folder with your images.                          |
+| `-o, --out <dir>`       | `out`       | `dist`    | Output folder for the plugin.                     |
+| `-t, --title <text>`    | `title`     | `Gallery` | Panel title shown in Orca.                        |
+| `-i, --interval <sec>`  | `interval`  | `180`     | Seconds between images. `0` disables rotation.    |
+| `-s, --max-size <px>`   | `maxSize`   | `800`     | Longest side of each image, in pixels.            |
+| `-q, --quality <1-100>` | `quality`   | `80`      | WebP quality.                                     |
+| `--fit <mode>`          | `fit`       | `contain` | Initial mode: `contain` (whole image) or `cover`. |
+| `--effect <name>`       | `effect`    | `none`    | `none`, or `kenburns` for a slow zoom.            |
+| `--no-blur`             | `blur`      | `true`    | Blurred background behind images.                 |
+| `--caption`             | `caption`   | `false`   | Show the image's file name.                       |
+| `-r, --recursive`       | `recursive` | `false`   | Include images in subfolders.                     |
+|                         | `galleries` |           | Several galleries; see above.                     |
+| `-w, --watch`           |             |           | Rebuild when images or the config file change.    |
+| `-c, --config <file>`   |             |           | Config file to read instead of the default.       |
+
+Precedence: command line, then the gallery's own settings, then the top level of
+`gallery.config.json`, then the defaults. Paths in the config file are relative to the file, and
+`~` means your home folder. The `fit`, `interval`, `blur`, `effect` and `caption` settings are
+only where the panel starts: you can change them from the panel itself.
+
+### Several galleries
+
+List them under `galleries`. Each one becomes its own panel in Orca. Settings at the top level
+apply to every gallery unless it sets its own; the top-level `title` names the plugin, and a
+gallery without a `title` is named after its folder.
+
+```json
+{
+  "$schema": "./gallery.config.schema.json",
+  "title": "My galleries",
+  "interval": 120,
+  "galleries": [
+    { "folder": "~/Pictures/wallpapers", "title": "Wallpapers", "effect": "kenburns" },
+    { "folder": "~/Pictures/art", "interval": 30, "caption": true }
+  ]
+}
+```
+
+Each panel has to stay under Orca's 10 MiB limit for a panel, and all of them together under
+its 50 MiB limit for a plugin.
+
+## How it works
+
+Orca renders a plugin panel as a sandboxed `srcdoc` iframe whose Content Security Policy only
+allows inline scripts and styles and `data:` images. A panel cannot read files from disk, and
+Orca's plugin API gives it no file or folder access either.
+
+So the images are packed into the panel when you build it:
+
+1. `src/images.ts` finds the supported images in your folder, in natural order.
+2. `src/encode.ts` uses [sharp](https://sharp.pixelplumbing.com) to apply EXIF rotation, shrink
+   each image to `--max-size` and re-encode it as WebP. That keeps transparency and animation,
+   and is far smaller than base64-encoded PNGs or GIFs.
+3. `src/html.ts` bundles the panel script (`src/panel/`, TypeScript) with
+   [esbuild](https://esbuild.github.io) and inlines it, the CSS and the images into one
+   `panel.html`.
+4. `src/build.ts` checks the result against Orca's 10 MiB limit for a panel. If it's over, it
+   names the largest images and suggests what to change.
+5. `src/manifest.ts` writes `orca-plugin.json`, taking the version from `package.json`, with
+   one panel per gallery.
+
+At the default settings a typical photo ends up around 40 KB, so the limit fits a couple of
+hundred images. Animated GIFs are much heavier.
+
+## Development
+
+```bash
+npm run check        # typecheck, lint, format check and unit tests
+npm run test:e2e     # the panel in headless Chromium (first run: npx playwright install chromium)
+npm run preview      # writes dist/preview.html: the built panel inside an Orca-like frame
+```
+
+| Path                           | What it is                                                                    |
+| ------------------------------ | ----------------------------------------------------------------------------- |
+| `src/cli.ts`, `src/options.ts` | Command-line entry point and argument parsing.                                |
+| `src/build.ts`                 | Builds the plugin: find, encode, render, check size, write.                   |
+| `src/panel/`                   | The code that runs inside Orca: slideshow, controls, translations and styles. |
+| `src/watch.ts`                 | Watch mode: reruns the build when the watched folders change.                 |
+| `src/preview.ts`               | Reproduces Orca's panel shell so the panel can be checked in a browser.       |
+| `test/`                        | Unit tests (`node:test`) and browser tests (`test/e2e/`, Playwright).         |
+| `examples/images/`             | Sample images, made by `scripts/generate-examples.ts`.                        |
+
+TypeScript runs directly on Node through
+[type stripping](https://nodejs.org/api/typescript.html#type-stripping), so there is no compile
+step while you work on it. Node won't strip types inside `node_modules`, so the npm package is
+compiled to `lib/` by `npm run build:lib`, which `npm pack` runs on its own. CI runs on Linux,
+macOS and Windows with Node 22.18, 22 and 24, and installs the packed package in an empty
+project to check that the command works.
+
+## Why it isn't in the Orca marketplace
+
+Plugins in the [Orca marketplace](https://github.com/stablyai/orca-plugins) are installed from a
+git repository as they are, but this panel only works once it has been built with your images. A marketplace entry could only ship the sample gallery.
+
+## Contributing
+
+Issues and pull requests are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE). The sample images in `examples/images/` are generated by code in this repository
+and are covered by the same license.

package/gallery.config.example.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "./gallery.config.schema.json",
+  "folder": "~/Pictures/wallpapers",
+  "title": "Wallpapers",
+  "interval": 60
+}

package/gallery.config.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Orca Gallery Panel settings",
+  "description": "Saved options for the gallery build. Command-line options override these.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "folder": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Folder with your images. Relative paths start from this file; ~ is your home folder.",
+      "default": "images"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "description": "Panel title shown in Orca. With \"galleries\", it names the plugin instead.",
+      "default": "Gallery"
+    },
+    "interval": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 86400,
+      "description": "Seconds between images. 0 disables automatic rotation.",
+      "default": 180
+    },
+    "maxSize": {
+      "type": "integer",
+      "minimum": 16,
+      "maximum": 8192,
+      "description": "Longest side of each image, in pixels.",
+      "default": 800
+    },
+    "quality": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100,
+      "description": "WebP quality.",
+      "default": 80
+    },
+    "fit": {
+      "enum": ["contain", "cover"],
+      "description": "Initial mode: contain shows the whole image, cover fills the panel.",
+      "default": "contain"
+    },
+    "blur": {
+      "type": "boolean",
+      "description": "Show a blurred copy of the image behind it when it doesn't fill the panel.",
+      "default": true
+    },
+    "effect": {
+      "enum": ["none", "kenburns"],
+      "description": "none, or kenburns for a slow zoom while each image is shown.",
+      "default": "none"
+    },
+    "caption": {
+      "type": "boolean",
+      "description": "Show the image's file name at the top of the panel.",
+      "default": false
+    },
+    "recursive": {
+      "type": "boolean",
+      "description": "Include images in subfolders.",
+      "default": false
+    },
+    "out": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Output folder for the plugin.",
+      "default": "dist"
+    },
+    "galleries": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Several galleries, each in its own panel. Settings at the top level apply to all of them unless a gallery sets its own.",
+      "items": {
+        "$ref": "#/$defs/gallery"
+      }
+    }
+  },
+  "$defs": {
+    "gallery": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["folder"],
+      "properties": {
+        "folder": {
+          "$ref": "#/properties/folder"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "description": "Panel title. Defaults to the folder's name."
+        },
+        "interval": {
+          "$ref": "#/properties/interval"
+        },
+        "maxSize": {
+          "$ref": "#/properties/maxSize"
+        },
+        "quality": {
+          "$ref": "#/properties/quality"
+        },
+        "fit": {
+          "$ref": "#/properties/fit"
+        },
+        "blur": {
+          "$ref": "#/properties/blur"
+        },
+        "effect": {
+          "$ref": "#/properties/effect"
+        },
+        "caption": {
+          "$ref": "#/properties/caption"
+        },
+        "recursive": {
+          "$ref": "#/properties/recursive"
+        }
+      }
+    }
+  }
+}

package/lib/build.js

@@ -0,0 +1,129 @@
+import { mkdir, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { encodeImage } from "./encode.js";
+import { renderPanelHtml } from "./html.js";
+import { findImages, labelFor } from "./images.js";
+import { createManifest, isGeneratedPanelFile, MANIFEST_FILE, panelEntries } from "./manifest.js";
+/** Orca rejects a panel entry above this size (PLUGIN_PANEL_ENTRY_MAX_BYTES). */
+export const PANEL_ENTRY_MAX_BYTES = 10 * 1024 * 1024;
+/** Orca rejects a whole plugin above this size. */
+export const PLUGIN_MAX_BYTES = 50 * 1024 * 1024;
+const ENCODE_CONCURRENCY = 4;
+export class BuildError extends Error {
+    name = 'BuildError';
+}
+async function mapConcurrent(items, limit, task) {
+    const results = new Array(items.length);
+    let cursor = 0;
+    const worker = async () => {
+        while (cursor < items.length) {
+            const index = cursor++;
+            results[index] = await task(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${String(bytes)} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(0)} KB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+export function oversizeMessage(title, panelBytes, images) {
+    const largest = [...images]
+        .sort((a, b) => b.bytes - a.bytes)
+        .slice(0, 5)
+        .map((image) => `  ${formatBytes(image.bytes).padStart(8)}  ${basename(image.file)}${image.animated ? ' (animated)' : ''}`);
+    return [
+        `"${title}" is ${formatBytes(panelBytes)}, over Orca's ${formatBytes(PANEL_ENTRY_MAX_BYTES)} limit for a panel.`,
+        'Largest images:',
+        ...largest,
+        'Try a smaller --max-size or --quality, or remove some images.',
+    ].join('\n');
+}
+async function assertFolder(folder) {
+    const info = await stat(folder).catch(() => undefined);
+    if (!info?.isDirectory())
+        throw new BuildError(`Image folder not found: ${folder}`);
+}
+async function buildGallery(gallery, logger) {
+    await assertFolder(gallery.input);
+    const files = await findImages(gallery.input, gallery.recursive);
+    const skipped = [];
+    const encoded = await mapConcurrent(files, ENCODE_CONCURRENCY, async (file) => {
+        try {
+            return { file, image: await encodeImage(file, gallery) };
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            skipped.push({ file, reason });
+            logger.warn(`Skipping ${basename(file)}: ${reason}`);
+            return undefined;
+        }
+    });
+    const ok = encoded.filter((entry) => entry !== undefined);
+    if (ok.length === 0) {
+        throw new BuildError(files.length === 0
+            ? `No supported images in ${gallery.input}${gallery.recursive ? '' : ' (use --recursive to include subfolders)'}`
+            : `None of the ${String(files.length)} images in ${gallery.input} could be read`);
+    }
+    const images = ok.map(({ file, image }) => ({
+        src: image.dataUrl,
+        label: labelFor(file),
+    }));
+    const reports = ok.map(({ file, image }) => ({
+        file,
+        bytes: image.bytes,
+        width: image.width,
+        height: image.height,
+        animated: image.animated,
+    }));
+    const html = await renderPanelHtml({
+        images,
+        intervalMs: gallery.intervalSeconds * 1000,
+        fit: gallery.fit,
+        blur: gallery.blur,
+        effect: gallery.effect,
+        caption: gallery.caption,
+    });
+    const panelBytes = Buffer.byteLength(html);
+    if (panelBytes > PANEL_ENTRY_MAX_BYTES) {
+        throw new BuildError(oversizeMessage(gallery.title, panelBytes, reports));
+    }
+    return { html, images: reports, skipped };
+}
+/** Removes panel files an earlier build wrote for galleries that no longer exist. */
+async function removeStalePanels(outDir, keep) {
+    const files = await readdir(outDir);
+    await Promise.all(files
+        .filter((file) => isGeneratedPanelFile(file) && !keep.has(file))
+        .map((file) => rm(join(outDir, file))));
+}
+export async function buildPlugin(options, logger = console) {
+    const entries = panelEntries(options.galleries.map((gallery) => gallery.title));
+    const built = [];
+    for (const gallery of options.galleries)
+        built.push(await buildGallery(gallery, logger));
+    const totalBytes = built.reduce((sum, { html }) => sum + Buffer.byteLength(html), 0);
+    if (totalBytes > PLUGIN_MAX_BYTES) {
+        throw new BuildError(`The galleries add up to ${formatBytes(totalBytes)}, over Orca's ${formatBytes(PLUGIN_MAX_BYTES)} limit for a plugin.`);
+    }
+    await mkdir(options.outDir, { recursive: true });
+    await Promise.all([
+        ...built.map(({ html }, i) => writeFile(join(options.outDir, entries[i]?.entry ?? ''), html)),
+        writeFile(join(options.outDir, MANIFEST_FILE), `${JSON.stringify(createManifest(options.name, entries), null, 2)}\n`),
+    ]);
+    await removeStalePanels(options.outDir, new Set(entries.map(({ entry }) => entry)));
+    return {
+        outDir: options.outDir,
+        galleries: built.map(({ html, images, skipped }, i) => ({
+            title: entries[i]?.title ?? '',
+            entry: entries[i]?.entry ?? '',
+            panelBytes: Buffer.byteLength(html),
+            images,
+            skipped,
+        })),
+    };
+}

package/lib/cli.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { basename, dirname, relative, resolve, sep } from 'node:path';
+import { pkg } from "./package-info.js";
+import { buildPlugin, BuildError, formatBytes, PANEL_ENTRY_MAX_BYTES, } from "./build.js";
+import { loadConfigFile } from "./config-file.js";
+import { isSupportedImage } from "./images.js";
+import { CONFIG_FILE, HELP, parseCommand, resolveOptions, UsageError, } from "./options.js";
+import { watchLoop } from "./watch.js";
+function configFilePath({ configPath, cwd }) {
+    return resolve(cwd, configPath ?? CONFIG_FILE);
+}
+async function loadOptions(invocation) {
+    const { settings, configPath, cwd } = invocation;
+    const configFile = await loadConfigFile(configFilePath(invocation), {
+        required: configPath !== undefined,
+    });
+    if (configFile)
+        console.log(`Using settings from ${configPath ?? CONFIG_FILE}`);
+    return resolveOptions([...(configFile ? [configFile] : []), { settings, baseDir: cwd }], cwd);
+}
+function displayPath(path, cwd) {
+    const relativePath = relative(cwd, path);
+    if (relativePath === '')
+        return '.';
+    return relativePath.startsWith('..') ? path : relativePath;
+}
+function plural(count, noun) {
+    return `${String(count)} ${noun}${count === 1 ? '' : 's'}`;
+}
+function report(options, result, cwd) {
+    const where = displayPath(result.outDir, cwd);
+    const usage = (bytes) => `${((bytes / PANEL_ENTRY_MAX_BYTES) * 100).toFixed(0)}%`;
+    const [only] = result.galleries;
+    if (result.galleries.length === 1 && only) {
+        console.log(`Built "${only.title}" with ${plural(only.images.length, 'image')}: ` +
+            `${formatBytes(only.panelBytes)} (${usage(only.panelBytes)} of Orca's limit) in ${where}`);
+    }
+    else {
+        console.log(`Built "${options.name}" with ${String(result.galleries.length)} panels in ${where}:`);
+        const width = Math.max(...result.galleries.map((gallery) => gallery.title.length));
+        for (const gallery of result.galleries) {
+            console.log(`  ${gallery.title.padEnd(width)}  ${plural(gallery.images.length, 'image').padStart(10)}  ` +
+                `${formatBytes(gallery.panelBytes).padStart(8)} (${usage(gallery.panelBytes)} of the limit)`);
+        }
+    }
+    const skipped = result.galleries.reduce((sum, gallery) => sum + gallery.skipped.length, 0);
+    if (skipped > 0)
+        console.warn(`${String(skipped)} file(s) skipped.`);
+}
+function watchTargets(invocation, options) {
+    const config = configFilePath(invocation);
+    const targets = [
+        {
+            path: dirname(config),
+            recursive: false,
+            accept: (file) => basename(file) === basename(config),
+        },
+    ];
+    for (const gallery of options?.galleries ?? []) {
+        targets.push({
+            path: gallery.input,
+            recursive: true,
+            accept: (file) => isSupportedImage(file) && (gallery.recursive || !file.includes(sep)),
+        });
+    }
+    return targets;
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function watchAndBuild(invocation) {
+    const controller = new AbortController();
+    process.once('SIGINT', () => {
+        controller.abort();
+    });
+    await watchLoop(async () => {
+        let options;
+        try {
+            options = await loadOptions(invocation);
+            report(options, await buildPlugin(options), invocation.cwd);
+        }
+        catch (error) {
+            if (!(error instanceof UsageError || error instanceof BuildError))
+                throw error;
+            console.error(describe(error));
+        }
+        console.log(`[${new Date().toLocaleTimeString()}] Watching for changes. Ctrl+C to stop.`);
+        return watchTargets(invocation, options);
+    }, {
+        signal: controller.signal,
+        onSkip: (target, error) => {
+            console.warn(`Not watching ${target.path}: ${describe(error)}`);
+        },
+    });
+}
+async function main(argv) {
+    const command = parseCommand(argv);
+    if (command.kind === 'help') {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (command.kind === 'version') {
+        process.stdout.write(`${pkg.version}\n`);
+        return 0;
+    }
+    const invocation = {
+        settings: command.settings,
+        configPath: command.configPath,
+        cwd: process.cwd(),
+    };
+    if (command.watch) {
+        await watchAndBuild(invocation);
+        return 0;
+    }
+    const options = await loadOptions(invocation);
+    report(options, await buildPlugin(options), invocation.cwd);
+    console.log('Load it in Orca from Settings > Plugins > Development > Add path; it reloads on every build.\n' +
+        'Add --watch to rebuild on its own whenever your images change.');
+    return 0;
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    if (error instanceof UsageError) {
+        console.error(`${error.message}\n\nRun with --help for usage.`);
+        process.exitCode = 2;
+    }
+    else if (error instanceof BuildError) {
+        console.error(error.message);
+        process.exitCode = 1;
+    }
+    else {
+        console.error(error);
+        process.exitCode = 1;
+    }
+});

package/lib/config-file.js

@@ -0,0 +1,38 @@
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, resolve } from 'node:path';
+import { SETTING_KEYS, UsageError, validateSettings } from "./options.js";
+/**
+ * Reads saved build settings so a rebuild is just `npm run build`. Returns
+ * undefined when an optional file is missing; a file that exists but is
+ * invalid always fails, so a typo never silently falls back to defaults.
+ */
+export async function loadConfigFile(path, { required }) {
+    const file = resolve(path);
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (!required && error.code === 'ENOENT')
+            return undefined;
+        throw new UsageError(`Cannot read config file ${file}`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        throw new UsageError(`${basename(file)} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new UsageError(`${basename(file)} must contain a JSON object`);
+    }
+    const entries = raw;
+    const unknown = Object.keys(entries).filter((key) => key !== '$schema' && !SETTING_KEYS.includes(key));
+    if (unknown.length > 0) {
+        throw new UsageError(`Unknown setting ${unknown.map((key) => `"${key}"`).join(', ')} in ${basename(file)}. ` +
+            `Valid settings: ${SETTING_KEYS.join(', ')}`);
+    }
+    const settings = validateSettings(entries, (key) => `"${key}" in ${basename(file)}`);
+    return { settings, baseDir: dirname(file) };
+}