Merge p22-w2-jsonld-type-fix into dev

Fix JSON-LD @type serialization: concrete nodes were emitting a bare Type alongside @type because the attribute sat only on the abstract base override. Validator now clean.
fix: put [JsonPropertyName("@type")] on each concrete JsonLdNode override
2026-06-23 06:57:44 -04:00 · 2026-06-23 06:57:05 -04:00 · 2026-06-23 06:21:52 -04:00 · 2026-06-23 06:16:31 -04:00 · 2026-06-23 06:10:03 -04:00 · 2026-06-23 05:41:55 -04:00
28 changed files with 2977 additions and 15 deletions
@@ -9,7 +9,7 @@ DeepDrftHome is a **net10.0** solution consisting of ten projects implementing a
 ### Core Projects

 - **DeepDrftPublic**: ASP.NET Core host. Blazor Web App with Server + WASM render modes. Owns browser-facing proxy controller for `api/track/*` (metadata listing and audio streaming), MudBlazor theme prerender, and TypeScript→JS audio interop. Public-facing site for listeners.
- **DeepDrftPublic.Client**: Blazor WebAssembly assembly. All interactive UI (pages, player stack, dark-mode plumbing, HTTP clients for both backends). Pages include the public `/about` editorial page (`Pages/About.razor` — three-movement **"Liner Notes"** editorial treatment: numbered left-rail (oversized Bodoni numerals + vertical hairline spine + mono marginalia captions), asymmetric content column, pull-quotes breaking into the margin, hand-authored SVG waveform movement dividers (self-contained motif, not the live `WaveformVisualizer`), and stacked editorial definition list for CUTS/SESSIONS/MIXES; active-movement highlight via `about-rail.ts` IntersectionObserver interop; registered in `Layout/Pages.cs`). Home hero stat row (`NowPlayingStats.razor`) is live-data-backed via `IStatsDataService` / `StatsClient` (named `"DeepDrft.API"` client) with a `PersistentComponentState` prerender bridge; `RuntimeFormat` helper converts mix runtime seconds to `hh:mm`. Consumed by the public site.
+- **DeepDrftPublic.Client**: Blazor WebAssembly assembly. All interactive UI (pages, player stack, dark-mode plumbing, HTTP clients for both backends). Pages include the public `/about` editorial page (`Pages/About.razor` — three-movement **"Liner Notes"** editorial treatment: numbered left-rail (oversized Bodoni numerals + vertical hairline spine + mono marginalia captions), asymmetric content column, pull-quotes breaking into the margin, hand-authored SVG waveform movement dividers (self-contained motif, not the live `WaveformVisualizer`), and stacked editorial definition list for CUTS/SESSIONS/MIXES; active-movement highlight via `about-rail.ts` IntersectionObserver interop; registered in `Layout/Pages.cs`). Home hero stat row (`NowPlayingStats.razor`) is live-data-backed via `IStatsDataService` / `StatsClient` (named `"DeepDrft.API"` client) with a `PersistentComponentState` prerender bridge; `RuntimeFormat` helper converts mix runtime seconds to `hh:mm`. **SEO component** (`Controls/SeoHead.razor` + `Common/SeoModel`, `SeoJsonLd`, `SeoOptions`, `SeoUrls`, `SeoEnvironment`): `SeoHead` is a presentational `<HeadContent>` emitter (one line per page, no fetch); `SeoModel` named factories (`ForRelease`/`ForHome`/`ForAbout`/`ForBrowse`/`ForNotFound`) encode the medium→schema.org mapping in one place; `SeoJsonLd` builds typed JSON-LD (MusicGroup / MusicAlbum+LiveAlbum / MusicRecording / CollectionPage) with inline-safe escaping; `SeoOptions` holds site-wide config (`BaseUrl https://deepdrft.com`, title suffix, default OG image seam, IG `sameAs`) registered via the static `Startup` seam; `SeoEnvironment` is a scoped `[PersistentState]` bridge (mirrors `DarkModeSettings`) seeded in `DeepDrftPublic/Components/App.razor` from `IWebHostEnvironment.IsProduction()` — robots defaults to `index,follow` only in Production, `noindex,nofollow` everywhere else (fail-safe is noindex); per-page `SeoModel.Robots` overrides the default. Tags are present in prerendered HTML (rides the existing `PersistentComponentState` bridge; no new fetch). Canonical/OG origins come from `SeoOptions.BaseUrl` (config), not `window.location` — no `window` at server prerender and the origin cannot be derived behind the nginx proxy. Consumed by the public site.
 - **DeepDrftManager**: ASP.NET Core host. Blazor Web App with server-rendered `InteractiveServer` render mode. Hosts all CMS Razor components and pages under `Components/Pages/Cms/`, `Components/Pages/Tracks/`, `Components/Layout/CmsLayout.razor`, and `Components/Shared/` (all inlined from the former `DeepDrftCms` RCL). Public entry point: `Components/Pages/Home.razor` (`@page "/"`, no `[Authorize]`, uses lean `CmsHomeLayout`) — unauthenticated visitors see a DeepDrft-branded splash with a Login CTA; authenticated admins are redirected to `/catalogue` via `RedirectToCatalogue`. `Routes.razor` resolves `DefaultLayout` from the cascaded `Task<AuthenticationState>`: unauthenticated → `CmsHomeLayout`, authenticated → `CmsLayout`; this means the AuthBlocks `Login`/`Register` pages (which declare no `@layout`) render in the lean layout for unauthenticated visitors. `CmsLayout` carries a left `MudDrawer` (app-bar hamburger toggle) holding the CMS destinations (Catalogue `/catalogue`, Releases `/releases`, Upload `/tracks/upload`), the AuthBlocks `UserAdminMenu` fragment (self-gates to `UserAdmin`+, links Users/Registrations/Permissions), and a "Provision User" link to `/useradmin/users/new` wrapped in a `HierarchicalRoleAuthorizeView` (`UserAdmin`-gated) — making the AuthBlocks user-administration surface reachable from the CMS UI. The catalogue dashboard (`Components/Pages/Index.razor`) lives at `@page "/catalogue"` and remains `[Authorize]`-gated with `CmsLayout`; its cards are **CUTS / SESSIONS / MIXES**, each deep-linking to `/releases?medium=<medium>` with the matching tab pre-selected. The consolidated browse surface is `Components/Pages/Tracks/Releases.razor` (`@page "/releases"`): bulk-action buttons (Generate All Profiles / Backfill High-res) → medium tab strip (ALL / CUTS / SESSIONS / MIXES) → the active tab's grid; waveform columns (Profile / High-res) — each showing a status icon when a datum is present and an always-visible generate/regenerate button — and per-track info tooltip live in `CmsAlbumBrowser`'s expanded child-row track table. Old list routes `/tracks`, `/tracks/albums`, `/tracks/archive` are kept as aliases on `Releases.razor` so bookmarks don't 404; operational sub-routes (`/tracks/upload`, edit routes, etc.) remain at `/tracks/*`. Gated by AuthBlocks login and hierarchical `Admin` role authorization. All track operations (upload, metadata read/write, delete, replace audio) are HTTP proxies via `ICmsTrackService` / `CmsTrackService` injected directly into Blazor components; no in-process data layer. The per-track "Replace audio" affordance in `BatchEdit` / `BatchTrackList` / `BatchTrackDetail` swaps the vault bytes, regenerates both waveform datums server-side, and re-derives `DurationSeconds` from the new audio; the track id, `EntryKey`, release membership, position, and all other metadata are preserved. The remove control on a persisted track is hidden when it is the release's sole remaining persisted track — a release can reach zero live tracks only via replace or release-level delete, not per-track removal. Two named HttpClients: `DeepDrft.Content.Cms` (bounded 100 s default, for all non-upload calls) and `DeepDrft.Content.Cms.Upload` (`InfiniteTimeSpan`, for large WAV uploads). Upload progress and idle/heartbeat timeout are driven by a single `ProgressStreamContent` wrapper (`Services/ProgressStreamContent.cs`); `CmsTrackService.UploadTrackAsync` adds a two-phase cancellation (idle window resets per progress tick; separate response-wait budget arms when the body completes). The upload form is create-only: `BatchUpload.razor` calls `GET api/track/release/exists` as a pre-flight before transferring bytes and blocks the submit with a visible message if a (title, artist) match already exists; the server also rejects duplicates with 409. The authenticated user's id (`NameIdentifier` claim) is captured once into `_createdByUserId` at component initialization (`OnInitializedAsync`) — not re-read at submit — so a mid-session token expiry cannot discard a long-composed release; the page is `[Authorize]`-gated and runs `prerender: false`, so the auth state is fully available at init and only one init pass occurs. Within-batch multi-track Cuts still work by passing the release id from row 1 as `releaseId` on rows 2..N (the ATTACH path), while `BatchEdit.razor` uses the same ATTACH path for its legitimate adds-to-existing-release.
 - **DeepDrftShared.Client**: Razor Class Library. Shared Blazor components consumed by both `DeepDrftPublic` and `DeepDrftManager` for consistency across public and admin surfaces.
 - **DeepDrftData**: Class library. EF Core domain logic: `DeepDrftContext`, `TrackConfiguration`, `Migrations`, `TrackRepository`, `TrackService`, `TrackManager`. Consumed by `DeepDrftAPI` and tests.
