Themes Package System

Authoritative product notes also live in themes/README.md inside the Streamly repo.

Layout

themes/<id>/
  theme.json           # id, name, version, author, capabilities, templateEntry
  config.ts            # default branding seed + gallery copy/swatches
  skin.ts              # page-shell / button chrome tokens (no React)
  index.ts             # ThemeManifest + template component export
  *Template.tsx        # Storefront home template (colocated)

Shims (no logic): components/landing/templates/{Streamly,Streamlix,OneTube}Template.tsx.

Rules

Do not fork routes per theme.
Prefer capabilities (supportsLightMode, supportsFeaturesSection) over hardcoded theme ids.
Streamly is the final default look — other themes must not regress it.
Public catalog API facade: lib/branding/theme-catalog.ts.
Live look must not change unless operator Apply or Brand & Experience edit — install/export never auto-apply.

Operator APIs

Method	Path	Effect
`GET`	`/api/operator/themes`	List built-ins + uploaded (no config writes)
`POST`	`/api/operator/themes/apply`	Body `{ themeId }` — presets; never overwrite `seo_*` / page SEO
`GET`	`/api/operator/themes/[themeId]/export`	Download `.streamly-theme.zip`
`DELETE`	`/api/operator/themes/[themeId]`	Soft-uninstall uploaded package (not built-ins / active)
`POST`	`/api/operator/themes/install`	Multipart zip → `tenant_theme_packages` (does not Apply)

Upload/export/uninstall UI currently hidden (SHOW_THEME_PACKAGE_IO_UI = false). APIs remain.

Package zip layout

theme.json    # id, version, templateEntry (streamly|streamlix|streamtube), preview, …
config.json   # Apply seed (colors/fonts/layout). SEO keys stripped on install/apply.

Uploaded packages cannot ship new React templates — only skin a built-in templateEntry. Built-in ids cannot be overwritten on install.

Public SEO (not in theme packages)

Controlled in Brand & Experience:

Surface	Source
Home	`seo_title`, `seo_description`, `seo_allow_indexing`, OG/Twitter
Articles index	`page_articles_seo_*`
Article detail	Per-post SEO in blog editor
About	`page_about_seo_*`

Preview

/?__theme_preview=<themeId> — admin only; middleware sets preview header; merges preset/seed in memory; switches data-storefront-theme chrome; floating banner back to Themes.

​Layout

​Rules

​Operator APIs

​Package zip layout

​Public SEO (not in theme packages)

​Preview

​Related