V1 Web PWA · Surface walkthrough

Lilith Studio · Saraswati track generation

A per-surface walkthrough of the V1 Web PWA customer surface: layout, states, interactions, data, and cross-references.

walked
8sections3 minread
Markdown source
On this page

Context. surface customer · domain lilith · route /lilith-studio/music · auth signed-in + role:v1_editorial_producer (default) · source apps/oshun/web/src/app/lilith-studio/music/page.tsx

Last walked. 2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data (2xx), console/page-errors, expected content, screenshot verified; live screen-reader, touch, offline, and telemetry-delivery checks pending a manual AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; content re-verified 2026-06-03 against current source

Purpose#

Submit a rights-complete track-generation job to Saraswati and move the generated result into V1 review with model, prompt, royalty, and remix provenance attached. The page (apps/oshun/web/src/app/lilith-studio/music/page.tsx) returns <LilithMusicAuthoring /> directly; the <ShellLayout active="studio"> wrapper and the editorial scope gate are supplied by the route's apps/oshun/web/src/app/lilith-studio/layout.tsx.

Entry points#

  • Lilith Studio shell (/lilith-studio) — "Music authoring" surface tab → "Open Music authoring" link
  • From concert pipeline (/lilith-studio/concerts) — "Music queue" link
  • Direct URL / bookmark — yes (signed-in)

Layout regions#

LilithMusicAuthoring (apps/oshun/web/src/app/lilith-studio/music/LilithMusicAuthoring.tsx):

  • Header: eyebrow "Lilith Studio / Music authoring", title "Saraswati track generation", lede, two header actions — "Lilith shell" → /lilith-studio, "Rights taxonomy" → /studio/hathor/journal-and-codex
  • Three-panel grid:
    • Pipeline trigger panel (aria-label="Saraswati pipeline trigger"):
      • Model <select> (data-lilith-music-model-select) — three options: Saraswati raga generator, Saraswati ambient bed, Saraswati kirtan sketch
      • Style preset <select> (data-lilith-music-style-select) — three options: Tara dawn raga / 72 BPM / D, Moon bowl ambient / 54 BPM / A, Festival kirtan / 96 BPM / G
      • Generation prompt textarea (data-lilith-music-prompt); default copy is a steady dawn practice description
      • Provenance strip — prov:lilith-music:job:<...> ID
    • Royalty-share editor panel (aria-label="Royalty-share editor"):
      • Three royalty <input type="number"> fields (data-lilith-music-royalty-share=<partyId>): Saraswati house composer (default 60%), Tara instructor (default 25%), Platform operations (default 15%)
      • Total readout — must equal 100 to be valid (data-lilith-music-rights-total, data-valid)
    • Remix rights + review queue panel (aria-label="Remix rights and review queue"):
      • Remix rights <select> (data-lilith-music-remix-rights) — three options: Editorial remix only, Allowed with attribution, Remix blocked
      • Readiness list (4 items): Generation prompt, Royalty shares, Remix rights, Review queue
      • "Generate track" release button (data-lilith-music-submit-job)
      • Queue status block (data-lilith-music-review-queue-status) — "Result entered review queue" / "Review queue pending"
  • Manifest panel (aria-label="Music provenance evidence") — kicker "Full provenance", title "Generation review bundle", state pill ("Queued" / "Draft"), manifest textarea (read-only, data-lilith-music-provenance-manifest)
  • LilithProvenanceInspector — surface ID music-authoring; lists models, styles, rights as provenance assets

States#

  • Loading — client component; data-hydrated="false" until mount
  • Default draft — model raga-v1, style tara-dawn-raga, prompt default, shares 60/25/15, rights editorial-only
  • Royalty total ≠ 100 — data-rights-valid="false"; Generate disabled
  • Royalty total = 100 — valid
  • Submit disabled — when !readiness.canSubmit
  • Submitted — jobState='review-queued', data-review-queue-state="queued"; review queue ID + generation job ID + track result ID populated
  • Any field changed after submit — resetJob() returns state to draft
  • Offline — client-only; works offline

Interactions#

  • "Lilith shell" link — href /lilith-studio
  • "Rights taxonomy" link — href /studio/hathor/journal-and-codex

Pipeline trigger#

  • Model select — three options; resets job on change
  • Style preset select — three options; resets job
  • Generation prompt textarea — free-text; resets job

Royalty shares#

  • Composer share input (number, min 0 max 100, default 60) — data-lilith-music-royalty-share="composer", aria-label="Saraswati house composer royalty share"
  • Instructor share input (default 25)
  • Platform share input (default 15)

Remix rights#

  • Remix rights select — three options

Review queue#

  • "Generate track" button (release button, data-lilith-music-submit-job)
    • Function: submitGenerationJob → setJobState('review-queued')
    • Disabled when !readiness.canSubmit

Manifest#

  • Manifest textarea (read-only, aria-label="Music authoring provenance manifest")

Provenance inspector#

  • LilithProvenanceInspector — read its own walkthrough

Data & contracts#

  • Reads: in-file constants LILITH_MUSIC_MODELS, LILITH_MUSIC_STYLE_PRESETS, LILITH_MUSIC_REMIX_RIGHTS, LILITH_MUSIC_ROYALTY_PARTIES, LILITH_MUSIC_PROVENANCE_ASSETS
  • Writes: client state only; submission is in-memory (setJobState)
  • Realtime: none
  • Caching: client bundle
  • Auth/role check: middleware enforces signed-in

Cross-references#

Open questions / known gaps#

  • Confirm whether the generation job is submitted to a real Saraswati service or stays in client state
  • Document where the review queue lives (/studio/...) and how the handed-off track surfaces back into the V1 editorial workflow
  • Verify rights-taxonomy interplay — the "Rights taxonomy" header link points to /studio/hathor/journal-and-codex; confirm that route handles music rights labels