MUSEUM UNLIMITED — STATIC FIRST-PERSON MUSEUM

Open index.html directly in a modern browser. The museum is completely local:
there is no server, build process, package installation, or network dependency.

CONTROLS
- Click Create Museum to generate a new plan for the selected exhibition, then
  use Up/Down to move and Left/Right to turn.
- Choose Exhibition opens the collection browser. Pick an available exhibition
  and click Enter Museum to generate it inside a new plan.
- Hold Shift with Left/Right to move sideways.
- W/S also move, A/D also move sideways. The mouse never controls the view.
- Escape pauses exploration. M opens the floor map.
- New Museum opens the generation panel. Choose artwork in that panel opens the
  exhibition browser without leaving the current tour.
- Complete: New Museum + Artwork creates a new plan and randomly selects any
  available built-in or historical exhibition. Personal exhibitions are never
  selected by this action. New Museum Plan changes only the architecture.
- Walk up the architectural ramps to reach floors 2 and 3.
- Aim at a nearby artwork and click to inspect it.
- The artwork viewer opens local curated collections in Fill mode. Historical
  and personal exhibitions open in Fit mode so the complete image is visible.
  Use the Fill/Fit controls to switch between either presentation.
- The numbered floor buttons move you directly between levels.
- Space opens a targeted artwork; otherwise it makes the visitor jump.
- M opens and closes the map. Hover artwork dots for previews and click a dot
  to travel directly to that work.
- Open the journey counter to continue the curated route or jump to a surprise
  unvisited work. Each curated-route press advances to the next stop, whether
  or not the previous artwork was opened. R performs a surprise transport.
- Artwork discoveries, exhibition choice and the latest generated museum seed
  are saved locally in the browser, separately for every plan and exhibition.
- Use the top-right controls to switch modes and tune gallery lighting.
- The museum opens in charcoal dark mode; switch to light mode at any time.
- Every generated museum has a ground-floor doorway into a changing exterior
  sculpture garden and museum café. The garden is intentionally omitted from
  the indoor floor map and is discovered by walking through the museum. Its
  procedural sky, horizon, tall trees and optional fountain change with the plan.
- Every generated plan includes second-floor windows overlooking the garden and
  a walkable third-floor landscape balcony reached through an open doorway.
- Generated artwork positions preserve a visible wall margin at every corner.
  Protected viewing corridors also keep plants, water, sculpture, partitions
  and smaller decorative objects away from the front and edges of every work.

EXHIBITIONS AND ARTWORK
artworks.js contains the editable metadata for the curated exhibitions. The
first collection uses assets/exhibit-1/exhibit-01.jpg through
assets/exhibit-1/exhibit-18.jpg. The
second collection, The Archive Dreams Back by Olio Imaginarium, uses the 20 JPG
files in assets/exhibit-2. Each work can define title, code, year, discipline,
image path, floor, dimensions and description. A collection can contain 1–20
works. Collections of up to three works remain entirely on the ground floor;
larger collections are balanced across all three floors unless their manifest
contains a valid custom floor arrangement. Capacity is seven works on floors 1
and 2 and six on floor 3.

Frames are generated from each image's natural aspect ratio. Portrait, square,
landscape and panoramic works therefore keep their original proportions in the
gallery instead of being stretched into a shared format.

Visitors can also choose Your Exhibition and select 1–20 JPEG, PNG or WebP
images by browsing or dropping files into the exhibition builder. These remain
private in IndexedDB on that device, survive the page
reload used to generate a plan, and are never added to the website files or sent
to a server. Once loaded, the exhibition browser shows the first uploaded image
as the collection cover and reports the saved image count. Select the card to
reuse the collection; click it again while selected to replace its images.
Clearing browser site data removes the personal exhibition.

The builder also accepts 1–20 direct HTTP or HTTPS image URLs, one per line.
Only the lightweight links are saved. Because the images become WebGL textures,
the image host must permit cross-origin (CORS) loading; page URLs and protected
image hosts will be skipped with an explanatory status message. The URL import
panel includes links and tested direct-image examples for Rijksmuseum IIIF,
Smithsonian IIIF and Wikimedia Commons.

