orca-gallery-panel 1.4.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.
@@ -115,27 +118,43 @@ git, so your paths stay on your machine; `gallery.config.example.json` is a star
 
 ## 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
 

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

@@ -87,6 +87,9 @@ async function buildGallery(gallery, logger, demo) {
         blur: gallery.blur,
         effect: gallery.effect,
         caption: gallery.caption,
+        layout: gallery.layout,
+        count: gallery.count,
+        rotate: gallery.rotate,
         demo,
     });
     const panelBytes = Buffer.byteLength(html);

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, demo } = 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) => {
@@ -36,7 +54,27 @@ export function parseConfig(raw) {
     if (demo !== undefined && typeof demo !== 'boolean') {
         throw new TypeError('Config.demo must be a boolean');
     }
-    return { images: parsed, intervalMs, fit, blur, effect, caption, demo: demo ?? false };
+    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,6 +16,9 @@ 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.',
@@ -44,6 +47,9 @@ 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.',

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;
@@ -80,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;
@@ -107,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'),
@@ -138,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)))
@@ -166,7 +254,7 @@ class Gallery {
         document.addEventListener('visibilitychange', () => {
             this.#schedule();
         });
-        this.#next();
+        this.#applyLayout();
     }
     #renderStaticText() {
         const text = (selector, value) => {
@@ -180,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];
         }
@@ -224,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));
@@ -247,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);
         }
     }

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

package/lib/panel/template.html

@@ -10,18 +10,24 @@
   </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>
@@ -115,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.4.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",