simple-module-pagebuilder 0.0.9__tar.gz → 0.0.11__tar.gz

{simple_module_pagebuilder-0.0.9 → simple_module_pagebuilder-0.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_pagebuilder
-Version: 0.0.9
+Version: 0.0.11
 Summary: Drag-and-drop visual page builder for simple_module apps
 Project-URL: Repository, https://github.com/antosubash/simple_module_python_modules
 Author-email: Anto Subash <antosubash@live.com>
@@ -50,6 +50,13 @@ at `/p/{slug}`.
 - **Content snapshots** — capture the whole site, download or upload it as a
   `.zip`, and restore behind an approval gate. See below.
 
+**Full documentation** lives in [`docs/`](docs/index.md):
+[user guide](docs/user-guide.md) (the editor, workflow, layout, media and
+snapshots screens), [API reference](docs/api-reference.md) (every
+`/api/pagebuilder` route, public claims, errors), [operations](docs/operations.md)
+(install, settings, languages, tenancy, troubleshooting) and
+[architecture](docs/architecture.md).
+
 ## Installation
 
 ```bash
@@ -131,8 +138,10 @@ make migrate
 ```
 
 Add `branch_labels = ("pagebuilder",)` to that first generated revision so the
-module can later be removed on its own with
-`alembic downgrade pagebuilder@base`.
+revision can be named. That does **not** make `alembic downgrade
+pagebuilder@base` remove pagebuilder alone: autogenerate chains every revision
+off the current head, so the command walks everything beneath it
+(antosubash/simple_module_python#333).
 
 ## Permissions
 

{simple_module_pagebuilder-0.0.9 → simple_module_pagebuilder-0.0.11}/README.md

@@ -26,6 +26,13 @@ at `/p/{slug}`.
 - **Content snapshots** — capture the whole site, download or upload it as a
   `.zip`, and restore behind an approval gate. See below.
 
+**Full documentation** lives in [`docs/`](docs/index.md):
+[user guide](docs/user-guide.md) (the editor, workflow, layout, media and
+snapshots screens), [API reference](docs/api-reference.md) (every
+`/api/pagebuilder` route, public claims, errors), [operations](docs/operations.md)
+(install, settings, languages, tenancy, troubleshooting) and
+[architecture](docs/architecture.md).
+
 ## Installation
 
 ```bash
@@ -107,8 +114,10 @@ make migrate
 ```
 
 Add `branch_labels = ("pagebuilder",)` to that first generated revision so the
-module can later be removed on its own with
-`alembic downgrade pagebuilder@base`.
+revision can be named. That does **not** make `alembic downgrade
+pagebuilder@base` remove pagebuilder alone: autogenerate chains every revision
+off the current head, so the command walks everything beneath it
+(antosubash/simple_module_python#333).
 
 ## Permissions
 

simple_module_pagebuilder-0.0.11/docs/api-reference.md

@@ -0,0 +1,302 @@
+# PageBuilder API reference
+
+All admin routes are JSON under `/api/pagebuilder`. Every one of them runs three
+router-level dependencies, in this order:
+
+1. **Authentication** — `401 Not authenticated` without a signed-in user, unless
+   the `requires_auth` setting is off (read per request).
+2. **Tenant binding** (`tenancy.bind_admin`) — single-tenant host: tenant
+   `"default"`; multi-tenant host: the tenant the framework resolved, or
+   `403 tenant_required`.
+3. **CSRF** — every `POST`/`PUT`/`PATCH`/`DELETE` needs the session token in an
+   `X-CSRF-Token` header, else `403 Invalid or missing CSRF token` (when
+   `csrf_protect` is on). The admin views expose it as the Inertia shared prop
+   `csrf.token` and in a JS-readable cookie (`pagebuilder_csrf` by default).
+
+"Permission" below is the extra `RequiresPermission` check on top; **auth** means
+any signed-in user. Errors are `{"detail": "<message>"}`; the table is at the end.
+
+## Pages
+
+### `GET /api/pagebuilder/pages` — auth
+
+Query: `search` (title or slug, case-insensitive, wildcards literal), `status`
+(`draft` | `submitted_for_review` | `published`; empty = no filter), `locale`,
+`limit` (1–200, default **unbounded**), `offset`. Newest first, trashed pages
+excluded.
+
+```json
+{"items": [PageRead, …], "total": 42}
+```
+
+`PageRead`:
+
+```json
+{"id": 7, "slug": "about", "locale": "en", "translation_group": "9f…",
+ "title": "About", "status": "published", "has_published": true,
+ "meta_title": null, "meta_description": "…", "og_image": null,
+ "canonical_url": null, "index_in_search": true, "rejection_note": null,
+ "publish_at": null, "unpublish_at": null, "parent_id": null,
+ "is_template": false, "show_in_header_nav": true, "show_in_footer": false,
+ "deleted_at": null, "created_at": "…", "updated_at": "…"}
+```
+
+### Literal list routes
+
+| Route | Permission | Returns |
+|---|---|---|
+| `GET /pages/trash` | `pagebuilder.edit` | trashed pages, most recently binned first |
+| `GET /pages/templates` | auth | pages with `is_template`, by title |
+| `GET /pages/pending` | `pagebuilder.approve` | pages in `submitted_for_review` |
+
+All three return `{"items": [PageRead], "total": n}`.
+
+### `GET /api/pagebuilder/locales` — auth
+
+`{"locales": ["en", "de"], "default": "en"}` — the configured content languages.
+
+### `POST /api/pagebuilder/pages` — `pagebuilder.edit` → 201
+
+```json
+{"title": "About", "slug": "about", "locale": "de",
+ "meta_title": null, "meta_description": null, "og_image": null,
+ "canonical_url": null, "index_in_search": true, "json_ld": null,
+ "show_in_header_nav": false, "show_in_footer": false,
+ "draft_data": {}, "publish_at": null, "unpublish_at": null,
+ "parent_id": null, "is_template": false, "copy_from_page_id": null}
+```
+
+Only `title` (1–300) and `slug` (`^[a-z0-9][a-z0-9-]*$`, ≤200) are required.
+`locale` omitted means the default content locale; an unconfigured one is 422.
+`copy_from_page_id` seeds `draft_data` from that page's draft and is not stored.
+The page starts as a `draft` in a translation group of its own. Returns
+`PageDetail`. Slug taken in that language → `409 Slug already in use in <locale>`.
+
+### `GET /api/pagebuilder/pages/{id}` — auth
+
+`PageDetail` = `PageRead` plus:
+
+```json
+{"draft_data": {…}, "published_data": {…} | null, "json_ld": {…} | null,
+ "translations": [{"id": 7, "locale": "en", "slug": "about", "title": "About",
+                   "status": "published", "trashed": false}, …]}
+```
+
+`translations` lists every page in the group, this one and trashed ones included,
+ordered by locale. A trashed page is 404 here.
+
+### `PUT /api/pagebuilder/pages/{id}` — `pagebuilder.edit`
+
+Partial update: any of `title`, `slug`, `meta_title`, `meta_description`,
+`show_in_header_nav`, `show_in_footer`, `og_image`, `canonical_url`,
+`index_in_search`, `json_ld`, `draft_data`, `parent_id`, `is_template`. There is
+no `locale`: a page's language cannot change. A slug change records a redirect
+from the old slug (same locale). Returns `PageDetail`.
+
+### `POST /api/pagebuilder/pages/{id}/translations` — `pagebuilder.edit` → 201
+
+```json
+{"locale": "de", "slug": null, "title": null, "copy_content": true}
+```
+
+Creates a draft sibling in the same `translation_group` and returns **its**
+`PageDetail`. `slug` defaults to the source's (or `-2`, `-3`… if taken in that
+language); `title` to the source's. Inherits meta description, social image,
+indexing, template flag and nav flags; never `canonical_url`; `parent_id` is the
+parent's counterpart in that language, or none. Errors: 422 unconfigured locale;
+409 `This page is already in <locale>.`; 409 `A <locale> translation already
+exists.` with header `X-Existing-Page-Id`; 409 slug taken.
+
+### Trash
+
+| Route | Permission | Effect |
+|---|---|---|
+| `DELETE /pages/{id}` | `pagebuilder.edit` | 204. Moves to trash (`deleted_at`). Publishes nothing. |
+| `POST /pages/{id}/restore` | `pagebuilder.edit` | `PageDetail`, status `draft`, `published_data` kept. 404 unless trashed. |
+| `DELETE /pages/{id}/purge` | `pagebuilder.edit` | 204. Removes the row, revisions and redirects, un-parents children, commits, then publishes `PageDeleted`. 404 unless trashed. |
+
+## Workflow
+
+Each returns `PageRead`. Bodies marked *note* take `{"note": "…"}` (≤2000,
+optional; send `{}` or no body).
+
+| Route | Permission | Body | Transition |
+|---|---|---|---|
+| `POST /pages/{id}/publish` | `pagebuilder.publish` | note | any → `published`; draft copied to published; clears `publish_at` and `rejection_note` |
+| `POST /pages/{id}/unpublish` | `pagebuilder.publish` | note | → `draft`; clears `unpublish_at` |
+| `POST /pages/{id}/submit` | `pagebuilder.edit` | note | `draft` → `submitted_for_review`, else 409 |
+| `POST /pages/{id}/approve` | `pagebuilder.approve` | note | `submitted_for_review` → `published`, else 409 |
+| `POST /pages/{id}/reject` | `pagebuilder.approve` | `{"note": "…"}` required, 1–2000 | `submitted_for_review` → `draft`, sets `rejection_note`, else 409 |
+| `POST /pages/{id}/schedule` | `pagebuilder.publish` | `{"publish_at"?, "unpublish_at"?}` | sets timestamps only |
+
+Every transition except `schedule` writes a revision with event `publish`,
+`unpublish`, `submit`, `approve` or `reject`. For `schedule`, an absent key leaves
+that field alone, `null` clears it, `{}` is a no-op; naive datetimes are UTC; both
+set with `publish_at >= unpublish_at` is
+`422 publish_at must be strictly before unpublish_at`.
+
+## Revisions
+
+| Route | Permission | Returns |
+|---|---|---|
+| `GET /pages/{id}/revisions` | auth | `{"items": [PageRevisionRead]}`, newest first |
+| `GET /pages/{id}/revisions/{rev}` | auth | `PageRevisionRead` + `data` |
+| `GET /pages/{id}/revisions/{before}/diff/{after}` | auth | `RevisionDiffResponse` |
+| `POST /pages/{id}/revisions/{rev}/restore` | `pagebuilder.edit` | `PageDetail`; copies title, meta description, social image and blocks into the draft |
+
+`PageRevisionRead`: `id`, `page_id`, `title`, `meta_description`, `og_image`,
+`event`, `note`, `created_at`, `created_by`. The diff names direction
+explicitly because a restored revision can have a higher id and older content:
+
+```json
+{"before_id": 3, "after_id": 5,
+ "metadata": {"title": {"before": "A", "after": "B"}},
+ "blocks": {"added": [{"id": "…", "type": "Hero", "fields": []}],
+            "changed": [{"id": "…", "type": "Text", "fields": ["text"]}],
+            "removed": []}}
+```
+
+A revision that belongs to another page is 404.
+
+## Site layout
+
+| Route | Permission | Body / returns |
+|---|---|---|
+| `GET /layout` | auth | `LayoutDetail` (`id`, `header_data`, `footer_data`, timestamps); created empty on first read |
+| `PUT /layout` | `pagebuilder.edit` | `{"header_data"?, "footer_data"?, "note"?}`; `null`/absent leaves a slot alone. An unchanged save writes no revision. |
+| `GET /layout/revisions` | auth | `{"items": [{"id", "layout_id", "note", "created_at", "created_by"}]}` |
+| `GET /layout/revisions/{id}` | auth | revision + `header_data`, `footer_data` |
+| `POST /layout/revisions/{id}/restore` | `pagebuilder.edit` | `LayoutDetail` |
+
+## Media
+
+### `GET /api/pagebuilder/uploads` — auth
+
+Query: `search`, `content_type`, `folder` (absent = all, empty = unfiled, else
+exact path), `min_size_bytes`, `max_size_bytes`, `cursor`, `offset`, `limit`
+(1–200, default 60). Newest first. `offset` takes precedence over `cursor` and
+adds `total`.
+
+```json
+{"items": [{"id": 4, "filename": "3f…a1.jpg", "original_filename": "hero.jpg",
+            "content_type": "image/jpeg", "size_bytes": 482113,
+            "url": "/media/pagebuilder/default/3f…a1.jpg", "width": 2400,
+            "height": 1600, "folder": "marketing/heros", "alt_text": "",
+            "caption": "", "credit": "",
+            "variants": {"w640": {"filename": "…", "url": "…", "content_type": "image/webp",
+                                 "width": 640, "height": 427, "size_bytes": 31022}},
+            "created_at": "…"}],
+ "next_cursor": 3, "folders": ["marketing/heros"], "total": null}
+```
+
+### `POST /api/pagebuilder/uploads` — `pagebuilder.edit` → 201
+
+Multipart: `file`, optional `folder`. Returns `MediaAssetRead`. The declared type
+must be in `media_allowed_content_types` and match the sniffed magic bytes (415
+otherwise); over `media_max_bytes` is 413. Stored under a random name with the
+sniffed extension; WebP variants generated for each configured width below the
+original's.
+
+### One asset — all `pagebuilder.edit`
+
+| Route | Effect |
+|---|---|
+| `GET /uploads/{id}` | `{"asset": MediaAssetRead, "used_in": [{"page_id", "title", "slug", "status", "draft_only"}], "used_in_total": n}` (first 20 pages) |
+| `PUT /uploads/{id}` | `{"alt_text"?, "caption"?, "credit"?}` (≤500/500/200); returns the same detail shape |
+| `DELETE /uploads/{id}/checked` | 204, or `409 Still used on N page(s): …. Detach it there first.` |
+| `DELETE /uploads/{id}` | 204, unconditionally: removes the row, file and variants |
+
+Usage counts non-trashed pages whose draft or published data contains the
+asset's URL (current or pre-tenancy flat URL).
+
+## Snapshots and imports
+
+| Route | Permission | Body / returns |
+|---|---|---|
+| `GET /snapshots` | auth | `{"items": [SnapshotRead]}` |
+| `POST /snapshots` | `pagebuilder.publish` | `{"note"?}` → 201 `SnapshotRead` |
+| `GET /snapshots/{id}/download` | `pagebuilder.publish` | `application/zip`, `content-snapshot-{id}.zip` |
+| `POST /snapshots/upload` | `pagebuilder.publish` | multipart `file` → 201 `SnapshotRead`; 413 over `snapshot_max_upload_bytes`; 422 invalid bundle |
+| `DELETE /snapshots/{id}` | `pagebuilder.publish` | 204 |
+| `POST /snapshots/{id}/restore` | `pagebuilder.publish` | 201 `PendingImportRead`; writes nothing to the site; 409 if one is pending |
+| `GET /imports/pending` | auth | `PendingImportRead` or `null` |
+| `POST /imports/{id}/approve` | `pagebuilder.approve` | `ImportApplyResponse` |
+| `POST /imports/{id}/reject` | `pagebuilder.approve` | `{"note"?}` → `PendingImportRead` |
+
+`SnapshotRead`: `id`, `note`, `source` (`manual` | `upload` | `pre_restore`),
+`format_version`, `manifest`, `size_bytes`, `created_at`, `created_by`.
+`PendingImportRead`: `id`, `snapshot_id`, `plan`, `status` (`pending` |
+`approved` | `rejected`), `note`, `created_*`, `decided_at`, `decided_by`.
+`ImportApplyResponse`: `pages_created`, `pages_updated`, `media_added`,
+`redirects`, `redirects_dropped` (slugs). Deciding an import twice is 409
+`Import already decided`. Self-approval is allowed.
+
+## Public routes
+
+Anonymous, `GET`/`HEAD` only, mounted at startup from the settings:
+
+| Route | Notes |
+|---|---|
+| `{public_route_prefix}/{slug}` | default content locale, e.g. `/p/about` |
+| `/{locale}{public_route_prefix}/{slug}` | each other content locale, e.g. `/de/p/about` |
+| `/{default}{public_route_prefix}/{slug}` | multilingual sites only: 301 to the unprefixed URL |
+| `/sitemap.xml` | when `sitemap_enabled` |
+| `/robots.txt` | when `robots_enabled` |
+| `{media_url_prefix}/{tenant}/{file}` | uploaded media, `max-age=31536000, immutable` |
+
+An old slug answers 301 to the page's current address. A claimed slug (below)
+answers 404 here. See [operations.md](operations.md#public-pages-caching-and-csp)
+for headers.
+
+## For other modules
+
+**Contracts.** DTOs are exported from `pagebuilder.contracts`; anything else in
+the package may change without a major version.
+
+**`PageDeleted(page_id, slug)`** (`pagebuilder.contracts.events`) is published
+on the event bus when a page is *purged* — not when it is trashed, since a
+restore would otherwise come back without what other modules dropped. A module
+that keys rows to a page id must handle it: there is no cross-module foreign key,
+and SQLite reuses ids.
+
+**Public claims** (`pagebuilder.public_claims`). A module that presents a page at
+its own address registers a claim from its startup hook:
+
+```python
+from pagebuilder import public_claims
+
+async def claim(db, slugs, locale) -> dict[str, str]:
+    # return {slug: public_path} for the slugs in `locale` this module serves
+    ...
+
+public_claims.register(claim)
+```
+
+Claims are asked in bulk, one locale at a time. A claimed slug is then refused
+(404) by `/p/{slug}`; the sitemap, `hreflang` alternates, nav links and old-slug
+redirects all point at the claimed path instead. On the same slug the earliest
+registered claim wins. `public_claims.reset()` clears them (tests).
+
+To serve the claimed page, call
+`pagebuilder.endpoints.public_views.render_public_page(slug, request, inertia,
+db, settings, url_prefix=…, locale=…)` from a router that depends on
+`tenancy.bind_public`: it applies the same ETag, cache, CSP, canonical,
+`hreflang`, nav and redirect handling.
+
+## Errors
+
+| Status | Detail | When |
+|---|---|---|
+| 401 | `Not authenticated` | no user and `requires_auth` on |
+| 403 | `tenant_required` | multi-tenant host, admin request with no tenant |
+| 403 | `Invalid or missing CSRF token` | mutating request without the header |
+| 403 | (framework) | missing permission |
+| 404 | `Page not found` / `Revision not found` / `Asset not found` / `Snapshot not found` / `Import not found` | unknown id, trashed page, other tenant's row |
+| 409 | `Slug already in use in <locale>` | create, update |
+| 409 | `Cannot submit/approve/reject a page in '<status>' status` | workflow |
+| 409 | translation exists / page already in that locale | translations |
+| 409 | `Still used on …` | checked media delete |
+| 409 | `An import is already awaiting approval` / `Import already decided` | imports |
+| 413 | `File exceeds N bytes` / `Bundle exceeds N bytes` | uploads |
+| 415 | content-type not allowed, or sniffed type mismatch | media upload |
+| 422 | validation; unconfigured locale; schedule order; unsupported bundle format | various |

simple_module_pagebuilder-0.0.11/docs/architecture.md

@@ -0,0 +1,235 @@
+# PageBuilder architecture
+
+Design records for the larger changes are under `docs/superpowers/specs/` at the
+repo root (for example `2026-10-05-pagebuilder-tenancy-design.md`). This page
+describes the code as it is.
+
+## Boundaries
+
+Pagebuilder depends on the framework (`simple_module_core`, `_db`, `_hosting`)
+and on the framework's **Settings** module (`depends_on=["Settings"]`), nothing
+else. Other modules reach it only through:
+
+| Seam | Used for |
+|---|---|
+| `pagebuilder.contracts` | DTOs; everything else is internal |
+| `PageDeleted` event | dropping rows keyed to a purged page |
+| `pagebuilder.public_claims` | serving a page at another module's address |
+| `render_public_page` | rendering a claimed page with the viewer's headers |
+| `registerPuckBlocks` (frontend) | adding blocks to the palette |
+
+A module that only *might* have pagebuilder installed (news does this) imports it
+lazily behind a guard.
+
+## Data
+
+| Table | Unique | Holds |
+|---|---|---|
+| `pagebuilder_pages` | `(tenant_id, locale, slug)`, `(tenant_id, translation_group, locale)` | title, `draft_data`, `published_data` (Puck JSON), status, SEO fields, nav flags, `parent_id`, `is_template`, schedule, `rejection_note`, `deleted_at` |
+| `pagebuilder_page_revisions` | — | one row per transition: event, note, title, meta description, og image, `data` |
+| `pagebuilder_page_redirects` | per tenant + locale + `from_slug` | old slug → `page_id` |
+| `pagebuilder_layout` | one row per tenant (lazily created) | `header_data`, `footer_data` |
+| `pagebuilder_layout_revisions` | — | one row per changed save |
+| `pagebuilder_media` | per tenant + filename | file name, original name, type, size, dimensions, folder, alt/caption/credit, `variants` |
+| `pagebuilder_snapshots`, `pagebuilder_snapshot_media`, `pagebuilder_pending_imports` | one pending import per tenant | snapshot manifests, the media each references, staged restores and their plans |
+
+Every table carries `MultiTenantMixin`; most carry `AuditMixin`
+(`created_by`/`updated_by`). `translation_group` is a generated key, not a
+pointer to an "original": translations are siblings, so deleting one orphans
+nothing. `parent_id` is breadcrumb-only and never part of the URL.
+`published_data` is kept on unpublish and restore, which is what
+`has_published` reports.
+
+## Tenancy (#38)
+
+The framework filters `MultiTenantMixin` tables only while a tenant is bound; with
+none bound a read is **unfiltered**. So every entry point binds one itself and
+never relies on one happening to be set (`pagebuilder/tenancy.py`):
+
+| Entry point | Binding |
+|---|---|
+| Admin API and views | `bind_admin` router dependency: `"default"` single-tenant; resolved tenant or 403 `tenant_required` multi-tenant |
+| Public viewer, sitemap | `bind_public`: `"default"`, or resolved tenant, or the same 404 an unknown slug gets |
+| Media files | `MediaFiles` maps the request to `<media_root>/<tenant>/` |
+| Scheduler | scans due tenants under `all_tenants()`, then one session per tenant under `tenant_context` |
+
+`bind_admin`/`bind_public` must precede `get_db` so the commit runs while the
+tenant is still bound; router-level dependencies guarantee that. The mode is
+detected once, in `on_startup`, from the built middleware stack
+(`tenancy.configure`), and a host fixed to a non-`default` tenant is refused. A
+`text()` statement on a pagebuilder table would need its own `tenant_id`
+predicate (there are none).
+
+## Boot order and settings
+
+Settings are DB-backed (`settings.PagebuilderSettings`, registered with
+`register_module_settings`; `settings_customise_sources` returns init kwargs
+only). The host hydrates them at **lifespan start**, after app construction. So:
+
+- `register_routes` reads no setting; the admin auth and CSRF dependencies read
+  `app.state.pagebuilder.settings` per request.
+- `register_public_routes` does nothing. `on_startup` (`boot.py`) exempts the
+  public prefixes (one per content locale, trailing `/` so `/p` never exempts
+  `/pagebuilder/`), mounts one `locale_router` per locale, the default-locale
+  alias, the SEO router and the media mount.
+- `CsrfCookieMiddleware` is always installed and checks `csrf_protect` per
+  request.
+
+Any field read in `on_startup` is marked `json_schema_extra=_RESTART`. Adding a
+field means adding it to the class; there is no env var to add.
+
+## Status machine (`service/_workflow.py`)
+
+| From | Action | To | Revision | Side effects |
+|---|---|---|---|---|
+| any | publish | `published` | `publish` | draft → published, clear `publish_at`, `rejection_note` |
+| any | unpublish | `draft` | `unpublish` | clear `unpublish_at` |
+| `draft` | submit | `submitted_for_review` | `submit` | clear `rejection_note` |
+| `submitted_for_review` | approve | `published` | `approve` | draft → published |
+| `submitted_for_review` | reject | `draft` | `reject` | set `rejection_note` |
+| `draft` + `publish_at` due | scheduler | `published` | `publish` ("Auto-published on schedule") | |
+| `published` + `unpublish_at` due | scheduler | `draft` | `unpublish` | |
+
+Anything else is 409. Saving (`PUT`) and restoring a revision write no revision;
+a revision always snapshots `draft_data` after the transition. Trash is
+orthogonal (`service/_trash.py`): `deleted_at` hides the row from every query via
+`NOT_TRASHED`, restore sets status `draft`, and **purge** is the one method that
+commits itself — it must commit before publishing `PageDeleted`, because a
+subscriber's own session would otherwise hit SQLite's lock and the bus swallows
+handler errors. Purge clears revisions and redirects and nulls children's
+`parent_id` explicitly (SQLite does not enforce FKs and reuses ids).
+
+## The public viewer (`endpoints/public_views.py`)
+
+```mermaid
+sequenceDiagram
+  participant V as Visitor
+  participant R as locale_router(locale)
+  participant C as public_claims
+  participant DB as pages / redirects / layout
+  V->>R: GET /de/p/about
+  R->>R: bind_public (tenant or 404)
+  R->>C: claimed_url(about, de)? → 404 if claimed
+  R->>DB: published page (slug, locale)
+  alt not found
+    R->>DB: redirects.resolve(slug, locale) → 301 to current (or claimed) URL, else 404
+  end
+  R->>DB: layout + site_nav(locale)
+  R->>R: ETag(page, layout, variant, nav) → 304 on match
+  R-->>V: Inertia PublicPage + Cache-Control, CSP, Content-Language, Vary
+```
+
+- **Title** is `meta_title` stripped, else `title`; **canonical** is
+  `canonical_url` or `public_base_url` + path; **alternates** are the group's
+  *published* pages (each resolved through claims), plus `x-default` = the
+  default locale, omitted when fewer than two.
+- **`site_nav`** (`site_nav.py`) returns published, non-trashed pages in the
+  page's locale with either flag, ordered by `lower(title)`, hrefs through
+  claims. The SiteHeader/SiteFooter widgets append them after the layout's links,
+  skipping hrefs the layout already has (trailing slash ignored, dropdown
+  children included) — `appendPages` in
+  `components/widgets/_internal/site-nav-context.tsx`. Order is the layout's.
+- **Preview** (`/pagebuilder/{id}/preview`) renders `draft_data` through the same
+  `PublicPage` component with `index_in_search=False` and no alternates, so the
+  preview cannot disagree with the live renderer.
+- **Sitemap** uses a column-only query (no block JSON), asks claims once per
+  locale, and adds `xhtml:link` alternates per translation group.
+
+Redirects (`redirects.py`) are locale-scoped. `record` first deletes any redirect
+*from* the new slug (no loops) and from the old one (re-renames move it);
+`resolve` returns the *page's* current slug, so chains collapse to one hop.
+
+## Media
+
+`media_service.upload` checks the declared type against the allowlist, sniffs
+magic bytes, requires the two to agree, names the file `<uuid><sniffed ext>`,
+streams to disk under the size cap, then generates WebP variants in a thread
+(`media_images.process_image`). Usage (`media_usage.find`) searches draft and
+published JSON for the asset's URL — both the per-tenant URL and the pre-#38 flat
+one — ignoring trashed pages.
+
+## Snapshots (`snapshots/`)
+
+- **Capture** writes pages (keyed by `(locale, slug)`), redirects and the layout
+  as JSON documents, media URLs rewritten to `asset://<name>` sentinels, media
+  bytes into a per-tenant content-addressed blob store shared across snapshots.
+  `FORMAT_VERSION` is 2; versions 1 and 2 are readable (v1 pages are read as the
+  default locale).
+- **Upload** validates the zip at the boundary (`archive.py`, `validate.py`):
+  entry names stay inside the destination, the manifest declares a readable
+  format, every blob hashes to its name, the expanded size stays under
+  `snapshot_max_extracted_bytes`.
+- **Restore** computes a plan (`plan.py`) and parks it as a `PendingImport`.
+  **Approve** takes a `pre_restore` snapshot, then `apply.apply_bundle`: media
+  matched by digest, pages upserted by `(locale, slug)` (a trashed match is
+  revived, not duplicated), parents and redirects resolved by slug in a second
+  pass, the layout saved through `LayoutService`. No page revisions are written;
+  the `pre_restore` snapshot is the before-state. Nothing is deleted.
+
+## Frontend
+
+- **Pages.** `pagebuilder/pages/*.tsx` are Inertia pages, registered by
+  `import.meta.glob`: the file name *is* the page name (`PageBuilder/PageList`).
+- **Block palette.** `components/widgetCatalog.ts` lists the built-ins and their
+  categories; `puckConfig.tsx` merges in `registerPuckBlocks` registrations
+  (`{blocks, category?, layout?}`) and is memoised on the registry version.
+  Built-in names are declared so a module cannot shadow one (a duplicate name
+  throws: names are the stored `type`). `layoutPuckConfig.tsx` is a curated
+  allowlist with **Site chrome**; blocks once offered there stay registered but
+  hidden so saved layouts keep rendering. Heavy blocks use `lazyBlock` so their
+  dependencies stay out of the entry chunk.
+- **Stored data** goes through `migrateContent` on every load (editor, public
+  page, layout) to upgrade older Puck shapes.
+- **Markdown** lives in `utils/markdown.ts` (blocks, lists, emphasis, HTML export)
+  and `utils/markdown-links.ts` (links and images with the scheme allowlist);
+  `_internal/rich-text.tsx` renders them for widget fields.
+- **i18n.** Every editor string is in `locales/en.json`, namespace
+  `pagebuilder`. `utils/i18n.ts` derives the `keys` tree from that JSON at
+  compile time, so `tsc` rejects an undefined key. Block configs are module-scope
+  constants and cannot call hooks, so their labels hold keys and
+  `localizeConfig.ts` resolves the assembled config (including `arrayFields` /
+  `objectFields`) inside `PageEditor` and `LayoutEditor`. `defaultProps` stay
+  literal: they are seed content saved into the document.
+- **Library helpers.** `conversion/` (`blocksToHtml`) and `translation/`
+  (extract and re-apply translatable strings) are pure functions with no storage.
+
+## Rules for contributors
+
+- **300-line cap** on every `.py`, `.ts` and `.tsx`, enforced by
+  `scripts/check_file_size.py` (`make lint`). Nothing under `modules/` is exempt;
+  that is why `service/`, `models/`, `endpoints/api/` and `contracts/schemas/`
+  are packages of mixins and sub-routers.
+- **Never add a file under `pagebuilder/pages/` unless it is a real Inertia
+  page.** A stray `.tsx` there silently registers a page. Extractions go to
+  `components/`, `hooks/` or `utils/`.
+- **Every slug lookup, redirect and claim takes a locale.** One that does not is
+  how `/de/p/x` starts serving the English page.
+- **Every new entry point binds a tenant** (`bind_admin`, `bind_public`, or
+  `tenant_context` outside a request). Code in another module reading these
+  tables pins `tenant_id` itself.
+- **No env vars.** New settings go on `PagebuilderSettings`; boot-time ones are
+  read from `app.state.pagebuilder.settings` in `on_startup` and marked restart.
+- **No migrations in the module.** Hosts autogenerate against the models.
+- **Literal API paths before `/pages/{page_id}`**, or `trash` parses as an id
+  (422). Same for `/uploads/{id}/checked`, which is why `media_detail` is
+  included before `uploads`.
+- New UI strings go in `locales/en.json`; `utils/i18n.test.ts` rejects unused
+  entries and unfilled placeholders.
+
+## File map
+
+| Path | Role |
+|---|---|
+| `module.py`, `boot.py` | registration hooks; startup wiring |
+| `settings.py`, `locales.py` | DB-backed settings; content-locale helpers |
+| `tenancy.py`, `security.py`, `permissions.py` | tenant binding; auth/CSRF; permissions and roles |
+| `models/`, `contracts/` | tables; public DTOs and `PageDeleted` |
+| `service/` | `PagesService` (CRUD, workflow, revisions, trash, translations) |
+| `layout_service.py`, `site_nav.py`, `redirects.py`, `public_claims.py` | layout; nav flags; old slugs; claims |
+| `media_*.py` | upload, images, queries, files, usage |
+| `scheduler.py` | per-tenant publish/unpublish/purge loop |
+| `snapshots/` | capture, archive, validate, plan, apply |
+| `endpoints/api/` | JSON API, one file per resource |
+| `endpoints/views.py`, `content_views.py` | Inertia admin views |
+| `endpoints/public_views.py`, `seo.py` | public viewer; sitemap and robots |
+| `pages/`, `components/`, `hooks/`, `utils/` | frontend |

simple_module_pagebuilder-0.0.11/docs/index.md

@@ -0,0 +1,67 @@
+# PageBuilder documentation
+
+`simple_module_pagebuilder` is the content module of a SimpleModule site. An
+editor composes **pages** from a palette of blocks in a drag-and-drop editor
+([Puck](https://puckeditor.com)); each page has a draft, a published copy, a
+revision history and an approval workflow, and is served to anonymous visitors
+at `/p/{slug}` inside a shared **site layout** (header and footer). Around that
+sit a **media library** with server-generated thumbnails, per-page SEO
+(canonical, noindex, JSON-LD, `hreflang`, a sitemap), multilingual content, and
+**snapshots** that export the whole site as a `.zip` and restore it behind an
+approval gate.
+
+Start with the document that matches what you are trying to do.
+
+## Who should read what
+
+| You are | Read |
+|---|---|
+| An editor, publisher or approver writing and publishing pages | [user-guide.md](user-guide.md) |
+| A developer calling the pagebuilder API, or presenting pages from another module | [api-reference.md](api-reference.md) |
+| An operator installing it, configuring languages and the public site, or answering "why does this page 404?" | [operations.md](operations.md) |
+| A developer changing the module or adding blocks | [architecture.md](architecture.md) |
+
+### [user-guide.md](user-guide.md) — for editors, publishers and approvers
+
+The screens under **Site** in the sidebar (Pages, Site layout, Media library,
+Import / Export), using the exact UI labels: a page's lifecycle from **New
+page** to **Delete forever**, the approval workflow, scheduling, translations,
+slugs and the redirects a rename leaves, the SEO tab, the header/footer nav
+flags, the media library, snapshots, a tour of the block palette by category,
+and what the Markdown block understands.
+
+### [api-reference.md](api-reference.md) — for integrators
+
+Every route under `/api/pagebuilder`: method, permission, request and response
+shapes, and the error table. Also the public routes, the `PageDeleted` event,
+the public-claims seam another module uses to serve a page at its own address,
+and `render_public_page`.
+
+### [operations.md](operations.md) — for operators
+
+Installing and migrating, every setting (all database-backed, none read from the
+environment, several needing a restart), turning on more languages, tenancy on a
+single- and multi-tenant host, caching, ETags and the Content-Security-Policy on
+public pages, the scheduler, storage on disk, and a troubleshooting table that
+starts from the symptom.
+
+### [architecture.md](architecture.md) — for maintainers
+
+The tables, how a request binds a tenant, why boot-time settings are read in
+`on_startup`, the status machine as a table, how the public viewer assembles a
+page (claims, redirects, nav, ETag), how snapshots are captured and applied, the
+frontend's block registry and i18n, and the contributor rules: the 300-line cap
+and what may live under `pagebuilder/pages/`.
+
+## The module in one paragraph
+
+A page is one row with a `draft_data` and a `published_data` Puck document.
+Editing writes the draft; **Publish** (or **Approve** after **Submit for
+review**) copies the draft to the published copy and writes a revision. A page
+is written in exactly one language for its lifetime; a translation is a sibling
+page sharing a `translation_group`, with its own slug, draft and workflow. Slugs
+are unique per tenant and language, and a rename records a redirect from the old
+slug. Deleting moves a page to the trash for 30 days; purging removes it and
+announces `PageDeleted`. Every table is tenant-owned, and every entry point binds
+a tenant before it reads anything. Settings live in the database and are edited
+on the Settings screen; the ones that decide routes need a restart.