@@ -6,6 +6,28 @@ Newest entries at the top. Group by phase/wave header (mirroring `PLAN.md` / `CM

 ---

+## Phase 22 — SEO Metadata Component (landed 2026-06-23)
+
+**Landed:** 2026-06-23 on dev.
+
+- **What:** A parameterized, reusable SEO head component (`SeoHead.razor`) that emits the full modern-SEO head surface — standard meta, canonical, robots, Open Graph, Twitter Card, and schema.org JSON-LD — for every public page in one line of markup. **Public listener site only** (`DeepDrftPublic` host + `DeepDrftPublic.Client`); the CMS is explicitly out of scope. No data-model/schema change, no new API endpoint.
+
+- **Why:** `App.razor` had a static `<head>` with no description, canonical, OG, Twitter Card, or JSON-LD anywhere; pages set only an ad-hoc `<PageTitle>` with an inconsistent suffix. A shared `/mixes/{key}` link unfurled as a bare title + URL. Crawlers and social unfurlers saw nothing useful.
+
+- **Shape:**
+  - **`Controls/SeoHead.razor`** (new): purely presentational `<HeadContent>` + `<PageTitle>` emitter. Accepts a single `SeoModel` parameter; owns no data fetch. Each page wires it in one line.
+  - **`Common/SeoModel.cs`** (new): typed per-page input with named factories — `ForRelease(release, baseUrl, options)` (medium-dispatched), `ForHome`, `ForAbout`, `ForBrowse`, `ForNotFound`. Factories encode the medium→schema mapping in one place. Explicit `SeoModel.Robots` override available; default is environment-gated (see `SeoEnvironment`).
+  - **`Common/SeoJsonLd.cs`** (new): typed schema.org JSON-LD builders. Cut → `MusicAlbum` with ordered `MusicRecording` track list; Session → `MusicAlbum`/`LiveAlbum`; Mix → single `MusicRecording` with ISO-8601 duration; Home/About → `MusicGroup` (with `sameAs: ["https://instagram.com/deepdrft.music"]`); Browse → `CollectionPage`. `byArtist` wired per-release. JSON-LD body is inline-safe-escaped (`<`/`>`/`&` → `\uXXXX`) to prevent script-breakout from CMS-authored text.
+  - **`Common/SeoOptions.cs`** (new): site-wide config — `BaseUrl` (`https://deepdrft.com`), title suffix (`Deep DRFT`, middot separator), default OG image seam (uses `ImageProxyController` route), IG handle in `sameAs`, no Twitter handle. Registered via the static `Startup` seam (runs in both server and WASM `Program.cs`).
+  - **`Common/SeoUrls.cs`** (new): URL helpers for canonical and `og:image` construction from `SeoOptions.BaseUrl` (config, not `window.location` — no `window` at server prerender and the origin can't be derived behind the nginx proxy).
+  - **`Common/SeoEnvironment.cs`** (new): scoped `[PersistentState]` bridge seeded in `DeepDrftPublic/Components/App.razor` from `IWebHostEnvironment.IsProduction()` — mirrors the `DarkModeSettings` bridge. Default robots is `index,follow` only in Production; `noindex,nofollow` in every non-production environment so the beta/staging site stays uncrawled. Explicit per-page `SeoModel.Robots` overrides this default. Fail-safe default is `noindex`.
+  - **Wired into:** Home, About, Cut/Session/Mix detail pages (incl. their not-found branches → `noindex`), the browse views (Albums/Sessions/Mixes/Archive), and the 404 NotFound page.
+  - **Render-mode correctness:** `SeoHead` rides the existing `PersistentComponentState` bridge (the same `ReleaseDto` the detail pages already bridge) — no new fetch. The `InteractiveAuto` double-render produces identical head content across prerender and WASM passes (fed from bridged state, guarded on id/key equality).
+
+- **Design memo:** `product-notes/phase-22-seo-metadata-component.md`.
+
+---
+
 ## Phase 20 — Theater Mode (landed 2026-06-20)

 **Landed:** 2026-06-20 on dev. Pending: final manual browser/GPU smoke-test on dev.
@@ -40,6 +40,7 @@ All interactive UI for the site. Blazor WebAssembly. Pages, controls, the stream
  - `AddToQueueButton.razor`: Append-only Add-to-Queue button shared across detail-page play sites (Phase 17 wave 17.4). Two modes: track mode (calls `IQueueService.Enqueue` with a single `TrackDto`) and release mode (calls `IQueueService.EnqueueRange` with an ordered track list). Material `PlaylistAdd` glyph; tooltip "Add to queue" (track mode) / "Add release to queue" (release mode). Reads the cascaded `IQueueService`; disabled until interactive or when the cascade is absent. Append-only — does not play, does not navigate. Placed at: `CutDetail` header (release mode, `TrackNumber`-ordered list), `CutDetail` track rows (track mode), `SessionDetail` hero play (track mode), `MixDetail` hero play (track mode). Excluded from `StreamNowButton` (OQ9) and `ReleaseGallery` cards (OQ10, deferred).
  - `ReleaseDetailScaffold.razor`: Shared scaffold for release detail pages. Gained an optional `Ambient` `RenderFragment` slot (Phase 12) — a full-bleed layer rendered behind the main content. Absent slot = no regression. Cut mounts `<WaveformVisualizer>` + `<WaveformVisualizerControlPopover>` here; Mix uses its own full-bleed mount outside the scaffold. The scaffold's default masthead PLAY (`PlayTrack`) routes through `IQueueService.PlayTrack` (deque PLAY semantics — prepends the track to the queue front) when the queue cascade is present, falling back to `IStreamingPlayerService.SelectTrackStreaming` when absent; toggle-pause is handled directly via `IStreamingPlayerService.TogglePlayPause` when this track is already active.
  - `SharePopover.razor`: Share affordance serving both track and release surfaces from one clipboard/popover-chrome source. **Track mode** (`EntryKey` set): copies the track's canonical URL and offers an iframe embed snippet pointing at `FramePlayer?TrackEntryKey=…`. **Release mode** (`ReleaseEntryKey` + `ReleaseMedium` set): copies the release's canonical detail URL (via `ReleaseRoutes.DetailHref`) and offers an iframe embed snippet pointing at `FramePlayer?ReleaseEntryKey=…`, which queues and auto-advances through the release's tracks on first play. Both modes offer the embed affordance — release mode no longer suppresses it. The iframe snippet is built by `EmbedSnippetBuilder`. A transient "Copied!" confirmation resets after a short delay.
+  - `SeoHead.razor`: Purely presentational SEO head emitter (Phase 22). Renders a `<PageTitle>` + `<HeadContent>` block from a single `SeoModel` parameter — standard meta (description, robots), canonical, Open Graph, Twitter Card, and schema.org JSON-LD. Owns no data fetch; each page wires it in one line and supplies the model from its already-bridged ViewModel state. Wired on Home, About, Cut/Session/Mix detail (incl. not-found branches → `noindex`), browse views, and the 404 page.
 - `Helpers/`: Utilities and mapper functions.
  - `PlaybackIcons.cs`: Static `Resolve(isPlaying, isPaused, trackId, currentTrackId)` method — the sole glyph-mapping source for transport icons across all surfaces. Returns `(Icon, IsActive, IsPaused)` tuple.
  - `RuntimeFormat.cs`: Static `ToHoursMinutes(double totalSeconds)` helper. Formats a seconds value as `h:mm` (hours not zero-padded, minutes always two digits). Negative / non-finite inputs return `"0:00"`. Used by `NowPlayingStats` for the mix runtime figure.
@@ -70,6 +71,11 @@ All interactive UI for the site. Blazor WebAssembly. Pages, controls, the stream
 - `Common/`: Shared utilities.
  - `DarkModeSettings.cs`: `[PersistentState]`-annotated class (single source of truth for dark mode in the client). Registered scoped.
  - `ReleaseRoutes.cs`: Static helper. `DetailHref(long id, ReleaseMedium)` returns the canonical public detail route for a release; consumed by Archive, AlbumsView, player bar, and TrackRedirect (11.B).
+  - `SeoModel.cs`: Typed per-page SEO input (Phase 22). Named factories: `ForRelease` (medium-dispatched — Cut → `MusicAlbum`, Session → `MusicAlbum`/`LiveAlbum`, Mix → `MusicRecording`), `ForHome`, `ForAbout`, `ForBrowse`, `ForNotFound`. Encodes the medium→schema.org mapping in one place. `SeoModel.Robots` overrides the environment-default (see `SeoEnvironment`).
+  - `SeoJsonLd.cs`: Typed schema.org JSON-LD builders (Phase 22). Types: `MusicGroup` (home/about, with `sameAs: ["https://instagram.com/deepdrft.music"]`), `MusicAlbum`/`LiveAlbum` (cuts/sessions, with ordered `MusicRecording` track list and per-release `byArtist`), `MusicRecording` (mixes, with ISO-8601 `duration`), `CollectionPage` (browse). All serialized output is inline-safe-escaped (`<`/`>`/`&` → `\uXXXX`) to prevent script-breakout from CMS-authored text.
+  - `SeoOptions.cs`: Site-wide SEO config (Phase 22). `BaseUrl` (`https://deepdrft.com`), title suffix (`Deep DRFT`, middot separator), default OG image seam (uses `ImageProxyController` route), IG handle in `sameAs`, no Twitter handle. Registered via the static `Startup` seam (both server and WASM `Program.cs`). `BaseUrl` is config, not `window.location` — no `window` at server prerender, and the origin cannot be derived reliably behind the nginx proxy.
+  - `SeoUrls.cs`: URL helpers for canonical and `og:image` construction from `SeoOptions.BaseUrl` (Phase 22).
+  - `SeoEnvironment.cs`: Scoped `[PersistentState]` bridge for the server environment flag (Phase 22). Seeded in `DeepDrftPublic/Components/App.razor` from `IWebHostEnvironment.IsProduction()` — mirrors the `DarkModeSettings` bridge pattern. Default robots is `index,follow` only in Production; `noindex,nofollow` in every non-production environment so the beta/staging site stays uncrawled. Explicit per-page `SeoModel.Robots` overrides this default. Fail-safe default is `noindex`.
 - `Program.cs`: WASM entry point. Calls `Startup.ConfigureApiHttpClient`, `ConfigureContentServices`, `ConfigureDomainServices`.
 - `_Imports.razor`: Global using statements and component imports.

@@ -129,6 +135,8 @@ New modules in `DeepDrftPublic/Interop/audio/`:

 The flow ensures the first paint uses the correct theme (no flash), and toggling the button persists the setting to a 365-day cookie.

+**`SeoEnvironment` follows the same `[PersistentState]` bridge pattern** (Phase 22). It is seeded server-side in `DeepDrftPublic/Components/App.razor` from `IWebHostEnvironment.IsProduction()` and bridged to the WASM client. Consumers (`SeoHead`) read `SeoEnvironment.IsProduction` to gate the default robots directive (`index,follow` in Production, `noindex,nofollow` elsewhere). The pattern is identical to `DarkModeSettings` — one server-side seed, one `PersistentComponentState` round-trip, one scoped client read.
+
 ## MVVM convention

 Component state lives in ViewModels (registered scoped in DI). Components render and dispatch only.
@@ -0,0 +1,33 @@
+using Microsoft.AspNetCore.Components;
+
+namespace DeepDrftPublic.Client.Common;
+
+/// <summary>
+/// Environment-gated robots bridge (Phase 22 remediation §4). The beta/staging site is web-hosted and must
+/// not be crawled, so the <i>default</i> robots directive is environment-gated: <c>index,follow</c> only in
+/// Production, <c>noindex,nofollow</c> everywhere else. A per-page <see cref="SeoModel.Robots"/> override
+/// still wins — this only sets the default.
+///
+/// <para>
+/// Crawlers read the server-prerendered HTML, so correctness lives in the server prerender pass — but the
+/// value must be identical across the InteractiveAuto double render (AC6), so the WASM pass has to resolve
+/// the same flag. The WASM assembly has no <c>IWebHostEnvironment</c> (config comes from the server). This
+/// mirrors the DarkMode bridge exactly: a scoped service the server seeds during prerender (from
+/// <c>IWebHostEnvironment.IsProduction()</c>) and <c>[PersistentState]</c> rounds to the client, so both
+/// passes resolve the identical value. <c>SeoHead</c> injects this rather than an environment dependency,
+/// honouring the no-environment-in-the-component constraint.
+/// </para>
+/// </summary>
+public class SeoEnvironment
+{
+    /// <summary>
+    /// True only in Production. Seeded server-side and persisted across the WASM boot. Defaults to
+    /// <c>false</c> so the fail-safe is "do not index" — a missing bridge never accidentally opens a
+    /// non-production site to crawlers.
+    /// </summary>
+    [PersistentState]
+    public bool IsProduction { get; set; }
+
+    /// <summary>The environment-gated default robots directive. Explicit page values override this.</summary>
+    public string DefaultRobots => IsProduction ? "index,follow" : "noindex,nofollow";
+}
@@ -0,0 +1,127 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace DeepDrftPublic.Client.Common;
+
+/// <summary>
+/// Typed schema.org JSON-LD nodes (Phase 22, OQ5 — the typed-builder option). Each record mirrors one
+/// schema.org type; <see cref="SeoJsonLd.Serialize"/> renders a node to the <c>&lt;script type="application/ld+json"&gt;</c>
+/// body. Keeping the shape in C# (not hand-written JSON in pages) is what makes the medium→type mapping
+/// live in one place (DRY, §4.3) and the output unit-testable (AC5) rather than a manual validator pass.
+///
+/// <para>
+/// All nodes share <see cref="JsonLdNode"/> so the <c>@context</c>/<c>@type</c> pair serialises first and
+/// once. Null properties are omitted (the serializer ignores nulls) so partial data never emits an empty
+/// or broken node (C6/AC4).
+/// </para>
+/// </summary>
+public static class SeoJsonLd
+{
+    private static readonly JsonSerializerOptions Options = new()
+    {
+        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+        // schema.org keys are PascalCase ("@type", "byArtist", "datePublished"); JsonPropertyName drives
+        // each. Encoder relaxed so the JSON sits inline in HTML without over-escaping apostrophes etc.
+        // Note: the relaxed encoder leaves <, >, & raw — InlineSafe re-escapes exactly those before the
+        // body is injected into the <script> element. See Serialize.
+        Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
+        WriteIndented = false,
+    };
+
+    /// <summary>
+    /// Renders a node to its compact JSON-LD script body. The host component wraps it in the script tag.
+    /// The body is run through <see cref="InlineSafe"/> so CMS-authored values containing
+    /// <c>&lt;/script&gt;</c> or <c>&lt;</c> cannot break out of the inline script element (XSS).
+    /// </summary>
+    public static string Serialize<TNode>(TNode node) where TNode : JsonLdNode =>
+        InlineSafe(JsonSerializer.Serialize(node, node.GetType(), Options));
+
+    /// <summary>
+    /// Escapes the three characters that can break out of an inline <c>&lt;script type="application/ld+json"&gt;</c>
+    /// element. Replacing <c>&lt;</c>/<c>&gt;</c>/<c>&amp;</c> with their <c>\uXXXX</c> JSON escapes keeps the
+    /// JSON byte-for-byte equivalent on parse (a JSON string treats <c><</c> and <c>&lt;</c> identically)
+    /// while making <c>&lt;/script&gt;</c> impossible to emit raw — the documented safe pattern for inline JSON-LD.
+    /// </summary>
+    internal static string InlineSafe(string json) => json
+        .Replace("<", "\\u003C")
+        .Replace(">", "\\u003E")
+        .Replace("&", "\\u0026");
+}
+
+/// <summary>Base for every schema.org node: emits <c>@context</c> and <c>@type</c> first.</summary>
+public abstract record JsonLdNode
+{
+    [JsonPropertyName("@context")]
+    [JsonPropertyOrder(-2)]
+    public string Context => "https://schema.org";
+
+    [JsonPropertyName("@type")]
+    [JsonPropertyOrder(-1)]
+    public abstract string Type { get; }
+}
+
+/// <summary>The Deep DRFT collective entity — the home/about node.</summary>
+public sealed record MusicGroupNode : JsonLdNode
+{
+    [JsonPropertyName("@type")] public override string Type => "MusicGroup";
+
+    [JsonPropertyName("name")] public string Name { get; init; } = string.Empty;
+    [JsonPropertyName("url")] public string? Url { get; init; }
+    [JsonPropertyName("genre")] public string? Genre { get; init; }
+    [JsonPropertyName("description")] public string? Description { get; init; }
+    [JsonPropertyName("logo")] public string? Logo { get; init; }
+    [JsonPropertyName("sameAs")] public IReadOnlyList<string>? SameAs { get; init; }
+}
+
+/// <summary>A studio cut or a live session release. <c>AlbumProductionType</c> distinguishes them.</summary>
+public sealed record MusicAlbumNode : JsonLdNode
+{
+    [JsonPropertyName("@type")] public override string Type => "MusicAlbum";
+
+    [JsonPropertyName("name")] public string Name { get; init; } = string.Empty;
+    [JsonPropertyName("byArtist")] public ArtistRef? ByArtist { get; init; }
+
+    /// <summary>schema.org <c>MusicAlbumProductionType</c> URI, e.g. <c>StudioAlbum</c> or <c>LiveAlbum</c>.</summary>
+    [JsonPropertyName("albumProductionType")] public string? AlbumProductionType { get; init; }
+
+    [JsonPropertyName("datePublished")] public string? DatePublished { get; init; }
+    [JsonPropertyName("genre")] public string? Genre { get; init; }
+    [JsonPropertyName("image")] public string? Image { get; init; }
+    [JsonPropertyName("url")] public string? Url { get; init; }
+
+    /// <summary>Ordered list of the album's recordings (cut track list, in TrackNumber order).</summary>
+    [JsonPropertyName("track")] public IReadOnlyList<MusicRecordingNode>? Track { get; init; }
+}
+
+/// <summary>A single recording — a mix release, or one track inside an album's <c>track</c> list.</summary>
+public sealed record MusicRecordingNode : JsonLdNode
+{
+    [JsonPropertyName("@type")] public override string Type => "MusicRecording";
+
+    [JsonPropertyName("name")] public string Name { get; init; } = string.Empty;
+    [JsonPropertyName("byArtist")] public ArtistRef? ByArtist { get; init; }
+
+    /// <summary>ISO-8601 duration (e.g. <c>PT1H2M3S</c>) from <c>DurationSeconds</c>.</summary>
+    [JsonPropertyName("duration")] public string? Duration { get; init; }
+
+    [JsonPropertyName("genre")] public string? Genre { get; init; }
+    [JsonPropertyName("image")] public string? Image { get; init; }
+    [JsonPropertyName("url")] public string? Url { get; init; }
+}
+
+/// <summary>A browse/index surface listing releases (cuts/sessions/mixes/archive).</summary>
+public sealed record CollectionPageNode : JsonLdNode
+{
+    [JsonPropertyName("@type")] public override string Type => "CollectionPage";
+
+    [JsonPropertyName("name")] public string Name { get; init; } = string.Empty;
+    [JsonPropertyName("description")] public string? Description { get; init; }
+    [JsonPropertyName("url")] public string? Url { get; init; }
+}
+
+/// <summary>A nested <c>byArtist</c> reference — the collective as a MusicGroup, by name.</summary>
+public sealed record ArtistRef
+{
+    [JsonPropertyName("@type")] public string Type => "MusicGroup";
+    [JsonPropertyName("name")] public string Name { get; init; } = string.Empty;
+}
@@ -0,0 +1,209 @@
+using DeepDrftModels.DTOs;
+using DeepDrftModels.Enums;
+
+namespace DeepDrftPublic.Client.Common;
+
+/// <summary>
+/// The OG <c>og:type</c> for a page. Releases map per medium (§3.4); everything else is a website.
+/// </summary>
+public enum SeoOgType
+{
+    Website,
+    MusicAlbum,
+    MusicSong,
+}
+
+/// <summary>
+/// The typed per-page SEO input (Phase 22). A page hands <c>SeoHead</c> one model instead of ~15 loose
+/// parameters; the named factories below encode the per-page / per-medium mapping (title, description,
+/// canonical path, og:type, JSON-LD node) in exactly one place each (DRY, §4.1/§4.2). The factories are
+/// pure functions over DTOs the page already holds — unit-testable without rendering.
+///
+/// <para>
+/// <see cref="CanonicalPath"/> is site-relative; <c>SeoHead</c> absolutises it against
+/// <see cref="SeoOptions.BaseUrl"/>. Release pages pass <see cref="ReleaseRoutes.DetailHref"/> so the
+/// canonical is the dedicated route regardless of alias/query routes (AC7). A null cover means the model
+/// carries no <see cref="ImagePath"/> and <c>SeoHead</c> falls back to the default OG image (C6/AC4).
+/// </para>
+/// </summary>
+public sealed record SeoModel
+{
+    /// <summary>Bare page title, no site suffix. <c>SeoHead</c> composes <c>"{Title} · {suffix}"</c>.</summary>
+    public required string Title { get; init; }
+
+    /// <summary>Meta/OG description. Null falls back to <see cref="SeoOptions.DefaultDescription"/>.</summary>
+    public string? Description { get; init; }
+
+    /// <summary>Site-relative canonical path. Null defaults to the current path in <c>SeoHead</c>.</summary>
+    public string? CanonicalPath { get; init; }
+
+    /// <summary>Relative cover <c>ImagePath</c>. Null → the default OG image.</summary>
+    public string? ImagePath { get; init; }
+
+    public SeoOgType OgType { get; init; } = SeoOgType.Website;
+
+    /// <summary>Robots directive. Null falls back to <see cref="SeoOptions.DefaultRobots"/>.</summary>
+    public string? Robots { get; init; }
+
+    /// <summary>Pre-serialised JSON-LD script body, or null to emit no structured-data script.</summary>
+    public string? JsonLd { get; init; }
+
+    // --- Music-vertical OG, release pages only (null elsewhere → tags omitted) ---
+    public string? Artist { get; init; }
+    public DateOnly? ReleaseDate { get; init; }
+    public double? DurationSeconds { get; init; }
+
+    // ------------------------------------------------------------------ Factories
+
+    /// <summary>Home page: the collective entity (MusicGroup JSON-LD), site-level OG.</summary>
+    public static SeoModel ForHome(SeoOptions options) => new()
+    {
+        Title = "Electronic Music Collective",
+        Description = options.DefaultDescription,
+        CanonicalPath = "/",
+        OgType = SeoOgType.Website,
+        JsonLd = SeoJsonLd.Serialize(MusicGroup(options)),
+    };
+
+    /// <summary>About page: the collective again, with the bio lede as description.</summary>
+    public static SeoModel ForAbout(SeoOptions options) => new()
+    {
+        Title = "The Collective",
+        Description =
+            "Two people, many hats. Deep DRFT brings the heart and soul of Midwest deep house to " +
+            "Charleston — informed by the founders of the style, and promising to push it forward.",
+        CanonicalPath = "/about",
+        OgType = SeoOgType.Website,
+        JsonLd = SeoJsonLd.Serialize(MusicGroup(options) with
+        {
+            Description =
+                "Two people, many hats. Deep DRFT brings the heart and soul of Midwest deep house to " +
+                "Charleston — informed by the founders of the style, and promising to push it forward.",
+        }),
+    };
+
+    /// <summary>A browse surface: <c>CollectionPage</c> JSON-LD, website OG.</summary>
+    public static SeoModel ForBrowse(SeoOptions options, ReleaseMedium? medium, string path)
+    {
+        var (title, description) = BrowseCopy(medium);
+        return new SeoModel
+        {
+            Title = title,
+            Description = description,
+            CanonicalPath = path,
+            OgType = SeoOgType.Website,
+            JsonLd = SeoJsonLd.Serialize(new CollectionPageNode
+            {
+                Name = title,
+                Description = description,
+                Url = SeoUrls.Absolute(options, path),
+            }),
+        };
+    }
+
+    /// <summary>The 404 page: no canonical, <c>noindex,follow</c>, no JSON-LD.</summary>
+    public static SeoModel ForNotFound(SeoOptions options) => new()
+    {
+        Title = "Not Found",
+        Description = options.DefaultDescription,
+        Robots = "noindex,follow",
+        OgType = SeoOgType.Website,
+    };
+
+    /// <summary>
+    /// A release detail page. The medium picks the schema (cut/session → MusicAlbum, mix → MusicRecording),
+    /// the og:type, and the music-vertical OG fields; the canonical is the dedicated route. The optional
+    /// <paramref name="tracks"/> seed the album's ordered <c>track</c> list (cut). <b>One call site, all tags.</b>
+    /// </summary>
+    public static SeoModel ForRelease(SeoOptions options, ReleaseDto release, IReadOnlyList<TrackDto>? tracks = null)
+    {
+        var canonicalPath = ReleaseRoutes.DetailHref(release.EntryKey, release.Medium);
+        var image = SeoUrls.CoverOrDefault(options, release.ImagePath);
+        // byArtist reflects the release's own artist, consistent with the music:musician OG tag (Daniel's
+        // call) — not the collective name. Album sub-recordings share it: the tracks are by this artist.
+        var artist = new ArtistRef { Name = release.Artist };
+        var description = string.IsNullOrWhiteSpace(release.Description) ? options.DefaultDescription : release.Description;
+
+        // A mix is a single recording; its duration comes from the (single) track when present.
+        var mixDurationSeconds = release.Medium == ReleaseMedium.Mix
+            ? tracks?.FirstOrDefault()?.DurationSeconds
+            : null;
+
+        JsonLdNode node = release.Medium switch
+        {
+            ReleaseMedium.Mix => new MusicRecordingNode
+            {
+                Name = release.Title,
+                ByArtist = artist,
+                Duration = SeoUrls.IsoDuration(mixDurationSeconds),
+                Genre = release.Genre,
+                Image = image,
+                Url = SeoUrls.Absolute(options, canonicalPath),
+            },
+            // Cut and Session are both albums; the production type distinguishes a live session.
+            _ => new MusicAlbumNode
+            {
+                Name = release.Title,
+                ByArtist = artist,
+                AlbumProductionType = release.Medium == ReleaseMedium.Session
+                    ? "https://schema.org/LiveAlbum"
+                    : "https://schema.org/StudioAlbum",
+                DatePublished = release.ReleaseDate?.ToString("yyyy-MM-dd"),
+                Genre = release.Genre,
+                Image = image,
+                Url = SeoUrls.Absolute(options, canonicalPath),
+                Track = AlbumTracks(options, artist, tracks),
+            },
+        };
+
+        return new SeoModel
+        {
+            Title = release.Title,
+            Description = description,
+            CanonicalPath = canonicalPath,
+            ImagePath = release.ImagePath,
+            OgType = release.Medium == ReleaseMedium.Mix ? SeoOgType.MusicSong : SeoOgType.MusicAlbum,
+            Artist = release.Artist,
+            ReleaseDate = release.ReleaseDate,
+            DurationSeconds = mixDurationSeconds,
+            JsonLd = SeoJsonLd.Serialize(node),
+        };
+    }
+
+    // The collective entity, built once from config — the home/about JSON-LD root.
+    private static MusicGroupNode MusicGroup(SeoOptions options) => new()
+    {
+        Name = options.SiteName,
+        Url = SeoUrls.Absolute(options, "/"),
+        Genre = options.Genre,
+        Description = options.DefaultDescription,
+        Logo = SeoUrls.Absolute(options, options.DefaultImageUrl),
+        SameAs = options.SameAs.Count > 0 ? options.SameAs : null,
+    };
+
+    // Ordered recording list for an album's `track` property. Null when there are no tracks so the
+    // property is omitted rather than emitting an empty array (C6).
+    private static IReadOnlyList<MusicRecordingNode>? AlbumTracks(
+        SeoOptions options, ArtistRef artist, IReadOnlyList<TrackDto>? tracks)
+    {
+        if (tracks is null || tracks.Count == 0) return null;
+
+        return tracks
+            .OrderBy(t => t.TrackNumber)
+            .Select(t => new MusicRecordingNode
+            {
+                Name = t.TrackName,
+                ByArtist = artist,
+                Duration = SeoUrls.IsoDuration(t.DurationSeconds),
+            })
+            .ToList();
+    }
+
+    private static (string Title, string Description) BrowseCopy(ReleaseMedium? medium) => medium switch
+    {
+        ReleaseMedium.Cut => ("Cuts", "Studio cuts from Deep DRFT — composed, layered, and finished."),
+        ReleaseMedium.Session => ("Sessions", "Live sessions from Deep DRFT — performances caught in the moment, unrepeatable and unedited."),
+        ReleaseMedium.Mix => ("Mixes", "DJ mixes from Deep DRFT — uninterrupted sets, one track bleeding into the next."),
+        _ => ("Archive", "The full Deep DRFT catalogue — cuts, sessions, and mixes, indexed and always expanding."),
+    };
+}
@@ -0,0 +1,52 @@
+namespace DeepDrftPublic.Client.Common;
+
+/// <summary>
+/// Site-wide SEO defaults (Phase 22). These are non-secret brand constants — a single canonical origin,
+/// the site name/suffix, the fallback share image, the social links — sourced once and injected into
+/// <c>SeoHead</c> so no page re-declares them. Registered as a singleton in
+/// <see cref="Startup.ConfigureDomainServices"/>, which runs in <b>both</b> the server prerender and the
+/// WASM passes, so both passes resolve identical values (the double-render-identity requirement, §5/AC6).
+///
+/// <para>
+/// <see cref="BaseUrl"/> is the load-bearing field: absolute canonical / <c>og:url</c> / <c>og:image</c>
+/// origins all come from here, never from a browser API — there is no <c>window.location</c> during
+/// server prerender, and the request host is unreliable behind the nginx reverse proxy (§5, OQ1).
+/// </para>
+/// </summary>
+public sealed record SeoOptions
+{
+    /// <summary>Canonical production origin, no trailing slash. Absolute URLs are this + a resolved path (OQ1).</summary>
+    public string BaseUrl { get; init; } = "https://deepdrft.com";
+
+    /// <summary>The brand name used in <c>og:site_name</c>, <c>application-name</c>, and the JSON-LD MusicGroup.</summary>
+    public string SiteName { get; init; } = "Deep DRFT";
+
+    /// <summary>Appended to a page's bare title as <c>"{Title} · {TitleSuffix}"</c>. Resolves the prior suffix inconsistency (OQ4).</summary>
+    public string TitleSuffix { get; init; } = "Deep DRFT";
+
+    /// <summary>Fallback meta/OG description for pages that supply none.</summary>
+    public string DefaultDescription { get; init; } =
+        "Deep DRFT — an electronic music collective from Charleston, South Carolina. Studio cuts, live sessions, and DJ mixes.";
+
+    /// <summary>
+    /// Absolute or root-relative URL of the default 1200×630 share image used when a page has no cover (OQ2).
+    /// A placeholder path until the real asset is dropped in; swapping it is a one-value change.
+    /// </summary>
+    public string DefaultImageUrl { get; init; } = "/img/og-default.png";
+
+    /// <summary>OG locale. Optional surface tag.</summary>
+    public string Locale { get; init; } = "en_US";
+
+    /// <summary>The collective's primary genre, used in the MusicGroup JSON-LD node.</summary>
+    public string Genre { get; init; } = "Electronic";
+
+    // The default robots directive is NOT a static option — it is environment-gated (Production →
+    // index,follow; non-production → noindex,nofollow) via SeoEnvironment so the beta/staging site is
+    // never crawled. A page's explicit SeoModel.Robots still overrides that default.
+
+    /// <summary>
+    /// Public social profile URLs for the MusicGroup <c>sameAs</c> array (OQ3). Instagram only —
+    /// no Twitter/X account exists, so no <c>twitter:site</c>/<c>twitter:creator</c> handle is emitted.
+    /// </summary>
+    public IReadOnlyList<string> SameAs { get; init; } = ["https://instagram.com/deepdrft.music"];
+}
@@ -0,0 +1,44 @@
+namespace DeepDrftPublic.Client.Common;
+
+/// <summary>
+/// Absolute-URL composition for SEO tags (Phase 22). Canonical / <c>og:url</c> / <c>og:image</c> origins
+/// all come from <see cref="SeoOptions.BaseUrl"/> (config), never from a browser API — there is no
+/// <c>window.location</c> during server prerender and the request host is unreliable behind nginx
+/// (§5, OQ1). Shared by the <c>SeoModel</c> factories (which absolutise JSON-LD <c>url</c>/<c>image</c>)
+/// and <c>SeoHead</c> (which absolutises the meta/OG tags) so the rule lives in exactly one place.
+/// </summary>
+public static class SeoUrls
+{
+    /// <summary>BaseUrl + a site-relative path. Both sides are trimmed so the join never doubles or drops the slash.</summary>
+    public static string Absolute(SeoOptions options, string path)
+    {
+        var origin = options.BaseUrl.TrimEnd('/');
+        if (string.IsNullOrEmpty(path)) return origin;
+        return $"{origin}/{path.TrimStart('/')}";
+    }
+
+    /// <summary>
+    /// Absolute URL of a release/track cover from its FileDatabase <c>ImagePath</c>, via the public image
+    /// route (<c>api/image/{escaped}</c>). Returns the configured default share image when no cover exists
+    /// (C6/AC4 — a default guarantees <c>og:image</c> presence).
+    /// </summary>
+    public static string CoverOrDefault(SeoOptions options, string? imagePath)
+    {
+        if (string.IsNullOrWhiteSpace(imagePath))
+            return Absolute(options, options.DefaultImageUrl);
+
+        return Absolute(options, $"api/image/{Uri.EscapeDataString(imagePath)}");
+    }
+
+    /// <summary>
+    /// ISO-8601 duration (e.g. <c>PT1H2M3S</c>) from a seconds value, for JSON-LD <c>duration</c> and the
+    /// <c>music:duration</c> OG tag. Null / non-finite / non-positive input yields null (omit the tag).
+    /// </summary>
+    public static string? IsoDuration(double? seconds)
+    {
+        if (seconds is null || double.IsNaN(seconds.Value) || double.IsInfinity(seconds.Value) || seconds.Value <= 0)
+            return null;
+
+        return System.Xml.XmlConvert.ToString(TimeSpan.FromSeconds(seconds.Value));
+    }
+}
@@ -0,0 +1,116 @@
+@using DeepDrftPublic.Client.Common
+@inject SeoOptions Seo
+@inject SeoEnvironment SeoEnv
+@inject NavigationManager Nav
+
+@*
+   The single reusable SEO head surface (Phase 22). Presentational and parameter-fed — owns no fetch and
+   no business logic (C4); it reads the injected SeoOptions for defaults and NavigationManager for the
+   current path. Renders <PageTitle> (the sole title source — pages drop their bare <PageTitle>) plus a
+   <HeadContent> block carrying the full standard/OG/Twitter/JSON-LD surface (§3), projected into the
+   <HeadOutlet> in App.razor so it is present in the prerendered HTML a crawler sees (C2/AC1).
+
+   Identical output across the InteractiveAuto double render (AC6): every value comes from the parameter
+   Model (built from the page's bridged PersistentComponentState) and config — never a browser API — so
+   the prerender and WASM passes render byte-identical tags.
+
+   Partial data (C6/AC4): a missing value falls back to config or omits its tag; og:image always resolves
+   (the default guarantees presence) so there is never a content="" attribute or a broken node.
+*@
+
+<PageTitle>@_fullTitle</PageTitle>
+
+<HeadContent>
+    @* Standard / search *@
+    <meta name="description" content="@_description" />
+    <link rel="canonical" href="@_canonical" />
+    <meta name="robots" content="@_robots" />
+    <meta name="application-name" content="@Seo.SiteName" />
+
+    @* Open Graph *@
+    <meta property="og:title" content="@Model.Title" />
+    <meta property="og:description" content="@_description" />
+    <meta property="og:url" content="@_canonical" />
+    <meta property="og:type" content="@_ogType" />
+    <meta property="og:site_name" content="@Seo.SiteName" />
+    <meta property="og:locale" content="@Seo.Locale" />
+    <meta property="og:image" content="@_image" />
+    @if (_hasCover)
+    {
+        <meta property="og:image:alt" content="@($"{Model.Title} cover art")" />
+    }
+
+    @* Music-vertical OG (release pages only) *@
+    @if (!string.IsNullOrWhiteSpace(Model.Artist))
+    {
+        <meta property="music:musician" content="@Model.Artist" />
+    }
+    @if (Model.ReleaseDate is not null)
+    {
+        <meta property="music:release_date" content="@Model.ReleaseDate.Value.ToString("yyyy-MM-dd")" />
+    }
+    @if (_isoDuration is not null)
+    {
+        <meta property="music:duration" content="@_isoDuration" />
+    }
+
+    @* Twitter Card. No twitter:site / twitter:creator — no X account exists (OQ3). *@
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content="@Model.Title" />
+    <meta name="twitter:description" content="@_description" />
+    <meta name="twitter:image" content="@_image" />
+
+    @* JSON-LD structured data *@
+    @if (!string.IsNullOrEmpty(Model.JsonLd))
+    {
+        <script type="application/ld+json">@((MarkupString)Model.JsonLd)</script>
+    }
+</HeadContent>
+
+@code {
+    /// <summary>The page's resolved SEO input, built via a <see cref="SeoModel"/> factory.</summary>
+    [Parameter, EditorRequired] public required SeoModel Model { get; set; }
+
+    private string _fullTitle = string.Empty;
+    private string _description = string.Empty;
+    private string _canonical = string.Empty;
+    private string _robots = string.Empty;
+    private string _ogType = "website";
+    private string _image = string.Empty;
+    private bool _hasCover;
+    private string? _isoDuration;
+
+    protected override void OnParametersSet()
+    {
+        _fullTitle = $"{Model.Title} · {Seo.TitleSuffix}";
+        _description = string.IsNullOrWhiteSpace(Model.Description) ? Seo.DefaultDescription : Model.Description;
+        // Default robots is environment-gated (non-production → noindex,nofollow) so beta/staging is never
+        // crawled; an explicit per-page Robots still wins (e.g. the 404's / soft-404's noindex,follow).
+        _robots = string.IsNullOrWhiteSpace(Model.Robots) ? SeoEnv.DefaultRobots : Model.Robots;
+        _ogType = OgTypeString(Model.OgType);
+
+        // Canonical: BaseUrl + the model's path, defaulting to the current relative path. The origin is
+        // always config (no browser API) so prerender and WASM agree (§5).
+        var path = Model.CanonicalPath ?? RelativePath();
+        _canonical = SeoUrls.Absolute(Seo, path);
+
+        _hasCover = !string.IsNullOrWhiteSpace(Model.ImagePath);
+        _image = SeoUrls.CoverOrDefault(Seo, Model.ImagePath);
+        _isoDuration = SeoUrls.IsoDuration(Model.DurationSeconds);
+    }
+
+    private string RelativePath()
+    {
+        var path = Nav.ToBaseRelativePath(Nav.Uri);
+        var query = path.IndexOf('?');
+        if (query >= 0) path = path[..query];
+        return "/" + path;
+    }
+
+    private static string OgTypeString(SeoOgType type) => type switch
+    {
+        SeoOgType.MusicAlbum => "music.album",
+        SeoOgType.MusicSong => "music.song",
+        _ => "website",
+    };
+}
@@ -2,8 +2,9 @@
@using DeepDrftPublic.Client.Controls
@implements IAsyncDisposable
@inject IJSRuntime JsRuntime
+@inject SeoOptions Seo

-<PageTitle>The Collective - Deep DRFT</PageTitle>
+<SeoHead Model="@SeoModel.ForAbout(Seo)" />

@* ──────────────────────────────────────────────────────────────────────────────
   THE LINER NOTES — a numbered three-movement editorial essay.
@@ -1,7 +1,9 @@
@page "/cuts"
+@using DeepDrftModels.Enums
@using DeepDrftPublic.Client.Controls
+@inject SeoOptions Seo

-<PageTitle>DeepDrft Cuts</PageTitle>
+<SeoHead Model="@SeoModel.ForBrowse(Seo, ReleaseMedium.Cut, "/cuts")" />

@* The shared release-card grid; each card routes to /cuts/{entryKey} via the one ReleaseRoutes table.
   Cuts show a track count where other media show the artist, supplied via SubtitleResolver. *@
@@ -1,8 +1,9 @@
@page "/archive"
@using DeepDrftModels.Enums
@using DeepDrftPublic.Client.Controls
+@inject SeoOptions Seo

-<PageTitle>DeepDrft Archive</PageTitle>
+<SeoHead Model="@SeoModel.ForBrowse(Seo, null, "/archive")" />

 <div>
    <MudContainer MaxWidth="MaxWidth.Large" Class="archive-view-container">
@@ -3,8 +3,7 @@
@using DeepDrftPublic.Client.Controls
@using DeepDrftPublic.Client.Services
@inherits CutDetailBase
-
-<PageTitle>@(ViewModel.Release?.Title ?? "Cut") - DeepDrft</PageTitle>
+@inject SeoOptions Seo

@if (ViewModel.IsLoading)
 {
@@ -17,6 +16,9 @@
 }
 else if (ViewModel.NotFound || ViewModel.Release is null)
 {
+    @* Soft-404: a bad key renders a 200 "not found" view, so it must carry noindex so it is not indexed
+       (mirrors the dedicated /404 NotFound page). *@
+    <SeoHead Model="@SeoModel.ForNotFound(Seo)" />
    <div class="deepdrft-track-detail-container">
        <div class="deepdrft-track-detail-masthead">
            <MudText Typo="Typo.h4" Align="Align.Center">Cut not found.</MudText>
@@ -37,6 +39,10 @@ else
    var hasYear = release.ReleaseDate is not null;
    var firstTrack = ViewModel.Tracks.Count > 0 ? ViewModel.Tracks[0] : null;

+    @* SEO head — fed from the same bridged release + ordered tracks, so the prerender and WASM passes
+       render identical tags (AC6). MusicAlbum/StudioAlbum with the ordered track list (§3.4). *@
+    <SeoHead Model="@SeoModel.ForRelease(Seo, release, ViewModel.Tracks)" />
+
    @* Full-screen content body (Phase 20 Wave 2 §1): the scaffold has no Class param, so a thin wrapper
       carries the min-height. dd-detail-fill keeps the body >= viewport height (below the nav) so the
       ambient visualizer reads full-screen and the site footer is pushed below the fold. *@
@@ -1,8 +1,9 @@
@page "/"
@using DeepDrftPublic.Client.Controls
@using DeepDrftPublic.Client.Services
+@inject SeoOptions Seo

-<PageTitle>Deep DRFT - Electronic Music Collective</PageTitle>
+<SeoHead Model="@SeoModel.ForHome(Seo)" />

@* Hero - split 50/50 *@
 <section class="hero">
@@ -2,8 +2,7 @@
@using DeepDrftPublic.Client.Controls
@using DeepDrftPublic.Client.Services
@inherits ReleaseDetailBase
-
-<PageTitle>@(ViewModel.Release?.Title ?? "Mix") - DeepDrft</PageTitle>
+@inject SeoOptions Seo

@if (ViewModel.IsLoading)
 {
@@ -16,6 +15,9 @@
 }
 else if (ViewModel.NotFound || ViewModel.Release is null)
 {
+    @* Soft-404: a bad key renders a 200 "not found" view, so it must carry noindex so it is not indexed
+       (mirrors the dedicated /404 NotFound page). *@
+    <SeoHead Model="@SeoModel.ForNotFound(Seo)" />
    <div class="deepdrft-track-detail-container">
        <div class="deepdrft-track-detail-masthead">
            <MudText Typo="Typo.h4" Align="Align.Center">Mix not found.</MudText>
@@ -32,6 +34,11 @@ else if (ViewModel.NotFound || ViewModel.Release is null)
 else
 {
    var release = ViewModel.Release;
+    var mixTracks = ViewModel.Track is not null ? new[] { ViewModel.Track } : null;
+
+    @* SEO head — fed from the same bridged release + single track, so prerender and WASM render identical
+       tags (AC6). MusicRecording with ISO-8601 duration from the track (§3.4). *@
+    <SeoHead Model="@SeoModel.ForRelease(Seo, release, mixTracks)" />

    @* Full-page waveform sits behind the scaffold content. The scaffold's container is positioned
       above it via the mix-detail-foreground stacking context. TrackId lets the visualizer couple to
@@ -1,8 +1,10 @@
@page "/mixes"
+@using DeepDrftModels.Enums
@using DeepDrftPublic.Client.Controls
@inherits MediumBrowseBase
+@inject SeoOptions Seo

-<PageTitle>DeepDrft Mixes</PageTitle>
+<SeoHead Model="@SeoModel.ForBrowse(Seo, ReleaseMedium.Mix, "/mixes")" />

 <ReleaseGallery Releases="@Releases"
                Loading="@Loading"
@@ -1,4 +1,9 @@
@page "/404"
+@using DeepDrftPublic.Client.Controls
+@inject SeoOptions Seo
+
+@* The 404 must not be indexed (AC8): noindex,follow — no canonical, no JSON-LD. *@
+<SeoHead Model="@SeoModel.ForNotFound(Seo)" />

 <MudText Typo="Typo.h3">
    Not Found
@@ -3,8 +3,7 @@
@using DeepDrftPublic.Client.Controls
@using DeepDrftPublic.Client.Services
@inherits ReleaseDetailBase
-
-<PageTitle>@(ViewModel.Release?.Title ?? "Session") - DeepDrft</PageTitle>
+@inject SeoOptions Seo

@if (ViewModel.IsLoading)
 {
@@ -20,6 +19,9 @@
 }
 else if (ViewModel.NotFound || ViewModel.Release is null)
 {
+    @* Soft-404: a bad key renders a 200 "not found" view, so it must carry noindex so it is not indexed
+       (mirrors the dedicated /404 NotFound page). *@
+    <SeoHead Model="@SeoModel.ForNotFound(Seo)" />
    <div class="deepdrft-track-detail-container">
        <div class="deepdrft-track-detail-masthead">
            <MudText Typo="Typo.h4" Align="Align.Center">Session not found.</MudText>
@@ -40,6 +42,10 @@ else
    // Hero image precedence: the session's dedicated hero, then the release cover, then a placeholder.
    var heroImage = !string.IsNullOrEmpty(heroKey) ? heroKey : release.ImagePath;

+    @* SEO head — fed from the same bridged release, so prerender and WASM render identical tags (AC6).
+       MusicAlbum/LiveAlbum (a session is a live release, §3.4/OQ6). *@
+    <SeoHead Model="@SeoModel.ForRelease(Seo, release)" />
+
    @* Ambient living waveform behind the hero overlay (Phase 12 §3e option b / §3f mode B). Session does
       NOT compose ReleaseDetailScaffold, so it mounts the shared engine directly with its own thin
       full-bleed wrapper — the engine is single-source either way, only the mount differs (§3b). The
@@ -1,8 +1,10 @@
@page "/sessions"
+@using DeepDrftModels.Enums
@using DeepDrftPublic.Client.Controls
@inherits MediumBrowseBase
+@inject SeoOptions Seo

-<PageTitle>DeepDrft Sessions</PageTitle>
+<SeoHead Model="@SeoModel.ForBrowse(Seo, ReleaseMedium.Session, "/sessions")" />

 <ReleaseGallery Releases="@Releases"
                Loading="@Loading"
@@ -45,6 +45,16 @@ public static class Startup
        services.AddScoped<IAnonIdProvider, AnonIdProvider>();
        services.AddScoped<IPlayEventSink, BeaconPlayEventSink>();
        services.AddScoped<ShareTracker>();
+
+        // Phase 22 SEO defaults — non-secret brand constants (canonical origin, site name, default share
+        // image, social links). Singleton: stateless config, identical in the server-prerender and WASM
+        // passes (this method runs in both), which is what makes SeoHead's double-render output identical.
+        services.AddSingleton(new SeoOptions());
+
+        // Environment-gated robots bridge. Scoped + [PersistentState] like DarkModeSettings: the server
+        // seeds IsProduction during prerender and it rounds to the WASM pass, so SeoHead resolves the same
+        // default robots in both render passes (non-production → noindex,nofollow, keeping beta uncrawled).
+        services.AddScoped<SeoEnvironment>();
    }

    public static void ConfigureApiHttpClient(IServiceCollection services, string baseAddress)
@@ -1,4 +1,5 @@
@using DeepDrftPublic.Client
+@using DeepDrftPublic.Client.Common
@using DeepDrftPublic.Services
@using DeepDrftShared.Client.Components
 <!DOCTYPE html>
@@ -34,11 +35,16 @@
@code {

    [Inject] public required DarkModeService DarkModeService { get; set; }
+    [Inject] public required SeoEnvironment SeoEnvironment { get; set; }
+    [Inject] public required IWebHostEnvironment HostEnvironment { get; set; }

    protected override void OnInitialized()
    {
        base.OnInitialized();
        DarkModeService.CheckDarkMode();
+        // Seed the environment-gated robots bridge during prerender; [PersistentState] rounds it to WASM
+        // so both render passes resolve the same default robots (Production → index, else noindex).
+        SeoEnvironment.IsProduction = HostEnvironment.IsProduction();
    }

 }
@@ -0,0 +1,423 @@
+using System.Text.Json;
+using DeepDrftModels.DTOs;
+using DeepDrftModels.Enums;
+using DeepDrftPublic.Client.Common;
+
+namespace DeepDrftTests;
+
+/// <summary>
+/// Unit tests for the Phase 22 SEO typed builders (<see cref="SeoModel"/> factories + <see cref="SeoJsonLd"/>
+/// nodes + <see cref="SeoUrls"/>). These are pure functions over the DTOs a page already holds — the
+/// medium→schema mapping (AC3), graceful partial data (AC4), JSON-LD validity (AC5), and canonical
+/// correctness (AC7) are all testable here without rendering. The JSON-LD is parsed back to a document so
+/// each assertion checks real structure, not a substring.
+/// </summary>
+[TestFixture]
+public class SeoModelTests
+{
+    private static readonly SeoOptions Options = new()
+    {
+        BaseUrl = "https://deepdrft.com",
+        SiteName = "Deep DRFT",
+        TitleSuffix = "Deep DRFT",
+        DefaultDescription = "default description",
+        DefaultImageUrl = "/img/og-default.png",
+        Genre = "Electronic",
+        SameAs = ["https://instagram.com/deepdrft.music"],
+    };
+
+    private static ReleaseDto Release(
+        ReleaseMedium medium,
+        string? image = "cover.jpg",
+        string? description = "desc",
+        string title = "Test Release",
+        string artist = "Aphex Twin") => new()
+    {
+        EntryKey = "abc-key",
+        Title = title,
+        Artist = artist,
+        Genre = "House",
+        Description = description,
+        ImagePath = image,
+        ReleaseDate = new DateOnly(2026, 3, 14),
+        Medium = medium,
+    };
+
+    private static JsonElement Parse(string? json)
+    {
+        Assert.That(json, Is.Not.Null.And.Not.Empty, "expected a JSON-LD body");
+        return JsonDocument.Parse(json!).RootElement;
+    }
+
+    // --- AC3: per-medium schema -------------------------------------------------
+
+    [Test]
+    public void ForRelease_Cut_IsMusicAlbum_StudioAlbum_WithOrderedTrackList()
+    {
+        var tracks = new List<TrackDto>
+        {
+            new() { TrackName = "Second", TrackNumber = 2, DurationSeconds = 60 },
+            new() { TrackName = "First", TrackNumber = 1, DurationSeconds = 30 },
+        };
+
+        var model = SeoModel.ForRelease(Options, Release(ReleaseMedium.Cut), tracks);
+        var node = Parse(model.JsonLd);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(node.GetProperty("@type").GetString(), Is.EqualTo("MusicAlbum"));
+            Assert.That(node.GetProperty("albumProductionType").GetString(), Is.EqualTo("https://schema.org/StudioAlbum"));
+            Assert.That(model.OgType, Is.EqualTo(SeoOgType.MusicAlbum));
+
+            var trackArray = node.GetProperty("track");
+            Assert.That(trackArray.GetArrayLength(), Is.EqualTo(2));
+            // Ordered by TrackNumber, not input order.
+            Assert.That(trackArray[0].GetProperty("name").GetString(), Is.EqualTo("First"));
+            Assert.That(trackArray[1].GetProperty("name").GetString(), Is.EqualTo("Second"));
+            Assert.That(trackArray[0].GetProperty("duration").GetString(), Is.EqualTo("PT30S"));
+        });
+    }
+
+    [Test]
+    public void ForRelease_Session_IsMusicAlbum_LiveAlbum()
+    {
+        var model = SeoModel.ForRelease(Options, Release(ReleaseMedium.Session));
+        var node = Parse(model.JsonLd);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(node.GetProperty("@type").GetString(), Is.EqualTo("MusicAlbum"));
+            Assert.That(node.GetProperty("albumProductionType").GetString(), Is.EqualTo("https://schema.org/LiveAlbum"));
+            Assert.That(model.OgType, Is.EqualTo(SeoOgType.MusicAlbum));
+        });
+    }
+
+    [Test]
+    public void ForRelease_Mix_IsMusicRecording_WithIsoDuration()
+    {
+        var tracks = new List<TrackDto> { new() { TrackName = "The Mix", DurationSeconds = 3723 } }; // 1h 2m 3s
+        var model = SeoModel.ForRelease(Options, Release(ReleaseMedium.Mix), tracks);
+        var node = Parse(model.JsonLd);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(node.GetProperty("@type").GetString(), Is.EqualTo("MusicRecording"));
+            Assert.That(node.GetProperty("duration").GetString(), Is.EqualTo("PT1H2M3S"));
+            Assert.That(model.OgType, Is.EqualTo(SeoOgType.MusicSong));
+            Assert.That(model.DurationSeconds, Is.EqualTo(3723));
+            // A mix is one recording, not an album — it carries no track list.
+            Assert.That(node.TryGetProperty("track", out _), Is.False);
+        });
+    }
+
+    [Test]
+    public void ForRelease_AllNodes_DeclareSchemaOrgContext()
+    {
+        foreach (var medium in Enum.GetValues<ReleaseMedium>())
+        {
+            var node = Parse(SeoModel.ForRelease(Options, Release(medium)).JsonLd);
+            Assert.That(node.GetProperty("@context").GetString(), Is.EqualTo("https://schema.org"),
+                $"{medium} node must declare the schema.org context");
+        }
+    }
+
+    // --- AC4: graceful partial data ---------------------------------------------
+
+    [Test]
+    public void ForRelease_NoDescription_FallsBackToDefault()
+    {
+        var model = SeoModel.ForRelease(Options, Release(ReleaseMedium.Cut, description: null));
+        Assert.That(model.Description, Is.EqualTo(Options.DefaultDescription));
+    }
+
+    [Test]
+    public void ForRelease_NoCover_OmitsImagePath_SoHeadFallsBackToDefault()
+    {
+        var model = SeoModel.ForRelease(Options, Release(ReleaseMedium.Cut, image: null));
+        // The model carries no relative ImagePath; the JSON-LD image is absolutised to the default.
+        var node = Parse(model.JsonLd);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(model.ImagePath, Is.Null);
+            Assert.That(node.GetProperty("image").GetString(), Is.EqualTo("https://deepdrft.com/img/og-default.png"));
+        });
+    }
+
+    [Test]
+    public void ForRelease_NoGenre_OmitsGenreProperty_NoEmptyValue()
+    {
+        var release = Release(ReleaseMedium.Cut);
+        release.Genre = null;
+
+        var node = Parse(SeoModel.ForRelease(Options, release).JsonLd);
+        Assert.That(node.TryGetProperty("genre", out _), Is.False, "a null genre must be omitted, not emitted empty");
+    }
+
+    [Test]
+    public void ForRelease_Mix_NoTrack_OmitsDuration()
+    {
+        var node = Parse(SeoModel.ForRelease(Options, Release(ReleaseMedium.Mix), tracks: null).JsonLd);
+        Assert.That(node.TryGetProperty("duration", out _), Is.False, "a mix with no track must omit duration");
+    }
+
+    // --- AC7: canonical correctness ---------------------------------------------
+
+    [TestCase(ReleaseMedium.Cut, "https://deepdrft.com/cuts/abc-key")]
+    [TestCase(ReleaseMedium.Session, "https://deepdrft.com/sessions/abc-key")]
+    [TestCase(ReleaseMedium.Mix, "https://deepdrft.com/mixes/abc-key")]
+    public void ForRelease_CanonicalPath_IsDedicatedRoute_AndJsonLdUrlAgrees(ReleaseMedium medium, string expectedAbsolute)
+    {
+        var model = SeoModel.ForRelease(Options, Release(medium));
+        var node = Parse(model.JsonLd);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(SeoUrls.Absolute(Options, model.CanonicalPath!), Is.EqualTo(expectedAbsolute));
+            // The JSON-LD url must be the same absolute canonical (AC7: canonical == og:url == node url).
+            Assert.That(node.GetProperty("url").GetString(), Is.EqualTo(expectedAbsolute));
+        });
+    }
+
+    // --- Home / About / Browse / NotFound ---------------------------------------
+
+    [Test]
+    public void ForHome_IsMusicGroup_WithSameAs()
+    {
+        var model = SeoModel.ForHome(Options);
+        var node = Parse(model.JsonLd);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(node.GetProperty("@type").GetString(), Is.EqualTo("MusicGroup"));
+            Assert.That(node.GetProperty("name").GetString(), Is.EqualTo("Deep DRFT"));
+            Assert.That(node.GetProperty("sameAs")[0].GetString(), Is.EqualTo("https://instagram.com/deepdrft.music"));
+            Assert.That(model.CanonicalPath, Is.EqualTo("/"));
+        });
+    }
+
+    [Test]
+    public void ForAbout_IsMusicGroup()
+    {
+        var node = Parse(SeoModel.ForAbout(Options).JsonLd);
+        Assert.That(node.GetProperty("@type").GetString(), Is.EqualTo("MusicGroup"));
+    }
+
+    [TestCase(ReleaseMedium.Cut, "/cuts")]
+    [TestCase(ReleaseMedium.Session, "/sessions")]
+    [TestCase(ReleaseMedium.Mix, "/mixes")]
+    public void ForBrowse_IsCollectionPage_WithAbsoluteUrl(ReleaseMedium medium, string path)
+    {
+        var model = SeoModel.ForBrowse(Options, medium, path);
+        var node = Parse(model.JsonLd);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(node.GetProperty("@type").GetString(), Is.EqualTo("CollectionPage"));
+            Assert.That(node.GetProperty("url").GetString(), Is.EqualTo($"https://deepdrft.com{path}"));
+            Assert.That(model.CanonicalPath, Is.EqualTo(path));
+        });
+    }
+
+    [Test]
+    public void ForBrowse_NullMedium_IsArchive()
+    {
+        var model = SeoModel.ForBrowse(Options, null, "/archive");
+        Assert.That(model.Title, Is.EqualTo("Archive"));
+    }
+
+    [Test]
+    public void ForNotFound_IsNoindex_NoCanonical_NoJsonLd()
+    {
+        var model = SeoModel.ForNotFound(Options);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(model.Robots, Is.EqualTo("noindex,follow"));
+            Assert.That(model.CanonicalPath, Is.Null);
+            Assert.That(model.JsonLd, Is.Null);
+        });
+    }
+
+    // --- byArtist consistency: per-release artist, matching music:musician -------
+
+    [TestCase(ReleaseMedium.Cut)]
+    [TestCase(ReleaseMedium.Session)]
+    [TestCase(ReleaseMedium.Mix)]
+    public void ForRelease_ByArtist_IsPerReleaseArtist_NotCollectiveName(ReleaseMedium medium)
+    {
+        var model = SeoModel.ForRelease(Options, Release(medium, artist: "Aphex Twin"));
+        var node = Parse(model.JsonLd);
+
+        Assert.Multiple(() =>
+        {
+            // byArtist mirrors the OG music:musician value (the release's own artist), not the SiteName.
+            Assert.That(node.GetProperty("byArtist").GetProperty("name").GetString(), Is.EqualTo("Aphex Twin"));
+            Assert.That(node.GetProperty("byArtist").GetProperty("name").GetString(), Is.Not.EqualTo(Options.SiteName));
+            Assert.That(model.Artist, Is.EqualTo("Aphex Twin"));
+        });
+    }
+
+    [Test]
+    public void ForRelease_Cut_AlbumTracks_ByArtist_IsPerReleaseArtist()
+    {
+        var tracks = new List<TrackDto> { new() { TrackName = "Track", TrackNumber = 1, DurationSeconds = 30 } };
+        var node = Parse(SeoModel.ForRelease(Options, Release(ReleaseMedium.Cut, artist: "Aphex Twin"), tracks).JsonLd);
+
+        Assert.That(node.GetProperty("track")[0].GetProperty("byArtist").GetProperty("name").GetString(),
+            Is.EqualTo("Aphex Twin"));
+    }
+
+    // --- AC5 regression: no stray CLR `Type` property emitted alongside `@type` ---
+    // System.Text.Json previously emitted both `@type` (from the base [JsonPropertyName]) and `Type`
+    // (the raw CLR override name) on concrete derived nodes, failing the schema.org validator.
+    // The fix: repeat [JsonPropertyName("@type")] directly on each concrete override.
+
+    [Test]
+    public void MusicAlbumNode_SerializesAtType_OnlyOnce_NoBareTypeProperty()
+    {
+        var tracks = new List<TrackDto> { new() { TrackName = "T", TrackNumber = 1, DurationSeconds = 30 } };
+        var node = Parse(SeoModel.ForRelease(Options, Release(ReleaseMedium.Cut), tracks).JsonLd);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(node.GetProperty("@type").GetString(), Is.EqualTo("MusicAlbum"),
+                "MusicAlbumNode must emit @type");
+            Assert.That(node.TryGetProperty("Type", out _), Is.False,
+                "MusicAlbumNode must NOT emit a bare Type property");
+        });
+    }
+
+    [Test]
+    public void MusicRecordingNode_TopLevel_SerializesAtType_NoBareTypeProperty()
+    {
+        var tracks = new List<TrackDto> { new() { TrackName = "The Mix", DurationSeconds = 3600 } };
+        var node = Parse(SeoModel.ForRelease(Options, Release(ReleaseMedium.Mix), tracks).JsonLd);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(node.GetProperty("@type").GetString(), Is.EqualTo("MusicRecording"),
+                "MusicRecordingNode must emit @type");
+            Assert.That(node.TryGetProperty("Type", out _), Is.False,
+                "MusicRecordingNode must NOT emit a bare Type property");
+        });
+    }
+
+    [Test]
+    public void MusicRecordingNode_NestedTrack_SerializesAtType_NoBareTypeProperty()
+    {
+        // The nested track[] MusicRecordingNode is a different code path from the top-level mix node.
+        var tracks = new List<TrackDto> { new() { TrackName = "T", TrackNumber = 1, DurationSeconds = 30 } };
+        var albumNode = Parse(SeoModel.ForRelease(Options, Release(ReleaseMedium.Cut), tracks).JsonLd);
+        var trackNode = albumNode.GetProperty("track")[0];
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(trackNode.GetProperty("@type").GetString(), Is.EqualTo("MusicRecording"),
+                "nested MusicRecordingNode must emit @type");
+            Assert.That(trackNode.TryGetProperty("Type", out _), Is.False,
+                "nested MusicRecordingNode must NOT emit a bare Type property");
+        });
+    }
+
+    [Test]
+    public void MusicGroupNode_SerializesAtType_NoBareTypeProperty()
+    {
+        var node = Parse(SeoModel.ForHome(Options).JsonLd);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(node.GetProperty("@type").GetString(), Is.EqualTo("MusicGroup"),
+                "MusicGroupNode must emit @type");
+            Assert.That(node.TryGetProperty("Type", out _), Is.False,
+                "MusicGroupNode must NOT emit a bare Type property");
+        });
+    }
+
+    [Test]
+    public void CollectionPageNode_SerializesAtType_NoBareTypeProperty()
+    {
+        var node = Parse(SeoModel.ForBrowse(Options, ReleaseMedium.Cut, "/cuts").JsonLd);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(node.GetProperty("@type").GetString(), Is.EqualTo("CollectionPage"),
+                "CollectionPageNode must emit @type");
+            Assert.That(node.TryGetProperty("Type", out _), Is.False,
+                "CollectionPageNode must NOT emit a bare Type property");
+        });
+    }
+
+    [Test]
+    public void ArtistRef_NestedByArtist_SerializesAtType_NoBareTypeProperty()
+    {
+        // ArtistRef (byArtist) was already clean — this asserts it stays clean after the fix.
+        var node = Parse(SeoModel.ForRelease(Options, Release(ReleaseMedium.Cut)).JsonLd);
+        var byArtist = node.GetProperty("byArtist");
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(byArtist.GetProperty("@type").GetString(), Is.EqualTo("MusicGroup"),
+                "ArtistRef must emit @type");
+            Assert.That(byArtist.TryGetProperty("Type", out _), Is.False,
+                "ArtistRef must NOT emit a bare Type property");
+        });
+    }
+
+    [Test]
+    public void AllNodes_ContextIsPresent_AndSchemaOrg()
+    {
+        // Belt-and-suspenders: @context must not regress alongside the @type fix.
+        var nodes = new[]
+        {
+            Parse(SeoModel.ForHome(Options).JsonLd),
+            Parse(SeoModel.ForAbout(Options).JsonLd),
+            Parse(SeoModel.ForBrowse(Options, ReleaseMedium.Cut, "/cuts").JsonLd),
+            Parse(SeoModel.ForRelease(Options, Release(ReleaseMedium.Cut)).JsonLd),
+            Parse(SeoModel.ForRelease(Options, Release(ReleaseMedium.Session)).JsonLd),
+            Parse(SeoModel.ForRelease(Options, Release(ReleaseMedium.Mix)).JsonLd),
+        };
+
+        foreach (var node in nodes)
+            Assert.That(node.GetProperty("@context").GetString(), Is.EqualTo("https://schema.org"),
+                "@context must remain present after the @type fix");
+    }
+
+    // --- Critical: inline JSON-LD script-breakout escaping (XSS) -----------------
+
+    [Test]
+    public void ForRelease_TitleWithScriptClose_DoesNotEmitRawAngleBracket()
+    {
+        // A CMS-authored title containing </script> / < must not survive raw in the inline script body —
+        // that is a breakout/XSS vector. The escaped < keeps the JSON parseable while neutralising it.
+        var release = Release(ReleaseMedium.Cut, title: "Evil</script><script>alert(1)</script>");
+        var body = SeoModel.ForRelease(Options, release).JsonLd;
+
+        Assert.That(body, Is.Not.Null);
+        Assert.Multiple(() =>
+        {
+            Assert.That(body, Does.Not.Contain("<"), "no raw < may appear in the inline JSON-LD body");
+            Assert.That(body, Does.Not.Contain(">"), "no raw > may appear in the inline JSON-LD body");
+            Assert.That(body, Does.Contain("\\u003C"), "< must be emitted as its \\u003C JSON escape");
+            // The escaped body still parses as JSON and round-trips the original value.
+            var node = Parse(body);
+            Assert.That(node.GetProperty("name").GetString(), Is.EqualTo("Evil</script><script>alert(1)</script>"));
+        });
+    }
+
+    [Test]
+    public void ForRelease_TitleWithAmpersand_EscapesAmpersand_StillParses()
+    {
+        // The title is serialized into the JSON-LD `name`, so an ampersand there exercises the & escape.
+        var release = Release(ReleaseMedium.Mix, title: "Sound & Vision");
+        var body = SeoModel.ForRelease(Options, release).JsonLd;
+
+        Assert.That(body, Is.Not.Null);
+        Assert.Multiple(() =>
+        {
+            Assert.That(body, Does.Not.Contain("&"), "no raw & may appear in the inline JSON-LD body");
+            Assert.That(body, Does.Contain("\\u0026"), "& must be emitted as its \\u0026 JSON escape");
+            Assert.That(Parse(body).GetProperty("name").GetString(), Is.EqualTo("Sound & Vision"));
+        });
+    }
+}
@@ -0,0 +1,68 @@
+using DeepDrftPublic.Client.Common;
+
+namespace DeepDrftTests;
+
+/// <summary>
+/// Unit tests for <see cref="SeoUrls"/> — the absolute-URL composition shared by the SeoModel factories
+/// and SeoHead (Phase 22). Origin always comes from config (never a browser API), so these pin the
+/// slash-join, the cover-vs-default fallback (C6/AC4), and the ISO-8601 duration edge cases.
+/// </summary>
+[TestFixture]
+public class SeoUrlsTests
+{
+    private static readonly SeoOptions Options = new()
+    {
+        BaseUrl = "https://deepdrft.com",
+        DefaultImageUrl = "/img/og-default.png",
+    };
+
+    [TestCase("/cuts/key", "https://deepdrft.com/cuts/key")]
+    [TestCase("cuts/key", "https://deepdrft.com/cuts/key")]
+    [TestCase("/", "https://deepdrft.com/")]
+    [TestCase("", "https://deepdrft.com")]
+    public void Absolute_JoinsOriginAndPath_WithoutDoublingOrDroppingSlash(string path, string expected)
+    {
+        Assert.That(SeoUrls.Absolute(Options, path), Is.EqualTo(expected));
+    }
+
+    [Test]
+    public void Absolute_TrimsTrailingSlashOnBaseUrl()
+    {
+        var withSlash = Options with { BaseUrl = "https://deepdrft.com/" };
+        Assert.That(SeoUrls.Absolute(withSlash, "/cuts"), Is.EqualTo("https://deepdrft.com/cuts"));
+    }
+
+    [Test]
+    public void CoverOrDefault_WithCover_BuildsEscapedImageRoute()
+    {
+        Assert.That(SeoUrls.CoverOrDefault(Options, "my cover.jpg"),
+            Is.EqualTo("https://deepdrft.com/api/image/my%20cover.jpg"));
+    }
+
+    [TestCase(null)]
+    [TestCase("")]
+    [TestCase("   ")]
+    public void CoverOrDefault_WithoutCover_FallsBackToDefaultImage(string? image)
+    {
+        Assert.That(SeoUrls.CoverOrDefault(Options, image),
+            Is.EqualTo("https://deepdrft.com/img/og-default.png"));
+    }
+
+    [TestCase(30.0, "PT30S")]
+    [TestCase(90.0, "PT1M30S")]
+    [TestCase(3723.0, "PT1H2M3S")]
+    public void IsoDuration_PositiveSeconds_RendersIso8601(double seconds, string expected)
+    {
+        Assert.That(SeoUrls.IsoDuration(seconds), Is.EqualTo(expected));
+    }
+
+    [TestCase(null)]
+    [TestCase(0.0)]
+    [TestCase(-5.0)]
+    [TestCase(double.NaN)]
+    [TestCase(double.PositiveInfinity)]
+    public void IsoDuration_NonPositiveOrNonFinite_ReturnsNull(double? seconds)
+    {
+        Assert.That(SeoUrls.IsoDuration(seconds), Is.Null);
+    }
+}
@@ -443,8 +443,217 @@ not the same work; this phase does not satisfy or depend on that one.

 ---

