Refactor overlay-first install with ui-module slots and valentus v1 pin docs.

Slipstream dark mode no longer occupies ui.bundle; document valentus-theme as the full-stack successor with rolling v1 pin for former antora-dark-theme sites.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: AMDphreak

.github/workflows/release.yml

@@ -76,6 +76,17 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Publish to npm
+        if: github.ref_name =~ /^v\d+\.\d+\.\d+$/ && !contains(github.ref_name, '-')
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          pnpm ui-modules:sync
+          pnpm ui-modules:validate
+          node -e "const fs=require('fs');const p=JSON.parse(fs.readFileSync('package.json','utf8'));delete p.private;fs.writeFileSync('package.json',JSON.stringify(p,null,2)+'\n')"
+          npm publish --access public
+          npm deprecate antora-dark-theme@* "Renamed — use valentus-theme (bundled dark mode). See https://github.com/antora-supplemental/valentus-theme" || true
+
       - name: Resolve release commit
         id: rel
         run: echo "sha=$(git rev-list -n 1 "${GITHUB_REF}")" >> "$GITHUB_OUTPUT"

CHANGELOG.adoc

@@ -8,6 +8,14 @@ and this project adheres to https://semver.org/spec/v2.0.0.html[Semantic Version
 
 Entries below are in **chronological order** by date: prior release, then the **2026-03-04** org creation and repository move, then the next release.
 
+== [1.3.0] - 2026-06-13
+
+* *npm:* First publish as `antora-dark-mode` (overlay transport: `supplemental-ui/` + `ui-modules/`). Deprecate legacy `antora-dark-theme` npm package name.
+* *Install model:* Overlay-first and slot-based `dark-mode` ui-module; `ui-bundle.zip` is convenience-only (Default UI quick start).
+* *UI module:* `ui-modules/packages/dark-mode` with `head`/`foot` slots (no partial replace).
+
+link:changelog-details/2026-06-13%20-%20overlay-first%20install%20and%20ui-module.adoc[Detailed notes — 2026-06-13]
+
 == [Unreleased]
 
 == [1.2.0] - 2026-06-09

README.adoc

@@ -10,9 +10,10 @@
 
 A dark mode UI for {url-antora}[Antora] documentation sites.
 
-IMPORTANT: Use the GitHub release `ui-bundle.zip` (Default UI + this theme, pre-merged)—the habit every site should adopt.
-The npm package is *deprecated and unpublished*; see xref:npm-deprecation.adoc[npm deprecation (archive & lessons learned)].
-Discover this theme via link:https://antora-supplemental.github.io/docs/[Antora Supplemental docs] (extensions registry).
+IMPORTANT: Install dark mode as a *supplemental overlay* or slot-based ui-module — it must not occupy `ui.bundle` when you mix it with another theme.
+GitHub `ui-bundle.zip` is a *convenience* artifact (Default UI + dark mode pre-merged) for quick starts only.
+npm is optional overlay transport — see xref:npm-distribution.adoc[npm distribution].
+Discover this extension via link:https://antora-supplemental.github.io/docs/[Antora Supplemental docs] (extensions registry).
 
 image:https://img.shields.io/badge/license-MIT-blue.svg[License: MIT]
 image:https://img.shields.io/badge/antora-3.x-purple.svg[Antora 3.x]
@@ -41,35 +42,45 @@ If you'd like to see native dark mode support in Antora, please upvote the featu
 
 Your support helps the Antora team prioritize this feature!
 
-**Doc-site chrome** (mast, header layout, VCS icons) lives in the separate link:https://github.com/antora-supplemental/valentus-theme[valentus-theme] project. Pair valentus supplemental UI on top of this dark-mode release bundle when you want both.
+**Doc-site chrome** (mast, header layout, VCS icons) lives in link:https://github.com/antora-supplemental/valentus-theme[valentus-theme].
+Pair dark mode as overlay or ui-module on top of the *valentus* `ui.bundle` — not the other way around.
 
 == Quick Start
 
-Use the release bundle. That is the correct default—not a mild preference.
+=== Overlay on your theme bundle (recommended)
 
-=== The habit: release `ui-bundle.zip`
-
-Point your playbook at a pinned GitHub Release asset.
-You do not need this project on npm.
+Reserve `ui.bundle` for your theme. Layer dark mode via one `supplemental_files` directory:
 
 [source,yaml]
 ----
 ui:
   bundle:
-    url: https://github.com/antora-supplemental/antora-dark-mode/releases/download/v1.2.0/ui-bundle.zip
+    url: https://github.com/antora-supplemental/valentus-theme/releases/download/v1/ui-bundle.zip
     snapshot: true
-  supplemental_files: ./supplemental-ui-overrides
+  supplemental_files: ./site/supplemental-ui   # merge antora-dark-mode supplemental-ui here
 ----
 
-Optional `supplemental_files` is *one* directory of your files (logo, favicon)—not a second theme install.
+npm transport: `pnpm add -D antora-dark-mode` then copy from `node_modules/antora-dark-mode/supplemental-ui`.
+See xref:installation.adoc[Installation] and xref:ui-modules.adoc[UI Modules] (slot-based, no partial collisions).
 
-Catalog and org docs: link:https://antora-supplemental.github.io/docs/[antora-supplemental.github.io/docs^].
+=== Convenience `ui-bundle.zip` (Default UI only)
 
-Former npm consumers: xref:npm-deprecation.adoc[npm deprecation].
+Pre-merged Default UI + dark mode — use only when you do not need another theme in `ui.bundle`:
+
+[source,yaml]
+----
+ui:
+  bundle:
+    url: https://github.com/antora-supplemental/antora-dark-mode/releases/download/v1.2.0/ui-bundle.zip
+    snapshot: true
+  supplemental_files: ./supplemental-ui-overrides
+----
 
 WARNING: Antora accepts *one* supplemental directory *or* virtual files—not multiple directories in YAML.
 
-See link:examples/antora-playbook.yml[`examples/antora-playbook.yml`].
+Examples: link:examples/antora-playbook-overlay.yml[`antora-playbook-overlay.yml`] (overlay), link:examples/antora-playbook-ui-modules.yml[`antora-playbook-ui-modules.yml`] (slots), link:examples/antora-playbook-convenience-bundle.yml[`antora-playbook-convenience-bundle.yml`] (Default UI quick start).
+
+Catalog and org docs: link:https://antora-supplemental.github.io/docs/[antora-supplemental.github.io/docs^].
 
 === Version pinning (production vs. rolling lines)
 
@@ -165,22 +176,26 @@ See the dark theme in action: {url-demo}[Live Demo]
 [source]
 ----
 antora-dark-mode/
-├── supplemental-ui/
-│   ├── css/
-│   │   └── site-extra.css      # Dark mode CSS styles
-│   ├── js/
-│   │   └── site-dark-mode.js   # Toggle button logic and theme management
-│   └── partials/
-│       ├── footer-scripts.hbs  # Loads the dark mode script
-│       └── head-meta.hbs       # Loads CSS and prevents FOUC
-├── docs/                        # Demo documentation
+├── supplemental-ui/             # Direct overlay install (merge into one supplemental dir)
+│   ├── css/site-extra.css
+│   ├── js/site-dark-mode.js
+│   └── partials/                # head-meta, footer-scripts (full replace — use ui-module for themes)
+├── ui-modules/                  # Slot-based dark-mode module (recommended with valentus orchestrator)
+│   ├── registry.json5
+│   ├── recipes/dark-mode-only.json5
+│   └── packages/dark-mode/
+│       ├── ui-module.json5
+│       └── ui/
+├── docs/
 │   ├── antora.yml              # Component descriptor
 │   └── modules/ROOT/
 │       ├── nav.adoc            # Navigation
 │       └── pages/              # Sample pages
 ├── examples/
-│   ├── antora-playbook.yml     # Example playbook (release bundle; recommended)
-│   └── antora-playbook-local.yml # Example playbook (bundle + optional overrides)
+│   ├── antora-playbook-overlay.yml           # Overlay on theme bundle (recommended)
+│   ├── antora-playbook-ui-modules.yml        # Slot-based via orchestrator
+│   ├── antora-playbook-convenience-bundle.yml # Default UI quick start
+│   └── antora-playbook.yml                   # Alias for convenience bundle
 ├── .github/workflows/
 │   └── deploy.yml              # GitHub Pages deployment
 ├── antora-playbook.yml         # Playbook for demo site (online / CI)

