orca-gallery-panel 1.3.0 → 1.5.0

package/README.md

@@ -17,11 +17,14 @@ can change without leaving Orca.
 
 - **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.
+- **Several at once**: `--layout stack` stacks 2 to 4 images top to bottom, with no image on
+  screen twice. They change one at a time, taking turns, or all together with `--rotate all`.
+- **Controls** on hover: previous, pause/resume, next, a position counter (slideshow only),
+  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
+  automatic change), or the sliders to turn on a blurred background, a slow Ken Burns zoom,
+  the image's name or the stacked layout, and to pick how many images it stacks and whether they
+  change one at a time. 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.
@@ -38,88 +41,120 @@ can change without leaving Orca.
 
 ## Quick start
 
-Requires [Node.js](https://nodejs.org) 22.18 or later and Orca 1.4.160 or later.
+### 1. Try it from Orca
 
-```bash
-mkdir ~/orca-gallery && cd ~/orca-gallery
-npx orca-gallery-panel ~/Pictures/wallpapers --title "Wallpapers"
-```
+[Open in Orca](https://onorca.dev/plugins/jerrazuw.gallery-panel-demo?catalog=community) takes you
+to **Gallery Panel (demo)** in Orca's plugin directory; the first time, Orca asks to add its
+community catalog. Click **Install**, then open the panel from the right sidebar. It rotates
+through a few sample images and explains, inside the panel, how to show your own.
 
-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.
+Orca installs plugins from the directory as they are, so the listed one can only carry sample
+images. Your own photos take one command, below.
 
-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/`.
+### 2. Show your own photos
 
-To work from a clone instead (also the way to try the bundled samples with
-`npm run build -- examples/images`):
+You need [Node.js](https://nodejs.org) 22.18 or later and Orca 1.4.160 or later. In a terminal,
+run this with the path to your folder instead of `~/Pictures/wallpapers`:
 
 ```bash
-git clone https://github.com/jerrazuw/orca-gallery-panel.git
-cd orca-gallery-panel
-npm install
-npm run build -- ~/Pictures/wallpapers --title "Wallpapers"
+npx orca-gallery-panel ~/Pictures/wallpapers --out ~/orca-gallery --watch
 ```
 
-### Saving your settings
+It packs every image in the folder into an Orca plugin in `~/orca-gallery`, then keeps watching
+the folder. In Orca, go to **Settings → Plugins → Development**, click **Add path** and enter the
+full path of that folder (`/Users/<you>/orca-gallery` on a Mac). Open the panel from the right
+sidebar.
 
-Instead of repeating options on every build, copy the example config and edit it:
+If you installed the demo, uninstall it from **Settings → Plugins** so you don't have two
+galleries.
 
-```bash
-cp gallery.config.example.json gallery.config.json
-```
+### 3. Add photos whenever you like
+
+While the command runs, copy photos into your folder or delete them, and the panel updates by
+itself within a few seconds: the plugin is rebuilt and Orca reloads it. Copying 20 photos at once
+triggers a single rebuild. A good place to leave it running is a terminal tab inside Orca.
+
+`Ctrl+C` stops it. Next time, run the same command again: it picks up whatever changed in the
+meantime and goes back to watching. Without `--watch`, it builds once and exits, so run it again
+after changing your photos.
+
+### Saving your settings
+
+Instead of typing the options every time, put them in a `gallery.config.json` in the folder you
+run the command from (your home folder, for example):
 
 ```json
 {
-  "$schema": "./gallery.config.schema.json",
+  "$schema": "https://unpkg.com/orca-gallery-panel/gallery.config.schema.json",
   "folder": "~/Pictures/wallpapers",
+  "out": "~/orca-gallery",
   "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,
+From then on, `npx orca-gallery-panel --watch` is enough, and editing the file while it runs
+rebuilds the panel too. 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 run,
 and `--config <file>` reads a different one.
 
-### Updating your images
+If you installed the plugin with **Install plugin → Local folder** instead of **Development**,
+Orca keeps a copy, so you need to install it again after each build.
+
+### Working from a clone
 
-Add or remove files in your folder and run `npm run build` again. A plugin loaded from
-**Development** reloads on its own.
+To change the code, or to try the bundled samples with `npm run build -- examples/images`:
 
-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.
+```bash
+git clone https://github.com/jerrazuw/orca-gallery-panel.git
+cd orca-gallery-panel
+npm install
+npm run build -- ~/Pictures/wallpapers --watch
+```
 
-If you installed it with **Install plugin → Local folder** instead, Orca keeps a copy, so you
-need to install it again after each build.
+Here `npm run build --` takes the place of `npx orca-gallery-panel`, and the plugin goes to
+`dist/` unless you pass `--out`. `gallery.config.json` at the root of the clone is ignored by
+git, so your paths stay on your machine; `gallery.config.example.json` is a starting point.
 
 ## 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.       |
+| 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.                      |
+| `--layout <mode>`       | `layout`    | `slideshow` | `slideshow`, or `stack` for several at once.       |
+| `--count <2-4>`         | `count`     | `3`         | Images stacked at once with `stack`.               |
+| `--rotate <mode>`       | `rotate`    | `one`       | With `stack`: change `one` per interval, or `all`. |
+|                         | `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.
+`~` means your home folder. The `fit`, `interval`, `blur`, `effect`, `caption`, `layout`,
+`count` and `rotate` settings are only where the panel starts: you can change them from the panel
+itself.
+
+### Several images at once
+
+```bash
+npx orca-gallery-panel ~/Pictures/wallpapers --out ~/orca-gallery --layout stack --watch
+```
+
+The panel splits into three images stacked top to bottom (`--count 2` to `4` changes that), never
+the same image twice. Every interval one of them changes, top to bottom in turn, so each stays up
+for three intervals; with `--rotate all` the whole set changes at once. Next and previous swap the
+whole set, and clicking an image replaces just that one. With fewer images than places, it stacks
+as many as there are.
 
 ### Several galleries
 
@@ -182,6 +217,7 @@ npm run preview      # writes dist/preview.html: the built panel inside an Orca-
 | `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`.                        |
+| `plugin/`                      | The demo build listed in Orca's plugin directory, by `npm run build:demo`.    |
 
 TypeScript runs directly on Node through
 [type stripping](https://nodejs.org/api/typescript.html#type-stripping), so there is no compile
@@ -190,10 +226,13 @@ compiled to `lib/` by `npm run build:lib`, which `npm pack` runs on its own. CI
 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
+## In Orca's plugin directory
 
-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.
+Orca lists a plugin from a tagged commit of its repository and installs it as it is, with no build
+step, so it cannot pack your photos. The listed plugin is the build in `plugin/`: the sample images
+with a note on how to load your own, under its own id (`gallery-panel-demo`) so it can sit next to
+the plugin you build. `npm run build:demo` writes it, and `npm version` reruns that for every
+release.
 
 ## Contributing
 

package/gallery.config.schema.json

@@ -67,6 +67,23 @@
       "description": "Include images in subfolders.",
       "default": false
     },
+    "layout": {
+      "enum": ["slideshow", "stack"],
+      "description": "slideshow shows one image at a time; stack shows several stacked top to bottom.",
+      "default": "slideshow"
+    },
+    "count": {
+      "type": "integer",
+      "minimum": 2,
+      "maximum": 4,
+      "description": "Images shown at once with the stack layout.",
+      "default": 3
+    },
+    "rotate": {
+      "enum": ["one", "all"],
+      "description": "With the stack layout: change one image per interval, taking turns, or all of them at once.",
+      "default": "one"
+    },
     "out": {
       "type": "string",
       "minLength": 1,
@@ -120,6 +137,15 @@
         },
         "recursive": {
           "$ref": "#/properties/recursive"
+        },
+        "layout": {
+          "$ref": "#/properties/layout"
+        },
+        "count": {
+          "$ref": "#/properties/count"
+        },
+        "rotate": {
+          "$ref": "#/properties/rotate"
         }
       }
     }

package/lib/build.js

@@ -48,7 +48,7 @@ async function assertFolder(folder) {
     if (!info?.isDirectory())
         throw new BuildError(`Image folder not found: ${folder}`);
 }
-async function buildGallery(gallery, logger) {
+async function buildGallery(gallery, logger, demo) {
     await assertFolder(gallery.input);
     const files = await findImages(gallery.input, gallery.recursive);
     const skipped = [];
@@ -87,6 +87,10 @@ async function buildGallery(gallery, logger) {
         blur: gallery.blur,
         effect: gallery.effect,
         caption: gallery.caption,
+        layout: gallery.layout,
+        count: gallery.count,
+        rotate: gallery.rotate,
+        demo,
     });
     const panelBytes = Buffer.byteLength(html);
     if (panelBytes > PANEL_ENTRY_MAX_BYTES) {
@@ -104,8 +108,9 @@ async function removeStalePanels(outDir, keep) {
 export async function buildPlugin(options, logger = console) {
     const entries = panelEntries(options.galleries.map((gallery) => gallery.title));
     const built = [];
+    const demo = options.demo ?? false;
     for (const gallery of options.galleries)
-        built.push(await buildGallery(gallery, logger));
+        built.push(await buildGallery(gallery, logger, demo));
     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.`);
@@ -113,7 +118,7 @@ export async function buildPlugin(options, logger = console) {
     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`),
+        writeFile(join(options.outDir, MANIFEST_FILE), `${JSON.stringify(createManifest(options.name, entries, { demo }), null, 2)}\n`),
     ]);
     await removeStalePanels(options.outDir, new Set(entries.map(({ entry }) => entry)));
     return {

package/lib/manifest.js

@@ -1,5 +1,15 @@
 import { pkg } from "./package-info.js";
 export const PLUGIN_ID = 'gallery-panel';
+/**
+ * The sample build in plugin/, listed in Orca's plugin directory. A different id
+ * lets it sit next to the plugin people build from their own photos.
+ */
+export const DEMO_PLUGIN_ID = 'gallery-panel-demo';
+export const DEMO_NAME = 'Gallery Panel (demo)';
+export const DEMO_TITLE = 'Gallery (demo)';
+export const DEMO_DESCRIPTION = 'Background images for Orca: a side panel that rotates through your pictures. This install shows sample images; the panel explains how to show a folder of your own photos that updates as you add more.';
+/** Square plugin icon, written next to the demo manifest. */
+export const DEMO_ICON = 'icon.png';
 export const PUBLISHER = 'jerrazuw';
 export const PANEL_ID = 'gallery';
 export const PANEL_ENTRY = 'panel.html';
@@ -41,17 +51,18 @@ export function panelEntries(titles) {
 export function isGeneratedPanelFile(file) {
     return file === PANEL_ENTRY || /^panel-[a-z0-9]+(?:-[a-z0-9]+)*\.html$/.test(file);
 }
-export function createManifest(name, panels) {
+export function createManifest(name, panels, { demo = false } = {}) {
     return {
         manifestVersion: 1,
-        id: PLUGIN_ID,
+        id: demo ? DEMO_PLUGIN_ID : PLUGIN_ID,
         publisher: PUBLISHER,
         name,
         version: pkg.version,
-        description: pkg.description,
+        description: demo ? DEMO_DESCRIPTION : pkg.description,
         author: pkg.author,
         repository: pkg.repository.url.replace(/^git\+/, ''),
         engines: { orca: `>=${MIN_ORCA_VERSION}` },
+        ...(demo ? { icon: DEMO_ICON } : {}),
         pluginApi: 1,
         contributes: {
             panels: panels.map(({ id, title, entry }) => ({ id, title, icon: PANEL_ICON, entry })),

package/lib/options.js

@@ -1,7 +1,7 @@
 import { homedir } from 'node:os';
 import { basename, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
-import { EFFECTS, FIT_MODES, isEffect, isFitMode, MAX_INTERVAL_SECONDS, } from "./panel/config.js";
+import { EFFECTS, FIT_MODES, isEffect, isFitMode, isLayout, isRotation, LAYOUTS, MAX_INTERVAL_SECONDS, MAX_STACK_COUNT, MIN_STACK_COUNT, ROTATIONS, } from "./panel/config.js";
 export class UsageError extends Error {
     name = 'UsageError';
 }
@@ -18,6 +18,9 @@ export const DEFAULTS = {
     effect: 'none',
     caption: false,
     recursive: false,
+    layout: 'slideshow',
+    count: 3,
+    rotate: 'one',
 };
 export const GALLERY_KEYS = [
     'folder',
@@ -30,6 +33,9 @@ export const GALLERY_KEYS = [
     'effect',
     'caption',
     'recursive',
+    'layout',
+    'count',
+    'rotate',
 ];
 export const SETTING_KEYS = [
     ...GALLERY_KEYS,
@@ -40,6 +46,7 @@ const LIMITS = {
     interval: [0, MAX_INTERVAL_SECONDS],
     maxSize: [16, 8192],
     quality: [1, 100],
+    count: [MIN_STACK_COUNT, MAX_STACK_COUNT],
 };
 export const HELP = `Build an Orca side panel plugin from a folder of images.
 
@@ -60,6 +67,9 @@ Options:
       --effect <name>    ${EFFECTS.join(' | ')} (default: ${DEFAULTS.effect})
       --no-blur          No blurred background behind images that don't fill the panel
       --caption          Show the image name
+      --layout <mode>    ${LAYOUTS.join(' | ')}: one image, or several stacked (default: ${DEFAULTS.layout})
+      --count <2-4>      Images stacked at once with --layout stack (default: ${String(DEFAULTS.count)})
+      --rotate <mode>    With --layout stack, change ${ROTATIONS.join(' | ')} image(s) per interval (default: ${DEFAULTS.rotate})
   -r, --recursive        Include images in subfolders
   -w, --watch            Rebuild whenever the images or the config file change
   -c, --config <file>    Read settings from this file (default: ./${CONFIG_FILE} if it exists)
@@ -95,7 +105,7 @@ export function validateGallerySettings(raw, name) {
             throw new UsageError(`${name('title')} must be at most 256 characters`);
         }
     }
-    for (const key of ['interval', 'maxSize', 'quality']) {
+    for (const key of ['interval', 'maxSize', 'quality', 'count']) {
         const value = raw[key];
         if (value === undefined)
             continue;
@@ -117,6 +127,18 @@ export function validateGallerySettings(raw, name) {
         }
         settings.effect = raw['effect'];
     }
+    if (raw['layout'] !== undefined) {
+        if (!isLayout(raw['layout'])) {
+            throw new UsageError(`${name('layout')} must be one of ${LAYOUTS.join(', ')}, got ${JSON.stringify(raw['layout'])}`);
+        }
+        settings.layout = raw['layout'];
+    }
+    if (raw['rotate'] !== undefined) {
+        if (!isRotation(raw['rotate'])) {
+            throw new UsageError(`${name('rotate')} must be one of ${ROTATIONS.join(', ')}, got ${JSON.stringify(raw['rotate'])}`);
+        }
+        settings.rotate = raw['rotate'];
+    }
     for (const key of ['blur', 'caption', 'recursive']) {
         if (raw[key] !== undefined)
             settings[key] = validateBoolean(raw[key], name(key));
@@ -163,6 +185,9 @@ const FLAG_NAMES = {
     blur: '--no-blur',
     caption: '--caption',
     recursive: '--recursive',
+    layout: '--layout',
+    count: '--count',
+    rotate: '--rotate',
 };
 /** Numeric flags arrive as text; anything that is not a plain number is kept so validation reports it. */
 function numberFlag(value) {
@@ -188,6 +213,9 @@ export function parseCommand(argv) {
                 'no-blur': { type: 'boolean' },
                 caption: { type: 'boolean' },
                 recursive: { type: 'boolean', short: 'r' },
+                layout: { type: 'string' },
+                count: { type: 'string' },
+                rotate: { type: 'string' },
                 watch: { type: 'boolean', short: 'w', default: false },
                 config: { type: 'string', short: 'c' },
                 help: { type: 'boolean', short: 'h', default: false },
@@ -218,6 +246,9 @@ export function parseCommand(argv) {
         blur: values['no-blur'] === true ? false : undefined,
         caption: values.caption,
         recursive: values.recursive,
+        layout: values.layout,
+        count: numberFlag(values.count),
+        rotate: values.rotate,
     }, (key) => FLAG_NAMES[key] ?? key);
     return { kind: 'build', settings, configPath: values.config, watch: values.watch };
 }
@@ -253,6 +284,9 @@ function galleryOptions(layers, cwd, title) {
         effect: pick('effect').value,
         caption: pick('caption').value,
         recursive: pick('recursive').value,
+        layout: pick('layout').value,
+        count: pick('count').value,
+        rotate: pick('rotate').value,
     };
 }
 /**

package/lib/panel/config.js

@@ -1,5 +1,11 @@
 export const FIT_MODES = ['contain', 'cover'];
 export const EFFECTS = ['none', 'kenburns'];
+/** slideshow: one image at a time. stack: several images stacked top to bottom. */
+export const LAYOUTS = ['slideshow', 'stack'];
+/** How a stack changes: one image per interval, taking turns, or all of them at once. */
+export const ROTATIONS = ['one', 'all'];
+export const MIN_STACK_COUNT = 2;
+export const MAX_STACK_COUNT = 4;
 export const CONFIG_ELEMENT_ID = 'gallery-config';
 export const MAX_INTERVAL_SECONDS = 86_400;
 export function isFitMode(value) {
@@ -8,10 +14,22 @@ export function isFitMode(value) {
 export function isEffect(value) {
     return EFFECTS.includes(value);
 }
+export function isLayout(value) {
+    return LAYOUTS.includes(value);
+}
+export function isRotation(value) {
+    return ROTATIONS.includes(value);
+}
+export function isStackCount(value) {
+    return (typeof value === 'number' &&
+        Number.isInteger(value) &&
+        value >= MIN_STACK_COUNT &&
+        value <= MAX_STACK_COUNT);
+}
 export function parseConfig(raw) {
     if (typeof raw !== 'object' || raw === null)
         throw new TypeError('Config must be an object');
-    const { images, intervalMs, fit, blur, effect, caption } = raw;
+    const { images, intervalMs, fit, blur, effect, caption, layout, count, rotate, demo } = raw;
     if (!Array.isArray(images))
         throw new TypeError('Config.images must be an array');
     const parsed = images.map((image, i) => {
@@ -33,7 +51,30 @@ export function parseConfig(raw) {
         throw new TypeError('Config.blur must be a boolean');
     if (typeof caption !== 'boolean')
         throw new TypeError('Config.caption must be a boolean');
-    return { images: parsed, intervalMs, fit, blur, effect, caption };
+    if (demo !== undefined && typeof demo !== 'boolean') {
+        throw new TypeError('Config.demo must be a boolean');
+    }
+    if (layout !== undefined && !isLayout(layout)) {
+        throw new TypeError(`Config.layout must be one of ${LAYOUTS.join(', ')}`);
+    }
+    if (count !== undefined && !isStackCount(count)) {
+        throw new TypeError(`Config.count must be an integer from ${String(MIN_STACK_COUNT)} to ${String(MAX_STACK_COUNT)}`);
+    }
+    if (rotate !== undefined && !isRotation(rotate)) {
+        throw new TypeError(`Config.rotate must be one of ${ROTATIONS.join(', ')}`);
+    }
+    return {
+        images: parsed,
+        intervalMs,
+        fit,
+        blur,
+        effect,
+        caption,
+        layout: layout ?? 'slideshow',
+        count: count ?? 3,
+        rotate: rotate ?? 'one',
+        demo: demo ?? false,
+    };
 }
 /** Parses what a user typed as the interval; undefined unless it is a whole number of seconds in range. */
 export function parseIntervalSeconds(text) {

package/lib/panel/i18n.js

@@ -16,10 +16,18 @@ const en = {
     blur: 'Blurred background',
     kenburns: 'Slow zoom (Ken Burns)',
     caption: 'Show image name',
+    stack: 'Several images, stacked',
+    count: 'Images at once',
+    rotateOne: 'Change one at a time',
     settingsNote: 'Changes last until the panel reloads. Set defaults in gallery.config.json.',
     counter: (position, total) => `Image ${String(position)} of ${String(total)}`,
     empty: 'No images yet. Rebuild the panel with a folder that contains images.',
     allFailed: 'None of the images could be displayed.',
+    demoTitle: 'These are sample images',
+    demoRun: 'To show your own photos, run this in a terminal, with the path to your folder:',
+    demoAdd: 'Then, in Orca, go to Settings → Plugins → Development, click Add path and enter the full path of orca-gallery in your home folder.',
+    demoWatch: 'Leave the command running: photos you add to or remove from your folder show up in the panel on their own.',
+    demoDismiss: 'Hide this note',
 };
 const es = {
     previous: 'Imagen anterior',
@@ -39,10 +47,18 @@ const es = {
     blur: 'Fondo difuminado',
     kenburns: 'Zoom lento (Ken Burns)',
     caption: 'Mostrar nombre',
+    stack: 'Varias imágenes apiladas',
+    count: 'Imágenes a la vez',
+    rotateOne: 'Cambiar de a una',
     settingsNote: 'Los cambios duran hasta que el panel se recargue. Los valores por defecto van en gallery.config.json.',
     counter: (position, total) => `Imagen ${String(position)} de ${String(total)}`,
     empty: 'Todavía no hay imágenes. Vuelve a generar el panel con una carpeta que tenga imágenes.',
     allFailed: 'No se pudo mostrar ninguna de las imágenes.',
+    demoTitle: 'Estas son imágenes de ejemplo',
+    demoRun: 'Para ver tus propias fotos, corre esto en una terminal, con la ruta de tu carpeta:',
+    demoAdd: 'Después, en Orca, ve a Settings → Plugins → Development, haz clic en Add path y escribe la ruta completa de orca-gallery en tu carpeta personal.',
+    demoWatch: 'Deja el comando corriendo: las fotos que agregues o quites de tu carpeta aparecen solas en el panel.',
+    demoDismiss: 'Ocultar este aviso',
 };
 export const catalogs = { en, es };
 export function pickLocale(languages) {

package/lib/panel/main.js

@@ -1,4 +1,4 @@
-import { CONFIG_ELEMENT_ID, parseConfig, parseIntervalSeconds, } from "./config.js";
+import { CONFIG_ELEMENT_ID, MAX_STACK_COUNT, parseConfig, parseIntervalSeconds, } from "./config.js";
 import { catalogs, pickLocale } from "./i18n.js";
 import { Playlist } from "./playlist.js";
 const KEN_BURNS_IDLE_MS = 30_000;
@@ -16,6 +16,20 @@ function showMessage(text) {
     document.body.classList.add('message');
     query('#message', HTMLElement).textContent = text;
 }
+/** In the sample build, explains how to load a folder of your own photos. */
+function showDemoNote(t) {
+    const note = query('#demo-note', HTMLElement);
+    query('#demo-title', HTMLElement).textContent = t.demoTitle;
+    query('#demo-run', HTMLElement).textContent = t.demoRun;
+    query('#demo-add', HTMLElement).textContent = t.demoAdd;
+    query('#demo-watch', HTMLElement).textContent = t.demoWatch;
+    const dismiss = query('#demo-dismiss', HTMLButtonElement);
+    setLabel(dismiss, t.demoDismiss);
+    dismiss.addEventListener('click', () => {
+        note.hidden = true;
+    });
+    note.hidden = false;
+}
 function readConfig() {
     const raw = document.getElementById(CONFIG_ELEMENT_ID)?.textContent ?? '';
     return parseConfig(JSON.parse(raw));
@@ -66,24 +80,87 @@ class Popover {
             this.button.focus();
     }
 }
+const SWITCHES = ['blur', 'kenburns', 'caption', 'stack', 'rotateOne'];
+/** Steps "previous" can walk back through in the stack layout. */
+const MAX_SNAPSHOTS = 100;
+/** One place for an image: two layers that cross-fade, a blurred backdrop each, and a caption. */
+class Slot {
+    root;
+    #layers;
+    #caption;
+    #front = 0;
+    #shown = 0;
+    #request = 0;
+    /** The image shown or loading here; undefined while the slot is not in use. */
+    index;
+    constructor(root) {
+        this.root = root;
+        const layers = root.querySelectorAll('.layer');
+        const [a, b] = [layers[0], layers[1]];
+        if (!a || !b)
+            throw new Error('A slot needs two layers');
+        this.#layers = [a, b];
+        this.#caption = query('.caption', HTMLElement, root);
+    }
+    /** Loads into the hidden layer and cross-fades once it is decoded; stale loads are ignored. */
+    show(image, index, loaded, failed) {
+        this.index = index;
+        const request = ++this.#request;
+        const back = this.#layers[this.#front === 0 ? 1 : 0];
+        const front = this.#layers[this.#front];
+        const photo = query('.photo', HTMLImageElement, back);
+        const backdrop = query('.backdrop', HTMLImageElement, back);
+        photo.onload = () => {
+            if (request !== this.#request)
+                return;
+            backdrop.src = image.src;
+            back.classList.toggle('alternate', this.#shown++ % 2 === 1);
+            // Flushes the removal of "animate" so the zoom restarts even if no frame ran in between.
+            back.getBoundingClientRect();
+            back.classList.add('visible', 'animate');
+            front.classList.remove('visible');
+            this.#front = this.#front === 0 ? 1 : 0;
+            this.#caption.textContent = image.label;
+            loaded();
+        };
+        photo.onerror = () => {
+            if (request !== this.#request)
+                return;
+            failed();
+        };
+        // The outgoing layer keeps its zoom while it fades; this one restarts it once loaded.
+        back.classList.remove('animate');
+        photo.alt = image.label;
+        photo.src = image.src;
+    }
+    /** Takes the slot out of use, drops any load still in flight, and blanks it. */
+    clear() {
+        this.index = undefined;
+        this.#request++;
+        for (const layer of this.#layers)
+            layer.classList.remove('visible', 'animate');
+        this.#caption.textContent = '';
+    }
+}
 class Gallery {
     #config;
     #t;
     #playlist;
-    #layers;
+    #slots;
     #buttons;
     #counter;
-    #caption;
     #interval;
     #settings;
     #switches;
+    #counts;
     #failed = new Set();
     #state;
-    #front = 0;
-    #shown = 0;
+    /** In the stack layout, which slot changes next when they take turns. */
+    #turn = 0;
+    /** In the stack layout, what was on screen before each change, for "previous". */
+    #snapshots = [];
     #paused = false;
     #timer;
-    #request = 0;
     constructor(config, t) {
         this.#config = config;
         this.#t = t;
@@ -93,11 +170,19 @@ class Gallery {
             blur: config.blur,
             effect: config.effect,
             caption: config.caption,
+            layout: config.layout,
+            count: config.count,
+            rotate: config.rotate,
         };
         this.#playlist = new Playlist(config.images.length);
-        this.#layers = [query('#layer-a', HTMLElement), query('#layer-b', HTMLElement)];
         this.#counter = query('#counter', HTMLElement);
-        this.#caption = query('#caption', HTMLElement);
+        const container = query('#slots', HTMLElement);
+        const template = query('#slot-template', HTMLTemplateElement);
+        this.#slots = Array.from({ length: MAX_STACK_COUNT }, () => {
+            const root = query('.slot', HTMLElement, template.content.cloneNode(true));
+            container.append(root);
+            return new Slot(root);
+        });
         const button = (action) => query(`[data-action="${action}"]`, HTMLButtonElement);
         this.#buttons = {
             previous: button('previous'),
@@ -124,23 +209,40 @@ class Gallery {
             blur: toggle('blur'),
             kenburns: toggle('kenburns'),
             caption: toggle('caption'),
+            stack: toggle('stack'),
+            rotateOne: toggle('rotateOne'),
         };
+        this.#counts = Array.from(document.querySelectorAll('input[name="count"]'));
     }
     get #size() {
         return this.#config.images.length;
     }
+    /** How many slots are in use: one for the slideshow, up to `count` for the stack. */
+    get #active() {
+        return this.#state.layout === 'stack' ? Math.min(this.#state.count, this.#size) : 1;
+    }
+    get #activeSlots() {
+        return this.#slots.slice(0, this.#active);
+    }
     start() {
         this.#renderStaticText();
         this.#renderAll();
         this.#bindToolbar();
         this.#bindInterval();
         this.#bindSettings();
-        for (const layer of this.#layers) {
-            layer.addEventListener('click', () => {
-                if (this.#size > 1)
+        this.#slots.forEach((slot) => {
+            slot.root.addEventListener('click', () => {
+                if (this.#size <= 1)
+                    return;
+                if (this.#state.layout === 'stack') {
+                    this.#remember();
+                    this.#replace(slot);
+                }
+                else {
                     this.#next();
+                }
             });
-        }
+        });
         document.addEventListener('pointerdown', (event) => {
             const open = Popover.current;
             if (open && !(event.target instanceof Node && open.contains(event.target)))
@@ -152,7 +254,7 @@ class Gallery {
         document.addEventListener('visibilitychange', () => {
             this.#schedule();
         });
-        this.#next();
+        this.#applyLayout();
     }
     #renderStaticText() {
         const text = (selector, value) => {
@@ -166,7 +268,8 @@ class Gallery {
         this.#interval.apply.textContent = this.#t.apply;
         text('#settings-title', this.#t.settings);
         text('#settings-note', this.#t.settingsNote);
-        for (const name of ['blur', 'kenburns', 'caption']) {
+        text('#count-label', this.#t.count);
+        for (const name of SWITCHES) {
             query('span', HTMLElement, this.#switches[name].closest('label') ?? document).textContent =
                 this.#t[name];
         }
@@ -210,22 +313,39 @@ class Gallery {
         this.#switches.caption.addEventListener('change', () => {
             this.#update({ caption: this.#switches.caption.checked });
         });
+        this.#switches.stack.addEventListener('change', () => {
+            this.#update({ layout: this.#switches.stack.checked ? 'stack' : 'slideshow' });
+        });
+        this.#switches.rotateOne.addEventListener('change', () => {
+            this.#update({ rotate: this.#switches.rotateOne.checked ? 'one' : 'all' });
+        });
+        for (const radio of this.#counts) {
+            radio.addEventListener('change', () => {
+                if (radio.checked)
+                    this.#update({ count: Number(radio.value) });
+            });
+        }
     }
     #update(change) {
         Object.assign(this.#state, change);
         this.#renderAll();
-        if (change.intervalMs !== undefined)
+        if (change.layout !== undefined || change.count !== undefined)
+            this.#applyLayout();
+        else if (change.intervalMs !== undefined || change.rotate !== undefined)
             this.#schedule();
     }
     #renderAll() {
-        const { fit, blur, effect, caption, intervalMs } = this.#state;
+        const { fit, blur, effect, caption, intervalMs, layout, count, rotate } = this.#state;
         const body = document.body;
         body.dataset['fit'] = fit;
+        body.dataset['layout'] = layout;
         body.classList.toggle('blur', blur);
         body.classList.toggle('kenburns', effect === 'kenburns');
         body.classList.toggle('show-caption', caption);
         body.classList.toggle('paused', this.#paused);
-        body.style.setProperty('--gallery-kenburns', `${String(intervalMs > 0 ? intervalMs + 600 : KEN_BURNS_IDLE_MS)}ms`);
+        // Taking turns, each image stays up for one interval per slot.
+        const visibleMs = layout === 'stack' && rotate === 'one' ? intervalMs * this.#active : intervalMs;
+        body.style.setProperty('--gallery-kenburns', `${String(visibleMs > 0 ? visibleMs + 600 : KEN_BURNS_IDLE_MS)}ms`);
         setLabel(this.#buttons.fit, fit === 'contain' ? this.#t.fill : this.#t.fit);
         setLabel(this.#interval.popover.button, this.#t.interval(intervalMs / 1000));
         this.#buttons.toggle.setAttribute('aria-pressed', String(this.#paused));
@@ -233,60 +353,147 @@ class Gallery {
         this.#switches.blur.checked = blur;
         this.#switches.kenburns.checked = effect === 'kenburns';
         this.#switches.caption.checked = caption;
+        this.#switches.stack.checked = layout === 'stack';
+        this.#switches.rotateOne.checked = rotate === 'one';
+        this.#switches.rotateOne.disabled = layout !== 'stack';
+        for (const radio of this.#counts) {
+            radio.checked = Number(radio.value) === count;
+            radio.disabled = layout !== 'stack';
+        }
     }
-    #next() {
-        this.#show(this.#playlist.next());
+    /** Shows the slots the layout uses, hides the rest, and fills any that are empty. */
+    #applyLayout() {
+        const active = this.#active;
+        this.#slots.forEach((slot, i) => {
+            slot.root.hidden = i >= active;
+            if (i >= active)
+                slot.clear();
+        });
+        this.#snapshots = [];
+        this.#turn = 0;
+        for (const slot of this.#activeSlots) {
+            if (slot.index === undefined)
+                this.#replace(slot);
+        }
+        const [first] = this.#slots;
+        if (this.#state.layout === 'slideshow' && first?.index !== undefined) {
+            this.#renderCounter(first.index);
+        }
+        this.#schedule();
     }
-    #previous() {
-        this.#show(this.#playlist.previous());
+    /** The next image from the playlist that hasn't failed and isn't in `exclude`. */
+    #draw(exclude) {
+        // Every cycle holds each image once, so two cycles always reach any free image.
+        for (let tries = 0; tries < this.#size * 2; tries++) {
+            const index = this.#playlist.next();
+            if (!this.#failed.has(index) && !exclude.has(index))
+                return index;
+        }
+        return undefined;
     }
-    /** Loads into the hidden layer and cross-fades once it is decoded; stale loads are ignored. */
-    #show(index) {
+    /** Images on screen in the slots in use, except in `slot`. */
+    #onScreen(except) {
+        const shown = new Set();
+        for (const slot of this.#activeSlots) {
+            if (slot !== except && slot.index !== undefined)
+                shown.add(slot.index);
+        }
+        return shown;
+    }
+    /** Puts a different image, not on screen elsewhere, in one slot. */
+    #replace(slot) {
+        const exclude = this.#onScreen(slot);
+        if (slot.index !== undefined)
+            exclude.add(slot.index);
+        const index = this.#draw(exclude);
+        if (index !== undefined)
+            this.#load(slot, index);
+    }
+    #load(slot, index) {
         const image = this.#config.images[index];
         if (!image)
             return;
-        const request = ++this.#request;
-        const back = this.#layers[this.#front === 0 ? 1 : 0];
-        const front = this.#layers[this.#front];
-        const photo = query('.photo', HTMLImageElement, back);
-        const backdrop = query('.backdrop', HTMLImageElement, back);
-        photo.onload = () => {
-            if (request !== this.#request)
-                return;
-            backdrop.src = image.src;
-            back.classList.toggle('alternate', this.#shown++ % 2 === 1);
-            // Flushes the removal of "animate" so the zoom restarts even if no frame ran in between.
-            back.getBoundingClientRect();
-            back.classList.add('visible', 'animate');
-            front.classList.remove('visible');
-            this.#front = this.#front === 0 ? 1 : 0;
-            this.#caption.textContent = image.label;
-            this.#renderCounter(index);
+        slot.show(image, index, () => {
+            if (this.#state.layout === 'slideshow')
+                this.#renderCounter(index);
             this.#schedule();
-        };
-        photo.onerror = () => {
-            if (request !== this.#request)
-                return;
+        }, () => {
             this.#failed.add(index);
+            // Keeps showing what was there while another image loads.
+            slot.index = undefined;
             if (this.#failed.size >= this.#size) {
                 clearTimeout(this.#timer);
                 showMessage(this.#t.allFailed);
                 return;
             }
-            this.#next();
-        };
-        // The outgoing layer keeps its zoom while it fades; this one restarts it once loaded.
-        back.classList.remove('animate');
-        photo.alt = image.label;
-        photo.src = image.src;
+            this.#replace(slot);
+        });
+    }
+    /** Saves what is on screen so "previous" in the stack layout can bring it back. */
+    #remember() {
+        const current = this.#activeSlots.map((slot) => slot.index);
+        if (current.some((index) => index === undefined))
+            return;
+        this.#snapshots.push(current);
+        if (this.#snapshots.length > MAX_SNAPSHOTS)
+            this.#snapshots.shift();
+    }
+    #next() {
+        if (this.#state.layout === 'slideshow') {
+            const index = this.#draw(new Set());
+            const [slot] = this.#slots;
+            if (index !== undefined && slot)
+                this.#load(slot, index);
+            return;
+        }
+        // A whole new set, with no image twice.
+        this.#remember();
+        const chosen = new Set();
+        for (const slot of this.#activeSlots) {
+            const index = this.#draw(chosen);
+            if (index === undefined)
+                continue;
+            chosen.add(index);
+            this.#load(slot, index);
+        }
+    }
+    #previous() {
+        if (this.#state.layout === 'slideshow') {
+            const [slot] = this.#slots;
+            if (slot)
+                this.#load(slot, this.#playlist.previous());
+            return;
+        }
+        const snapshot = this.#snapshots.pop();
+        if (!snapshot)
+            return;
+        this.#activeSlots.forEach((slot, i) => {
+            const index = snapshot[i];
+            if (index !== undefined && index !== slot.index)
+                this.#load(slot, index);
+        });
+    }
+    /** What the timer does: the next image, the next set, or the next slot's turn. */
+    #advance() {
+        if (this.#state.layout === 'stack' && this.#state.rotate === 'one') {
+            const slots = this.#activeSlots;
+            const slot = slots[this.#turn % slots.length];
+            this.#turn = (this.#turn + 1) % slots.length;
+            if (!slot)
+                return;
+            this.#remember();
+            this.#replace(slot);
+            return;
+        }
+        this.#next();
     }
     #schedule() {
         clearTimeout(this.#timer);
         this.#timer = undefined;
-        const rotates = this.#state.intervalMs > 0 && this.#size > 1;
+        const rotates = this.#state.intervalMs > 0 && this.#size > this.#active;
         if (rotates && !this.#paused && !document.hidden) {
             this.#timer = setTimeout(() => {
-                this.#next();
+                this.#advance();
             }, this.#state.intervalMs);
         }
     }
@@ -358,5 +565,7 @@ function main() {
         return;
     }
     new Gallery(config, t).start();
+    if (config.demo)
+        showDemoNote(t);
 }
 main();

package/lib/panel/panel.css

@@ -40,6 +40,26 @@ body {
   overflow: hidden;
 }
 
+/* One slot for the slideshow; up to four stacked top to bottom for the stack layout. */
+.slots {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.slot {
+  position: relative;
+  flex: 1 1 0;
+  min-height: 0;
+  overflow: hidden;
+}
+
+.slot[hidden] {
+  display: none;
+}
+
 .layer {
   position: absolute;
   inset: 0;
@@ -144,6 +164,7 @@ body.message .message-text {
 }
 
 body.message .controls,
+body.message .slots,
 body.message .layer,
 body.message .caption {
   display: none;
@@ -344,6 +365,72 @@ body.single .counter {
   transform: translateX(12px);
 }
 
+/* The stack shows several images, so a single position means nothing. */
+body[data-layout='stack'] .counter {
+  display: none;
+}
+
+.count-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 5px 0;
+}
+
+.segmented {
+  display: inline-flex;
+  padding: 2px;
+  border-radius: calc(var(--gallery-radius) - 4px);
+  background: var(--gallery-input);
+}
+
+.segmented label {
+  position: relative;
+  cursor: pointer;
+}
+
+.segmented input {
+  position: absolute;
+  inset: 0;
+  margin: 0;
+  opacity: 0;
+  cursor: pointer;
+}
+
+.segmented span {
+  display: block;
+  min-width: 22px;
+  padding: 1px 6px;
+  border-radius: calc(var(--gallery-radius) - 6px);
+  text-align: center;
+  font-variant-numeric: tabular-nums;
+}
+
+.segmented input:checked + span {
+  background: var(--gallery-primary);
+  color: var(--gallery-primary-fg);
+  font-weight: 600;
+}
+
+.segmented input:focus-visible + span {
+  outline: 2px solid var(--gallery-ring);
+  outline-offset: 1px;
+}
+
+/* Count and turn-taking only apply to the stack. */
+.switch:has(input:disabled),
+.count-row:has(input:disabled) {
+  opacity: 0.45;
+}
+
+.switch:has(input:disabled),
+.switch input:disabled,
+.segmented input:disabled,
+.segmented label:has(input:disabled) {
+  cursor: default;
+}
+
 .hint {
   margin: 6px 0 0;
   color: var(--gallery-muted);
@@ -353,9 +440,89 @@ body.single .counter {
   color: var(--gallery-danger);
 }
 
+/* Note in the sample build listed in Orca's plugin directory */
+
+.demo-note {
+  position: absolute;
+  inset: 12px 12px auto;
+  max-height: calc(100% - 80px);
+  overflow-y: auto;
+  padding: 10px 32px 10px 12px;
+  border: 1px solid var(--gallery-border);
+  border-radius: var(--gallery-radius);
+  background: color-mix(in srgb, var(--gallery-surface) 92%, transparent);
+  backdrop-filter: blur(6px);
+  box-shadow: 0 8px 24px rgb(0 0 0 / 0.25);
+}
+
+.demo-note[hidden] {
+  display: none;
+}
+
+.demo-note p {
+  margin: 0 0 6px;
+}
+
+.demo-note p:last-of-type {
+  margin-bottom: 0;
+  color: var(--gallery-muted);
+}
+
+.demo-title {
+  font-weight: 600;
+}
+
+.demo-command {
+  display: block;
+  margin: 0 0 6px;
+  padding: 6px 8px;
+  border-radius: calc(var(--gallery-radius) - 4px);
+  background: var(--gallery-bg);
+  font:
+    11px/1.4 ui-monospace,
+    monospace;
+  overflow-wrap: break-word;
+  user-select: all;
+}
+
+.demo-dismiss {
+  position: absolute;
+  top: 6px;
+  right: 6px;
+  display: grid;
+  place-items: center;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  border: 0;
+  border-radius: calc(var(--gallery-radius) - 4px);
+  background: transparent;
+  color: var(--gallery-muted);
+  cursor: pointer;
+}
+
+.demo-dismiss:hover {
+  background: color-mix(in srgb, var(--gallery-fg) 10%, transparent);
+  color: var(--gallery-fg);
+}
+
+.demo-dismiss svg {
+  width: 14px;
+  height: 14px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2;
+  stroke-linecap: round;
+}
+
+body.message .demo-note {
+  display: none;
+}
+
 /* Focus and motion */
 
 .control:focus-visible,
+.demo-dismiss:focus-visible,
 .apply:focus-visible,
 .interval-row input:focus-visible,
 .switch input:focus-visible {

package/lib/panel/template.html

@@ -10,18 +10,37 @@
   </head>
   <body>
     <main class="stage">
-      <div id="layer-a" class="layer">
-        <img class="backdrop" alt="" aria-hidden="true" />
-        <img class="photo" alt="" />
-      </div>
-      <div id="layer-b" class="layer">
-        <img class="backdrop" alt="" aria-hidden="true" />
-        <img class="photo" alt="" />
-      </div>
-      <p id="caption" class="caption"></p>
+      <div id="slots" class="slots"></div>
       <p id="message" class="message-text" role="status"></p>
     </main>
 
+    <template id="slot-template">
+      <div class="slot">
+        <div class="layer">
+          <img class="backdrop" alt="" aria-hidden="true" />
+          <img class="photo" alt="" />
+        </div>
+        <div class="layer">
+          <img class="backdrop" alt="" aria-hidden="true" />
+          <img class="photo" alt="" />
+        </div>
+        <p class="caption"></p>
+      </div>
+    </template>
+
+    <aside id="demo-note" class="demo-note" aria-labelledby="demo-title" hidden>
+      <p id="demo-title" class="demo-title"></p>
+      <p id="demo-run"></p>
+      <code class="demo-command"
+        >npx orca-gallery-panel ~/Pictures --out ~/orca-gallery --watch</code
+      >
+      <p id="demo-add"></p>
+      <p id="demo-watch"></p>
+      <button type="button" id="demo-dismiss" class="demo-dismiss">
+        <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M6 6l12 12M18 6 6 18" /></svg>
+      </button>
+    </aside>
+
     <div class="controls" role="toolbar">
       <button type="button" class="control" data-action="previous">
         <svg viewBox="0 0 24 24" aria-hidden="true"><path d="m15 18-6-6 6-6" /></svg>
@@ -102,6 +121,22 @@
           <input type="checkbox" role="switch" data-setting="caption" />
           <span></span>
         </label>
+        <label class="switch">
+          <input type="checkbox" role="switch" data-setting="stack" />
+          <span></span>
+        </label>
+        <div class="count-row" role="radiogroup" aria-labelledby="count-label">
+          <span id="count-label"></span>
+          <span class="segmented">
+            <label><input type="radio" name="count" value="2" /><span>2</span></label>
+            <label><input type="radio" name="count" value="3" /><span>3</span></label>
+            <label><input type="radio" name="count" value="4" /><span>4</span></label>
+          </span>
+        </div>
+        <label class="switch">
+          <input type="checkbox" role="switch" data-setting="rotateOne" />
+          <span></span>
+        </label>
         <p id="settings-note" class="hint"></p>
       </div>
     </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orca-gallery-panel",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Background images for the Orca agent IDE: a side panel with a rotating gallery of your own pictures.",
   "keywords": [
     "orca",
@@ -50,7 +50,9 @@
     "check": "npm run typecheck && npm run lint && npm run format:check && npm test",
     "test:e2e": "node --test --test-concurrency=1 \"test/e2e/**/*.test.ts\"",
     "build:lib": "node scripts/build-lib.ts",
-    "prepack": "npm run build:lib"
+    "build:demo": "node scripts/build-demo-plugin.ts",
+    "prepack": "npm run build:lib",
+    "version": "npm run build:demo && git add plugin"
   },
   "dependencies": {
     "esbuild": "^0.28.2",