+## Phase 18 — Opus Low-Data Streaming (dual-format lossless + Opus delivery)
+
+The concrete realization of the long-deferred **"Non-WAV formats"** intent (`CONTEXT.md §5`). Daniel's
+direction (2026-06-23): **two delivery formats per track — the existing lossless WAV path, and a new
+low-data Ogg Opus (fullband, 320 kbps) path — so the listener gets a choice, with Opus the
+bandwidth-friendly default-candidate.** Lossless streaming becomes *optional*, not the only path. The
+bespoke Web Audio decode→schedule graph is **retained by deliberate choice** — Opus feeds the same
+`IFormatDecoder` seam, not an HTML `<media>` element or MSE (the decision shared with Phase 21 OQ5).
+**Sequenced BEFORE Phase 21** — windowing must work across both formats. Surfaces: ingest/preprocessing
+in `DeepDrftContent` (`AudioProcessor`/router/`WaveformProfileService`) + `DeepDrftAPI`
+(`UnifiedTrackService.UploadAsync`, replace-audio); delivery/decode in `DeepDrftAPI` (stream endpoint +
+`Range`) + `DeepDrftPublic` proxy + `DeepDrftPublic.Client` player stack + `DeepDrftPublic/Interop/audio`
+TS decoders. Full design, the three directions with SOLID/road-not-taken rationale, the storage and
+delivery options, the Opus decoder + seek math, acceptance criteria, open questions, and wave
+decomposition: `product-notes/phase-18-opus-low-data-streaming.md`.
+
+**Much further along than the backlog line implies (verified 2026-06-23).** The multi-format *substrate*
+already exists on both sides: the producer-side `AudioProcessorRouter` routes `.wav`/`.mp3`/`.flac` and
+`TrackContentService.AddTrackAsync` is format-agnostic (it **stores originals**, no transcode); the
+decoder-side `AudioPlayer.createFormatDecoder` is a **wired** strategy registry dispatching on
+`Content-Type` (WAV/MP3/FLAC decoders all present — correcting the Phase 21 spec's stale
+"implemented-not-wired" note). **The actual gap is Daniel's specific ask:** (1) a **transcode-at-ingest**
+step that *derives* an Opus 320 artifact per track (nothing derives Opus today), and (2) a **per-format
+delivery selection** so one track serves as either WAV or Opus on request.
+
+**Open questions RESOLVED (Daniel, 2026-06-23).** OQ1 selection UX → **global, via a new public-site
+Settings menu** (not a bare app-bar control); OQ2 default → **Opus by default, capability-gated** (defer
+network-awareness); OQ3 remembered → **persisted via the dark-mode seam** (cookie → prerender-read →
+`PersistentComponentState` → client cookie service); OQ4 → **always-on Opus + Backfill-Opus**; OQ5 →
+**Ogg Opus**; OQ6 transcode model → **background job after the file is available, with a visible
+Post-Processing phase on the CMS upload meter.** OQ7 (seek-index granularity) → **0.5 s (half-second)
+buckets** (~115 KB index for a 1-hour mix).
+
+**Architectural spine — a derived artifact set + a delivery param + one new decoder + a precomputed
+accurate seek index; leaf implementations only, zero changes to existing format code (the strong OCP
+signal).** Transcode is a new processor sibling in `DeepDrftContent`, invoked post-store alongside
+`WaveformProfileService` **as a background job** (a 1 GB WAV transcode must not block the upload; the source
+is stored and the track plays lossless *first*, then Opus is derived) — mirroring the landed waveform-datum
+pattern (derive at ingest, regenerate via a CMS bulk action + ApiKey endpoint). The Opus bytes are a
+**derived artifact** stored like the high-res waveform datum (recommend a dedicated `track-opus` vault, the
+`track-waveforms` precedent; final call staff-engineer's). Delivery adds a **`?format=opus|lossless` param**
+(mirroring the existing `offset` param threading through `TrackProxyController`) resolved server-side to the
+right artifact + content-type, with a **lossless fallback** when no Opus artifact exists (additive, never
+404/silence). The player gains one `OpusFormatDecoder` (`IFormatDecoder`): Ogg-page-aligned segmenting
+(`OggS` scan — the FLAC frame-sync analogue) and `OpusHead`/`OpusTags` setup-bytes carry (the FLAC
+`streamInfoBytes` analogue). **Browser constraint flagged:** Ogg-Opus `decodeAudioData` is Safari-18.4+ only
+(Chrome/FF long-standing), so the Opus default is **capability-gated** — fall back to the universal lossless
+path on browsers that can't decode it.
+
+**VBR-safe ACCURATE seeking (Daniel, 2026-06-23 — supersedes the earlier "approximate" hand-wave).** Raw
+byte-offset seek and rough page interpolation are inadequate for VBR Opus — there is no linear time↔byte
+relationship. The fix is an **accurate transfer function built at transcode time** (the one moment the
+whole encoded stream is walked): a precomputed **seek index** mapping Ogg-page `granulepos` (48 kHz sample
+counts → time) → exact byte offset (**0.5 s buckets** snapped to page starts — OQ7; ~7,200 entries ×
+16 bytes ≈ ~115 KB for a 1-hour mix). The decode **setup header** (`OpusHead`/`OpusTags`, needed to decode any mid-stream slice) is made
+available too. Recommended concrete design: **one sidecar artifact per track = `[setup header][seek
+index]`, built at transcode, stored beside the Opus bytes, fetched once on track load**, parsed into
+`OpusSeekData`. Client seek flow: `calculateByteOffset(t)` binary-searches the index for the exact page
+offset → `Range: bytes=X-` fetch (landed Phase 4 primitive, unchanged) → prepend the cached setup header →
+decode → fine re-sync to `t` within the bucket. **The listener lands at the correct time, not
+approximately** (AC9), **without** the full PCM in memory — so it composes with Phase 21 windowed refill,
+which calls the **same** index resolver. The earlier "approximate page-interpolation" language is rejected.
+
+**Constraints/invariants:** keep the bespoke graph (no MSE); preprocessing is **additive** (WAV path
+untouched, byte-for-byte; a track with no Opus artifact still plays losslessly); reuse the landed
+`Range`/offset seek path; no format branches leak outside the new decoder + one selection arm + the
+transcode/delivery seam; transcode failure must not block ingest; format selection is a delivery-time
+decision resolving one `EntryKey` to one of two artifacts (one source, two views — **not** a second
+`TrackEntity` row, which would fracture share/queue/play-count/release identity).
+
+Sequenced as six waves. `18.1 → 18.2 → {18.3, 18.4} → 18.5`, with `18.6` (Settings menu) able to run in
+parallel (it needs only 18.3's format mechanism before its toggle is live). **18.1 (ingest transcode +
+seek-index + setup-header derived artifacts) is the cold-start prerequisite** — nothing downstream has
+bytes to serve, decode, or seek against until those artifacts exist.
+
+- **18.1 — Ingest transcode + seek-index + setup-header (cold-start; load-bearing).** New
+  `OpusTranscodeService`/processor in `DeepDrftContent`, invoked post-store from
+  `UnifiedTrackService.UploadAsync` alongside `WaveformProfileService` **as a background job** (OQ6);
+  produces Ogg Opus fullband 320; **walks the encoded stream once to build the granule→byte seek index and
+  extract the `OpusHead`/`OpusTags` setup header**; stores the Opus bytes **and** the combined seek/setup
+  **sidecar** as derived artifacts (recommend a `track-opus` vault). Failure-tolerant. **Independent of the
+  delivery/decoder waves — can begin immediately.**
+- **18.2 — Storage + lookup contract.** The derived-artifact key/vault convention (Opus bytes + sidecar) +
+  server-side "given `EntryKey` + format, return the right `AudioBinary` + content-type (+ the sidecar),"
+  including the lossless fallback. **Depends on 18.1.**
+- **18.3 — Delivery: `?format=opus|lossless` param + sidecar serving + proxy threading.** On the
+  `DeepDrftAPI` stream endpoint (resolves via 18.2), forwarded through `TrackProxyController` (mirror
+  `offset`), `Range` serving the chosen artifact; **plus serving the seek/setup sidecar**; player sends the
+  format param via `TrackMediaClient`. **Depends on 18.2; parallel-ok with 18.4.**
+- **18.4 — `OpusFormatDecoder` + index-based seek resolver in the player stack.** New `IFormatDecoder`
+  (Ogg-page segmenting via `OggS` scan, `OpusHead`/`OpusTags` setup carry from the cached sidecar,
+  **`calculateByteOffset` that binary-searches the precomputed seek index** — NOT interpolation — with an
+  `OpusSeekData` accelerator holding the parsed index + setup bytes, and the one-time sidecar fetch+parse on
+  track load) + one arm in `createFormatDecoder` on `audio/ogg`/`audio/opus`; capability detection for the
+  lossless fallback. **Depends on 18.2; parallel-ok with 18.3.**
+- **18.5 — Backfill + replace-audio + end-to-end validation (incl. seek accuracy).** "Backfill Opus" CMS
+  bulk action (third sibling to Generate-Profiles / Backfill-High-res), rebuilding Opus bytes + sidecar for
+  existing tracks; replace-audio Opus + sidecar regeneration; the AC1–AC10 acceptance pass **including AC9
+  (an Opus seek lands at the correct time, not approximately)** and the Phase-21 handshake (Opus windowable
+  via the index resolver + sidecar setup header). **Depends on 18.1–18.4.**
+- **18.6 — Public Settings menu + quality toggle (the listener selection UX).** New public-site
+  Settings-menu shell (app-bar trigger + MudBlazor menu + a settings-item abstraction + a
+  `PublicSiteSettings`/`ListenerSettings` object + the dark-mode-pattern persistence seam: `streamQuality`
+  cookie, a `DeepDrftPublic` prerender-read service, `PersistentComponentState` bridge, client cookie
+  service); the **quality toggle is its first occupant** (Low-data/Lossless, Opus default, capability-gated)
+  + the CMS upload meter's **Post-Processing phase** (OQ6). Built design-for-adaptability so dark mode can
+  plug in later without restructuring (not migrated now). **Depends on 18.3** for the toggle; the menu shell
+  can be built ahead. *Splittable* (shell, then toggle) if Daniel wants the shell proven first.
+
+**Dependency shape:** `18.1 → 18.2 → {18.3 ∥ 18.4} → 18.5`; `18.6 ∥` (needs 18.3 for the live toggle);
+18.1 is the only cold-start wave. **Phase-level: 18 precedes Phase 21** (windowed refill consumes the Phase
+18 seek-index resolver). **OQ1–OQ7 RESOLVED (above); OQ7 (seek-index granularity) = 0.5 s buckets.** None
+block 18.1.
+
 ---

+## Phase 21 — Windowed Streaming Buffer (bounded client memory for long streams)
+
+Bound the **client memory** a playing track consumes to a small, configurable forward window —
+**independent of total stream length** — so a 1 GB+ DJ MIX (Phase 9 `Mix` medium: a single long track)
+plays without the whole decoded PCM accumulating in the browser. **Public listener site only**
+(`DeepDrftPublic.Client` player stack + `DeepDrftPublic` TypeScript audio interop); no CMS, no API
+endpoint, no schema change.
+
+**Sequenced AFTER Phase 18 (Opus Low-Data Streaming) — Daniel, 2026-06-23.** Format support (the
+derived Ogg Opus 320 low-data path, Phase 18) is a prerequisite that comes first; windowing must work
+across **both** delivery formats. Phase 21's C5 invariant already anticipated this ("must not foreclose
+MP3/FLAC"); **Opus is now the concrete VBR/paged driver** — windowing an Opus stream uses the decoder's
+**accurate index-based** byte↔time mapping (`OpusFormatDecoder.calculateByteOffset`, a binary search in the
+Phase 18 precomputed seek index — *not* the exact CBR-WAV `byteRate` math, and *not* approximate page
+interpolation: VBR-safe and exact, per the Phase 18 seek-model resolution 2026-06-23). The windowed refill
+controller calls the **same** index resolver an explicit seek does, and a window opening away from byte 0
+still decodes via the Phase 18 sidecar setup header. Build the window machinery format-agnostically so it
+inherits Opus for free.
+
+The network path already streams in adaptive 16–64 KB chunks. The accumulation is on the **decode
+side**: `PlaybackScheduler` holds an `AudioBuffer[]` it **never evicts** ("Supports pause/resume/seek by
+retaining all buffers" — its own doc comment). Decoded PCM is larger than the source (Web Audio is
+32-bit float per sample/channel — a 16-bit stereo WAV roughly doubles once decoded), so a 1 GB WAV
+becomes ~2 GB of retained float data. That is the OOM. The fix: hold only a sliding forward window plus a
+small back-retain, discard already-played buffers, and refill on demand.
+
+**Architectural spine — a sliding window keyed on playback position, built as a generalization of the
+landed seek-beyond-buffer path.** The Phase 4 HTTP `Range: bytes=X-` → 206 primitive already does every
+plumbing primitive the window needs (discard-buffers-keep-offset via `clearForSeek`/`setPlaybackOffset`;
+fetch-from-offset via `TrackMediaClient`; decode-header-less-body via
+`StreamDecoder.reinitializeForRangeContinuation`; time→byte via `IFormatDecoder.calculateByteOffset`),
+just triggered manually and one-shot. The only genuinely new mechanisms are **partial eviction** on the
+scheduler and **back-pressure** on the forward read loop (stop calling `ReadAsync` above a high-water
+mark, resume below low-water). Recommended **Direction A** (sliding window on the existing single forward
+stream); **Direction B** (discrete Range-fetched segments — the HLS/DASH/MSE-eviction analogue) held as
+the documented fallback; **Direction C** (adopt MSE and let the browser manage the buffer) **rejected
+(OQ5 = NO, Daniel 2026-06-23)** — the bespoke Web Audio graph is a deliberate long-term commitment, and
+the compressed-delivery move that would have justified MSE is met instead by **Phase 18 (Opus) feeding
+the same bespoke graph** through the `IFormatDecoder` seam. Direction A is therefore the permanent
+destination, not a stopgap MSE would retire.
+
+**Invariants that must hold (the §3.5 seam contract).** Reuse the Range path, don't fork it; playback-
+start latency at parity; the `IFormatDecoder` abstraction untouched (windowing is format-agnostic, so
+wiring MP3/FLAC later inherits it free); read-only playback (no new control); the single-instance JS
+decoder stays single-writer (every refill routes through the existing cancellation/drain discipline). The
+**Mix visualizer is provably unaffected** — it renders from the preprocessed per-track high-res datum
+(Phase 10/12), never from live decoded PCM, so evicting played buffers cannot starve it. The 1 GB mix is
+both the canonical case *and* the proof the eviction is safe.
+
+**Interaction with deferred Phase 1 features (same seam):** windowing should land **before** preload
+(1.3) — it makes preload of long tracks memory-safe by construction (a staged next-track decoder inherits
+the bounded scheduler); it makes crossfade (1.4) between two long mixes affordable (the overlap doubles
+the *window*, not the track); it adds a minor "don't evict the final window before the gapless boundary"
+care point for 1.5. It **enlarges the error surface** (1.6): windowed refill issues mid-stream fetches
+the listener didn't initiate, one of which can fail deep into a 1 GB mix — so the *cheap* half of 1.6
+(clean refill-failure handling, no wedged player) is folded into this phase's acceptance criteria, not
+left fully to 1.6.
+
+Full design, the three directions with SOLID/road-not-taken rationale, use cases, acceptance criteria,
+the open-question set, and the wave decomposition: `product-notes/phase-21-windowed-streaming-buffer.md`.
+
+Sequenced as four waves. `21.1 → 21.2 → 21.3`, with `21.4` validating the whole. **21.1 is the cold-start
+prerequisite and the load-bearing change** — independent of the open questions (window *sizes* are
+parameters fed in later).
+
+- **21.1 — Partial eviction in `PlaybackScheduler` (cold-start; load-bearing).** Drop already-played
+  buffers while keeping the position/index/time-anchor bookkeeping exact against a buffer array that no
+  longer begins at absolute time 0 (today `getCurrentPosition`/`playFromPosition`/the schedule loop all
+  assume `buffers[0]` is the track start). The hardest correctness work in the phase. No refill yet.
+  **Independent of the open questions — can begin immediately.**
+- **21.2 — Back-pressure on the forward read loop.** Stop `ReadAsync` above the high-water mark, resume
+  below low-water; together with 21.1 this bounds *both* the played and unplayed regions (the AC1
+  guarantee). Routes resume/pause through the existing single-loop cancellation discipline. **Depends on
+  21.1.**
+- **21.3 — Seek-back-past-window refill.** When a backward seek lands earlier than the retained tail,
+  refetch via the existing seek-beyond-buffer Range path pointed at the earlier offset; plus the minimal
+  clean refill-failure handling (the 1.6 adjacency). Mostly reuse of the landed seek path. **Depends on
+  21.1 + 21.2.**
+- **21.4 — Validation against the 1 GB target (acceptance).** Memory profiling (bounded under 1 GB is the
+  headline), latency parity, edge-to-edge playback, the seek matrix, induced refill failure, visualizer-
+  running, rapid-seek concurrency. Largely measurement; breaks are tuning fixes in 21.1's anchor math or
+  21.2's water-marks. **Depends on 21.1–21.3.**
+
+**Dependency shape:** `21.1 → 21.2 → 21.3 → 21.4`; 21.1 is the only cold-start wave. **Phase-level
+prerequisite: Phase 18 (Opus) lands first** so windowing is built against both formats. **Open questions
+for Daniel (spec §6):** window-size policy axis (time-based window + memory guard — recommended); seek-
+back-past-window re-buffer acceptable (recommend yes, symmetric to forward); a hard total in-flight
+memory cap as a guard rail (recommend yes); window everything vs. only long tracks (recommend everything
+— one path, short tracks never hit a refill). **OQ5 (adopt MSE) — RESOLVED NO (Daniel 2026-06-23): the
+bespoke graph stays by deliberate choice; recorded considered-and-declined, kept visible per file
+convention.** None block 21.1.
+
+---
+
+
 ## Working with this file

 - **Add items by extending an existing phase first**; only create a new phase when the addition genuinely doesn't fit any of 1–5. Phase numbers are organisational, not sequencing.
@@ -181,6 +181,7 @@ if need_cred "authblocks"; then
  read -rp "  Email host (SMTP server or API host): " EMAIL_HOST
  read -rsp "  Email token (API key / SMTP password): " EMAIL_TOKEN
  echo
+  read -rp "  Sender email address (From:, e.g. noreply@${DOMAIN_PUBLIC}): " EMAIL_FROM

  # Admin account
  echo
@@ -201,10 +202,10 @@ if need_cred "authblocks"; then
  read -rp "  Support email address: " SUPPORT_EMAIL

  write_cred "authblocks" "$(cat <<JSON
-{"AuthBlocks":{"Jwt":{"Secret":"$(json_escape "${JWT_SECRET}")","Issuer":"$(json_escape "${JWT_ISSUER}")","Audience":"$(json_escape "${JWT_AUDIENCE}")"},"Email":{"Host":"$(json_escape "${EMAIL_HOST}")","Token":"$(json_escape "${EMAIL_TOKEN}")"},"Admin":{"UserName":"$(json_escape "${ADMIN_USERNAME}")","Email":"$(json_escape "${ADMIN_EMAIL}")","Password":"$(json_escape "${ADMIN_PASSWORD}")"},"SupportEmail":"$(json_escape "${SUPPORT_EMAIL}")"}}
+{"AuthBlocks":{"Jwt":{"Secret":"$(json_escape "${JWT_SECRET}")","Issuer":"$(json_escape "${JWT_ISSUER}")","Audience":"$(json_escape "${JWT_AUDIENCE}")"},"Email":{"Host":"$(json_escape "${EMAIL_HOST}")","Token":"$(json_escape "${EMAIL_TOKEN}")","From":"$(json_escape "${EMAIL_FROM}")"},"Admin":{"UserName":"$(json_escape "${ADMIN_USERNAME}")","Email":"$(json_escape "${ADMIN_EMAIL}")","Password":"$(json_escape "${ADMIN_PASSWORD}")"},"SupportEmail":"$(json_escape "${SUPPORT_EMAIL}")"}}
 JSON
 )"
