orca-gallery-panel 1.3.0 → 1.4.0

package/README.md

@@ -38,64 +38,80 @@ 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
 
@@ -182,6 +198,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 +207,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/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,7 @@ async function buildGallery(gallery, logger) {
         blur: gallery.blur,
         effect: gallery.effect,
         caption: gallery.caption,
+        demo,
     });
     const panelBytes = Buffer.byteLength(html);
     if (panelBytes > PANEL_ENTRY_MAX_BYTES) {
@@ -104,8 +105,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 +115,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/panel/config.js

@@ -11,7 +11,7 @@ export function isEffect(value) {
 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, demo } = raw;
     if (!Array.isArray(images))
         throw new TypeError('Config.images must be an array');
     const parsed = images.map((image, i) => {
@@ -33,7 +33,10 @@ 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');
+    }
+    return { images: parsed, intervalMs, fit, blur, effect, caption, 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

@@ -20,6 +20,11 @@ const en = {
     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',
@@ -43,6 +48,11 @@ const es = {
     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

@@ -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));
@@ -358,5 +372,7 @@ function main() {
         return;
     }
     new Gallery(config, t).start();
+    if (config.demo)
+        showDemoNote(t);
 }
 main();

package/lib/panel/panel.css

@@ -353,9 +353,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

@@ -22,6 +22,19 @@
       <p id="message" class="message-text" role="status"></p>
     </main>
 
+    <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>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orca-gallery-panel",
-  "version": "1.3.0",
+  "version": "1.4.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",