README.md

@@ -1,67 +1,51 @@
-# DEPRECATED — do not install
+# antora-dark-mode
 
-**This npm package is retired.** It will not receive updates. New documentation sites must not add `antora-dark-mode` as a dependency.
+Dark mode supplemental UI for Antora — overlay install or slot-based ui-module.
 
-If the yellow deprecation banner above this README is hard to read (npm dark theme), **use this README instead** — it is the authoritative migration notice.
+**Does not occupy `ui.bundle`** when mixed with valentus or other themes. See [Installation](https://antora-supplemental.github.io/antora-dark-mode/antora-dark-mode/guide/installation.html).
 
 ---
 
-## Why you should not use npm for this theme
+## Install (overlay — recommended)
 
-Antora Dark Theme is a **static UI bundle** (CSS, Handlebars, JavaScript), not a Node library. Installing it from npm:
-
-- Adds a useless entry to your `package.json` and lockfile
-- Encourages invalid setups (multiple `supplemental_files` directories, copy/sync scripts from `node_modules`)
-- Duplicates what the official release artifact already ships
-
-The **correct habit** is a single pinned URL in your Antora playbook—no `npm install`.
-
----
-
-## What to do instead (correct instructions)
-
-### 1. Use the GitHub release UI bundle
-
-In `antora-playbook.yml`:
+```bash
+pnpm add -D antora-dark-mode
+```
 
 ```yaml
 ui:
   bundle:
-    url: https://github.com/antora-supplemental/antora-dark-mode/releases/download/v1.2.0/ui-bundle.zip
+    url: https://github.com/antora-supplemental/valentus-theme/releases/download/v1/ui-bundle.zip
     snapshot: true
+  supplemental_files: ./site/supplemental-ui   # merge node_modules/antora-dark-mode/supplemental-ui
 ```
 
-Pin an exact semver tag for production. See [Version Pinning](https://antora-supplemental.github.io/antora-dark-mode/antora-dark-mode/guide/version-pinning.html) for `releases/latest`, rolling line tags (`v1.0`, `v1`), and Renovate.
-
-### 2. Optional branding (one directory only)
+For slot-based installs (no partial collisions), see [UI Modules](https://antora-supplemental.github.io/antora-dark-mode/antora-dark-mode/guide/ui-modules.html).
 
-```yaml
-  supplemental_files: ./supplemental-ui-overrides   # e.g. img/logo.svg
-```
+## Convenience bundle (Default UI only)
 
-### 3. Remove this package if it is already installed
+Pre-merged `ui-bundle.zip` — quick start when you do not use another theme in `ui.bundle`:
 
-```bash
-pnpm remove -D antora-dark-mode
-# or: npm uninstall antora-dark-mode
+```yaml
+ui:
+  bundle:
+    url: https://github.com/antora-supplemental/antora-dark-mode/releases/download/v1.2.0/ui-bundle.zip
+    snapshot: true
 ```
 
-Delete any `prebuild` / `sync:ui` scripts that copied `node_modules/antora-dark-mode/supplemental-ui`.
+## npm registry
 
----
+Republishing to npm as **overlay transport** (not `ui.bundle` replacement). Same package name `antora-dark-mode` — npm does not support renaming packages. See [npm distribution](https://antora-supplemental.github.io/antora-dark-mode/antora-dark-mode/guide/npm-distribution.html).
 
-## Where to find full documentation
+## Links
 
 | Resource | URL |
 |----------|-----|
-| **Install guide & lessons learned** | [npm deprecation (Antora site)](https://antora-supplemental.github.io/antora-dark-mode/antora-dark-mode/guide/npm-deprecation.html) |
-| **Live demo** | [antora-supplemental.github.io/antora-dark-mode](https://antora-supplemental.github.io/antora-dark-mode) |
-| **Extensions catalog (org hub)** | [antora-supplemental.github.io/docs](https://antora-supplemental.github.io/docs/) |
-| **Source repository** | [github.com/antora-supplemental/antora-dark-mode](https://github.com/antora-supplemental/antora-dark-mode) |
-| **Example playbook** | [examples/antora-playbook.yml](https://github.com/antora-supplemental/antora-dark-mode/blob/main/examples/antora-playbook.yml) |
-
----
+| Install guide | [installation.adoc](docs/modules/guide/pages/installation.adoc) |
+| UI modules | [ui-modules.adoc](docs/modules/guide/pages/ui-modules.adoc) |
+| Live demo | [antora-supplemental.github.io/antora-dark-mode](https://antora-supplemental.github.io/antora-dark-mode) |
+| Source | [github.com/antora-supplemental/antora-dark-mode](https://github.com/antora-supplemental/antora-dark-mode) |
 
 ## License
 
-[MIT](https://github.com/antora-supplemental/antora-dark-mode/blob/main/LICENSE)
+[MIT](LICENSE)

antora-playbook.yml

@@ -12,8 +12,8 @@ content:
       branches: HEAD
       start_path: docs
 
-# This repo builds the demo site from ./supplemental-ui (theme sources).
-# Consumers should use the release ui-bundle.zip — see README and examples/.
+# This repo's demo uses overlay install (Default UI + ./supplemental-ui).
+# Consumers: overlay on your theme bundle, ui-module slots, or convenience ui-bundle.zip — see README.
 ui:
   bundle:
     url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable

changelog-details/2026-06-13 - overlay-first install and ui-module.adoc

@@ -0,0 +1,9 @@
+= 2026-06-13 — overlay-first install and slot-based dark-mode ui-module
+:description: Changelog detail for antora-dark-mode unreleased overlay restore
+:navtitle: Overlay-first install restore
+
+* *Problem:* Bundle-only install docs (May 2026) made `antora-dark-mode` occupy `ui.bundle`, blocking theme mixing (e.g. valentus `ui-bundle` + dark mode).
+* *Fix:* Installation is overlay-first — theme owns `ui.bundle`; dark mode via `supplemental-ui` merge or `ui-modules/packages/dark-mode` slots.
+* *UI module:* `dark-mode` manifest uses `slots.head` (CSS + FOUC) and `slots.foot` (toggle JS); does not `replace` theme partials. Works with valentus `ui-orchestrator`.
+* *Convenience artifact:* GitHub `ui-bundle.zip` remains for Default UI quick starts only.
+* *npm:* Republish plan restores `antora-dark-mode` on npm as transport (`supplemental-ui` + `ui-modules`). Package rename on npm is not possible — reuse the existing name.

docs/maintainers/antora-chat-corrections.md

@@ -0,0 +1,54 @@
+# Antora Zulip — correction messages (antora-dark-theme → valentus-theme)
+
+Post these in [Antora Zulip](https://antora.zulipchat.com/) where older threads still reference `antora-dark-theme`.
+
+---
+
+## Short correction (reply to outdated install advice)
+
+The monolithic **`antora-dark-theme`** package was split and renamed:
+
+| Former | Use instead |
+|---|---|
+| `antora-dark-theme` (npm / GitHub) | **`valentus-theme`** — release `ui-bundle.zip` (chrome + **bundled dark mode**) |
+| Dark mode only on another theme | **`antora-dark-mode`** — slipstream overlay (does not use `ui.bundle`) |
+
+```yaml
+ui:
+  bundle:
+    url: https://github.com/antora-supplemental/valentus-theme/releases/download/v1/ui-bundle.zip
+    snapshot: true
+  supplemental_files: ./supplemental-ui-overrides   # optional branding
+```
+
+Docs: https://antora-supplemental.github.io/valentus-theme/
+
+---
+
+## Thread: npm install
+
+```bash
+# Former (retired)
+pnpm add -D antora-dark-theme
+
+# Full theme + dark mode (most former antora-dark-theme sites)
+# Use release bundle URL in playbook — no npm required.
+# Or: pnpm add -D valentus-theme for supplemental vendoring.
+
+# Dark mode only on a custom theme bundle
+pnpm add -D antora-dark-mode
+```
+
+---
+
+## Thread: doc-site chrome + dark mode
+
+Both ship in **valentus-theme** `ui-bundle.zip` since v1.1.0. You do not need to pin `antora-dark-mode` as `ui.bundle` and layer valentus on top.
+
+---
+
+## GitLab Default UI issue #216
+
+Community extension: https://github.com/antora-supplemental/valentus-theme (full stack) or https://github.com/antora-supplemental/antora-dark-mode (overlay only).
+
+Please update bookmarks and playbook URLs from `antora-dark-theme` to `valentus-theme`.

docs/maintainers/npm-registry-notice.md

@@ -1,5 +1,7 @@
 # npm: web deprecate + final patch publish (use both)
 
+> **Update (2026-06-13):** npm is being **restored** as overlay transport. See `npm-republish-plan.md` for the republish checklist. npm package rename is **not** supported — reuse `antora-dark-mode`.
+
 ## Already deprecated on npmjs.com?
 
 You cannot “double-deprecate.” Running `npm deprecate` again (CLI) or using the website **replaces** the message on the versions you target—it does not stack.

docs/maintainers/npm-republish-plan.md

@@ -0,0 +1,69 @@
+# npm re-publish plan — antora-dark-mode
+
+## Goal
+
+Publish `antora-dark-mode` to npm as **overlay transport** (`supplemental-ui/` + `ui-modules/`).
+
+**Note:** As of 2026-06-13, `antora-dark-mode` is **not yet on npm** (404). Legacy installs used `antora-dark-theme@1.0.9` (deprecated). This is a **first publish** under the new name, not a registry rename.
+
+## npm rename — not possible
+
+| Action | Supported? |
+|--------|------------|
+| Publish new versions to existing `antora-dark-mode` | Yes — same package name, same maintainer access |
+| Rename `antora-dark-mode` → new name on npm | **No** — npm has no rename API |
+| Redirect `antora-dark-theme` → `antora-dark-mode` | Deprecate old package only; names stay separate |
+
+**Recommendation:** Reuse `antora-dark-mode` on npm. Do not attempt a registry rename.
+
+## Tarball contents
+
+```
+supplemental-ui/     # overlay install (Default UI or theme bundle + supplemental_files)
+ui-modules/          # slot-based dark-mode module + registry.json5
+```
+
+Not included: pre-merged `ui-bundle.zip` (GitHub Releases only).
+
+## Pre-publish checklist
+
+1. `pnpm ui-modules:sync` — CSS/JS synced from `supplemental-ui/`
+2. `pnpm ui-modules:validate` — manifests + `registry-index.json`
+3. `README.md` — overlay-first install (not bundle-only retirement)
+4. `package.json` — `"files": ["supplemental-ui/**/*", "ui-modules/**/*"]`
+5. Version bump aligned with git tag (e.g. `1.3.0`)
+
+## Publish sequence
+
+**Local (requires `npm login`):**
+
+```powershell
+cd Z:\code\github.com\antora-supplemental\antora-dark-mode
+pnpm publish:npm
+```
+
+**CI:** `.github/workflows/release.yml` publishes on semver tags when `NPM_TOKEN` is configured.
+
+```powershell
+# After publish — deprecate legacy package name (if you own antora-dark-theme)
+npm deprecate antora-dark-theme@* "Renamed — use antora-dark-mode. See https://github.com/antora-supplemental/antora-dark-mode"
+```
+
+`prepack` script runs sync + validate automatically.
+
+## Post-publish
+
+- Update Antora Supplemental extensions catalog: npm = optional transport
+- GitHub Release still ships `ui-bundle.zip` as **convenience** (Default UI only)
+- Clear npm retirement banner (`npm deprecate … ""`)
+- Announce migration for sites using `antora-dark-mode` as `ui.bundle` + valentus `supplemental_files`
+
+## CI
+
+`.github/workflows/release.yml` — no change required for npm; optional future job for `npm publish` with `NPM_TOKEN` and `environment: npm` if maintainers want automated registry publish again.
+
+## Related docs
+
+- `docs/modules/guide/pages/npm-distribution.adoc` — consumer-facing
+- `docs/modules/guide/pages/installation.adoc` — overlay-first install
+- `docs/modules/guide/pages/ui-modules.adoc` — orchestrator path

docs/modules/guide/nav.adoc

@@ -1,7 +1,8 @@
 .Documentation
 * xref:index.adoc[Getting Started]
 * xref:installation.adoc[Installation]
-* xref:npm-deprecation.adoc[npm deprecation]
+* xref:ui-modules.adoc[UI Modules]
+* xref:npm-distribution.adoc[npm distribution]
 * xref:configuration.adoc[Configuration]
 * xref:version-pinning.adoc[Version Pinning]
 * xref:customization.adoc[Customization]