-  unset JWT_SECRET JWT_ISSUER JWT_AUDIENCE EMAIL_HOST EMAIL_TOKEN
+  unset JWT_SECRET JWT_ISSUER JWT_AUDIENCE EMAIL_HOST EMAIL_TOKEN EMAIL_FROM
  unset ADMIN_USERNAME ADMIN_EMAIL ADMIN_PASSWORD SUPPORT_EMAIL
 else
  echo "[setup-step10-creds] authblocks.json already exists, skipping"
@@ -0,0 +1,779 @@
+# Phase 18 — Opus Low-Data Streaming (dual-format lossless + Opus delivery)
+
+Product spec. Status: **design / framing — open questions RESOLVED (Daniel, 2026-06-23); implementation-ready.**
+Author: product-designer. Date: 2026-06-23. **No code has been written by this doc.**
+
+> **Resolution pass (Daniel, 2026-06-23).** OQ1–OQ7 are resolved (see §6 — each marked RESOLVED, kept
+> visible per file convention; OQ7 — seek-index granularity — set to **0.5 s buckets**). Two resolutions
+> reshaped the spec materially: (a) the listener quality
+> selection lives inside a **new public-site Settings menu surface** (not a bare app-bar control) — §4 +
+> §4a; and (b) Daniel rejected the "approximate page-interpolation" seek hand-wave outright — **VBR-safe
+> *accurate* seeking is now a first-class part of the architecture** (a precomputed seek-index artifact +
+> a separately-available setup header). §3.4 is rewritten and a dedicated seek-model section (§3.4a)
+> added. The Phase 21 cross-reference is updated to read "accurate index-based mapping," not
+> "approximate."
+
+This phase is the concrete realization of the long-deferred **"Non-WAV formats"** intent
+(`CONTEXT.md §5`, the "1.2" the streaming-feature items reference). It supersedes the abstract "a
+processor per format + a decoder strategy" framing with a specific, Daniel-directed product: **two
+delivery formats per track — the existing lossless WAV path and a new low-data Ogg Opus path — so the
+listener gets a choice, with Opus the bandwidth-friendly default-candidate.**
+
+Surfaces (named precisely):
+
+- **Ingest / preprocessing:** `DeepDrftContent` (`AudioProcessor` / `AudioProcessorRouter` /
+  `TrackContentService` / `WaveformProfileService`) + `DeepDrftAPI` (upload/persist —
+  `UnifiedTrackService.UploadAsync`, replace-audio) + `DeepDrftManager` (CMS upload form — the
+  **Post-Processing phase** on the existing upload progress meter, §3.1a).
+- **Delivery / decode:** `DeepDrftAPI` (the track stream endpoint + `Range` handler + the new
+  **seek-index** and **setup-header** sidecar endpoints, §3.4a) + `DeepDrftPublic` proxy
+  (`TrackProxyController`) + `DeepDrftPublic.Client` player stack (`StreamingAudioPlayerService`,
+  `TrackMediaClient`) + `DeepDrftPublic/Interop/audio` TS decoders (`AudioPlayer.createFormatDecoder`
+  registry, a new `OpusFormatDecoder`).
+- **Listener settings (NEW surface):** `DeepDrftPublic.Client` — a public-site **Settings menu** (app-bar
+  menu/popover) hosting the quality toggle as its first occupant, with a dark-mode-pattern persistence
+  seam (cookie → settings object → `PersistentComponentState` → client cookie service). §4a. The
+  prerender-cookie read lives in `DeepDrftPublic` (alongside `DarkModeService`).
+
+**Sequencing headline: Phase 18 comes BEFORE Phase 21 (Windowed Streaming Buffer).** Phase 21's
+windowing must work across both formats — its C5 invariant already anticipated this ("must not
+foreclose MP3/FLAC"); Opus is now the concrete VBR/containerized driver of that invariant. See §6 and
+the Phase 21 cross-reference.
+
+---
+
+## 0. State of the world (what already exists — verified 2026-06-23)
+
+This phase is **much further along than the "Non-WAV formats" backlog line implies**, on both sides.
+Two prior efforts already built most of the multi-format substrate; what is *missing* is specifically
+the **derived-Opus-artifact** idea, not generic format support.
+
+**Producer side is already multi-format (router landed):**
+- `AudioProcessorRouter.ProcessAudioFileAsync(filePath)` routes by extension — `.wav` →
+  `AudioProcessor`, `.mp3` → `Mp3AudioProcessor`, `.flac` → `FlacAudioProcessor`
+  (`DeepDrftContent/CLAUDE.md`).
+- `TrackContentService.AddTrackAsync(filePath, mimeType)` is **format-agnostic**: it selects the
+  processor, generates an entry GUID, and **stores the original bytes** with correct extension/MIME
+  in the `tracks` vault.
+- So today the system can *ingest and store* WAV/MP3/FLAC. It **does not transcode** — it keeps the
+  original. There is no derived artifact and no second format per track.
+
+**Decoder side is a wired strategy registry (not "implemented-not-wired" anymore):**
+- `AudioPlayer.createFormatDecoder(contentType)` (`AudioPlayer.ts:117`) dispatches on `Content-Type`:
+  `audio/mpeg|audio/mp3` → `Mp3FormatDecoder`, `audio/flac|audio/x-flac` → `FlacFormatDecoder`,
+  default → `WavFormatDecoder`. All three decoders exist and implement `IFormatDecoder`.
+- `IFormatDecoder` (`IFormatDecoder.ts`) is a clean per-format strategy: `tryParseHeader`,
+  `getAlignedSegmentSize`, `wrapSegment`, `calculateByteOffset`, plus a `FormatInfo` carrying
+  `byteRate`, `blockAlign`, `audioDataOffset`, and a `seekData` accelerator slot (already polymorphic:
+  `Mp3VbrSeekData | FlacSeekData`). **This is the seam an `OpusFormatDecoder` slots into.**
+- **Correction to the Phase 21 spec's §2 C3 note** ("MP3/FLAC implemented, not yet wired"): the
+  registry *is* wired and dispatches on content-type today. Phase 21's invariant still holds; the
+  parenthetical is stale and is corrected by this phase's reconciliation.
+
+**What this means for the gap.** Daniel's direction is **not** "add format support" — that substrate
+exists. It is "**derive a second, low-data artifact (Opus fullband 320) at ingest and let the listener
+pick which to stream.**" That is two genuinely new things: (1) a **transcode-at-ingest** step that
+produces a derived artifact per track (the router stores originals; nothing derives Opus), and (2) a
+**per-format delivery selection** so the same track can be served as either WAV or Opus on request.
+
+---
+
+## 1. Goal
+
+**Dual-format delivery.** Every track is streamable in two formats:
+
+- **Lossless** — the existing WAV path, unchanged. The archival / audiophile option.
+- **Low-data** — a derived **Ogg Opus, fullband, 320 kbps** artifact. The bandwidth-friendly
+  default-candidate.
+
+The listener chooses; Opus is the recommended default. The bespoke Web Audio decode→schedule graph is
+**retained by deliberate choice** (Daniel) — Opus is fed through the same `IFormatDecoder` strategy
+seam, not through an HTML `<media>` element or MSE.
+
+**Why Opus fullband 320.** Opus is the modern, royalty-free, best-in-class lossy codec; "fullband"
+(48 kHz, full 20 kHz audio bandwidth) at 320 kbps is transparent-to-most-listeners quality at roughly
+**1/4 to 1/5 the bytes of 16-bit/44.1 stereo WAV** (~1411 kbps). For a 1 GB DJ MIX (Phase 9 `Mix`
+medium), that is the difference between a ~1 GB transfer and a ~220 MB transfer — the headline
+low-data win, and directly relevant to the Phase 21 long-stream case.
+
+**Non-goals.** This phase does not retire WAV (it stays as the lossless option), does not change the
+bespoke graph for MSE (explicitly rejected — see §2 / Phase 21 OQ5), and does not add new transport
+mechanisms beyond the existing stream + `Range` primitive.
+
+---
+
+## 2. Constraints / invariants (the contract that must hold)
+
+- **C1 — Keep the bespoke Web Audio graph. MSE is rejected (Daniel, deliberate).** The custom
+  decode→schedule graph is a long-term commitment, not a stopgap. Opus is fed through the existing
+  `IFormatDecoder` → `StreamDecoder` → `PlaybackScheduler` pipeline. (This is the same decision
+  recorded as **Phase 21 OQ5 = NO**; the two phases share it.)
+- **C2 — Preprocessing is additive; the WAV path is untouched.** The Opus artifact is a **second
+  derived artifact per track**, not a replacement. The existing WAV in the `tracks` vault stays
+  byte-for-byte as it is today; the lossless stream path is unchanged. A track with no Opus artifact
+  (legacy rows, or a transcode that hasn't run yet) must still play losslessly — Opus is strictly
+  additive.
+- **C3 — Reuse the landed `Range`/offset seek path; do not fork it.** Phase 4's
+  `Range: bytes=X-` → `206` primitive (client `TrackMediaClient` → `DeepDrftPublic` proxy →
+  `DeepDrftAPI`) is the substrate for Opus seek too. Opus seek math differs from WAV (VBR /
+  container-paged, see §3.4) but it is expressed through the **same** `IFormatDecoder.calculateByteOffset`
+  seam the MP3/FLAC decoders already use — no second seek mechanism.
+- **C4 — Opus slots the `IFormatDecoder` registry; no format branches leak elsewhere.** The new
+  `OpusFormatDecoder` is selected by `AudioPlayer.createFormatDecoder` on `Content-Type:
+  audio/ogg`/`audio/opus`. The rest of the player stack stays format-agnostic. No `if (opus)` outside
+  the decoder and the one selection point.
+- **C5 — Format selection is a delivery-time decision, resolved server-side from a listener
+  signal.** The same `TrackEntity` / `EntryKey` addresses both artifacts; the *format* is a parameter
+  on the stream request (query param or `Accept` negotiation — see §3.3), not a different track id and
+  not a different vault entry key. One track, two renderings (the standing "one source, multiple
+  views" preference applied to delivery).
+- **C6 — Transcode failure must not block ingest.** If the Opus transcode fails or is slow, the
+  track still persists with its lossless artifact and is playable. Opus is generated best-effort and
+  can be (re)generated later — mirror the **waveform-datum** model (`WaveformProfileService`: compute
+  on upload, regenerate on demand via a CMS action), which is exactly the "derived artifact, generated
+  at ingest, regenerable" pattern this needs.
+- **C7 — The vault model holds: derived artifact is a new entry, not a mutation.** The Opus bytes
+  live in the FileDatabase under the track's `EntryKey` — either in the existing `tracks` vault under
+  a derived key, or in a new sibling vault (see §3.2 options). Either way it is `AudioBinary` with the
+  `.opus`/`.ogg` extension and correct MIME, registered like any other vault resource.
+
+---
+
+## 3. Architectural shape
+
+### 3.0 The mental model
+
+A track has one **source artifact** (the uploaded WAV/MP3/FLAC, stored as-is today) and gains one
+**derived low-data artifact** (Ogg Opus fullband 320, produced at ingest). The stream endpoint serves
+*either*, selected per request. The player picks a decoder by the response `Content-Type` exactly as
+it does today. Seeking uses the same `Range` primitive; the byte↔time math is the decoder's job.
+
+```
+INGEST (DeepDrftContent + DeepDrftAPI)
+  upload → AudioProcessorRouter (existing) → store SOURCE artifact in vault   [unchanged]
+                                          → TRANSCODE to Opus 320 → store DERIVED artifact   [NEW]
+                                          → WaveformProfileService (existing, unchanged)
+
+DELIVERY (DeepDrftAPI → DeepDrftPublic proxy → DeepDrftPublic.Client → Interop/audio)
+  GET api/track/{id}?format=opus|lossless  →  serve the chosen artifact's bytes (+ Range)   [NEW param]
+  player: createFormatDecoder(Content-Type) → OpusFormatDecoder | Wav | Mp3 | Flac   [+1 decoder]
+```
+
+### 3.1 Where the transcode lives (relative to existing processing)
+
+The transcode is a **new processor sibling** to the existing format processors, invoked **after** the
+source is stored, in the same orchestration that already calls `WaveformProfileService`:
+
+- It belongs in `DeepDrftContent` (the binary-content domain library) as e.g. an
+  `OpusTranscodeService` / `OpusProcessor`, **not** in a host and **not** in a controller (per the
+  `*.Services`-owns-domain-logic convention).
+- It is invoked from `UnifiedTrackService.UploadAsync` (the same place `WaveformProfileService`
+  computes the high-res datum on every new track) and from the **replace-audio** path (which already
+  regenerates both waveform datums — Opus is the third derived thing to regenerate there).
+- Like the waveform datum, it gets a **regenerate trigger**: a CMS per-track / bulk action and an
+  ApiKey-gated endpoint, so existing tracks can be backfilled. This mirrors the landed
+  "Generate All Profiles / Backfill High-res" bulk actions on `Releases.razor` — **Backfill Opus**
+  is the natural third bulk action.
+
+**The transcode engine itself is staff-engineer's call** (FFmpeg/libopus via a process invocation, a
+managed binding, or a libopus P/Invoke). The spec fixes the *artifact* (Ogg Opus, fullband, 320 kbps)
+and the *seam* (a derived artifact produced post-store, regenerable, failure-tolerant), not the tool.
+Note a real operational constraint to flag for implementation: transcoding a 1 GB WAV is **CPU- and
+time-expensive** and must not block the upload response — it wants the same off-the-hot-path treatment
+the upload body staging already gets (`Upload:StagingPath`). This is the single biggest implementation
+risk and is called out as such. The execution model is now **decided** (OQ6): **the source is stored and
+the track is playable (lossless) first, then the Opus transcode runs as a background job** — see §3.1a
+for the user-visible consequence on the upload UI.
+
+### 3.1a Transcode execution model + the Post-Processing upload phase (RESOLVED — OQ6)
+
+**Execution model (Daniel, 2026-06-23): background process *after* the file is available.** The upload
+flow is now two distinct server-side stages with a hard ordering:
+
+1. **Transfer + store + persist (existing, synchronous).** The WAV body streams in (the landed
+   `ProgressStreamContent` two-phase cancellation), the source is stored in the vault, the `TrackEntity`
+   is persisted, the waveform datums are computed. At the end of this stage **the track is fully playable
+   losslessly** — nothing about Opus gates a successful upload.
+2. **Opus transcode (NEW, background, after stage 1 completes).** A queued/background job reads the
+   stored source, transcodes to Ogg Opus 320, builds the **seek index** and extracts the **setup header**
+   (§3.4a), and stores all three derived artifacts. Until it finishes, `?format=opus` for that track
+   falls back to lossless (C2). On failure the track stays lossless-only and is eligible for Backfill-Opus
+   (C6).
+
+**The upload progress meter gains a visible Post-Processing phase.** The CMS upload forms
+(`BatchUpload.razor` / `BatchEdit.razor`) already render a progress meter driven by `ProgressStreamContent`
+(byte-transfer progress) and the two-phase cancellation (idle window during transfer, response-wait budget
+after the body completes). The transcode is a **third visible phase** appended to that meter — after the
+existing "uploading bytes" and "server is persisting" phases, a **Post-Processing** phase reflects the
+background transcode's status (queued → transcoding → done / failed). This is an *addition* to the
+existing meter, not a new UI.
+
+- The admin sees: bytes transfer → server persists (track now exists + plays lossless) → **Post-Processing**
+  (Opus being derived). The form may complete/return the admin to the catalogue after stage 1 (the track
+  is live); the Post-Processing phase can continue to report against that track in the browse/release view
+  (the Opus waveform/profile columns on `Releases.razor` already poll-and-show per-track derived-artifact
+  status — Post-Processing status fits the same affordance family).
+- **How status reaches the UI is staff-engineer's call** (poll the track's Opus-artifact presence, an SSE/
+  long-poll job channel, or a status field on the track read). The spec fixes that the phase is *visible*
+  and *non-blocking* — the admin is never made to wait on the transcode to consider the upload done.
+- This composes with the **always-on** decision (OQ4): every upload triggers the background transcode;
+  there is no per-upload opt-out, so the Post-Processing phase always appears.
+
+### 3.2 Where the Opus artifact is stored (two options)
+
+**Option S1 — derived key in the existing `tracks` vault (recommended).** Store the Opus bytes under
+a derived entry key alongside the source, e.g. `{entryKey}` for source and `{entryKey}.opus` (or a
+parallel key convention) in the same `tracks` vault. *Pro:* no new vault type, co-located with the
+source, simplest lookup. *Con:* mixes two artifacts per logical track in one vault's index.
+
+**Option S2 — a new sibling vault (e.g. `track-opus`).** Mirror the `track-waveforms` precedent
+(Phase 12 added a dedicated vault for the derived high-res datum). Opus bytes keyed by the same
+`EntryKey` in a `track-opus` vault. *Pro:* clean separation of source vs. derived, matches the
+established "derived artifacts get their own vault" pattern (`track-waveforms`), easy to enumerate /
+backfill / purge independently. *Con:* one more vault to register.
+
+**Recommendation: S2** — it is the pattern the codebase already chose for the *other* derived
+per-track artifact (the high-res waveform datum), so it is the least surprising and keeps the source
+`tracks` vault meaning exactly one thing. **Final call is staff-engineer's**; both are viable.
+
+### 3.3 How a listener's format choice reaches the bytes
+
+The stream endpoint gains a **format selector**. Two candidate mechanisms:
+
+- **D-a — explicit query param** `GET api/track/{id}?format=opus|lossless` (recommended). Mirrors the
+  existing `offset` query param the proxy already forwards (`TrackProxyController`). Explicit,
+  cache-friendly (distinct URLs), trivial to thread through the proxy, and the player already knows
+  which it asked for. Server resolves the param → the right artifact → sets the right `Content-Type`,
+  which the player's existing `createFormatDecoder` then dispatches on. **No new decoder-selection
+  mechanism** — the response content-type does the work it already does.
+- **D-b — HTTP content negotiation** (`Accept: audio/ogg` vs `audio/wav`). More "correct" REST, but
+  the proxy + WASM client wiring is fussier and caches are content-type-varied. Not worth it here.
+
+**Recommended: D-a.** The selection *policy* (which format a given listener gets by default, and how
+they switch) is a genuine **product call — see OQ1/OQ2**, deliberately not decided here. The
+*mechanism* (a query param resolved server-side to an artifact + content-type) is settled.
+
+Server-side fallback rule (C2): if `format=opus` is requested but no Opus artifact exists for that
+track (not yet transcoded / backfilled), the endpoint **falls back to lossless** rather than 404ing —
+Opus is additive, so its absence degrades to "you get the lossless one," never to "no audio."
+
+### 3.4 The Opus decoder (the genuinely new decode work)
+
+`OpusFormatDecoder implements IFormatDecoder` is the new code on the delivery side. **Ogg Opus is a
+containerized, paged format — not raw-frame-sliceable** the way WAV PCM is. WAV's `wrapSegment` prepends a
+44-byte PCM header to any PCM-aligned byte run; the current model assumes you can wrap an arbitrary aligned
+raw-audio slice and hand it to `decodeAudioData`. Ogg Opus is page-structured (Ogg pages carrying Opus
+packets, plus mandatory `OpusHead`/`OpusTags` **setup pages** at the very start). A mid-stream byte slice
+is **not** independently decodable: it needs (1) the setup header prepended, and (2) to begin on an Ogg
+**page boundary**. So:
+
+- `OpusFormatDecoder.getAlignedSegmentSize` aligns to **Ogg page boundaries** — scan for the `OggS`
+  capture pattern (analogous to FLAC's frame-sync scan; the `IFormatDecoder` interface already passes
+  `rawData` to `getAlignedSegmentSize` for exactly this reason).
+- `wrapSegment` / the continuation path **prepends the `OpusHead`/`OpusTags` setup bytes** to a mid-stream
+  page run before handing it to `decodeAudioData` (analogous to FLAC's `streamInfoBytes` carry in
+  `FlacSeekData`). The setup bytes come from the **setup-header mechanism** (§3.4a), not from re-reading
+  the stream start.
+- A new `OpusSeekData` variant joins `Mp3VbrSeekData | FlacSeekData` in the `seekData` accelerator slot —
+  but for Opus it carries the **accurate seek index** (§3.4a), not a heuristic TOC.
+
+**The `IFormatDecoder` abstraction already has the shape for both needs** — a format-specific `seekData`
+accelerator and a setup-bytes carry — because FLAC needed the same kind of thing. The genuinely new part
+is **where the seek index and setup header come from**, which §3.4a designs.
+
+> **Seek is NOT approximate for Opus (Daniel, 2026-06-23 — supersedes the earlier hand-wave).** An earlier
+> draft of this section proposed "granule-position/Ogg-page interpolation" — a best-effort approximate
+> offset, the Opus analogue of MP3's Xing TOC. **That is rejected.** Daniel: *"Killing seeking for
+> decoding is unacceptable… Raw bytes offset for seeking is no longer adequate due to VBR. We need an
+> accurate transfer function for seek time → true file byte offset."* Opus seeking is **accurate**, backed
+> by a precomputed index built at transcode time. See §3.4a.
+
+**Browser decode-support constraint (real, must be designed around).** The bespoke graph decodes
+segments via `AudioContext.decodeAudioData`. Ogg-Opus support in `decodeAudioData` is long-standing in
+Chrome and Firefox but arrived in **Safari only at 18.4 (macOS 15.4 / iOS 18.4, March 2025)**; older
+Safari decodes Opus only in a CAF container, not Ogg. iOS Safari is a primary music-listening surface,
+so this is not a corner case. Implications: (1) the **lossless WAV path is the universal fallback** for
+listeners whose browser can't decode Ogg Opus — which C2's additive design already provides for free;
+(2) the format default is **capability-gated** (OQ2, RESOLVED) — don't hand Ogg Opus to a Safari that
+can't decode it; detect support (a probe `decodeAudioData` on a tiny Opus blob, or a UA/version gate) and
+fall back to lossless. This intersects Phase 1.7 (Safari compatibility) and is flagged there too.
+([Browser support: caniuse / WebKit 18.4 release notes — see Sources.])
+
+### 3.4a VBR-safe accurate seeking (the seek-index artifact + the setup-header mechanism)
+
+This is the architectural core of the Opus delivery path, and it must compose with **Phase 21 windowed
+refill** (where most of the stream is *not* in memory). The requirement, decomposed from Daniel's
+direction:
+
+1. Seeking must be preserved for Opus **without** having the full PCM decoded in memory.
+2. Raw byte-offset seek is inadequate — a VBR Opus stream has **no linear time↔byte relationship**, so
+   `byteRate` math and even rough page interpolation are not accurate enough.
+3. We need an **accurate transfer function: seek-time → true file byte offset.**
+4. The decode setup header must be **available separately** (or cached before seeking past it), because a
+   mid-stream slice is undecodable without `OpusHead`/`OpusTags`.
+
+**The key insight: the one moment we already walk the entire encoded stream is the transcode.** That is
+precisely when an accurate index can be built for free. We never have to guess at delivery time — we read
+the answer out of a precomputed artifact.
+
+#### A. The seek-index artifact (the accurate transfer function)
+
+At transcode time, after the Opus bytes are produced, **walk the encoded Ogg stream once and record, for
+each Ogg page (or coarser bucket), the page's `granulepos` (a 48 kHz sample count → time) paired with its
+**byte offset** in the file.** That granule→byte table *is* the exact transfer function. This is the Opus
+analogue of FLAC's `SEEKTABLE` / MP3's Xing TOC — but **precomputed and exact**, not derived by
+interpolation guessing. Ogg granule positions are authoritative sample counts, so the mapping is true, not
+estimated.
+
+- **What it contains.** An ordered list of `(timeSeconds | granulepos, byteOffset)` entries, plus the
+  total duration and total byte length (for clamping a seek to range). A binary little-endian array of
+  fixed-width records is the natural shape (e.g. a `uint64 granulepos` + `uint64 byteOffset` per entry);
+  the exact encoding is staff-engineer's, but it should be a **compact binary blob**, fetched once and
+  parsed into a typed array client-side.
+- **Granularity vs. size — RESOLVED: 0.5 s (half-second) buckets (Daniel, 2026-06-23).** One entry per
+  Ogg page is the most precise but largest; an Ogg page is typically a few KB of audio (~tens of ms to a
+  few hundred ms), so a 1-hour mix could be tens of thousands of pages. The chosen bucket is **one index
+  entry per 0.5 seconds of audio** (snap each bucket boundary to the *nearest enclosing page start*, so
+  every indexed offset is still an exact page boundary). At 0.5 s granularity a 1-hour mix is
+  ~7,200 entries × 16 bytes ≈ **~115 KB** — still a trivial one-time fetch, and 0.5 s seek resolution is
+  finer than required (the decoder re-syncs to the exact page within the bucket anyway — see the client
+  flow — so the in-bucket trim is *sub-half-second*, tighter than the earlier ~1–2 s recommendation).
+  **Per-page precision remains the fallback if 0.5 s buckets ever prove too coarse**, at a larger index.
+  The bucket size is now fixed; the *shape* (precomputed exact granule→byte, bucketed, snapped to page
+  starts) is unchanged.
+- **Sidecar, not embedded (recommended).** Store the index as a **third derived artifact** alongside the
+  Opus bytes and the waveform datum — the same "derived artifacts get their own vault" pattern this phase
+  already uses (S2 / `track-opus`; the `track-waveforms` precedent). Keep it a separate vault resource
+  (e.g. `{entryKey}.seekidx` in a `track-opus` vault, or its own `track-opus-index` vault) rather than
+  embedding it in the Ogg stream. *Why sidecar:* it is fetched **once, up front** (small, cacheable),
+  independent of the audio byte stream; embedding it in the Ogg would force the client to read into the
+  stream to find it, defeating the "resolve the offset *before* the Range fetch" flow. *Road not taken —
+  derive the index lazily on first seek by scanning server-side:* rejected, because it re-walks the stream
+  at request time (the cost we avoid by computing at transcode) and gives nothing the precomputed sidecar
+  doesn't.
+
+#### B. The setup-header mechanism (decodability of any mid-stream slice)
+
+Any post-seek slice needs `OpusHead` + `OpusTags` prepended to decode. Two ways to make those bytes
+available to the client:
+
+- **B-a — Client-side caching of the leading setup pages on first read (recommended).** On first play, the
+  stream already begins at byte 0, so the client *already receives* the `OpusHead`/`OpusTags` pages as the
+  opening bytes. `OpusFormatDecoder.tryParseHeader` captures and **retains** those setup bytes (exactly as
+  `WavFormatDecoder` retains the parsed WAV header for `reinitializeForRangeContinuation` today, and FLAC
+  retains `streamInfoBytes`). Every subsequent post-seek continuation prepends the cached setup bytes. *No
+  new endpoint;* it reuses the header-retention discipline already in the codebase.
+- **B-b — A dedicated setup-header sidecar endpoint** (`GET api/track/{id}/opus/header` → just the
+  `OpusHead`/`OpusTags` bytes, also derivable at transcode time and stored as a tiny artifact). *Pro:* a
+  seek can be served even if the listener seeks **before** the stream start has been read (e.g. a deep-link
+  that begins mid-track, or a Phase 21 window that opens away from byte 0). *Con:* one more endpoint +
+  artifact.
+
+**Recommendation: B-a as the primary, B-b as a cheap insurance artifact.** B-a covers the overwhelming
+common case (play-then-seek) with **zero new surface** — it is the WAV-header-retention pattern applied to
+Opus. But Phase 21 windowing and deep-links can legitimately open a window that never read byte 0, so the
+setup header should **also** be derivable on demand. Cheapest reconciliation: **extract the setup bytes at
+transcode time and store them as a tiny sidecar artifact** (they are a few hundred bytes), and expose them
+**either** as a small endpoint **or** simply prepend them to the seek-index sidecar's header region so the
+single up-front index fetch *also* delivers the setup bytes. The latter folds B-b into the B-a fetch: **the
+client's one up-front sidecar fetch returns both the seek index and the setup header**, so it always has
+both before it ever issues a seek — and never needs byte 0 to have been read. **Recommended concrete
+design: one sidecar per track = `[setup-header bytes][seek-index table]`, fetched once on track load,
+parsed into `OpusSeekData`.** This is the cleanest: one new artifact, one new fetch, both needs met.
+
+#### C. The client-side seek flow, end to end
+
+With the sidecar (`OpusSeekData` = setup header + granule→byte index) fetched and parsed at track load:
+
+1. **Resolve time → byte offset (accurate).** Listener seeks to `t` seconds. `OpusFormatDecoder.calculateByteOffset(t)`
+   does a binary search in the index for the largest entry with `time ≤ t`, returns its exact (page-start)
+   `byteOffset`. **No interpolation, no `byteRate` math.** (For WAV this method stays the exact CBR
+   calculation it is today — the seam is identical; only the Opus implementation reads an index.)
+2. **Range fetch from the offset.** Issue `GET api/track/{id}?format=opus` with `Range: bytes={byteOffset}-`
+   — the **landed Phase 4 Range primitive, unchanged**. Server streams raw Opus bytes from that exact page
+   boundary (`206 Partial Content`).
+3. **Prepend the cached setup header + decode.** The continuation path (the Opus analogue of
+   `StreamDecoder.reinitializeForRangeContinuation`) prepends the retained/sidecar `OpusHead`/`OpusTags`
+   bytes to the incoming page run, then feeds it to `decodeAudioData`. Because the index offset is an exact
+   page start, the stream is immediately Ogg-sync-aligned.
+4. **Fine re-sync within the bucket.** The granule of the first decoded page tells the decoder the *exact*
+   time it landed at (≤ the bucket granularity ahead of `t`); the scheduler trims/positions to land
+   playback at `t` precisely. With 0.5 s buckets the trim is sub-half-second; with per-page granularity it
+   is near-zero. **Either way the listener lands at the correct time, not approximately** (AC9).
+
+#### D. Composition with Phase 21 windowed refill
+
+Phase 21's windowed refill controller resolves "I need bytes for playback position `P`" → a byte offset →
+a Range fetch. **It calls the *same* `OpusFormatDecoder.calculateByteOffset` (the index-based resolver)
+for Opus** that an explicit seek does — windowed refill is just a seek the listener didn't initiate. So the
+seek index serves both: explicit seeks and the window's low-water refills both resolve through the index,
+and both prepend the cached setup header. This is why §3.4a is in **Phase 18** (where the transcode that
+builds the index lives), and Phase 21 *consumes* it. The Phase 21 spec's "approximate mapping" language for
+Opus is now wrong and is corrected to **"accurate index-based mapping."**
+
+#### E. Reuse vs. extend (the seam discipline)
+
+- **Reused verbatim:** the Phase 4 `Range: bytes=X-` → 206 primitive (client → proxy → API); the
+  `IFormatDecoder.calculateByteOffset` seam; the header-retention/continuation discipline
+  (`reinitializeForRangeContinuation`'s Opus analogue); the derived-artifact-in-its-own-vault pattern
+  (`track-waveforms` → `track-opus`); the derive-at-transcode-regenerate-on-backfill lifecycle.
+- **Extended (new):** the seek-index + setup-header **sidecar artifact** (built at transcode, stored
+  beside the Opus bytes); the one-time **sidecar fetch** on track load (parsed into `OpusSeekData`); the
+  index **binary-search resolver** inside `OpusFormatDecoder`. Three additions, all leaf-level — no change
+  to the Range mechanism, the proxy, or the format-agnostic player.
+
+### 3.5 The three candidate directions (shape-level)
+
+Per file convention the alternatives are recorded; the recommendation follows.
+
+**Direction A — Derived Opus artifact at ingest + format param on delivery (recommended).** What §3.1
+–3.4a describe: transcode to Opus 320 post-store as a **background job** (OQ6), store as derived artifacts
+(S2 vault) — the Opus bytes **plus the seek-index/setup-header sidecar** (§3.4a) — serve via a `?format=`
+param resolved server-side to bytes + content-type, decode via a new `OpusFormatDecoder` in the existing
+registry, **seek accurately via the precomputed index**. *Why recommended:* additive (C2), reuses every
+existing seam (the processor orchestration, the waveform-datum derived-artifact pattern, the `Range` path,
+the decoder registry, the header-retention discipline), and the only genuinely new code is one transcode
+step (+ index build) + one decoder (+ index resolver). **Three** derived artifacts per track (Opus bytes,
+seek sidecar, and the existing waveform datum), all regenerable.
+
+**Direction B — On-the-fly transcode at delivery (no stored Opus artifact).** Transcode WAV→Opus per
+request in the stream endpoint, streaming the Opus out as it encodes. *Why not (default):* moves
+expensive CPU onto the **hot request path** (a 1 GB mix transcoded per play is untenable), breaks
+`Range`/seek (you can't byte-offset into a stream you're encoding live), and defeats caching. It *is*
+storage-cheaper (no second artifact on disk), so it is the fallback only if disk cost ever dominates —
+but for a music site where the same tracks are played repeatedly, precompute-once wins decisively.
+Rejected as the primary.
+
+**Direction C — Replace WAV ingest with Opus-only (transcode and discard the lossless source).** Make
+Opus *the* stored format; drop WAV. *Why not:* violates Daniel's explicit "lossless streaming
+*optional* — two delivery formats, listener gets a choice." Lossless is a kept option, not a thing to
+transcode away. Also irreversibly lossy at ingest (you can never recover the WAV). Rejected outright;
+recorded only because "just store Opus" is the tempting simplification and the spec should say why not.
+
+### 3.6 SOLID / road-not-taken rationale
+
+- **OCP, via the existing seams.** The transcode is a new processor sibling (the router pattern is
+  already open for extension); the decoder is a new `IFormatDecoder` (the registry is already open for
+  extension); the artifact is a new derived vault resource (the `track-waveforms` precedent is exactly
+  this). Phase 18 adds **three new leaf implementations** and **zero changes to existing format code**
+  — the strongest possible OCP signal that the seams were designed right.
+- **SRP, preserved.** Transcoding **and the seek-index build** are content-domain processor concerns
+  (`DeepDrftContent`); delivery selection is a thin endpoint concern (`DeepDrftAPI` resolves a param to an
+  artifact, and serves the sidecar); decode is the `OpusFormatDecoder`'s concern; byte↔time math stays
+  inside that decoder via `calculateByteOffset` (now reading the index, not interpolating). No
+  responsibility crosses a boundary it doesn't already own. The seek index is built **once, where the
+  stream is already walked** (transcode) — the natural home for an exact transfer function, never
+  recomputed at request time.
+- **DIP / "one source, multiple views."** One `TrackEntity`/`EntryKey` is the single source; "lossless
+  WAV" and "low-data Opus" are two *views* (renderings) of it, diverging only at the delivery/decode
+  layer — the same discipline the dark-mode and track-browse surfaces follow.
+- **Road not taken — a separate `TrackEntity` row (or a new track id) per format.** Tempting (one row
+  = one streamable file) but it fractures the track identity: shares, queues, play-counts (Phase 16),
+  release membership, and waveform data all key on one track, and doubling rows to carry a format
+  would force every one of those surfaces to dedupe. Format is a *delivery attribute of one track*,
+  not a *second track*. Rejected — keep one identity, two artifacts.
+
+---
+
+## 4. Format selection — the product surface (RESOLVED — global, via a Settings menu)
+
+**Resolved (Daniel, 2026-06-23):** the listener's quality choice is **global** (one session/visitor-level
+"streaming quality" preference, not per-track), Opus is the **default** (capability-gated), and the choice
+is **remembered** following the dark-mode persistence pattern. Crucially: *"Global is perfect, but we need
+a menu system for settings, don't just slap the quality control directly in the app bar."* So the toggle
+does **not** sit bare in the app bar — it lives inside a proper **public-site Settings menu** (§4a), of
+which it is the **first occupant**.
+
+- **What the listener sees.** A Settings affordance in the public app bar opens a Settings menu; inside it,
+  a "Streaming quality" control with two options — **Low-data (Opus)** / **Lossless (WAV)** — defaulting to
+  Low-data. Picking lossless flips the global preference; the player sends the matching `?format=` on
+  subsequent stream requests (§3.3). On a browser that can't decode Ogg Opus, the control is shown but the
+  effective stream is lossless (capability gate, §3.4 / OQ2) — surface this honestly rather than letting
+  the listener pick a format that silently can't play.
+- **Default before any choice:** Opus, capability-gated (OQ2 RESOLVED). A first-time visitor on a capable
+  browser streams Opus; on an incapable browser, lossless.
+- **Persistence:** mirror the dark-mode seam exactly (OQ3 RESOLVED) — see §4a.
+
+### 4a. The Settings menu surface (NEW — scoping + the dark-mode persistence pattern)
+
+Daniel asked for a **menu system for settings**, not a control bolted onto the app bar, and noted the
+existing **dark-mode toggle** is a natural future tenant of the same menu (design for adaptability — build
+the menu so dark mode *could* move into it later, but **do not force that migration now**).
+
+**Scoping recommendation: a small sub-track *within* Phase 18 (wave 18.6), not its own phase.** Reasoning:
+
+- The menu's only **required** occupant right now is the quality toggle, which Phase 18 owns end to end —
+  splitting the shell into a separate phase would create a phase whose sole deliverable is an empty menu
+  waiting for Phase 18's toggle. That is ceremony, not separation of concerns.
+- The menu is **small** — an app-bar trigger + a MudBlazor menu/popover + the persistence seam (which the
+  quality toggle needs *anyway*). It is not a platform; it is a container with one tenant.
+- It carries a real **design-for-adaptability** obligation (it must be able to host dark mode and future
+  settings later), but that is a *shape* requirement on a small surface, not a phase's worth of work.
+
+So: **build the Settings-menu shell as part of Phase 18 (wave 18.6), with the quality toggle as its first
+occupant, designed so dark mode and future preferences can plug in without restructuring.** Flag for
+Daniel: *if he wants the menu shell proven/landed independently before the quality toggle plugs in*, 18.6
+can be split into "menu shell" then "quality toggle plugs in" — but they are small enough to land together.
+This is **not** recommended as its own top-level phase. (If Daniel disagrees and wants a dedicated
+"Public Settings Menu" phase that Phase 18's toggle then targets, that is a clean alternative — it just
+front-loads a surface with no second tenant yet. Recommendation stands: sub-track.)
+
+**The menu shell — design-for-adaptability requirements (so it survives new tenants):**
+
+- A **settings-item abstraction**, not a hard-coded list. The menu renders a small set of settings entries;
+  adding dark mode later is adding an entry, not rewiring the menu. Each entry is a label + a control bound
+  to a persisted preference.
+- A **single public-site settings object** carrying all listener preferences (today: streaming quality;
+  tomorrow: dark mode, and whatever follows). This is the `DarkModeSettings` analogue, generalized — call
+  it e.g. `PublicSiteSettings` / `ListenerSettings`. Dark mode's existing `DarkModeSettings` can fold into
+  it *later* without disturbing the menu.
+
+**Persistence — mirror the dark-mode seam exactly (OQ3 RESOLVED).** The quality preference follows the
+*identical* path dark mode already uses (root `CLAUDE.md` "Theming and dark mode"):
+
+1. **Cookie** — a `streamQuality` cookie (365-day, like `darkMode`), the durable truth.
+2. **Server prerender read** — a service in `DeepDrftPublic` (sibling to `DarkModeService`) reads the
+   cookie during prerender and seeds the settings object, avoiding a wrong-default flash on first paint
+   (the streaming-quality analogue of the "wrong theme flash" fix).
+3. **`PersistentComponentState` bridge** — the seeded preference carries from server prerender into the
+   WASM render (the same bridge `DarkModeSettings` and `NowPlayingStats`/`StatsClient` already use), so the
+   client boots already knowing the quality without a re-read flash or a re-fetch.
+4. **Client cookie service** — a runtime client-side service (JS-interop cookie write, like the dark-mode
+   toggle) persists the choice when the listener changes it in the menu.
+
+**Why mirror rather than invent:** the dark-mode seam is the codebase's established, working pattern for "a
+listener preference seeded at prerender, carried to WASM, persisted in a cookie." Reusing its shape means
+the quality preference inherits the no-flash guarantee for free, and the eventual dark-mode-into-the-menu
+migration is a *consolidation of two identical seams*, not a reconciliation of two different ones. (This is
+the "one source, multiple views" / design-for-adaptability discipline applied to listener settings.)
+
+---
+
+## 5. Use cases
+
+- **UC1 — Listener streams the low-data Opus of a long mix (the headline win).** A ~1 GB lossless mix
+  transfers as ~220 MB of Opus; playback through the bespoke graph is identical in feel, far cheaper
+  on bandwidth. (Compounds with Phase 21 windowing for the memory side.)
+- **UC2 — Listener prefers lossless and switches to it.** The same track served as WAV via
+  `?format=lossless`; the bespoke graph decodes it exactly as today.
+- **UC3 — Legacy / not-yet-transcoded track.** `?format=opus` requested, no Opus artifact yet →
+  server falls back to lossless (C2); the listener still hears the track. A later Backfill-Opus pass
+  produces the artifact.
+- **UC4 — Admin backfills Opus for the existing catalogue.** A bulk "Backfill Opus" CMS action (the
+  third sibling to the existing Generate-Profiles / Backfill-High-res actions) transcodes every track
+  lacking an Opus artifact.
+- **UC5 — Replace-audio regenerates Opus.** The existing replace-audio path (which already regenerates
+  both waveform datums and re-derives duration) also regenerates the Opus artifact from the new
+  source.
+- **UC6 — Seek within an Opus stream (accurately).** Backward/forward seek resolves via the existing
+  `Range` path; the offset comes from the `OpusFormatDecoder`'s **precomputed seek index** (§3.4a) — an
+  exact granule→byte lookup, then fine re-sync to the requested time within the bucket. The listener lands
+  at the **correct** time, not approximately, and without the full PCM decoded in memory.
+- **UC7 — Safari that can't decode Ogg Opus.** Capability-gated to the lossless path (§3.4), so the
+  listener still plays audio. (Ties to OQ2 + Phase 1.7.)
+- **UC8 — Listener switches streaming quality in the Settings menu.** The listener opens the public
+  Settings menu, flips "Streaming quality" from Low-data to Lossless (or back); the choice persists
+  (cookie, dark-mode pattern) and applies to subsequent stream requests via `?format=`. On next visit the
+  preference is seeded at prerender (no flash, no re-pick). (§4 / §4a.)
+- **UC9 — Deep-link / windowed start away from byte 0.** A listener opens a stream at a mid-track position
+  (deep link, or a Phase 21 window that opens past byte 0) without ever reading the stream start. The
+  decoder still has the `OpusHead`/`OpusTags` setup bytes because they arrived with the up-front sidecar
+  fetch (§3.4a B), so the mid-stream slice is decodable immediately. (Composition case for Phase 21.)
+
+---
+
+## 6. Open questions — RESOLVED (Daniel, 2026-06-23)
+
+All seven open questions are resolved. Kept visible per file convention, each with the decision and
+the section that now carries it. OQ7 (raised by the seek-model design) is a narrow tuning call, now set to
+0.5 s buckets.
+
+- **OQ1 — Selection UX — RESOLVED: global, via a Settings *menu* (not a bare app-bar control).** Daniel:
+  *"Global is perfect, but we need a menu system for settings, don't just slap the quality control directly
+  in the app bar."* So: one global quality preference, surfaced inside a new **public-site Settings menu**
+  (§4 / §4a), of which the quality toggle is the first occupant. The menu is scoped as a **Phase 18
+  sub-track (wave 18.6)**, designed so dark mode (its natural future tenant) can plug in later. `[RESOLVED
+  — §4 / §4a]`
+- **OQ2 — Default policy — RESOLVED: Opus by default, capability-gated.** Opus is the default; on a browser
+  that cannot decode Ogg Opus (Safari < 18.4, §3.4), fall back to lossless rather than serving an
+  undecodable stream. Network-awareness (Opus on cellular / lossless on wifi) remains **deferred** as
+  gold-plating. `[RESOLVED — §3.4, §4]`
+- **OQ3 — Remembered choice — RESOLVED: persisted, following the dark-mode pattern.** A `streamQuality`
+  cookie seeded at server prerender → settings object → `PersistentComponentState` bridge into WASM →
+  client cookie service for runtime writes. The full dark-mode seam mirrored (§4a). `[RESOLVED — §4a]`
+- **OQ4 — Per-upload Opus control — RESOLVED: always-on + backfill.** Opus is generated for **every**
+  track, always (no per-upload opt-out). **Plus** a bulk **Backfill-Opus** CMS action processes the
+  existing catalogue. (The listener's lossless choice already covers "I want lossless," so a per-track
+  opt-out earns nothing.) `[RESOLVED — §3.1, UC4, wave 18.5]`
+- **OQ5 — Container — RESOLVED: Ogg Opus.** `.opus` / `audio/ogg` (broadest `decodeAudioData` support). No
+  CAF/WebM fallback — the lossless path already covers browsers that can't decode Ogg Opus (§3.4).
+  `[RESOLVED — §3.4]`
+- **OQ6 — Transcode execution model — RESOLVED: background job after the file is available; uploader shows
+  a Post-Processing phase.** The source is stored and the track is playable losslessly **first**; the Opus
+  transcode (+ seek-index build) runs as a **background job** afterward; the CMS upload progress meter
+  gains a visible **Post-Processing** phase reflecting the transcode status (§3.1a). A freshly uploaded
+  track is lossless-only until its Opus finishes — accepted, and now made visible rather than implicit.
+  `[RESOLVED — §3.1a]`
+
+**New open question raised by the seek-model design (§3.4a) — RESOLVED:**
+
+- **OQ7 — Seek-index granularity — RESOLVED: 0.5 s (half-second) buckets (Daniel, 2026-06-23).** The seek
+  index trades precision against size: per-Ogg-page (most precise, largest) vs. coarser time buckets snapped
+  to page starts. Daniel set the bucket at **0.5 s** (finer than the ~1–2 s the spec had recommended):
+  ~7,200 entries × 16 bytes ≈ **~115 KB** for a 1-hour mix — still a trivial one-time fetch. The decoder
+  fine-re-syncs within the bucket so seek *accuracy* is unaffected; at 0.5 s the in-bucket trim is
+  sub-half-second, tighter than before. The shape (precomputed exact granule→byte, page-snapped) is
+  unchanged. `[RESOLVED — §3.4a A]`
+
+---
+
+## 7. Acceptance criteria
+
+- **AC1 (headline) — Dual-format delivery works.** A track can be streamed as either lossless WAV or
+  Ogg Opus 320 from the same `EntryKey`, selected per request; both play correctly through the bespoke
+  Web Audio graph.
+- **AC2 — Opus is the low-data win.** The Opus artifact of a representative track is materially smaller
+  than its lossless source (target ~1/4–1/5 the bytes); a long mix's Opus transfer is correspondingly
+  smaller.
+- **AC3 — Additive, non-breaking (C2).** The existing lossless WAV path is byte-for-byte unchanged; a
+  track with no Opus artifact still plays losslessly; `?format=opus` on such a track falls back to
+  lossless (no 404, no silence).
+- **AC4 — Transcode at ingest as a background job, regenerable (C6, OQ6).** A new upload stores the source
+  and is playable losslessly **immediately**; the Opus artifact (+ seek-index/setup-header sidecar) is
+  produced by a **background job** afterward; a transcode failure does not block the upload or break
+  playback; a Backfill-Opus action (re)generates artifacts for existing tracks; replace-audio regenerates
+  the Opus artifact and its sidecar from the new source.
+- **AC4a — Post-Processing phase is visible on the upload meter (OQ6, §3.1a).** After the byte-transfer and
+  server-persist phases, the CMS upload progress UI shows a **Post-Processing** phase reflecting the
+  background transcode (queued → transcoding → done/failed). The admin is never blocked waiting on the
+  transcode; the track is live before Post-Processing finishes.
+- **AC5 — Opus seek via the existing `Range` path (C3).** Forward and backward seek in an Opus stream
+  resolve through the landed `Range: bytes=X-` primitive, with the offset coming from
+  `OpusFormatDecoder.calculateByteOffset`; no new seek *transport* mechanism is introduced.
+- **AC5a — Seek-index + setup-header sidecar exists and is fetched once (§3.4a).** Every track with an Opus
+  artifact has a sidecar carrying the setup header (`OpusHead`/`OpusTags`) and the granule→byte seek index;
+  the client fetches and parses it once on track load (into `OpusSeekData`) before issuing any seek.
+- **AC9 (the seek-accuracy criterion) — an Opus seek lands at the *correct* time, not approximately.**
+  Seeking to time `t` in an Opus stream resolves via the precomputed index and lands playback at `t`
+  (within the fine-resync tolerance — sub-half-second at the chosen 0.5 s bucket granularity), **measurably
+  accurate**, not a `byteRate`/interpolation estimate. Verifiable: seek to a known marker (e.g. a downbeat
+  at a known timestamp) and confirm playback resumes there, not seconds off. This holds **without** the
+  full PCM decoded in memory (composes with Phase 21).
+- **AC6 — No format branches leak (C4).** The only Opus-specific code is `OpusFormatDecoder`, its
+  `OpusSeekData` (carrying the index), the one `createFormatDecoder` selection arm, the transcode processor
+  (+ index build), the sidecar artifact + its serving, and the delivery param resolution. The
+  format-agnostic player/scheduler code is unchanged.
+- **AC7 — Capability-safe default (OQ2).** A browser that cannot decode Ogg Opus is served (or falls
+  back to) the lossless path and plays audio; no listener gets silence because of codec support.
+- **AC8 — Windowing-ready (the Phase 21 handshake).** The `OpusFormatDecoder`'s **index-based** byte↔time
+  resolver is the one Phase 21's windowed refill calls; Opus playback must be windowable by the same
+  machinery, and a windowed refill that opens away from byte 0 still decodes (setup header from the
+  sidecar — UC9). Verified jointly when Phase 21 lands on top (see §8 / Phase 21 cross-ref).
+- **AC10 — The Settings menu hosts the quality toggle and persists the choice (§4 / §4a).** The public app
+  bar opens a Settings menu containing a "Streaming quality" control (Low-data / Lossless, defaulting to
+  Low-data, capability-gated); changing it persists via the `streamQuality` cookie and is seeded at
+  prerender on the next visit (no flash). The menu shell is built so a future dark-mode entry can plug in
+  without restructuring.
+
+---
+
+## 8. Wave decomposition
+
+Dependency shape: `18.1 → 18.2 → {18.3, 18.4}`, with `18.5` (backfill + e2e) and `18.6` (settings menu)
+on top. **18.1 (the transcode + seek-index/setup-header derived artifacts) is the cold-start
+prerequisite** — until those artifacts exist, nothing downstream has bytes to serve, decode, or seek
+against. 18.3 (delivery param) and 18.4 (the decoder + index resolver) are largely parallel once 18.2
+(storage/lookup) settles, but both need artifacts to test against. **18.6 (the Settings menu) is the only
+wave with no audio-pipeline dependency** — it can proceed in parallel with the whole stack; it merely needs
+the `?format=` mechanism (18.3) wired before the toggle has anything to drive.
+
+- **18.1 — Ingest transcode + seek-index + setup-header (cold-start; load-bearing).** New
+  `OpusTranscodeService`/processor in `DeepDrftContent`, invoked post-store from
+  `UnifiedTrackService.UploadAsync` alongside `WaveformProfileService`, **as a background job** (OQ6,
+  §3.1a); produces Ogg Opus fullband 320; **walks the encoded stream once to build the granule→byte seek
+  index and extract the `OpusHead`/`OpusTags` setup header** (§3.4a A/B); stores the Opus bytes **and** the
+  combined seek/setup **sidecar** as derived artifacts (S2 vault recommended). Failure-tolerant (C6).
+  **Independent of the delivery/decoder waves; can begin immediately.**
+- **18.2 — Storage + lookup contract.** The derived-artifact key/vault convention (Opus bytes + sidecar)
+  and the server-side resolution "given `EntryKey` + format, return the right `AudioBinary` + content-type
+  (+ the sidecar on its own endpoint/path)," including the C2 fallback (no Opus → lossless). **Depends on
+  18.1** (artifacts must exist to resolve to).
+- **18.3 — Delivery: format param + sidecar serving + proxy threading.** `?format=opus|lossless` on the
+  `DeepDrftAPI` track stream endpoint (resolves via 18.2), forwarded through the `DeepDrftPublic`
+  `TrackProxyController` (mirror the existing `offset` param threading), and the `Range` handler serving
+  the chosen artifact's bytes; **plus serving the seek/setup sidecar** (a `GET …/opus/seekdata`-style path,
+  proxied the same way). The player sends the format param via `TrackMediaClient`. **Depends on 18.2.**
+  Parallel-ok with 18.4.
+- **18.4 — `OpusFormatDecoder` + the index-based seek resolver in the player stack.** New `IFormatDecoder`
+  implementation: Ogg-page-aligned `getAlignedSegmentSize` via `OggS` scan; `OpusHead`/`OpusTags` setup
+  carry in `wrapSegment`/the continuation path (sourced from the cached sidecar, §3.4a B); **`calculateByteOffset`
+  that binary-searches the precomputed seek index** (NOT interpolation), with an `OpusSeekData` accelerator
+  holding the parsed index + setup bytes; the **one-time sidecar fetch + parse** on track load. One new arm
+  in `AudioPlayer.createFormatDecoder` on `audio/ogg`/`audio/opus`. Capability detection for the lossless
+  fallback (§3.4, OQ2). **Depends on 18.2** (needs Opus bytes + sidecar). Parallel-ok with 18.3; they meet
+  at 18.5.
+- **18.5 — Backfill + replace-audio + end-to-end validation (incl. seek accuracy).** The Backfill-Opus CMS
+  bulk action (third sibling to Generate-Profiles / Backfill-High-res), which (re)builds Opus bytes + the
+  sidecar for existing tracks; replace-audio Opus + sidecar regeneration; and the AC1–AC10 acceptance pass
+  — **including AC9 (an Opus seek lands at the correct time, not approximately)** and AC8's confirmation
+  that Opus is windowable (index resolver + sidecar setup header) so Phase 21 can build on it. **Depends on
+  18.1–18.4.**
+- **18.6 — Public Settings menu + the quality toggle (the listener selection UX).** The new public-site
+  Settings-menu shell (§4a): an app-bar trigger + MudBlazor menu hosting a settings-item abstraction, the
+  `PublicSiteSettings`/`ListenerSettings` object, and the dark-mode-pattern persistence seam (`streamQuality`
+  cookie + a `DeepDrftPublic` prerender-read service + `PersistentComponentState` bridge + client cookie
+  service). The **quality toggle is its first occupant** (Low-data/Lossless, Opus default, capability-gated),
+  driving the `?format=` the player sends (needs 18.3). Built design-for-adaptability so dark mode can plug
+  in later without restructuring (not migrated now). **Depends on 18.3** (the toggle needs the format
+  mechanism); the menu *shell* can be built ahead of that. *Splittable* into "menu shell" + "toggle plugs
+  in" if Daniel wants the shell proven first — but small enough to land together (§4a).
+
+---
+
+## 9. Cross-references (read before implementing)
+
+- `CONTEXT.md §5` "Non-WAV formats" — the deferred intent this phase realizes (now concrete: derived
+  Opus low-data path, not generic format support).
+- `PLAN.md` Phase 21 / `product-notes/phase-21-windowed-streaming-buffer.md` — **sequenced AFTER this
+  phase.** Phase 21's C5 invariant ("WAV-only shipping target; must not foreclose MP3/FLAC") is now
+  driven by Opus's VBR/paged seek math; Phase 21 OQ5 (adopt MSE) is resolved **NO** — the bespoke
+  graph stays (the same C1 decision recorded here). Windowing a VBR/Opus stream uses
+  `OpusFormatDecoder.calculateByteOffset`'s **accurate index-based mapping** (§3.4a — *not* the earlier
+  "approximate page-interpolation"; that language in the Phase 21 doc is corrected). Phase 21's windowed
+  refill calls the **same** index resolver an explicit seek does (§3.4a D), and a window that opens away
+  from byte 0 still decodes via the sidecar setup header (UC9).
+- `PLAN.md` Phase 4 (landed) / `COMPLETED.md` — the HTTP `Range: bytes=X-` primitive Opus seek reuses.
+- `PLAN.md` Phase 1.5 (gapless) / 1.6 (track-skip on error) / 1.7 (Safari) — 1.5's "encoder
+  padding/priming" caveat applies to Opus (it has pre-skip samples in `OpusHead`); 1.6's
+  byte-scan-to-next-frame is the Ogg-page-sync analogue; 1.7's Safari floor intersects §3.4's Ogg-Opus
+  `decodeAudioData` support (Safari < 18.4).
+- `PLAN.md` Phase 12 / `product-notes/phase-12-waveform-visualizer-generalization.md` — the
+  `WaveformProfileService` derived-artifact-at-ingest + regenerate pattern this transcode mirrors
+  (compute on upload, regenerate via CMS action / endpoint, its own `track-waveforms` vault → the S2
+  precedent).
+- `PLAN.md` Phase 9 — defines the `Mix` medium (single long track), the canonical low-data case.
+- `PLAN.md` Phase 16 — play/share telemetry keys on one track identity; the §3.6 road-not-taken
+  (one-row-per-format) would have fractured this — kept to one identity, two artifacts.
+- `DeepDrftContent/Processors/AudioProcessor.cs` + `AudioProcessorRouter` + `DeepDrftContent/CLAUDE.md`
+  — the existing format-router and the `WaveformProfileService` derived-artifact seam; 18.1 lives here.
+- `DeepDrftPublic/Interop/audio/IFormatDecoder.ts` — the strategy interface `OpusFormatDecoder`
+  implements; `FlacFormatDecoder.ts` is the nearest prior art (setup-bytes carry + frame-sync scan).
+- `DeepDrftPublic/Interop/audio/AudioPlayer.ts` (`createFormatDecoder`, lines 117–125) — the decoder
+  registry gaining the Opus arm.
+- `DeepDrftPublic.Client/Clients/TrackMediaClient.cs` + `DeepDrftPublic/Controllers/TrackProxyController.cs`
+  — the media fetch + proxy that thread the new `?format=` param (mirroring `offset`), and proxy the new
+  seek/setup sidecar fetch.
+- Root `CLAUDE.md` "Theming and dark mode" + `DarkModeService` (in `DeepDrftPublic`) + `DarkModeSettings`
+  (`DeepDrftPublic.Client.Common`) — the cookie → prerender-read → `PersistentComponentState` → client
+  cookie-service seam the **streaming-quality preference** (§4a) mirrors exactly; the eventual dark-mode-
+  into-the-Settings-menu migration consolidates two copies of this seam.
+- `DeepDrftPublic.Client` `NowPlayingStats.razor` / `StatsClient` — the `PersistentComponentState`
+  prerender-bridge precedent (prerender fetch carried into WASM without a re-fetch/flash), the pattern the
+  quality preference's bridge follows; see the `tracksview-persistent-state-seam` auto-memory.
+
+## Sources
+
+- Ogg Opus support in `decodeAudioData`: Chrome/Firefox long-standing; Safari added Ogg-Opus at 18.4
+  (macOS 15.4 / iOS 18.4, March 2025) — prior Safari decoded Opus only in CAF.
+  https://chromestatus.com/feature/5649634416394240 ;
+  https://www.testmuai.com/learning-hub/opus-audio-codec-browser-support/
@@ -0,0 +1,383 @@
+# Phase 21 — Windowed Streaming Buffer (bounded client memory for long streams)
+
+Product spec. Status: **design / framing — implementation-ready pending Daniel's open-question calls.**
+Author: product-designer. Date: 2026-06-23. **No code has been written by this doc.**
+Surface: **public listener site only** (`DeepDrftPublic.Client` player stack + `DeepDrftPublic`
+TypeScript audio interop). No CMS (`DeepDrftManager`) change. No data-model or schema change. The one
+server touch is **reuse, not new surface**: the existing `DeepDrftAPI` HTTP `Range: bytes=X-`
+partial-content primitive (Phase 4, landed) is the load-bearing dependency; this phase adds no new API
+endpoint.
+
+> **Sequencing dependency (Daniel, 2026-06-23): Phase 18 (Opus Low-Data Streaming) comes BEFORE this
+> phase.** Format support — specifically the derived **Ogg Opus fullband 320** low-data delivery path
+> (`product-notes/phase-18-opus-low-data-streaming.md`) — is a prerequisite that sequences ahead of
+> windowing. Phase 21's windowing must work across **both** delivery formats (lossless WAV and Opus).
+> Its C5 invariant below already anticipated this ("must not foreclose MP3/FLAC"); **Opus is now the
+> concrete VBR/containerized driver of C5.** Windowing an Opus stream uses the decoder's **accurate
+> index-based** byte↔time mapping (`OpusFormatDecoder.calculateByteOffset` — a binary search in the Phase 18
+> precomputed seek index), exactly the C5 case — *not* the exact CBR-WAV `byteRate` math, and *not*
+> approximate Ogg-page interpolation. **Correction (Daniel, 2026-06-23):** an earlier draft described the
+> Opus mapping as "approximate page interpolation"; the Phase 18 seek-model resolution rejected that — Opus
+> seeking is **accurate**, backed by a precomputed seek index built at transcode time, so refill resolves to
+> the *exact* page offset. The windowed refill controller calls the **same** index resolver an explicit seek
+> does (Phase 18 §3.4a D); a window opening away from byte 0 still decodes via the Phase 18 sidecar setup
+> header. Build the window machinery format-agnostically (§2 C3/C5) so it inherits Opus for free.
+
+---
+
+## 1. Goal
+
+Bound the **client memory** a playing track consumes to a small, configurable forward window —
+**independent of total stream length** — so a 1 GB+ DJ MIX (Phase 9 `Mix` medium: a single long track)
+plays without the whole decoded PCM accumulating in the browser.
+
+**The defect, stated precisely.** The network path already streams in adaptive 16–64 KB chunks
+(`StreamingAudioPlayerService.StreamAudioWithEarlyPlayback`) — that part is fine. The accumulation is on
+the **decode side**: `PlaybackScheduler` holds `private buffers: AudioBuffer[]` and **never evicts**
+("Supports pause/resume/seek by **retaining all buffers**" — its own doc comment). Every 64 KB segment
+the `StreamDecoder` decodes is pushed via `addBuffer()` and kept for the life of the track. Decoded PCM
+is **larger than the compressed-or-raw source** in memory (Web Audio `AudioBuffer` is 32-bit float per
+sample per channel — a 16-bit stereo WAV roughly **doubles** in size once decoded), so a 1 GB WAV becomes
+~2 GB of retained `AudioBuffer` float data. That is the OOM.
+
+**One-line framing:** today the player decodes the whole track into memory and keeps it; Phase 21 makes
+it keep only a sliding forward window and discard what has already played, refilling on demand from the
+Range primitive it already uses for seek.
+
+---
+
+## 2. Constraints / invariants (the contract that must hold)
+
+These are non-negotiable. The §3.5 streaming seam (root `CLAUDE.md` "Streaming-first audio playback";
+`CONTEXT.md §3.5`) is called *the most architecturally load-bearing part of the playback path* by both
+docs. This phase **modifies that seam** — so the contract it must preserve is spelled out here.
+
+- **C1 — The seek-beyond-buffer Range path is the substrate, kept intact.** Phase 4 landed HTTP
+  `Range: bytes={offset}-` → `206 Partial Content` end to end (client `TrackMediaClient` →
+  `DeepDrftPublic` proxy → `DeepDrftAPI`), and `StreamDecoder.reinitializeForRangeContinuation` retains
+  the parsed format header on a continuation body (no re-parse). Windowed refill is a **generalization of
+  this exact path** (§3.1) — it must not require a second, divergent fetch mechanism.
+- **C2 — Playback start latency unchanged.** Today playback starts as soon as a configurable minimum
+  buffer count is queued (header-derived duration, not full-file). The window model must keep first-audio
+  latency at parity — bounding memory must not reintroduce a fetch-then-play stall.
+- **C3 — The format-decoder abstraction is untouched.** `IFormatDecoder` owns all format-specific
+  byte math; `AudioPlayer.createFormatDecoder` already dispatches on `Content-Type` (WAV/MP3/FLAC
+  decoders all wired today — verified 2026-06-23; an `OpusFormatDecoder` joins them in Phase 18).
+  Windowing lives in the
+  **format-agnostic** layer (`PlaybackScheduler` eviction + `StreamDecoder`/player refill
+  orchestration); it must add **no** format-specific branches. A future wired MP3/FLAC decoder inherits
+  windowing for free.
+- **C4 — Read-only playback only.** This is a memory-management change, not a UX change. No new
+  user-visible control, no change to seek/transport semantics beyond what the listener already
+  experiences. Seek must still feel identical.
+- **C5 — Must window both delivery formats (WAV lossless AND Opus low-data).** Byte↔time mapping for
+  refill is exact and cheap for WAV (CBR: `byteRate` from the header). **Phase 18 (Opus) is sequenced
+  before this phase and is the concrete VBR driver here** — and its mapping is **also exact**, but by a
+  different mechanism: an Ogg Opus 320 stream has no linear time↔byte relationship, so
+  `OpusFormatDecoder.calculateByteOffset` resolves via a **precomputed seek index** (granule→byte, built at
+  transcode; Phase 18 §3.4a), a binary search that returns the exact page offset — **not** an approximate
+  page interpolation. (An earlier draft of this invariant said "approximate"; the Phase 18 seek-model
+  resolution, Daniel 2026-06-23, made Opus seeking accurate. Corrected here.) The window machinery must
+  express refill purely in terms of the decoder's existing `calculateByteOffset`, so the same code windows
+  WAV (via `byteRate`) and Opus (via the index) — **no WAV-special-cased offset math in the window layer**,
+  and no approximation for either. A window that opens away from byte 0 must also prepend the decoder's
+  retained/sidecar setup header (Phase 18 §3.4a B) — the format-agnostic refill path already routes
+  continuations through the decoder's header-carry, so this comes for free. (MP3/FLAC decoders are already
+  wired in the registry too — the registry dispatches on content-type today; an `OpusFormatDecoder` joins
+  them in Phase 18.)
+- **C6 — No regression to the single-instance JS decoder concurrency guarantees.** The current code is
+  careful that only one streaming loop touches the single JS `StreamDecoder` at a time
+  (`DrainActiveStreamingTaskAsync`, the `_streamingCancellation` identity dance). Windowed refill
+  introduces *more* mid-stream fetches; it must route through the **same** drain/cancellation discipline,
+  not around it.
+- **C7 — The Mix visualizer's data source is independent and must stay that way.** The Phase 10/12
+  WebGL2 lava visualizer renders from a **preprocessed high-res waveform datum** fetched per-track
+  (`GET api/track/{entryKey}/waveform/high-res`), **not** from live decoded PCM. Confirmed: evicting
+  played `AudioBuffer`s cannot starve the visualizer — it never read them. The window model is invisible
+  to the visualizer. (This is the canonical 1 GB case *and* the case that proves the eviction is safe.)
+
+---
+
+## 3. Architectural shape
+
+### 3.0 The mental model
+
+A track's audio is a byte range `[0, fileLength)` on disk. At any moment the listener is at playback
+position `P` (seconds → byte offset via the format decoder). The player should hold decoded
+`AudioBuffer`s only for a bounded window roughly `[P - back, P + ahead]`:
+
+- **forward fill (`ahead`)** — enough decoded lookahead that playback never starves (covers the existing
+  500 ms scheduler lookahead plus network jitter headroom);
+- **back-retain (`back`)** — a small amount of *already-played* audio kept so a short seek-back does not
+  trigger a network refetch;
+- **evict** — anything older than `P - back` is dropped (`AudioBuffer` references released → GC reclaims
+  the float data);
+- **refill** — when forward decoded lookahead drops below a low-water mark, fetch+decode more from the
+  current byte position; when the window's tail is evicted and the listener seeks back past it, refetch
+  that region via the Range primitive (the seek-beyond-buffer path, run *backwards*).
+
+This is a **ring/sliding-window buffer keyed on playback position**, driven by high/low-water marks —
+the standard bounded-producer/bounded-consumer pattern, transplanted onto the decode→schedule seam.
+
+### 3.1 Why this is a generalization of seek-beyond-buffer, not a new mechanism
+
+The seek-beyond-buffer path already does **every primitive** the window needs, just triggered manually
+and one-shot:
+
+| Window operation              | Existing seek-beyond-buffer machinery it reuses                                    |
+|-------------------------------|-----------------------------------------------------------------------------------|
+| Discard buffers, keep offset  | `PlaybackScheduler.clearForSeek()` + `setPlaybackOffset()` (clears buffers, retains the absolute-time anchor) |
+| Fetch from a byte offset      | `TrackMediaClient.GetTrackMedia(key, byteOffset)` → `Range: bytes=X-` → 206       |
+| Decode a header-less body     | `StreamDecoder.reinitializeForRangeContinuation(remainingByteLength)`              |
+| Map time → byte offset        | `StreamDecoder.calculateByteOffset()` → `IFormatDecoder.calculateByteOffset()`    |
+| Single-loop safety on refetch | `_streamingCancellation` swap + `DrainActiveStreamingTaskAsync()`                  |
+
+The difference is **eviction does not exist yet** (the scheduler only ever `clear()`s wholesale) and
+**refill is one-shot** (a seek, not a continuous low-water-triggered loop). So the new work is two
+seams: a *partial-evict* on the scheduler, and a *position-driven refill controller* on the player. The
+fetch/decode/offset plumbing is reused verbatim.
+
+### 3.2 The three candidate directions
+
+Per file convention the alternatives are recorded; the recommendation follows.
+
+**Direction A — Sliding window on the existing single forward stream (recommended).**
+Keep the current model where the C# loop reads one forward HTTP stream and pumps chunks into the JS
+decoder. Add two things: (1) `PlaybackScheduler` gains *partial eviction* — drop buffers whose
+absolute-time end is older than `P - back`, adjusting its index bookkeeping so `getCurrentPosition()`
+and scheduling stay correct against a buffer array that no longer starts at index 0; (2) a
+*back-pressure* signal — when forward decoded lookahead exceeds the high-water mark, the C# loop
+**pauses reading** the HTTP stream (stops calling `ReadAsync`) until playback drains it below low-water,
+then resumes. Memory is bounded by high-water + back-retain. Seek-back beyond the retained window falls
+through to the **existing** seek-beyond-buffer path unchanged.
+*Why recommended:* smallest change to the load-bearing seam; reuses the live forward stream (no extra
+connections in the common case); eviction and back-pressure are the only genuinely new mechanisms, and
+both are local (one to the scheduler, one to the read loop). Back-pressure via "stop reading the socket"
+is exactly how TCP flow control already wants to behave — pausing `ReadAsync` lets the kernel window
+close; we are not fighting the transport.
+
+**Direction B — Discrete window segments, each its own Range fetch.**
+Treat the file as fixed-size byte segments (e.g. 4 MB). Hold N decoded segments around `P`; fetch the
+next/previous segment via a fresh Range request as the window slides; discard the far segment. No live
+long-lived forward stream — every window is an independent 206.
+*Why not (default):* turns one connection into many short Range requests (more proxy hops through
+`DeepDrftPublic`, more server-side `WavOffsetService`-style header synthesis, more places a fetch can
+fail mid-stream — worsening the §1.6 error surface), and the byte↔time segment math must be exact at
+every boundary. It *is* the cleaner model for true random-access (and the better base if seeking-heavy
+usage dominates), so keep it as the fallback if Direction A's back-pressure proves leaky in practice.
+Borrowed prior art: HLS/DASH segment windows and the MSE `SourceBuffer.remove()` eviction model — this
+is how every production HTML5 adaptive player bounds memory. We are doing the hand-rolled equivalent
+because the stack is a bespoke Web Audio graph, not `<media>` + MSE.
+
+**Direction C — Adopt MediaSource Extensions (MSE) and let the browser manage the buffer.**
+Stop hand-rolling the decode→schedule graph for long tracks; feed the Range stream into a `SourceBuffer`
+and let the browser evict via its built-in quota + `remove()`. Memory management becomes the platform's
+problem.
+*Why not — RESOLVED, rejected (Daniel, 2026-06-23; see OQ5):* MSE does not accept raw WAV/PCM — it
+wants containerized formats (fragmented MP4/WebM, or MP3/AAC elementary streams). The entire bespoke
+visualizer/spectrum graph is wired to the Web Audio `AudioContext`, not a `<media>` element. Adopting
+MSE is a **rewrite of the playback substrate**, not a windowing change. It *looked* like the real
+long-term answer once compressed delivery arrived — but Daniel has decided compressed delivery
+(**Phase 18 Opus**) will feed the **same bespoke graph** via the `IFormatDecoder` seam, so the
+compressed-delivery move that would have justified MSE happens *without* surrendering the graph. **The
+bespoke graph is a deliberate long-term commitment; MSE is rejected.** Direction A is therefore the
+permanent destination, not a stopgap that MSE will retire. Recorded as considered-and-declined.
+
+### 3.3 Recommended direction: A, with B held as the documented fallback
+
+Direction A is the smallest coherent change that hits the headline (bounded memory under a 1 GB stream)
+while honoring C1–C7. It keeps the live forward stream, reuses the seek-beyond-buffer path for the only
+genuinely random-access case (seek-back past the retained tail), and isolates the two new mechanisms.
+**The final architecture and the exact eviction/back-pressure API are staff-engineer's call at
+implementation** (per file convention); this spec fixes the *shape* and the invariants, not the method
+signatures.
+
+### 3.4 SOLID / road-not-taken rationale
+
+- **SRP, preserved.** Eviction is a `PlaybackScheduler` concern (it already owns buffer storage); refill
+  orchestration is a player-service/`StreamDecoder` concern (they already own the fetch loop); byte↔time
+  math stays in `IFormatDecoder`. No responsibility crosses a boundary it does not already own.
+- **OCP, via C3/C5.** Windowing added in the format-agnostic layer means wiring MP3/FLAC later changes
+  zero window code. The window expresses refill through `calculateByteOffset` — the one seam the
+  decoders already implement.
+- **The seam stays single-writer (C6).** Every new refetch routes through the existing
+  cancellation/drain discipline, so "only one loop touches the JS decoder" remains true. This is the
+  rule most likely to be violated by a naive implementation and is called out as a hard invariant.
+- **Road not taken — eager full decode with a memory cap that just stops decoding.** Tempting (decode
+  until you hit a byte budget, then stop) but it breaks playback of long tracks past the cap entirely —
+  it bounds memory by *refusing to play the rest*, not by sliding. Rejected: it is a degradation, not a
+  feature.
+
+---
+
+## 4. Use cases
+
+- **UC1 — Play a 1 GB+ DJ MIX start to finish (the headline).** Memory stays bounded throughout; the
+  listener experiences continuous playback identical to a short track.
+- **UC2 — Seek forward within a long track.** Already handled by seek-beyond-buffer; under windowing the
+  forward seek clears the window and refills at the target — no behavior change, now with eviction so the
+  pre-seek region does not linger.
+- **UC3 — Seek back a few seconds.** Served from the back-retain window with **no** network refetch
+  (the reason `back` exists).
+- **UC4 — Seek back far, past the evicted tail.** Falls through to the existing seek-beyond-buffer Range
+  fetch, run toward an earlier offset. (Open question OQ2 — see §6.)
+- **UC5 — Pause a long track for a long time.** Memory stays at the bounded window size while paused (no
+  continued decode). On resume, forward fill restarts from the low-water trigger.
+- **UC6 — Mix detail page with the lava visualizer running.** Visualizer reads its preprocessed datum
+  (C7); windowing is invisible to it. Confirmed non-interaction.
+
+---
+
+## 5. Interaction with the deferred Phase 1 streaming features
+
+This phase touches the **same decoder/scheduler seam** as the deferred Phase 1.3/1.4/1.5 items and the
+1.6/1.7 robustness items. The interactions, explicitly:
+
+- **1.3 Preload / prefetch (deferred; preload half).** *Shares machinery, does not conflict — and should
+  be sequenced after.* Preload stages the **next track** into a second decoder instance during the
+  current track's tail; windowing bounds the **current track's** forward buffer. They are orthogonal
+  axes (next-track vs. current-track-window), but they compound the memory question: a naive preload of a
+  second 1 GB mix would reintroduce the OOM this phase fixes. **Recommendation: land windowing first**,
+  so that when preload arrives, the staged next-track decoder is *also* windowed by construction (it
+  inherits the bounded scheduler). Windowing makes preload *safe for long tracks*; without it, preload of
+  mixes is a memory hazard.
+- **1.4 Crossfade (deferred).** Needs two simultaneous `PlaybackScheduler` instances briefly overlapping.
+  Both would be windowed instances — the overlap doubles the *window* size momentarily, not the whole
+  track. Windowing makes crossfade between two long mixes affordable. No reordering needed; 1.4 still
+  gates on 1.3.
+- **1.5 Gapless (deferred).** Sample-accurate hand-off of the next track's first buffer at the current
+  track's last buffer. Windowing changes *which* buffers are retained but not the hand-off mechanism;
+  the only care point is that the current track's **final** window must not be evicted before the gapless
+  boundary is scheduled. A minor invariant for whoever builds 1.5, not a blocker. Note 1.5's existing
+  WAV-only caveat stands.
+- **1.6 Track-skip on error (deferred).** *Windowing enlarges the error surface — call this out.* Today
+  a fetch failure happens at load (one fetch) or at a user seek (one fetch). Windowed refill issues
+  **mid-stream** fetches the listener did not initiate; one of those can fail at byte 700 M of a 1 GB
+  mix. So Phase 21 should ship with at least the *cheap* half of 1.6: a mid-stream refill failure must
+  **surface a clear error and not wedge the player** (it must not leave playback "running" with a starved
+  scheduler — mirror the `playFromPosition` end-of-buffer recovery already in `PlaybackScheduler`). The
+  rich half (byte-scan to next valid frame) stays deferred. **Recommendation: fold the minimal refill-
+  failure handling into Phase 21's acceptance criteria** (AC6) rather than leaving it entirely to 1.6 —
+  it is created by this phase.
+- **1.7 Safari compatibility (deferred).** Windowing adds no new Safari-specific surface beyond what the
+  streaming path already has. The one adjacency: more frequent `AudioContext` activity during refill
+  should be checked against the older-Safari `webkitAudioContext` quirks when 1.7 is addressed — note it,
+  do not block on it.
+
+---
+
+## 6. Open questions for Daniel (genuine product decisions, not implementation detail)
+
+These are policy calls with user-visible or resource trade-offs — flagged rather than decided here.
+
+- **OQ1 — Window size policy.** What bounds the window — a **fixed byte/time budget** (e.g. "hold at
+  most ~30 s decoded ahead + ~10 s behind"), or a **configurable memory budget** (e.g. "≤ N MB of
+  decoded PCM") that derives the time window from the stream's byte rate? Recommend a **time-based
+  forward window + small time-based back-retain** as the primary knob (intuitive, format-portable), with
+  a hard **memory ceiling** as a secondary guard. The exact numbers are tunable post-landing; Daniel
+  picks the *policy axis*. `[Daniel decision]`
+- **OQ2 — Seek-back past the evicted window.** When the listener seeks back earlier than the retained
+  tail, we must refetch (the audio is gone). Acceptable to take the same brief re-buffer the forward
+  seek-beyond-buffer takes today? (Recommend yes — it is the symmetric case and listeners already accept
+  it forward.) Or should back-retain be generous enough that this is rare? `[Daniel decision]`
+- **OQ3 — Configurable total in-flight memory cap.** Should there be a single hard byte ceiling on total
+  decoded audio held by the player (a safety net independent of the window-size policy), exposed as a
+  config value? Recommend **yes, as a guard rail** even if the window policy is time-based — it is the
+  backstop that makes "1 GB stream never OOMs" a guarantee rather than a tuning hope. `[Daniel
+  decision]`
+- **OQ4 — Apply windowing to all tracks, or only long ones?** A 3-minute Cut decoded whole is ~30–60 MB
+  — harmless today. Windowing everything is simpler (one code path) but adds refill machinery to short
+  tracks that never needed it. Recommend **window everything** (one path, C6-safe, and short tracks
+  simply never hit a refill because they fit inside the forward window) — but Daniel may prefer a
+  size threshold. `[Daniel decision]`
+- **OQ5 — Is MSE (Direction C) the real destination? — RESOLVED: NO (Daniel, 2026-06-23).** **Do not
+  adopt MSE. The bespoke Web Audio decode→schedule graph stays — it is bespoke by deliberate choice, a
+  long-term commitment, not a stopgap.** Daniel's rationale: the player is intentionally a custom
+  graph, not an HTML `<media>` element; the compressed-delivery move that *would* have made MSE
+  tempting is being met instead by **Phase 18 (Opus low-data path)** feeding the **same bespoke graph**
+  through the `IFormatDecoder` seam — so compressed delivery arrives *without* surrendering the graph.
+  Consequence for this phase: Direction A (the hand-rolled sliding window) is the destination, not a
+  placeholder; invest in it as permanent machinery. It will window both the WAV and the Opus path
+  (the sequencing note at the top). Direction C is recorded as **considered and declined** per file
+  convention; kept visible so a future reader sees the road not taken and why.
+  `[RESOLVED — bespoke graph retained; MSE rejected]`
+
+---
+
+## 7. Acceptance criteria
+
+- **AC1 (headline) — Bounded memory under a 1 GB stream.** Playing a 1 GB+ WAV mix start to finish, the
+  browser tab's retained decoded-audio memory stays bounded to the configured window (not growing toward
+  ~2 GB). Verifiable via browser memory tooling: peak decoded-audio footprint is independent of track
+  length and tracks the window-size policy, not the file size.
+- **AC2 — Playback-start latency at parity (C2).** First-audio latency for a track is unchanged from
+  pre-windowing (within noise). Windowing does not introduce a fetch-then-play stall.
+- **AC3 — Continuous playback, no starvation.** A long mix plays edge to edge with no audible gaps,
+  underruns, or stalls under normal network conditions — the forward fill stays ahead of the playhead.
+- **AC4 — Seek-back within the window is instant (UC3).** A short backward seek into retained audio
+  produces no network request.
+- **AC5 — Seek (forward, and back past the window) still works (UC2/UC4).** Both resolve via the
+  existing Range path with the same behavior the listener sees today; the pre-seek region is evicted, not
+  retained.
+- **AC6 — A mid-stream refill failure degrades cleanly (the 1.6 adjacency).** A failed refill fetch
+  surfaces a clear user-visible error and leaves the player in a recoverable state (not a wedged
+  "playing" with a starved scheduler). It must not silently hang.
+- **AC7 — The Mix visualizer is unaffected (C7).** With the lava visualizer running on a long mix, the
+  visualizer renders identically (it reads the preprocessed datum, never the evicted buffers).
+- **AC8 — Single-decoder concurrency invariant holds (C6).** Under rapid seek + refill activity, no
+  interleaved `ProcessStreamingChunk` calls corrupt the single JS decoder (the existing drain/cancel
+  discipline still governs every fetch).
+
+---
+
+## 8. Wave decomposition
+
+Dependency shape: `21.1 → 21.2 → 21.3`, with `21.4` validating the whole. 21.1 is the cold-start
+prerequisite and the load-bearing change; the rest layer on it.
+
+- **21.1 — Partial eviction in `PlaybackScheduler` (cold-start; the load-bearing change).** Give the
+  scheduler the ability to drop already-played buffers and keep its position/index bookkeeping correct
+  against a buffer array that no longer begins at absolute time 0 (today `getCurrentPosition`,
+  `playFromPosition`, and the scheduling loop all assume `buffers[0]` is the track start). This is the
+  hardest correctness work in the phase — the time-anchor math must stay exact through eviction. No
+  refill yet; with eviction alone and the forward read loop unchanged, this is provably memory-bounded
+  for the *played* region. **Independent of the §6 open questions** — it can begin immediately; the
+  window *sizes* (OQ1/OQ3) are parameters fed in later. Settled and cold-start.
+- **21.2 — Back-pressure on the forward read loop (the bound on the *unplayed* region).** Make the C#
+  `StreamAudioWithEarlyPlayback` loop stop calling `ReadAsync` when forward decoded lookahead exceeds the
+  high-water mark, and resume below low-water. Together with 21.1, this bounds *both* the played and
+  unplayed sides — the full memory guarantee (AC1). Must route resume/pause through the existing
+  cancellation-safe single-loop discipline (C6). **Depends on 21.1** (eviction must exist so the drained
+  region is reclaimed, not merely un-read).
+- **21.3 — Seek-back-past-window refill (close the random-access case).** Wire UC4 — when a backward
+  seek lands earlier than the retained tail, refetch via the existing seek-beyond-buffer Range path
+  pointed at the earlier offset, and the minimal AC6 refill-failure handling. Mostly **reuse** of the
+  landed seek path; the new work is the trigger (window-miss detection) and the clean-failure path.
+  **Depends on 21.1 + 21.2** (needs the window boundaries they define).
+- **21.4 — Validation pass against the 1 GB target (acceptance).** Exercise AC1–AC8 against a real 1 GB+
+  mix: memory profiling (AC1), latency parity (AC2), edge-to-edge playback (AC3), the seek matrix
+  (AC4/AC5), induced refill failure (AC6), visualizer-running (AC7), and rapid-seek concurrency (AC8).
+  Largely test/measurement; any break is likely a tuning fix in the 21.1 anchor math or the 21.2
+  water-marks. **Depends on 21.1–21.3.**
+
+---
+
+## 9. Cross-references (read before implementing)
+
+- Root `CLAUDE.md` "Streaming-first audio playback" / `CONTEXT.md §3.5` — the seam this phase modifies;
+  the §2 invariants here restate its contract. Both flag it as the most load-bearing path.
+- `PLAN.md` Phase 4 (landed) / `COMPLETED.md` — the HTTP Range `bytes=X-` primitive this generalizes.
+- `PLAN.md` Phase 1.3 / 1.4 / 1.5 / 1.6 / 1.7 — the deferred decoder/scheduler-seam features; §5 above
+  reconciles each.
+- `PLAN.md` Phase 9 — defines the `Mix` medium (single long track), the canonical 1 GB case.
+- `PLAN.md` Phase 10 / `product-notes/phase-10-mix-visualizer-lava-reframe.md` /
+  `product-notes/phase-12-waveform-visualizer-generalization.md` — establishes the preprocessed
+  per-track high-res waveform datum; the basis for C7 (visualizer does not read live PCM).
+- `DeepDrftPublic/Interop/audio/PlaybackScheduler.ts` — owns the unbounded `buffers: AudioBuffer[]`;
+  21.1 lives here.
+- `DeepDrftPublic/Interop/audio/StreamDecoder.ts` — `reinitializeForRangeContinuation`,
+  `calculateByteOffset`; the refill substrate.
+- `DeepDrftPublic.Client/Services/StreamingAudioPlayerService.cs` — the C# forward read loop
+  (`StreamAudioWithEarlyPlayback`), the seek-beyond-buffer path (`SeekBeyondBuffer`), and the
+  cancellation/drain discipline (C6); 21.2/21.3 live here.
+- `DeepDrftPublic.Client/Clients/TrackMediaClient.cs` — the Range-capable media fetch reused by refill.
@@ -0,0 +1,439 @@
+# Phase 22 — SEO Metadata Component (parameterized head/meta injection, public site)
+
+Product spec. Status: **design / framing — implementation-ready pending Daniel's open-question calls.**
+Author: product-designer. Date: 2026-06-23. **No code has been written by this doc.**
+Surface: **public listener site only** (`DeepDrftPublic` ASP.NET Core host + `DeepDrftPublic.Client`
+Blazor WASM assembly). The CMS (`DeepDrftManager`) is an authenticated admin surface and is
+**explicitly out of scope** — it must not be touched, and admin pages should if anything carry
+`noindex`. No data-model or schema change. No new API endpoint (every value the component needs is
+already returned by the existing `TrackDto` / `ReleaseDto` / `HomeStatsDto` reads).
+
+---
+
+## 1. Goal
+
+Give every public page a **single, reusable, parameterized component** that emits the full modern-SEO
+head surface — standard meta, canonical, robots, Open Graph, Twitter Card, and schema.org JSON-LD —
+so crawlers and social unfurlers see correct, page-specific metadata **in the prerendered HTML**, with
+no per-page boilerplate and no double-maintenance.
+
+**One-line framing:** today each page hand-writes a bare `<PageTitle>` and nothing else; Phase 22
+replaces that with one `<SeoHead …>` component that a page configures with a handful of parameters (or
+a typed model), defaulting everything else from a site-wide config, and that renders the complete head
+surface server-side during prerender where crawlers can read it.
+
+### What exists today (the starting point — verified 2026-06-23)
+
+- `App.razor` (`DeepDrftPublic/Components/App.razor`) declares `<HeadOutlet @rendermode="InteractiveAuto" />`
+  in `<head>`, and a static `<head>` block with charset, viewport, `<base href="/">`, stylesheet links,
+  `<ImportMap />`, and a favicon. **No** `<meta name="description">`, **no** canonical, **no** OG/Twitter
+  tags, **no** JSON-LD. The only per-page head contribution anywhere is `<PageTitle>`.
+- Pages set titles ad hoc: `Home.razor` → `<PageTitle>Deep DRFT - Electronic Music Collective</PageTitle>`;
+  `CutDetail.razor` → `<PageTitle>@(ViewModel.Release?.Title ?? "Cut") - DeepDrft</PageTitle>`. No shared
+  title-composition convention — the suffix (" - DeepDrft" vs " - Electronic Music Collective") is
+  already inconsistent.
+- `<html lang="en">` is set once in `App.razor`.
+- Detail pages (`CutDetail`, `SessionDetail`, `MixDetail`) inherit base classes (`ReleaseDetailBase` /
+  `CutDetailBase`) that load a `ReleaseDto` into a ViewModel in `OnParametersSetAsync` (not
+  `OnInitialized` — the documented same-template-nav reuse rule), and bridge the prerender fetch across
+  the WASM seam with `PersistentComponentState`. **This is the key fact for render-mode correctness
+  (§5):** the release data is already resolved during prerender, so the SEO tags it feeds can be too.
+- Canonical URL composition already exists for releases: `ReleaseRoutes.DetailHref(entryKey, medium)` →
+  `/cuts/{key}` | `/sessions/{key}` | `/mixes/{key}`. `SharePopover` already builds absolute share URLs
+  from this; the SEO canonical tag is the same URL, absolutized.
+- Cover art resolves to `api/image/{Uri.EscapeDataString(release.ImagePath)}` — the OG image source.
+
+### Why now / why it matters
+
+A public music catalogue lives or dies on discoverability and on how its links unfurl in iMessage,
+Discord, X, and search results. Right now a shared `/mixes/{key}` link unfurls as a bare title and a
+URL — no description, no cover image, no rich card. Search engines see a title and an empty description.
+The share affordance (Phase 16/17) is already a first-class feature; SEO/OG metadata is the missing
+half of "this link is worth sharing."
+
+---
+
+## 2. Constraints / invariants (the contract that must hold)
+
+- **C1 — Public site only.** Zero changes to `DeepDrftManager`. The component, its config, and its
+  registration all live in the public host + client. If anything, the CMS should later emit `noindex`
+  (noted as an adjacent concern in §7, not specified here).
+- **C2 — Tags must be present at prerender time, not after WASM boot.** Crawlers and unfurlers read the
+  server-rendered HTML and (mostly) do not execute the WASM runtime. The component must contribute its
+  head content during the **server prerender pass**. This is the single most load-bearing correctness
+  requirement and is detailed in §5. It governs *where the data comes from* (must be resolvable during
+  prerender) and *how the component renders* (via `<HeadContent>` into the existing `<HeadOutlet>`).
+- **C3 — One component, parameterized — DRY.** A page supplies only its own specifics; everything else
+  defaults from a site-wide config. No page re-declares the boilerplate set of ~15 tags. Adding a new
+  page type means passing a model, not copy-pasting a head block.
+- **C4 — SOLID seam.** The component renders; it does not fetch. Page-level data (the `ReleaseDto`, the
+  home stats) is already loaded by the page's ViewModel — the SEO component is **presentational**, fed
+  by parameters, exactly like `ReleaseHeroOverlay` / `ReleaseDescription` / `NowShowingPanel`. Defaults
+  come from an injected config object, not from a data fetch inside the component.
+- **C5 — No new fetch path, no new endpoint, no schema change.** Every value is already available:
+  `ReleaseDto` carries `Title`, `Artist`, `Genre`, `ReleaseDate`, `Description`, `ImagePath`, `EntryKey`,
+  `Medium`; `HomeStatsDto` backs the home page; the About page is static editorial. If a desired tag has
+  no source datum, it is either omitted or filled from config — **never** a reason to add a column.
+- **C6 — Graceful partial data.** A release with no `Description`, no `ImagePath`, or no `Genre` must
+  still emit a valid, complete-as-possible head (fall back to config defaults; omit truly optional tags
+  rather than emit empty ones — mirror `ReleaseDescription`'s "null description renders nothing" rule).
+- **C7 — Valid, non-duplicated output.** Exactly one `<title>`, one canonical, one OG block, one JSON-LD
+  script per page. `<PageTitle>` and the SEO component must not both emit a title — the component owns
+  the title (it composes `PageTitle` internally) so there is one source of truth. (See OQ4.)
+
+---
+
+## 3. Metadata surface (what the component emits)
+
+The full modern set, grouped. Each row notes its **source** (page param / config default / derived) and
+whether it is **always** emitted or **conditional**.
+
+### 3.1 Standard / search
+
+| Tag | Source | Emit |
+|-----|--------|------|
+| `<title>` | page (composed with config site-name suffix) | always |
+| `<meta name="description">` | page; falls back to config default description | always |
+| `<link rel="canonical" href>` | derived: config base URL + current path (releases via `ReleaseRoutes`) | always |
+| `<meta name="robots">` | config default (`index,follow`); page may override (e.g. `noindex` on `/404`) | always |
+| `<meta name="author">` / `<meta name="application-name">` | config (`Deep DRFT`) | optional |
+
+### 3.2 Open Graph (link unfurling — Facebook/iMessage/Discord/Slack)
+
+| Tag | Source | Emit |
+|-----|--------|------|
+| `og:title` | page (defaults to `<title>` sans suffix) | always |
+| `og:description` | page (defaults to meta description) | always |
+| `og:url` | = canonical | always |
+| `og:type` | page (`website` default; `music.album` / `music.song` for releases — see §4) | always |
+| `og:site_name` | config (`Deep DRFT`) | always |
+| `og:image` | page (release cover → absolute `…/api/image/{path}`); falls back to config default OG image | always (default guarantees presence) |
+| `og:image:alt` | page (e.g. `"{Title} cover art"`) | conditional (when image present) |
+| `og:locale` | config (`en_US`) | optional |
+| Music-vertical OG (`music:musician`, `music:release_date`, `music:duration`) | release params | conditional (release pages only) |
+
+### 3.3 Twitter Card
+
+| Tag | Source | Emit |
+|-----|--------|------|
+| `twitter:card` | config (`summary_large_image` when an image exists, else `summary`) | always |
+| `twitter:title` / `twitter:description` | mirror OG | always |
+| `twitter:image` | mirror `og:image` | always |
+| `twitter:site` / `twitter:creator` | config (the collective's handle, if any) | optional — **OQ3** |
+
+### 3.4 JSON-LD structured data (schema.org)
+
+One `<script type="application/ld+json">` per page, shaped by page type. This is where the music domain
+gets expressed richly (cuts/sessions/mixes map to schema.org music types):
+
+- **Site-wide / home** — `MusicGroup` (the Deep DRFT collective): `name`, `url`, `genre`, `description`,
+  `logo`, optional `sameAs` (social links — **OQ3**). Optionally a `WebSite` node with `potentialAction`
+  search (only if a public search surface exists — it does not today; defer).
+- **Cut detail** (`/cuts/{key}`, a studio release, possibly multi-track) — `MusicAlbum`:
+  `name`=Title, `byArtist`→`MusicGroup`, `albumProductionType` ≈ `StudioAlbum`, `datePublished`=ReleaseDate,
+  `genre`, `image`=cover, `url`=canonical, and `track`→ ordered list of `MusicRecording` (the album's
+  tracks; the page already holds `ViewModel.Tracks` in `TrackNumber` order).
+- **Session detail** (`/sessions/{key}`, a live release) — `MusicAlbum` with `albumProductionType` ≈
+  `LiveAlbum` (schema.org has `LiveAlbum`), or a `MusicEvent`/`MusicRecording` hybrid. **Recommend
+  `MusicAlbum`+`LiveAlbum`** for parity with cuts and because the catalogue treats a session as a
+  release, not a calendar event. (Revisit if a live *schedule* page lands — see §7.)
+- **Mix detail** (`/mixes/{key}`, a single long continuous track) — `MusicRecording` (one recording,
+  not an album): `name`, `byArtist`, `duration` (ISO-8601 from `DurationSeconds`), `genre`, `image`,
+  `url`. A mix is the cleanest single-`MusicRecording` case.
+- **About** (`/about`) — `AboutPage` referencing the `MusicGroup`, or simply the `MusicGroup` node again
+  with the editorial bio as `description`.
+- **Browse pages** (`/cuts`, `/sessions`, `/mixes`, `/archive`) — `CollectionPage`, optionally with an
+  `ItemList` of the releases shown. Lighter touch; the detail pages carry the rich per-release schema.
+
+> JSON-LD is the highest-leverage, music-specific part of this spec and the part most worth getting
+> right. It is also the part with the most modeling latitude — the exact node shapes above are a
+> **recommendation**; the precise schema.org property set is a refinement staff-engineer can tune
+> against Google's Rich Results test (see §8 AC5). The spec fixes *which schema type maps to which
+> medium* (the product decision) and leaves property-level polish to implementation.
+
+---
+
+## 4. Component design (the contract)
+
+### 4.1 Shape: one component + a typed model + a config
+
+Three pieces, each a clean SOLID responsibility:
+
+1. **`SeoHead.razor`** — the single reusable presentational component. Lives in `DeepDrftPublic.Client`
+   (it must render in the WASM-shared component graph so it works in both prerender and interactive
+   passes — see §5). Renders a `<PageTitle>` and a `<HeadContent>` block containing all of §3. Owns no
+   data fetch and no business logic. Parameterized over a model (below). It reads the injected
+   `SeoOptions` for defaults and `NavigationManager` for the current absolute URL (canonical/`og:url`).
+
+2. **`SeoModel`** (a record/class in `Common/`) — the typed per-page input. Rather than ~15 loose
+   `[Parameter]`s, the page hands `SeoHead` one model. Suggested surface:
+   - `Title` (string, required) — page title sans site suffix.
+   - `Description` (string?) — falls back to `SeoOptions.DefaultDescription`.
+   - `CanonicalPath` (string?) — defaults to `NavigationManager`'s current relative path; release pages
+     pass `ReleaseRoutes.DetailHref(...)` so the canonical is stable regardless of alias routes
+     (`/tracks/...` redirects, query strings).
+   - `ImagePath` (string?) — relative cover path; component absolutizes to `…/api/image/{escaped}`;
+     falls back to `SeoOptions.DefaultImageUrl`.
+   - `OgType` (enum/string, default `Website`).
+   - `Robots` (string?, default from config `index,follow`).
+   - `JsonLd` (a `RenderFragment` **or** a typed structured-data object) — the page supplies its
+     schema.org node; see 4.3 for the build-vs-pass decision (OQ5).
+   - Music-specific optionals used only by release pages: `Artist`, `Genre`, `ReleaseDate`,
+     `DurationSeconds`, and (for albums) the ordered track list.
+
+   A small set of **named factory helpers** keeps call sites terse and DRY — e.g.
+   `SeoModel.ForRelease(ReleaseDto, tracks?)`, `SeoModel.ForHome(HomeStatsDto)`, `SeoModel.ForAbout()`,
+   `SeoModel.ForBrowse(medium)`. Each factory encodes the medium→`OgType`→JSON-LD mapping from §3.4 in
+   exactly one place (DRY: a page never re-derives "a mix is a `MusicRecording`"). These factories are
+   pure functions over DTOs the page already holds — unit-testable without rendering.
+
+3. **`SeoOptions`** (config, in `Common/`) — site-wide defaults: `SiteName` (`Deep DRFT`),
+   `TitleSuffix`, `DefaultDescription`, `BaseUrl` (the canonical production origin — **OQ1**),
+   `DefaultImageUrl`, `TwitterSite`/`TwitterCreator` (**OQ3**), `DefaultRobots`, `Locale`, `Genre`,
+   social `sameAs` links (**OQ3**). Registered in `Startup.ConfigureDomainServices` (the existing seam
+   that runs in **both** server and WASM `Program.cs`, per the project's static-Startup convention).
+   Source values from `appsettings.json` server-side; the WASM pass either hardcodes the same constants
+   or receives them via the existing config seam. **Note:** these are non-secret brand constants — they
+   belong in `appsettings.json` / a constants class, not `environment/` secrets.
+
+### 4.2 How pages supply their specifics (DRY in practice)
+
+- **Home** (`Home.razor`): `<SeoHead Model="SeoModel.ForHome(stats)" />` — replaces the current bare
+  `<PageTitle>`. Description from config or a curated home string; JSON-LD = `MusicGroup`.
+- **About** (`/about`): `<SeoHead Model="SeoModel.ForAbout()" />` — static; description = the bio
+  lede; JSON-LD = `MusicGroup`/`AboutPage`.
+- **Release detail** (`CutDetail`/`SessionDetail`/`MixDetail`): `<SeoHead Model="@_seo" />` where
+  `_seo = SeoModel.ForRelease(ViewModel.Release, ViewModel.Tracks)` — set once the release is resolved.
+  The factory reads `Medium` and picks `MusicAlbum` (cut/session) vs `MusicRecording` (mix), the
+  `og:type`, the canonical via `ReleaseRoutes`, and the cover image. **One call site, all 15+ tags.**
+- **Browse** (`AlbumsView`/`SessionsView`/`MixesView`/`ArchiveView`): `SeoModel.ForBrowse(medium)`.
+- **404** (`NotFound`): `SeoModel` with `Robots = "noindex,follow"`.
+
+Each page touches **one line**. The boilerplate lives in `SeoHead` + the factories; the per-page values
+flow in through the model. That is the DRY mechanism C3 demands.
+
+### 4.3 Build-vs-pass for JSON-LD (the one genuine design fork — OQ5)
+
+Two ways to produce the `<script type="application/ld+json">` body:
+
+- **(a) Typed builder:** `SeoModel` carries strongly-typed structured-data objects (small C# records
+  mirroring the schema.org nodes) that a serializer renders to JSON. **Pros:** type-safe, unit-testable,
+  DRY (the medium→type mapping is C# in the factories), no hand-written JSON in pages. **Cons:** a small
+  amount of schema.org-shaped record plumbing to build once.
+- **(b) RenderFragment / raw string:** the page hands `SeoHead` a pre-built JSON-LD fragment. **Pros:**
+  trivial component. **Cons:** pushes JSON authoring into pages (violates C3/DRY), easy to get invalid,
+  not testable.
+
+**Recommend (a)** — the typed builder. It is the only option that honors DRY (the medium→schema mapping
+must live in one place) and is testable (AC5 wants Rich-Results validity; pure builders make that a unit
+test, not a manual check). The record set is small (a `MusicGroup`, a `MusicAlbum` with a `track` list,
+a `MusicRecording`) and confined to `Common/`. **This is the load-bearing implementation choice and is
+recorded as OQ5 for Daniel to confirm.**
+
+### 4.4 SOLID / road-not-taken rationale
+
+- **SRP:** `SeoHead` renders; `SeoModel` factories map DTOs→SEO shape; `SeoOptions` holds defaults;
+  pages fetch (already do). No responsibility crosses a boundary it does not already own — identical to
+  the `ReleaseHeroOverlay`/`ReleaseDescription` presentational-component pattern already in the codebase.
+- **OCP:** a new page type or a fourth medium adds a factory method, not a new tag block. The medium
+  switch lives next to `ReleaseRoutes`' existing medium switch (same "Cut is the default arm so a gap is
+  build-visible" discipline).
+- **DRY:** the ~15-tag boilerplate exists once. Pages pass values; the suffix inconsistency observed
+  today (`- DeepDrft` vs `- Electronic Music Collective`) is resolved by `SeoOptions.TitleSuffix`.
+- **Road not taken — a server-side middleware/filter that rewrites `<head>`.** Tempting (one place,
+  zero component change) but it cannot see Blazor's per-page render state cleanly, fights the
+  `HeadOutlet` mechanism Blazor provides for exactly this, and would be a parallel metadata path the
+  team has to reason about separately. Rejected: use the framework's head seam, not an HTTP filter.
+- **Road not taken — per-page hand-written `<HeadContent>` blocks (no shared component).** This is just
+  the status quo extended; it is the boilerplate-duplication C3 forbids. Rejected.
+
+---
+
+## 5. Render-mode correctness (the load-bearing requirement — C2)
+
+This is the part most likely to be got subtly wrong, so it is spelled out.
+
+**The mechanism.** Blazor's `<HeadContent>` projects child content into the `<HeadOutlet>` declared in
+`App.razor`. During the **server prerender pass**, components render to HTML server-side *before* WASM
+boots; their `<HeadContent>` is written into the `<head>` of the delivered document. A crawler fetching
+the page sees the fully-populated `<head>` in the initial HTML response — exactly what C2 requires —
+**provided the data the head depends on is available during that prerender pass.**
+
+**Why this works here (the key enabler).** The release detail pages already resolve their `ReleaseDto`
+during prerender and bridge it across the WASM seam via `PersistentComponentState` (documented in
+`DeepDrftPublic.Client/CLAUDE.md` and the `tracksview-persistent-state-seam` memory). The SEO data is a
+**projection of that same already-prerendered DTO.** So `SeoHead`, fed by the page's ViewModel, emits
+correct tags during prerender with **no new fetch and no new bridge** — it rides the one the page
+already has. This is why the component must be presentational and parameter-fed (C4): it inherits the
+page's prerender-readiness for free.
+
+**The render-mode flags to get right:**
+
+- `<HeadOutlet>` in `App.razor` is currently `@rendermode="InteractiveAuto"`. The **prerender** of that
+  outlet still happens server-side (Auto prerenders on the server first), so prerendered head content is
+  emitted. **Confirm during implementation** that prerender is not disabled for these pages — if any SEO
+  page were ever set `prerender: false` (as `BatchUpload` in the CMS is), its head would be empty for
+  crawlers. None of the public SEO-target pages disable prerender today; the spec's requirement is that
+  they must not.
+- **`SeoHead` lives in `DeepDrftPublic.Client`** so it participates in both the server-prerender render
+  tree and the WASM interactive render tree (the project's "static Startup called from both Program.cs"
+  convention guarantees identical DI in both passes). Putting it only in the server host would break the
+  interactive pass; putting it only in the client without prerender would break crawlers.
+
+**The risk to flag — the `InteractiveAuto`/WASM boundary and double-render.** On an Auto page the head
+is rendered **twice**: once server-side (prerender, what crawlers see) and again when the component
+re-renders client-side after WASM boot. Two cautions:
+
+1. **Idempotent, identical output across passes.** The tags the WASM pass produces must match the
+   prerender pass (same canonical, same OG, same JSON-LD), or the client re-render will replace correct
+   tags with different ones. Because the data is bridged via `PersistentComponentState` (not re-fetched),
+   the two passes see the same `ReleaseDto` and produce identical head content — **as long as the model
+   is built from the bridged state, not a fresh client fetch.** Guard the same way detail pages already
+   guard their restore: on id/key equality, to prevent cross-item bleed when prerender and WASM-boot
+   disagree on the current item (the documented `OnParametersSetAsync` rule).
+2. **Canonical/`og:url` absolutization must not depend on a browser-only API.** During server prerender
+   there is no `window.location`; the absolute base must come from `SeoOptions.BaseUrl` (config), not
+   from JS interop. `NavigationManager` is available server-side for the *path*; the *origin* comes from
+   config (this is also why `BaseUrl` is OQ1 — the canonical origin is a product decision, not
+   discoverable at prerender from the request reliably behind the nginx proxy).
+
+**Net:** the approach emits correct tags server-side at prerender because it projects already-prerendered
+data through the framework's own head seam. The only genuinely new care points are (1) identical
+output across the double render, solved by feeding from bridged state, and (2) config-sourced origin for
+absolute URLs, solved by `SeoOptions.BaseUrl`.
+
+---
+
+## 6. Use cases
+
+- **UC1 — A `/mixes/{key}` link pasted into Discord/iMessage unfurls richly.** Title, description, and
+  cover image appear in the unfurl card (OG tags present at prerender). Today: bare title + URL.
+- **UC2 — Google indexes a cut with structured data.** The `MusicAlbum` JSON-LD with its `track` list is
+  eligible for rich results; canonical points at `/cuts/{key}` regardless of how the user arrived
+  (alias `/tracks/...` route, query params).
+- **UC3 — The home page presents the collective.** `MusicGroup` JSON-LD + site-level OG so the root URL
+  unfurls and is indexed as the band's entity.
+- **UC4 — A release with no cover / no description still has valid metadata.** Falls back to the config
+  default OG image and default description; omits `og:image:alt`; emits valid (if leaner) tags (C6).
+- **UC5 — The 404 page is not indexed.** `NotFound` passes `Robots = "noindex,follow"`.
+- **UC6 — Twitter/X card renders large-image.** `summary_large_image` when a cover exists, `summary`
+  otherwise.
+
+---
+
+## 7. Open questions for Daniel (product calls, not implementation detail)
+
+- **OQ1 — Canonical production origin (`BaseUrl`).** What is the canonical public origin for absolute
+  canonical/`og:url`/`og:image` URLs (e.g. `https://deepdrft.com`)? This must be a fixed config value —
+  it cannot be reliably derived at prerender behind the nginx reverse proxy, and getting it wrong
+  silently breaks every absolute URL an unfurler resolves. **Also:** is there a single canonical host, or
+  do www/apex/staging variants need a canonical-host normalization rule? `[Daniel decision]`
+- **OQ2 — Default OG image.** What is the fallback share image for pages without a cover (home, about,
+  browse, and cover-less releases)? A branded 1200×630 card is the OG standard. Is there an existing
+  brand asset to use, or does one need to be produced? Until one exists, the component can omit
+  `og:image` (degrades to a `summary` Twitter card) — but a default image materially improves every
+  unfurl. `[Daniel decision — and an asset to point at]`
+- **OQ3 — Social handles / `sameAs`.** Does Deep DRFT have public social accounts (X/Twitter handle for
+  `twitter:site`/`creator`, and URLs for the `MusicGroup.sameAs` array)? If yes, supply them for the
+  config; if no, those tags are simply omitted (valid). `[Daniel decision]`
+- **OQ4 — Title suffix + composition.** Standardize the title pattern: recommend `"{PageTitle} · Deep
+  DRFT"` (or `" - Deep DRFT"`), with the home page as a special case (`"Deep DRFT — Electronic Music
+  Collective"`). Confirm the suffix string and separator; this resolves the existing inconsistency
+  (`- DeepDrft` vs `- Electronic Music Collective`). `[Daniel decision — low stakes, pick one]`
+- **OQ5 — JSON-LD: typed builder vs. passed fragment (§4.3).** Recommend the **typed builder** (option a)
+  for DRY + testability. Confirm, or accept the lighter passed-fragment approach if the record plumbing
+  is judged not worth it. `[Daniel decision — recommendation: typed builder]`
+- **OQ6 — Session schema type.** Recommend modeling a Session as `MusicAlbum` + `LiveAlbum`
+  `albumProductionType` (parity with cuts; the catalogue treats a session as a release, not an event).
+  Confirm — or, if a live *schedule* surface is ever planned, a session might better be a `MusicEvent`.
+  `[Daniel decision — recommendation: MusicAlbum/LiveAlbum for now]`
+
+### Adjacent but separate concerns (flagged, not specified here)
+
+These are SEO-adjacent and worth their own small follow-ups; they are **not** in this component's scope:
+
+- **`robots.txt`** — a static file (or a minimal endpoint) at the public host root: allow crawl, point at
+  the sitemap, and **disallow the CMS host** (`DeepDrftManager` is a separate app/host — its exclusion is
+  a deployment/robots concern, not a CMS code change). Small, separate task.
+- **`sitemap.xml`** — a generated sitemap enumerating home/about/browse + every release detail URL. This
+  *does* need a small server-side endpoint on the public host that lists releases (reusing the existing
+  paged release read — no new data) and emits XML. A natural Phase 22.x follow-on, but a different unit
+  of work (an endpoint, not a component). Flag for Daniel: **want this folded into Phase 22 as a second
+  wave, or tracked as its own phase?**
+- **CMS `noindex`** — ensuring `DeepDrftManager` pages are not indexed. Out of scope for this public-site
+  component (C1); noted so it is not forgotten. Cheapest fix is a robots disallow on the CMS host +/- a
+  blanket `noindex` meta in the CMS layout — a CMS-side change for a later, separately-scoped task.
+
+---
+
+## 8. Acceptance criteria
+
+- **AC1 — Tags present in prerendered HTML.** `curl`-ing (no JS execution) any public SEO-target page
+  returns a `<head>` containing title, description, canonical, the full OG block, the Twitter block, and
+  a JSON-LD script — populated with that page's specifics. (The crawler-visibility guarantee, C2.)
+- **AC2 — One component, one line per page.** Each target page invokes `SeoHead` with a single model;
+  no page hand-writes the tag set. Adding a hypothetical new page type requires a new factory method,
+  not a new tag block (C3/OCP).
+- **AC3 — Release pages carry correct per-medium schema.** A cut → `MusicAlbum` with an ordered `track`
+  list; a session → `MusicAlbum`/`LiveAlbum`; a mix → `MusicRecording` with ISO-8601 `duration`. Title,
+  artist, genre, date, cover, and canonical all match the release.
+- **AC4 — Graceful partial data.** A release with no description/cover/genre still emits valid head
+  content (config-default description, config-default or omitted image, omitted optional tags) — no empty
+  `content=""` tags, no broken JSON-LD (C6).
+- **AC5 — Structured data validates.** The emitted JSON-LD passes Google's Rich Results / Schema Markup
+  Validator for the chosen types (no errors; warnings acceptable). Pure-function builders make this a
+  unit test plus one manual validator pass.
+- **AC6 — Identical output across the double render.** The head content produced by the WASM interactive
+  pass is byte-identical to the prerender pass for the same page/item (fed from bridged
+  `PersistentComponentState`, not a fresh fetch) — no client re-render clobbering correct tags (§5).
+- **AC7 — Canonical correctness.** Canonical and `og:url` are absolute (config origin + resolved path),
+  point at the dedicated release route (not an alias/redirect path or a query-string variant), and are
+  identical to each other.
+- **AC8 — 404 is `noindex`.** The not-found page emits `robots: noindex`.
+- **AC9 — Zero CMS change.** No file under `DeepDrftManager` is touched (C1).
+
+---
+
+## 9. Wave decomposition
+
+Dependency shape: `22.1 → 22.2 → 22.3`, with `22.4` validating. `22.1` is the cold-start prerequisite.
+
+- **22.1 — Core component + config + model, on the simplest pages (cold-start).** Build `SeoHead`,
+  `SeoModel` (+ the standard/OG/Twitter tag rendering), and `SeoOptions` (registered via the static
+  `Startup` seam). Wire the **static pages first** — Home and About — where data is trivially available
+  at prerender and there is no double-render subtlety beyond the baseline. Proves §5's prerender
+  emission end to end (AC1) on the easy case. **Depends on OQ1/OQ2/OQ4** (origin, default image, suffix)
+  — these are config values it needs; can stub with placeholders and swap in Daniel's answers.
+- **22.2 — Release detail pages + per-medium JSON-LD (the rich case).** Add the `MusicGroup` /
+  `MusicAlbum` / `MusicRecording` builders (OQ5 recommendation: typed) and the `ForRelease` factory with
+  the medium→type mapping; wire `CutDetail`/`SessionDetail`/`MixDetail` from their already-bridged
+  `ReleaseDto`. This is where AC3/AC5/AC6/AC7 are exercised. **Depends on 22.1** and on OQ5/OQ6.
+- **22.3 — Browse + 404 + remaining pages.** `CollectionPage` for browse surfaces; `noindex` for 404;
+  any remaining public routes. **Depends on 22.1.**
+- **22.4 — Validation pass.** Exercise AC1–AC9: crawler-view via no-JS fetch (AC1), Rich Results
+  validator (AC5), double-render-identity check (AC6), canonical/alias matrix (AC7), partial-data
+  releases (AC4). Largely test/measurement. **Depends on 22.1–22.3.**
+- **(Adjacent, separate) — `robots.txt` + `sitemap.xml`.** Per §7, an endpoint-shaped follow-on, not a
+  component wave. Tracked as its own unit pending Daniel's call on folding-in vs. separate phase.
+
+---
+
+## 10. Cross-references (read before implementing)
+
+- `DeepDrftPublic/Components/App.razor` — the `<head>` block + `<HeadOutlet @rendermode="InteractiveAuto">`
+  this component feeds; the place to confirm prerender is not disabled.
+- `DeepDrftPublic.Client/CLAUDE.md` — the `PersistentComponentState` prerender-bridge convention, the
+  `OnParametersSetAsync` same-template-nav rule, the static-`Startup`-called-from-both-`Program.cs`
+  DI convention (where `SeoOptions` registers), and the presentational-component pattern `SeoHead` follows.
+- Auto-memory `tracksview-persistent-state-seam` — why the bridge matters for the double-render identity
+  (AC6); the SEO model must be built from bridged state, not a fresh client fetch.
+- `DeepDrftPublic.Client/Common/ReleaseRoutes.cs` — the canonical-URL source for release pages; the SEO
+  canonical reuses it (and extends the same "Cut is the default arm" medium-switch discipline).
+- `DeepDrftPublic.Client/Pages/{Home,CutDetail,SessionDetail,MixDetail,About}.razor` — the current bare
+  `<PageTitle>` usage these pages replace; the ViewModels (`ReleaseDto`, `HomeStatsDto`) that feed the model.
+- `DeepDrftPublic.Client/Controls/SharePopover.razor` — already builds absolute share URLs from
+  `ReleaseRoutes`; the canonical/OG URL is the same absolutization, sourced from `SeoOptions.BaseUrl`.
+- `DeepDrftModels` (`ReleaseDto`, `TrackDto`, `HomeStatsDto`) — the data the model projects; no new field
+  needed (C5).
+- Google Rich Results / Schema.org `MusicGroup`/`MusicAlbum`/`MusicRecording`/`LiveAlbum` docs — the
+  validation target (AC5) and the type vocabulary for §3.4.
Author	SHA1	Message	Date
daniel-c-harvey	33383cd675	Merge p22-w2-jsonld-type-fix into dev Deploy DeepDrftPublic / Build & Publish (push) Successful in 4m20s Details Package install tarball / package (push) Successful in 6s Details Deploy DeepDrftPublic / Deploy (push) Successful in 1m25s Details Fix JSON-LD @type serialization: concrete nodes were emitting a bare Type alongside @type because the attribute sat only on the abstract base override. Validator now clean.	2026-06-23 06:57:44 -04:00
daniel-c-harvey	56f7013314	fix: put [JsonPropertyName("@type")] on each concrete JsonLdNode override System.Text.Json emitted both "@type" and a bare "Type" because the attribute was only on the abstract base member. Adds regression assertions for all node types.	2026-06-23 06:57:05 -04:00
daniel-c-harvey	2653e62eeb	docs: reflect Phase 22 SEO metadata component as landed	2026-06-23 06:21:52 -04:00
daniel-c-harvey	45bd599bdd	Merge p22-w1-seo-metadata-component into dev Phase 22: parameterized SEO metadata component for the public site — SeoHead + typed JSON-LD builders, per-medium release schema, env-gated noindex (beta uncrawled), inline-safe JSON-LD escaping.	2026-06-23 06:16:31 -04:00
daniel-c-harvey	f976af0f7c	fix(seo): escape inline JSON-LD, per-release byArtist, soft-404 + env-gated noindex Escape </>& in JSON-LD body to kill script-breakout; byArtist now uses the release artist; detail-page not-found branches emit noindex; default robots gated to Production via a PersistentState SeoEnvironment bridge.	2026-06-23 06:10:03 -04:00
daniel-c-harvey	f3b89ca9d7	feature: Phase 22 SEO metadata component for public site One presentational SeoHead renders the full OG/Twitter/JSON-LD head surface at prerender via typed schema.org builders. Per-medium release schema, config-sourced canonicals, 404 noindex. Zero CMS change.	2026-06-23 05:41:55 -04:00
daniel-c-harvey	8752fc0c98	docs: resolve Phase 18 OQ7 seek-index granularity to 0.5s buckets	2026-06-23 05:36:25 -04:00
daniel-c-harvey	274d0ace62	Merge install-prep-analysis: installer prompts for AuthBlocks:Email:From	2026-06-23 05:28:17 -04:00
daniel-c-harvey	e3a4364b8c	docs(plan): Phase 18 OQ resolutions + VBR-safe accurate Opus seek model	2026-06-23 05:26:58 -04:00
daniel-c-harvey	564b704803	fix(installer): prompt for and write AuthBlocks:Email:From Without this field, DeepDrftAPI throws InvalidOperationException on startup. Adds the EMAIL_FROM prompt after EMAIL_TOKEN, writes "From" into the Email JSON object, and unsets the variable on cleanup.	2026-06-23 05:26:48 -04:00
daniel-c-harvey	6af6677a12	docs: spec Phase 22 — parameterized SEO metadata component (public site)	2026-06-23 05:12:31 -04:00
daniel-c-harvey	1bdaeaa164	docs(plan): add Phase 18 Opus low-data streaming; resolve Phase 21 OQ5 (no MSE)	2026-06-23 04:58:21 -04:00
daniel-c-harvey	a84a99c309	docs: spec Phase 21 — windowed streaming buffer for bounded client memory	2026-06-23 00:14:44 -04:00