UNSPLASH EXHIBITION BUILDER
The Choose an Exhibition browser includes a dedicated Unsplash Exhibition
Builder card. Visitors can combine a subject or phrase with curated starting
points, photography-style terms, orientation, dominant color and a 1–20 work
count. The contact sheet supports locking favorites, removing photographs and
rerolling only the unlocked selection. Finished selections are remembered in
this browser and historical/local exhibitions remain unchanged.

Live Unsplash search uses a very small proxy so the API access key is never
exposed in the static website files:
1. Deploy unsplash-proxy-worker.mjs to a JavaScript edge/serverless runtime.
2. Store the Unsplash application access key there as UNSPLASH_ACCESS_KEY.
3. Optionally set ALLOWED_ORIGIN to the deployed museum origin. Leave it as *
   while testing the museum from file:// or more than one origin.
4. Paste the deployed proxy URL into proxyUrl in unsplash-config.js.

For local testing, the builder also presents this setup directly above the
contact sheet. Paste the deployed proxy URL there and choose Save & test; the
public proxy address is remembered in that browser. If no proxy is configured,
Compose exhibition now opens the setup explanation instead of failing silently.

The HTML/CSS/JS museum still has no server dependency and all non-Unsplash
features work directly from file://. Only live Unsplash search requires the
configured internet proxy. The proxy uses API-returned hotlinks, high content
filtering and download-event reporting. Unsplash works default to Fit view and
receive per-photo photographer and Unsplash attribution fields; other viewer
content and attribution remain exactly as before.

HISTORICAL COLLECTIONS
The Choose an Exhibition browser includes an Art Across Time section with four
featured artists and a dedicated Browse Artists view. Eight remote exhibitions
are currently available, with 20 works each:
- Utagawa Hiroshige — Roads Through Weather
- Hilma af Klint — Invisible Orders
- James McNeill Whistler — Tonal Horizons
- Francisco de Goya — The Sleep of Reason
- Alfons Mucha — Line, Ornament, Desire
- Vincent van Gogh — The Sky Is Never Still
- Claude Monet — Light, Returning
- Gustav Klimt — Gold, Garden, Desire

Hiroshige and Goya use resized Rijksmuseum IIIF images. Hilma af Klint,
Whistler, Mucha, Van Gogh, Monet and Klimt use bounded Wikimedia Commons image
URLs. These collections keep the website package small but require an internet
connection while viewing
them. Every work includes a short interpretive note plus a link back to its
museum or Commons source record in the artwork viewer.

historical-artworks.js is the generated, runtime-ready manifest. To refresh it
from the public collection APIs, run `node build-historical-artworks.mjs`. The
builder uses only Node's built-in APIs and is not needed to view or deploy the
museum.

When the museum is hosted on any static website, those image files are loaded
directly. Browsers restrict WebGL from reading separate images under file://,
so art-assets.js contains an embedded fallback for direct local viewing.
After replacing either curated image set for file:// use, run
`node pack-artworks.mjs` once to refresh that fallback. This is only an optional
image-packing utility; the museum itself never needs Node.js or a server.

FILES
- index.html: accessible interface and museum shell
- styles.css: interface, responsive layout, light/dark presentation
- artworks.js: editable exhibition and artwork metadata manifests
- historical-artworks.js: generated manifests for remote historical exhibitions
- build-historical-artworks.mjs: optional no-package historical manifest builder
- unsplash-config.js: public proxy URL and referral source configuration
- unsplash-proxy-worker.mjs: optional serverless Unsplash API adapter
- museum.js: architecture, rendering, movement, lighting and interactions
- art-assets.js: embedded image fallback for direct file:// viewing
- pack-artworks.mjs: optional no-package utility to refresh the fallback
- vendor/three.min.js: locally bundled 3D renderer
- assets/: curated exhibition imagery and the startup-screen background