> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamly.watch/llms.txt
> Use this file to discover all available pages before exploring further.

# Themes Package System

> Developer reference for Streamly theme packages — layout, APIs, zip format, presets, preview, and UI roadmap.

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

1. Do not fork routes per theme.
2. Prefer capabilities (`supportsLightMode`, `supportsFeaturesSection`) over hardcoded theme ids.
3. Streamly is the **final** default look — other themes must not regress it.
4. Public catalog API facade: `lib/branding/theme-catalog.ts`.
5. 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.

## Related

* [Themes](/admin-dashboard/themes)
* [Themes & Skins](/viewer/themes-and-skins)
* [Brand Presets](/viewer/brand-presets)