README.md

---

_{Concept preview. Left: glass sidebar. Center: the conversation column with a feathered glass strip. Bottom-right: the persistent NASA/ESA credit line.}

✨ Features

• 🛰 Daily imagery, auto-fetched — the host half pulls the latest Hubble-related releases from NASA's public APIs (APOD + Image and Video Library) on startup and every 6 hours, no API key required. Strict filtering keeps astronomy in and press-conference portraits out.
• 🔀 Random playback — the client shuffles the combined gallery (daily picks + curated classics) with Fisher–Yates, 80 s dwell + 6 s crossfade + slow Ken Burns drift.
• 🌌 Living starfield — a three-layer parallax procedural starfield stays fully visible even when you dim the wallpaper, so the UI never goes dead-dark. It is also the zero-asset fallback.
• 🪟 Glass panels — dark-mode panel fills are scaled by panelOpacity through the documented ctx.theme.overrideTokens layer; text, borders, scrollbars and modal masks are untouched for readability.
• 🎚 Two independent dials — bgOpacity (wallpaper imagery / vignette / conversation glass strength) and panelOpacity (UI panel translucency) mix freely.
• 🔥 Hot reload — tune all visual parameters by saving one JSON file. No restart, ever again.
• 🪶 Zero-dependency, official seams only — no bundler, no patched dist, no hash-class selectors. Stable contract: --dsw-* tokens, slots semantic attributes, dsh.client manifest.

🚀 Quick start

Requires a working DeepSeek Harness checkout/install (verified against 0.1.0-rc.7).

# 1) install into your web profile
dsh plugin --profile web add github:Socrates666/dsh-hubble-theme
# (or a local path while hacking on it)
dsh plugin --profile web add /path/to/dsh-hubble-theme

# 2) ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: hubble-theme
      name: 'dsh-desktop-hubble-theme'
      config:
        imagesDir: 'D:/hubble-assets'   # where imagery + settings.json live (created automatically)

# 3) restart dsh web and open the client — the theme switches to dark on first visit

On first start the plugin creates settings.json inside imagesDir. That file is your day-to-day control panel:

{
  "bgOpacity": 0.2,
  "panelOpacity": 0.65,
  "dwellMs": 80000
}

Save it and the UI follows within ~4 seconds.

⚙️ Configuration

Two layers: cordis.patch.yml holds structural baseline values (restart to apply), while settings.json hot-overrides the three visual dials.

Key	Scope	Default	Hot	Description
imagesDir	yml	— (required)		Asset root. daily/, settings.json live here. Fail-loud if missing.
bgOpacity	both	1	✅	Wallpaper visibility 0–1. Scales image layers, vignette and the conversation column's glass strength. Starfield unaffected.
panelOpacity	both	1	✅	Glass panel opacity 0–1. Scales dark-mode panel fill alpha (sidebar, inputs, menus, toasts…). Text/borders/masks untouched.
dwellMs	both	80000	✅	Per-image dwell 5000–600000 ms (crossfade fixed at 6 s). Applies from the next slide.
dailyFetch	yml	true		Enable the daily NASA fetch loop.
dailyMax	yml	60		Daily library cap (FIFO eviction).
apodDays	yml	60		APOD look-back window in days.
apodApiKey	yml	DEMO_KEY		APOD key (free); demo quota is plenty for one run/day.

Hot-reload semantics: a valid key is applied; an invalid value or a mid-edit broken file keeps the current visuals (logged); deleting a key falls back to the yml baseline. A hidden page pauses polling and resumes on visibility.

🧠 How it works

┌─ host half (lib/index.js) ──────────────────────────────┐
│ webserver prefix /hubble:                                │
│   /img/<slug>.jpg   display/ → daily/ → originals/       │
│   /config.json      live tunables (settings.json-watched)│
│   /gallery.json     curated ∪ daily manifest             │
│ daily fetch (lib/daily.js): NASA APOD + IVL → daily/     │
│ tunables (lib/tunables.js): fs.watch + 300 ms debounce   │
└──────────────────────────────────────────────────────────┘
                      ↓ HTTP (no-store)
┌─ browser half (lib/client.js) ───────────────────────────┐
│ ctx.theme.overrideTokens: dark deep-space / light stock   │
│ background: crossfade + Ken Burns + parallax stars       │
│ gallery: Fisher–Yates shuffle, 5 min manifest poll       │
│ tunables: 3 s poll → CSS var / token replay / dwell      │
└──────────────────────────────────────────────────────────┘

No internal dsh modules are imported; the only contract surfaces are --dsw-* design tokens, slots semantic attributes ([data-slot=…]), the dsh.client manifest, and the webserver prefix router.

🛰 Data sources & filtering

• NASA IVL (images-api.nasa.gov) — searched per year window; a candidate must mention Hubble explicitly, carry a Hubble attribution signal (credit with ESA / Hubble / STScI, or Hubble named in the title), and survive three blocklists: event photos (panels, audiences, honorific bylines, "photograph shows"), ground ops (cleanrooms, lifts, transports), and non-Hubble imagery (Webb-led releases; multi-telescope band-composite credits like X-ray: …; Infrared: …). Same-day series are deduplicated to one frame. Accepted IVL items are archived at full resolution (~orig → originals/) alongside the runtime display copy.
• NASA APOD (api.nasa.gov) — look-back window; title hits or ≥2 explanation mentions of Hubble qualify.
• Curated classics (30 targets) — scripts/fetch-hubble-photos.mjs backfills from Wikimedia Commons, and scripts/fetch-ivl-curated.mjs backfills the same targets from NASA IVL (title-token matched, attribution filtered; the working fallback when Commons is unreachable). Both write display/ (2560px runtime) + originals/ (full resolution, up to 80 MB each).
• Failures log and never break the theme; offline machines keep the procedural starfield.
• Credits are non-negotiable: every image carries its NASA/ESA/STScI credit in the UI corner.

⚠️ Notes

• Verified against dsh 0.1.0-rc.7; rc APIs can move.
• Theme preference stays on the built-in dark scheme (third-party themes cannot persist as preference in rc.7) — light mode falls back to official stock tokens, never unreadable.
• Wikimedia Commons may be unreachable from some networks; the runtime uses NASA endpoints precisely because they tend to stay reachable.

🤝 Credits

• Imagery & metadata: NASA, ESA, STScI, and the Hubble Heritage Team — via the NASA APOD and Image and Video Library public APIs, and Wikimedia Commons. Not affiliated with or endorsed by NASA/ESA/STScI.
• Extension surfaces: DeepSeek Harness — ui-theme overrideTokens, webserver prefix routes, dsh.client bundles.

📄 License

MIT © 2026 Socrates666 — imagery remains public domain with mandatory attribution, per each source's terms.