# 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.
