oxyan.themes
============

`oxyan.themes` is the theme package for the Ocyan / MandelBlogStack ecosystem.
It provides the shared base templates, header/footer variants, SCSS theme
definitions, and webshop-oriented template overrides used by Ocyan projects.

Release line
============

The active MandelBlogStack release line for this repository is `2.0.x`.
Branch/runtime validation is driven through the centralized Jenkins shared
library (`mandel-ci`) on Python `3.12`.

Current theme selection
=======================

Theme selection is currently configuration-driven through the Ocyan config
section named `themes`. The plugin entrypoint maps those values into Django
settings:

* `OXYAN_THEME`
* `OXYAN_THEME_MIXINS`

Example::

    "themes": {
      "theme": "default",
      "mixins": ["sticky_header", "wide_container"]
    }

This package does not currently provide a first-class per-site Wagtail theme
selection model. Theme selection is effectively global for the running project.

Asset pipeline
==============

The runtime frontend contract is mixed, but the release contract is explicit.

Templates expect these compiled assets:

* JavaScript bundle: `oxyan/themes/static/bundle.js`
* CSS bundle: `oxyan/themes/static/bundle.css`

The runtime SCSS source tree still exists and remains part of the shipped
package:

* `oxyan/themes/static/scss/base.scss`

Source assets live in:

* `js/` for source JavaScript
* `oxyan/themes/static/scss/` for SCSS

Release builds must run:

* `npm ci`
* `npm run build`

before `python -m build`, so the generated wheel and sdist contain the compiled
bundle assets as well as the SCSS source tree. Released artifacts must install
without requiring Node/npm or network access during `pip install`.

Django compressor / libsass still compile SCSS at runtime for legacy theme
behavior. That mixed pipeline is current behavior and should be treated as
legacy architecture until a dedicated cleanup phase is approved.

Optional integrations
=====================

`oxyan.themes` is designed to work inside the broader Ocyan stack and has
optional or soft coupling with:

* Wagtail
* Oscar / webshop flows
* `ocyan.plugin.wagtail`
* `ocyan.plugin.seo`
* `ocyan.plugin.ai_assistant`

Oscar template overrides remain part of the package, but Oscar is not treated
as a hard installation dependency for the base theme release contract. Host
projects that use Oscar/webshop behavior must still install their Oscar layer
explicitly.

The AI Assistant widget is optional. If `ocyan.plugin.ai_assistant` is not
installed, the base theme should still render safely.

Known limitations
=================

Current limitations that remain intentionally unchanged in this phase:

* no dedicated per-site theme selection model
* strong template coupling to Oscar/webshop flows
* mixed asset pipeline with both webpack bundles and runtime SCSS compilation
* limited automated test coverage
* broader asset and template cleanup still belongs to a future hardening phase

Release automation
==================

This repository now follows the centralized MandelBlogStack plugin release
pattern:

* branch builds default to dry-run validation only
* annotated semver tags (`vX.Y.Z`) are the only allowed release trigger
* the pipeline builds the frontend assets first, then builds one exact wheel and
  sdist pair
* those exact artifacts are uploaded to `mandel/testing`, verified, then
  promoted unchanged to `mandel/stable`
* `release-artifacts/release.json` is archived for every run
