Theme Anatomy

views/
├── account/     25   the client area: dashboard, services, invoices, tickets, settings
├── auth/         6   sign in, sign up, forgotten password, reset, activate, accept invite
├── checkout/    14   configure, cart, checkout, pay, order complete
├── content/     14   knowledge base, news, contact, legal
├── products/     3   catalog surfaces
├── page/         1   file based pages: views/page/{slug} answers /{slug}
├── home.tpl          the one view apply_theme insists on
├── 404.tpl           theme's own not-found surface
├── maintenance.tpl   rendered while the site is closed
└── domain.tpl        the public domain search

render("account/dashboard")  ->  views/account/dashboard.tpl   (smarty)
                             ->  views/account/dashboard.twig  (twig)
                             ->  views/account/dashboard.php   (php)

$settings = [
    'groups' => [
        // group key      label = a key in the theme's locale file, NOT literal text
        'appearance' => ['label' => 'grp_appearance', 'icon' => 'bi-palette'],
        'checkout'   => ['label' => 'grp_checkout',   'icon' => 'bi-cart3'],
    ],
];

// The whole manifest of ANY theme, by folder name. Cached per name, empty array when absent.
public static function manifest(string $themeName): array;

// The running theme. Falls back to Basic when the configured folder is gone.
public static function active(): self;

public function meta(): array;                    // manifest['meta']
public function engine(): string;                 // lowercased, 'php' when unset
public function settings(): array;                // manifest['settings']
public function settingsSchema(): array;          // the SAME array as settings()
public function exists(): bool;                   // manifest is non-empty AND the directory is there

// Values.
public function savedConfig(): array;             // config.php, cached per instance
public function setting(string $key): mixed;      // saved value, else the field's default, else null
public function allSettings(): array;             // every schema field, merged, as views receive it

public static function is_shipped(?string $name = null): bool;   // one of Basic, WStyle, WCOM
public static function engineLabel(string $engine): string;      // 'smarty' -> 'Smarty', for the panel

return [
    'meta' => [
        'name'        => 'Acme',
        'version'     => '1.0.0',
        'author'      => 'Acme Ltd',
        'website'     => 'https://acme.example',
        'image'       => 'cover.png',      // beside theme.php, NOT under assets/
        'description' => '',               // locale/en.php wins, so it is left empty here

        // Behaviour flags: read by core, not by the catalogue.
        'signup_minimal'           => false,
        'dashboard_due_soon_alert' => false,
        'disabled_routes'          => ['references', 'references_detail'],
    ],
    'update-url' => '',                    // empty: never checked for updates
    'engine'     => 'smarty',
    'status'     => 'ready',
    'settings'   => [
        'groups' => [
            'topbar' => ['label' => 'grp_topbar', 'icon' => 'bi-megaphone'],
        ],
        'fields' => [
            'topbar_enabled' => [
                'type'    => 'switch',
                'group'   => 'topbar',
                'label'   => 'set_topbar_enabled',      // a key in locale/{lang}.php
                'desc'    => 'set_topbar_enabled_desc',
                'default' => false,
            ],
            'topbar_text' => [
                'type'      => 'textarea',
                'group'     => 'topbar',
                'label'     => 'set_topbar_text',
                'default'   => '',
                'rows'      => 3,
                'multilang' => true,        // one tab per active language
                'html'      => true,        // otherwise every tag is stripped on save
                'depends'   => ['topbar_enabled' => true],
            ],
        ],
    ],
];

return [
    // The catalogue card reads these two from here, not from meta.
    'name'        => 'Acme',
    'description' => 'A compact storefront theme with a promotional strip.',

    'grp_topbar'              => 'Promotional Strip',
    'set_topbar_enabled'      => 'Show the strip',
    'set_topbar_enabled_desc' => 'Prints a single line above the header on every public page.',
    'set_topbar_text'         => 'Strip content',
];

return [
    'topbar_enabled' => true,
    'topbar_text'    => [
        'en' => '<strong>Launch week</strong> 20% off every plan.',
        'tr' => '<strong>Lansman haftası</strong> tüm planlarda %20 indirim.',
    ],
];

{* $setting.topbar_text is already the active language's string, not the map. *}
{if $setting.topbar_enabled}
    <div class="topbar">{$setting.topbar_text nofilter}</div>
{/if}

// setting() returns the RAW stored value: a multilang field is still the lang => value map here.
$strip = Theme::active()->setting('topbar_text');
$lang  = Language::selected() ?: 'en';
$text  = is_array($strip) ? ($strip[$lang] ?? $strip['en'] ?? '') : (string) $strip;

// allSettings() is the resolved form, which is why the templates never do the above.
$resolved = Theme::active()->allSettings();
$text     = (string) ($resolved['topbar_text'] ?? '');