Skip to main content

HUD overlay

@scenography/overlay is a framework-agnostic DOM layer over the gallery canvas: buttons, hints, and any visual aid you want, positioned in a 3×3 grid of slots. It is plain DOM, so it works whether or not you use React.

Mounting​

createOverlay and the slot machinery live in @scenography/overlay; the ready-made widgets live in @scenography/overlay-presets.

import { createOverlay } from '@scenography/overlay';
import { fullscreenButton } from '@scenography/overlay-presets';

const overlay = createOverlay({ gallery });
overlay.add('top-right', fullscreenButton());

// later: overlay.destroy();

Or drop in the whole batteries-included HUD at once with defaultPreset — mute, fullscreen, an info panel, credits and a settings dialog:

import { createOverlay } from '@scenography/overlay';
import { defaultPreset } from '@scenography/overlay-presets';

const overlay = createOverlay({ gallery });
defaultPreset(overlay, {
  info: { title: 'Controls', text: 'Drag to look · WASD to move' },
});

Slots: top-left, top-center, top-right, middle-left, center, middle-right, bottom-left, bottom-center, bottom-right. add returns a function that removes the component.

Components are just functions​

A component is (ctx) => HTMLElement (optionally returning { element, destroy } for cleanup). The context gives you the running gallery and the surface (the element fullscreen targets). No daisyUI or framework required:

overlay.add('bottom-left', () => {
  const el = document.createElement('div');
  el.textContent = 'My gallery';
  el.style.color = '#fff';
  return el;
});

daisyUI prefab widgets​

@scenography/overlay-presets ships optional widgets (fullscreenButton, muteButton, infoPanel, defaultPreset, …) styled with daisyUI classes. They work as DOM regardless, but to look right they need daisyUI in your CSS pipeline. daisyui and tailwindcss are therefore optional peer dependencies — only install them if you use the prefab widgets.

With Tailwind v4:

styles.css
@import 'tailwindcss';
@plugin 'daisyui';

/* Tailwind only scans your own source by default, so the daisyUI classes the
   widgets use (modal, btn, badge…) wouldn't be generated and the dialogs would
   render unstyled. Point it at the package's dist too: */
@source '../node_modules/@scenography/overlay-presets/dist';

If you'd rather not use daisyUI, skip the prefab widgets and build your own components (just return an element with your own styles, as shown above).