Metadata-Version: 2.5
Name: mirrorwall
Version: 0.2.1
Summary: Design tokens, layout, component macros, SSE and JSON/error envelope helpers so three applications look like one family without sharing a page.
Project-URL: Homepage, https://github.com/JPKell/MirrorWall
Project-URL: Documentation, https://github.com/JPKell/MirrorWall/tree/main/docs
Project-URL: Changelog, https://github.com/JPKell/MirrorWall/blob/main/CHANGELOG.md
Author: Local AI Suite contributors
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: anyio<5,>=4
Requires-Dist: baseaicore<0.5,>=0.4
Requires-Dist: jinja2<4,>=3.1
Requires-Dist: setspec<0.5,>=0.4
Requires-Dist: starlette<2,>=1.3.1
Provides-Extra: dev
Requires-Dist: import-linter<3,>=2.0; extra == 'dev'
Requires-Dist: mypy<2,>=1.11; extra == 'dev'
Requires-Dist: pytest-cov<6,>=5; extra == 'dev'
Requires-Dist: pytest-randomly<4,>=3; extra == 'dev'
Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
Requires-Dist: respx<1,>=0.21; extra == 'dev'
Requires-Dist: ruff<1,>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# MirrorWall

Design tokens, layout, component macros, SSE and JSON/error envelope helpers so three applications look like one family without sharing a page.

**Status:** Phases 1 and 2 implemented at `0.2.0` — design tokens, the layout shell, the component
macros, template filters, JSON and error envelopes, request-ID/Host/CSRF middleware, SSE with a
gap-free replay-to-live handoff, static mounting with content-hashed URLs, and the health
primitives. LoadCoach renders every page on it. Phase 3 (the interactive table and chart modules,
the component gallery) is next — see the
[development plan](docs/packages/mirrorwall/development-plan.md).

Part of the **Local AI Suite**.

## Install

```bash
pip install mirrorwall
```

## Quickstart

```python
from pathlib import Path

from mirrorwall import create_template_environment, mount_static

environment = create_template_environment(
    app_template_dirs=(Path("src/yourapp/web/templates"),),
    globals_={
        "product_name": "YourApp",
        "product_version": "1.0.0",
        "nav_items": ({"key": "home", "href": "/", "label": "Home"},),
        "theme_storage_key": "yourapp-theme",
    },
)
mount_static(app, environment=environment)  # your Starlette/FastAPI application
```

Then a page is four lines:

```jinja
{% extends "mirrorwall/base.html" %}
{% from "mirrorwall/components.html" import table %}
{% block content %}{{ table(columns, rows, table_id="things", sortable=true) }}{% endblock %}
```

Streaming, with the replay-to-live handoff, heartbeats and thread dispatch handled for you:

```python
from mirrorwall import sse_response

return sse_response(
    your_event_source,
    stream_id=job_id,
    last_event_id=request.headers.get("last-event-id"),
    generator=GeneratorInfo(name="yourapp", version=__version__),
    terminal_events=frozenset({"result", "error"}),
)
```

See [docs/packages/mirrorwall/spec.md](docs/packages/mirrorwall/spec.md) §20 for the full surface.

## Documentation

Project documentation lives under [`docs/`](docs/README.md). Start with [`docs/README.md`](docs/README.md).

| Read this | For |
|---|---|
| [docs/packages/mirrorwall/spec.md](docs/packages/mirrorwall/spec.md) | Purpose, scope, non-goals, public contracts, configuration, acceptance criteria |
| [docs/packages/mirrorwall/development-plan.md](docs/packages/mirrorwall/development-plan.md) | The phased build plan: goals, work, tests, acceptance criteria per phase |

## Development

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install
pytest -m "not live and not performance"
```

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full workflow and [`SECURITY.md`](SECURITY.md) for
how to report a vulnerability.

## License

Apache-2.0 — see [`LICENSE`](LICENSE).
