cms/SPECS.md

# SiteWeaver CMS Core - Technical Specifications

This document defines the build-ready technical specifications for the SiteWeaver CMS Core (`/cms`).

## 1. System Requirements & Stack
- **Framework**: Laravel 11.x
- **PHP Version**: 8.2+
- **Database**: SQLite3
- **Frontend Stack**: 
    - **Admin CSS**: Semantic UI
    - **Admin/Editor JS**: Svelte 5 (compiled via Vite)
- **Asset Conflict Management**: Each plugin/theme must utilize a custom root-level CSS class (e.g., `.blog`) to prevent global namespace pollution.

## 2. Core Routing & URL Management
### 2.1 Admin Segment
- **Default**: `/loom` (Branded segment)
- **Configuration**: Managed via `ADMIN_PATH` in the `.env` file.
- **Priority**: System routes (Admin, Auth, API) have absolute priority over dynamic page slugs.

### 2.2 Reserved Slugs
- `loom`, `admin`, `api`, `login`, `logout`, `register`, `sw-admin`, `dashboard`, `themes`, `plugins`, `media`.

## 3. Block Editor: Server-Side Hydration (SSH)
### 3.1 Data Schema (JSON-First)
Content is stored as a JSON array of block objects:
```json
[
  { "type": "header", "data": { "level": 2, "text": "Hello SiteWeaver" } },
  { "type": "paragraph", "data": { "text": "This is a block-based CMS." } }
]
```
### 3.2 Rendering Flow
- **On Save**: The Svelte editor outputs JSON. The PHP core hydrates this JSON into a "Cached Rendered HTML" column in the database.
- **On Request**: The CMS serves the "Cached Rendered HTML" for high performance.
- **Fallback**: If the cached version is missing/outdated, the PHP core re-hydrates the JSON on-the-fly using Blade components associated with each block type.

## 4. Plugin & Theme Architecture
### 4.1 Plugin Lifecycle
- **Discovery**: CMS scans the `/plugins` directory for Service Providers.
- **Activation**: Toggle-based via Admin UI.
- **Migrations**: 
    - Plugins can define a custom migration path in the Service Provider.
    - **Default Path**: `/plugins/{plugin-name}/migrations/`.

### 4.2 Theme Engine
- **Location**: `/themes/{theme-name}/`.
- **Required Files**: `theme.md` (metadata) and a root layout Blade file.
- **Discovery**: Automated scanning of the `themes/` directory.
- **Inheritance**: Support for Child Themes (overriding parent files via directory hierarchy).
- **Asset Discovery & Loading**: 
    - **Helpers**: 
        - `css('path', $attributes)`: Outputs a `<link>` tag.
        - `js('path', $attributes)`: Outputs a `<script>` tag.
        - `sw_file('path', $attributes)`: **Smart Asset Helper**. Automatically detects file type (via extension/metadata) and outputs the appropriate HTML tag (`<img>` with `srcset` support, `<video>`, `<audio>`, or `<a>` for documents like PDF).
            - **JIT Image Parameters**: For images, special keys in the `$attributes` array like `w`, `h`, `fit`, `q` (quality), and `fm` (format) are automatically intercepted and passed to the JIT image generation engine.
    - **Functionality**: These helpers output the **FULL HTML TAG**.
    - **Attributes**: The optional `$attributes` array allows for specifying `defer`, `async`, `media`, `id`, `class`, `alt`, `w`, `h`, etc.
    - **Note**: `sw_file()` is used instead of `file()` to avoid conflicts with PHP's built-in `file()` function.
    - **Recursive Search**: The engine first looks in the current Theme folder. If a Child Theme is active and the file is missing, it automatically falls back to the Parent Theme folder.

## 5. Media Manager Specification
### 5.1 Storage & Logic
- **Abstraction**: Uses Laravel Flysystem (supports Local, S3, Nextcloud).
- **Focal Point**: Coordinates (X/Y) stored as metadata.
- **JIT Generation**: Managed via Glide/Intervention. 
    - **URL Format**: `/media/{filename}?w=800&fit=focal&fp-x=0.5&fp-y=0.5`.

### 5.2 Performance
- **Preview Cache Warming**: Images generated during the author's preview phase.
- **Automated Cache Warming**: Background jobs generate responsive `srcset` sizes upon publication.
- **Orphaned Media Watcher**: Periodic task to prune unreferenced original files and JIT caches.

## 6. Authentication & Identity Provider
- **Middleware**: `sw:auth` middleware.
- **Functionality**: Protects non-CMS Laravel routes using the CMS's session, user roles, and 2FA.
- **Roles**: Admin (Protected), Editor, Author, User.

## 7. Performance & Security
- **Full-Page Caching**: Native public-route caching.
- **Security Audits**: Automated periodic auditing for activated plugins.
- **Backups**: `sw site:backup` and Admin-side trigger to snapshot the SQLite DB and project root.
- **Restore**: `sw site:restore` and Admin-side UI to select and restore from existing backup files.