# Theme Magazine

## Package docs status

This page is generated from package source documentation in `the Capell packages repository` and the checked-in manifest. Source documentation is not distribution status. Before running a Composer command, verify that the exact package and compatible 1.x release are available through public Packagist or the authenticated marketplace account.

| Field | Value |
| --- | --- |
| Composer package | `capell-app/theme-magazine` |
| Package slug | `theme-magazine` |
| Product group | Capell Themes |
| Tier | premium |
| Bundle | `themes` |
| Runtime contexts | `frontend` |
| Capell version | `^1.0` |
| Source repository | `capell-app/packages` |
| Source path | `packages/theme-magazine` |
| Docs source | `packages/theme-magazine/docs` |
| Manifest | [`capell.json`](https://github.com/capell-app/packages/edit/main/packages/theme-magazine/capell.json) |

<!-- prettier-ignore-start -->

## What This Plugin Adds

Theme Magazine is an **Available**, **No schema impact** Capell theme in the **Capell Themes** product group. It ships as `capell-app/theme-magazine` and extends these surfaces: frontend.

Theme Magazine adds dispatch, city-guide, columnist, audio, photo-essay, and culture-timeline presentation. It styles Capell-managed stories and does not own their content data.

When selected, public pages can combine long-form dispatches, place-based guides, audio, and photography in a magazine-style hierarchy.

Evidence: [`src/MagazineThemeServiceProvider.php`](src/MagazineThemeServiceProvider.php), [`resources/views/sections/radio-audio.blade.php`](resources/views/sections/radio-audio.blade.php), [`resources/views/sections/city-guides.blade.php`](resources/views/sections/city-guides.blade.php), [`resources/views/sections/photo-essay.blade.php`](resources/views/sections/photo-essay.blade.php), [`tests/Unit/SignatureWidgetRenderTest.php`](tests/Unit/SignatureWidgetRenderTest.php), [`tests/Unit/PublicOutputSafetyTest.php`](tests/Unit/PublicOutputSafetyTest.php).

Status details:

- Status: Available
- Tier: premium
- Bundle: themes
- Composer package: `capell-app/theme-magazine`
- Namespace: `Capell\ThemeMagazine`
- Theme key: `magazine`

## Why It Matters

**For developers:** A typed Foundation-derived definition maps a broad editorial section set to package-owned Blade renderables.

**For teams:** Editorial teams can give text, audio, guides, and image-led stories distinct treatments within the same Capell publishing workflow.

Evidence: [`src/MagazineThemeServiceProvider.php`](src/MagazineThemeServiceProvider.php), [`tests/Unit/MagazineThemeDefinitionTest.php`](tests/Unit/MagazineThemeDefinitionTest.php), [`resources/views/sections/radio-audio.blade.php`](resources/views/sections/radio-audio.blade.php), [`resources/views/sections/city-guides.blade.php`](resources/views/sections/city-guides.blade.php), [`resources/views/sections/photo-essay.blade.php`](resources/views/sections/photo-essay.blade.php).

## Screens And Workflow

Screenshot contract: `docs/screenshots.json`.

<span class="theme-aware-image">
  <img class="theme-aware-image__light" src="screenshots/magazine-homepage.png" alt="Magazine Homepage" loading="lazy" />
  <img class="theme-aware-image__dark" src="screenshots/magazine-homepage-dark.png" alt="Magazine Homepage" loading="lazy" />
</span>

<span class="theme-aware-image">
  <img class="theme-aware-image__light" src="screenshots/magazine-landing.png" alt="Magazine Landing page" loading="lazy" />
  <img class="theme-aware-image__dark" src="screenshots/magazine-landing-dark.png" alt="Magazine Landing page" loading="lazy" />
</span>

Desktop, tablet, and mobile variants remain defined in the screenshot contract; this list groups them by workflow.

- Magazine Homepage (frontend, required).
- Magazine Landing page (frontend, required).
- Magazine List page (frontend, required).
- Magazine Blog Article (frontend, optional).
- Magazine Blog Listing (frontend, optional).
- Magazine Search results (frontend, optional).
- Magazine Search empty (frontend, optional).
- Magazine Contact form (frontend, optional).
- Magazine Page Not Found (frontend, optional).
- Magazine Call To Action (frontend, optional).

## Technical Shape

- Service providers: `Capell\ThemeMagazine\MagazineThemeServiceProvider`.
- Actions: `InstallMagazineThemeDemoAction`.
- Command signatures: `capell:theme-magazine-demo`.
- Console command classes: `DemoCommand`.
- Manifest contributions: `admin-page: Capell\ThemeMagazine\Manifest\ThemeManagementPageContribution`.
- Health checks: `Capell\ThemeMagazine\Health\ThemeMagazineHealthCheck`.
- Blade views: `packages/theme-magazine/resources/views/page.blade.php`, `packages/theme-magazine/resources/views/sections/city-guides--tabs.blade.php`, `packages/theme-magazine/resources/views/sections/city-guides.blade.php`, `packages/theme-magazine/resources/views/sections/columnists--roster.blade.php`, `packages/theme-magazine/resources/views/sections/columnists.blade.php`, `packages/theme-magazine/resources/views/sections/content-listing.blade.php`, `packages/theme-magazine/resources/views/sections/cta.blade.php`, `packages/theme-magazine/resources/views/sections/cultural-dispatch-timeline--compact.blade.php`, `packages/theme-magazine/resources/views/sections/cultural-dispatch-timeline.blade.php`, `packages/theme-magazine/resources/views/sections/footer.blade.php`, `packages/theme-magazine/resources/views/sections/hero.blade.php`, `packages/theme-magazine/resources/views/sections/lead-dispatch.blade.php`, `and 10 more`.
- Cache tags: `theme-magazine`.

## Data Model

This theme has no schema impact. It relies on core Capell site, page, locale, and theme records instead of declaring package-owned tables.

## Install Impact

- Required packages: `capell-app/core`, `capell-app/theme-foundation`, `capell-app/frontend`.
- Admin navigation: declares `admin-page: ThemeManagementPageContribution`; each Filament page or resource controls its own navigation visibility.
- Admin/editor extensions: none declared.
- Permissions: none declared in `capell.json`.
- Public routes: none declared.
- Database changes: no package migrations declared.
- Config: no package config files.
- Settings: no package settings declared.
- Queues or schedules: none declared.
- Cache tags: `theme-magazine`.
- Commands: `capell:theme-magazine-demo`.

## Common Pitfalls

- Keep required Capell packages on compatible v4 releases: `capell-app/core`, `capell-app/theme-foundation`, `capell-app/frontend`.
- Keep public Blade and cached HTML free of authoring markers, model IDs, permissions, signed editor URLs, and lazy database queries.
- Custom write integrations must preserve invalidation for `theme-magazine` cache tags.

## Troubleshooting

| Symptom | Likely cause | Check | Fix |
| --- | --- | --- | --- |
| Package surface is missing after install | Provider or manifest is not loaded | Confirm `capell.json`, package `composer.json`, and provider registration | Reinstall the package, refresh Composer autoload, and clear host caches |
| Public output leaks unexpected state | Render data, cache variation, or authoring boundary has regressed | Check public Blade, cache tags, and public-output safety tests | Move data loading out of Blade and rerun the package public-output tests |

## Quick Start

1. Install the package: `composer require capell-app/theme-magazine`.
2. No package-specific setup command or migrations are declared.
3. Open the Magazine Homepage and confirm the public output renders without admin state.

## Next Steps

- [Package docs](README.md)
- [Overview](overview.md)
- [Troubleshooting](#troubleshooting)
- [Screenshot contract](screenshots.json)
- [Marketplace assets](assets/marketplace/)
- [Capell content language plan](../../docs/CONTENT_LANGUAGE_PLAN.md)
- [Capell documentation design system](../../docs/DESIGN_SYSTEM.md)
- [Capell and package ERD notes](../../docs/erd/capell-and-package-erds.md)
- Related packages: [Theme Foundation](../theme-foundation/README.md), [Newsletter](../newsletter/README.md).
- Focused tests: `vendor/bin/pest packages/theme-magazine/tests --configuration=phpunit.xml`.

<!-- prettier-ignore-end -->