UI starters (kits) and their sample gallery

[einari]

Context

Want out-of-the-box, packaged UI starting points — a package set + a
theme choice + sample pages — that Studio's "new project" flow can
scaffold from. This is deliberately not a .play file / language
construct (see Screenplay theme issue's "out of scope" note): it's a
packaged, versioned tooling artifact that ships alongside Scene.React and
its component package adapters.

Proposal

ui starter Admin
  packages
    core
    PrimeReact

  themes
    Aurora
    Midnight

  gallery
    screen SampleDashboard
    screen SampleForm
    screen SampleTable

• A starter bundles: a package list, one or more compatible themes, and a
  gallery — a list of ordinary screen names shipped with the starter.
  Gallery screens are real Screenplay content with real seed/fixture data
  for their sample commands/queries, not static mockups.
• Studio boots the gallery through the real Scene.Engine +
  Scene.React (or whichever renderer matches the target profile) inside
  a sandboxed ui profile built from the starter's own package list —
  this is a working mini-app, not a simulated preview.
• Theme switching inside the gallery reuses the theme engine's live
  re-resolution (see theme engine issue) — no separate preview pipeline.
• If gallery screens declare navigation-item contributions, the gallery
  gets a working nav shell for free via the existing contribution
  mechanism — no bespoke gallery-nav widget needed.
• Starters are versioned per package combination they're built for, since
  package/theme compatibility is enforced (see theme construct).

Open questions

• Keep the gallery after scaffolding? Leaning yes — cheap to retain,
  and it doubles as a living style guide for the theme/package combo a
  team actually chose (useful for onboarding). Needs a decision on
  whether it's opt-out at scaffold time or always kept.
• Where does starter packaging/versioning live physically — alongside
  each component package adapter it targets, or centralized in Scene
  itself? Affects how a third-party package author would ship their own
  starter.

---

Dependencies

Depends on

• ui profile package resolution engine #3 — a starter is a package list, resolved through the package engine
• Theme engine: applying and validating theme/package compatibility #5 — gallery theme switching is the theme engine's live re-resolution
• Contribution point resolution at runtime, and the NavBar widget #2 — gallery nav comes free via the contribution mechanism
• Language construct: theme, with declared package compatibility Screenplay#96 — the scope boundary that keeps ui starter out of the .play language

Blocks

• New-project wizard: starter selection and gallery preview StudioIssues#162 — new-project wizard, starter selection and gallery preview

Gates other work: the gallery retention after scaffolding decision directly blocks the scaffold step of Cratis/StudioIssues#162.

Part of the screen work — build order and full dependency map: #7

---

Implementation notes

A ui starter is a packaged artifact, not a language construct — it never appears in a .play file. Ship it as data (a manifest) plus the gallery's .play content, versioned per package combination.

The gallery must boot through the real Scene.Engine + Scene.React — no separate preview pipeline, and no mocked screens. If a gallery screen cannot run for real, the starter is not finished.

[einari]

Fixed in #13.