Merge branch 'main' into fix/inertia-json-encoder-and-cache

Author: antosubash

CHANGELOG.md

@@ -28,6 +28,26 @@ All notable changes to this project are documented in this file. The format is b
   production-mode containers pass `UsersSettings` boot validation.
 
 ### Fixed
+- Public pages no longer reload the whole document when a visitor clicks a link
+  in authored content. A simple_module app is client-rendered — the root
+  template ships `<div id="app"></div>` empty — so a navigation that creates a
+  new document paints a blank white body until the bundle has booted. Admin
+  screens were never affected because the shell navigates with Inertia's
+  `<Link>`, but pagebuilder widgets and their markdown/rich-text fields render
+  author-entered URLs as plain `<a href>`, and there is no component to swap for
+  a `<Link>` when the anchor comes out of a markdown parser. A downstream site
+  measured ~330ms of blank viewport per click on a throttled connection.
+  `@simple-module-py/ui` now exports `startSpaLinkInterception()`, a delegated
+  click handler that routes same-origin page links through Inertia whatever
+  produced the anchor; the `smpy new` app template calls it. It deliberately
+  leaves alone anything Inertia cannot render — other origins, non-http schemes,
+  paths that look like a file, in-page anchors, `download`/`target`/
+  `rel="external"`/`data-native-link`, and anchors inside a Puck editor surface
+  — and falls back to a hard navigation if a visit returns without an
+  `x-inertia` header, so a media download can never be replaced by an error
+  modal. **Existing apps must add the one-line call to their own
+  `host/client_app/app.tsx`**, which is scaffold output and so is not upgraded
+  for them.
 - `smpy gen-pages` now emits module stylesheet `@import` lines as **absolute
   paths** instead of `#module/<pkg>` alias specifiers. The alias only resolved
   if the host's `vite.config.ts` defined a matching `resolve.alias` — but that

docs/frontend/inertia.md

@@ -149,6 +149,55 @@ createInertiaApp({
 
 `resolvePage` lives in `host/client_app/pages.ts` (hand-written). It builds a page-key → loader map from `moduleGlobs` (the `import.meta.glob` calls in the generated `modules.generated.ts`) plus the host's own `./pages/**/*.tsx` glob, mapping a page key (e.g. `"Orders/Browse"`) to a dynamic import of the matching `.tsx` file.
 
+
+## Link navigation
+
+The app is client-rendered: the root template ships `<div id="app"></div>` empty
+and `app.tsx` fills it. So a navigation that creates a **new document** shows a
+blank white page until the bundle has booted — which is what a plain
+`<a href="/somewhere">` does.
+
+Admin screens use Inertia's `<Link>` and are fine. The problem is authored
+content: pagebuilder widgets, and the markdown and rich-text fields inside them,
+turn author-entered URLs into plain anchors. An anchor that comes out of a
+markdown parser has no component to swap for a `<Link>`.
+
+`app.tsx` therefore calls `startSpaLinkInterception()` once, before the first
+render:
+
+```tsx
+import { startSpaLinkInterception } from "@simple-module-py/ui/lib/spa-links";
+
+setup({ el, App, props }) {
+  startSpaLinkInterception();
+  createRoot(el).render(<App {...props} />);
+}
+```
+
+It delegates one `click` listener on the document and routes same-origin page
+links through `router.visit()`, whatever produced the anchor. It runs in the
+bubble phase, so a `<Link>` — which cancels the event itself — is already
+`defaultPrevented` and is left alone rather than visited twice.
+
+The bias is towards **not** interfering. These keep the browser's own behaviour:
+
+| Left alone | Why |
+| --- | --- |
+| Another origin, or a non-http scheme (`mailto:`, `tel:`) | Not ours to route |
+| A path whose last segment looks like a file (`/media/report.pdf`) | Inertia would request it expecting a page and raise its error modal over the download |
+| `#`, `#section`, or a link to the current path | The browser scrolls correctly; `href="#"` is also what an unfilled pagebuilder nav row holds |
+| `download`, `target` other than `_self`, `rel="external"` | The author asked for it |
+| `data-native-link` | Explicit opt-out for anything the rules miss |
+| Anything inside `[data-puck-preview]` / `[data-puck-component]` | A Puck editor rendering without an iframe puts the edited page's real anchors in the admin document |
+| Modified clicks (⌘/ctrl/shift/alt) and non-left buttons | Open-in-new-tab must keep working |
+
+As a backstop, a visit that comes back **without** an `x-inertia` header is
+handed to the browser as a hard navigation, so a URL that turns out not to be a
+page still resolves instead of raising the error modal.
+
+`smpy new` wires this into the app template. An app scaffolded before this
+landed owns its own `app.tsx` and must add the call itself.
+
 ## CSRF
 
 There is no explicit CSRF token middleware. Protection comes from `SameSite=Lax` on the session cookie:

docs/modules/branding.md

@@ -1,8 +1,8 @@
 # branding
 
-White-labels the application. An administrator sets the **app name**, **logo** (plus an optional dark-background variant), **favicon**, **primary colour**, **[design pack](/framework-conventions#design-packs-site-wide-look)**, a site-wide **announcement banner**, and a **configurable footer** — from an admin page, with no code change or redeploy.
+White-labels the application. An administrator sets the **app name**, **logo** (plus an optional dark-background variant), **favicon**, **primary colour**, **[design pack](/framework-conventions#design-packs-site-wide-look)**, and a site-wide **announcement banner** — from an admin page, with no code change or redeploy.
 
-Values persist in the shared [settings](/modules/settings) store (there is no branding table) and reach **every** Inertia page — authenticated *and* guest — through a registered shared-props provider, so the frontend can render the name, swap the logo/favicon, apply the brand colour, and show the banner and footer everywhere.
+Values persist in the shared [settings](/modules/settings) store (there is no branding table) and reach **every** Inertia page — authenticated *and* guest — through a registered shared-props provider, so the frontend can render the name, swap the logo/favicon, apply the brand colour, and show the banner everywhere. Footer content is owned by the framework site layouts, not branding.
 
 ## ModuleMeta
 
@@ -27,16 +27,14 @@ Every JSON endpoint — including the reads — requires `branding.manage`; they
 | `GET /api/branding/` | → `BrandingOut` |
 | `PUT /api/branding/` | `BrandingUpdate` → `BrandingOut` |
 | `POST /api/branding/presets/{key}` | → `BrandingOut` (`404` for an unknown key) |
-| `GET /api/branding/footer` | → `FooterConfig` |
-| `PUT /api/branding/footer` | `FooterConfig` → `FooterConfig` (whole-object replace) |
 | `POST /api/branding/logo` | `multipart` (field `file`) → `BrandingOut` |
 | `POST /api/branding/logo-dark` | `multipart` (field `file`) → `BrandingOut` |
 | `POST /api/branding/favicon` | `multipart` (field `file`) → `BrandingOut` |
 | `DELETE /api/branding/logo` | → `BrandingOut` (logo cleared) |
 | `DELETE /api/branding/logo-dark` | → `BrandingOut` (dark logo cleared) |
 | `DELETE /api/branding/favicon` | → `BrandingOut` (favicon cleared) |
 
-`PUT /` only touches the text fields (`app_name`, `primary_color`, `design_pack`, `banner_message`, `banner_severity`); images are set and cleared through their dedicated upload/delete routes, and the footer through `PUT /footer`. A `design_pack` slug that no installed module registered is rejected with `422` — accepting it would put `"<slug>-root"` on the document with no stylesheet behind it, so the site would look unchanged with nothing in the UI explaining why.
+`PUT /` only touches the text fields (`app_name`, `primary_color`, `design_pack`, `banner_message`, `banner_severity`); images are set and cleared through their dedicated upload/delete routes. A `design_pack` slug that no installed module registered is rejected with `422` — accepting it would put `"<slug>-root"` on the document with no stylesheet behind it, so the site would look unchanged with nothing in the UI explaining why.
 
 Uploads are validated **before** the bytes reach `file_storage`: an unsupported or unconvincing type returns `415`, an oversized image `413` (see [Image guard-rails](#image-guard-rails)).
 
@@ -79,16 +77,12 @@ An unversioned URL can serve new bytes later, so it must never be immutable; the
 
 ```python
 from branding.contracts import BrandingOut, BrandingUpdate
-from branding.contracts.footer import FooterConfig, FooterColumn, FooterLink
 ```
 
 | Class | Purpose |
 |---|---|
 | `BrandingOut` | Current branding with images resolved to URLs: `app_name`, `primary_color`, `design_pack`, `logo_url`, `logo_dark_url`, `favicon_url`, `banner_message`, `banner_severity`. |
 | `BrandingUpdate` | Editable text fields, all optional: `app_name`, `primary_color`, `design_pack`, `banner_message`, `banner_severity`. |
-| `FooterConfig` | The whole footer: `tagline`, `copyright_owner`, `note`, `columns`, `social_links`. |
-| `FooterColumn` | A titled group: `title` + `links`. |
-| `FooterLink` | One `label` + `href`. |
 
 `BrandingUpdate` is the strict one. An unknown `banner_severity` is a clear `422` here, while the settings validator normalises it to `info` — settings hydrate from the DB, where a hand-edited row must degrade to a readable banner rather than stop the app from booting. `design_pack` and `primary_color` are shape-checked in the DTO for the same reason: a malformed value becomes a `422` instead of a `500` when `BrandingSettings` re-validates.
 
@@ -110,16 +104,9 @@ DB-backed via `register_module_settings`; pydantic defaults seed at boot. Edited
 | `favicon_file_id` | `""` | UUID of the favicon; `""` ⇒ no custom favicon. |
 | `banner_message` | `""` | Site-wide announcement text (≤ 500 chars); `""` ⇒ no banner. |
 | `banner_severity` | `"info"` | One of `info`, `warning`, `danger`. Unknown values normalise to `info`. |
-| `footer_tagline` | `""` | Footer tagline line. |
-| `footer_copyright_owner` | `""` | Name in the copyright line. |
-| `footer_note` | `""` | Small footer caption. |
-| `footer_columns` | `""` | JSON blob of `FooterColumn` entries (see [Configurable footer](#configurable-footer)). |
-| `footer_social_links` | `""` | JSON blob of `FooterLink` entries. |
 
 `app_name` rejects control characters, not just blanks: the name is used in HTML titles and — critically — email `Subject` headers, where an embedded CR/LF would survive a bare `strip()` and then raise, breaking every transactional email.
 
-The two footer lists are strings because the settings store holds strings; `branding.footer` owns (de)serialising them, leniently, so a malformed row degrades to "no configured footer" rather than an error. Each blob is capped at 8 000 characters so a single setting row can't grow unbounded.
-
 ### Image guard-rails
 
 Enforced in the API before the upload reaches `file_storage`:
@@ -160,23 +147,6 @@ A message plus a severity, rendered above every shell — app, public and auth 
 
 Severity colours are semantic, not brand-tinted: a warning wearing the deployment's accent colour stops reading as a warning.
 
-## Configurable footer
-
-Whole-object replace via `PUT /api/branding/footer` — a partial merge into nested link lists has no obvious semantics.
-
-| Limit | Value |
-|---|---|
-| Columns | 6 |
-| Links per column | 8 |
-| Social links | 8 |
-| Link label / column title | 40 chars |
-| Link URL | 500 chars |
-| Tagline / copyright / note | 200 chars |
-
-Link URLs are restricted to `http(s)` or a single-leading-slash app path. This is the security-relevant part: these are authored by an admin and rendered into an anchor on *every* page, including guest ones, so the scheme allow-list is what keeps a `javascript:` URL out of the document. `//host` is a protocol-relative absolute URL rather than a path, so it falls through to the scheme check and is rejected.
-
-With nothing configured the shared prop reports `footer: null` and the framework's built-in footer renders unchanged.
-
 ## Dark-background logo
 
 The sidebar and mobile bar sit on a near-black surface in every theme, while the sign-in card and public page are light — so a single logo cannot read on both. Uploading a *Logo (dark backgrounds)* variant swaps it in on those surfaces only.
@@ -196,19 +166,12 @@ On startup the module registers a shared-props provider (`register_inertia_share
     "logoUrl": "/api/branding/logo?v=<file id>",
     "logoDarkUrl": "/api/branding/logo-dark?v=<file id>",
     "faviconUrl": "/api/branding/favicon?v=<file id>",
-    "banner": { "message": "Maintenance at 22:00 UTC", "severity": "warning" },
-    "footer": {
-      "tagline": "Maps for everyone",
-      "copyrightOwner": "Acme Corp",
-      "note": "",
-      "columns": [{ "title": "Product", "links": [{ "label": "Docs", "href": "/docs" }] }],
-      "socialLinks": [{ "label": "GitHub", "href": "https://github.com/acme" }]
-    }
+    "banner": { "message": "Maintenance at 22:00 UTC", "severity": "warning" }
   }
 }
 ```
 
-`primaryColor` and `designPack` are `null` when unset; the three image URLs are `null` when no file is configured. `banner` is `null` when no message is set, so the frontend renders nothing at all rather than an empty bar, and `footer` is `null` when nothing is configured, so the built-in framework footer stays.
+`primaryColor` and `designPack` are `null` when unset; the three image URLs are `null` when no file is configured. `banner` is `null` when no message is set, so the frontend renders nothing at all rather than an empty bar.
 
 The provider is defensive — it returns `{}` if branding state isn't mounted yet, so a half-booted app never errors a render. Because changes go through the settings store, a save hot-reloads `app.state.branding.settings`; the next render reflects the new values without a restart.
 
@@ -217,7 +180,7 @@ The provider is defensive — it returns `{}` if branding state isn't mounted ye
 | Code | Granted to | Purpose |
 |---|---|---|
 | `branding.view` | `admin` | open the Branding admin page (`/branding`) |
-| `branding.manage` | `admin` | read + write branding via the API (name, colour, design pack, banner, footer, image upload/clear) |
+| `branding.manage` | `admin` | read + write branding via the API (name, colour, design pack, banner, image upload/clear) |
 
 ## Menu
 
@@ -227,7 +190,7 @@ The provider is defensive — it returns `{}` if branding state isn't mounted ye
 
 ## Inertia pages
 
-- `Branding/Manage.tsx` — the admin editor: app name, colour and design pack, preset picker, logo / dark logo / favicon upload and clear, banner editor, footer editor, and a live preview.
+- `Branding/Manage.tsx` — the admin editor: app name, colour and design pack, preset picker, logo / dark logo / favicon upload and clear, banner editor, and a live preview.
 
 ## Locales
 

docs/modules/index.md

@@ -11,7 +11,7 @@ simple_module_python ships with twelve first-party modules. Each is a regular Py
 | [`settings`](/modules/settings) | — | DB-backed key/value store with system / tenant / user precedence; per-module pydantic settings registration; hot reload; `smpy settings` CLI. |
 | [`feature_flags`](/modules/feature_flags) | — | Runtime feature toggles with system + tenant overrides. |
 | [`file_storage`](/modules/file_storage) | `settings` | Pluggable file storage (filesystem, S3-compatible) with upload validation, presigned URLs, browse/download/delete UI. |
-| [`branding`](/modules/branding) | `settings`, `file_storage` | White-labelling — app name, logo (plus a dark-background variant), favicon, primary colour, design pack, announcement banner and configurable footer, pushed to every page via Inertia shared props. Serves the logo and favicon from anonymous routes so guests see the brand too. |
+| [`branding`](/modules/branding) | `settings`, `file_storage` | White-labelling — app name, logo (plus a dark-background variant), favicon, primary colour, design pack and announcement banner, pushed to every page via Inertia shared props. Serves the logo and favicon from anonymous routes so guests see the brand too. |
 | [`background_tasks`](/modules/background_tasks) | `users` | Celery + Redis workers, persistent task history, retry, stuck-task sweep, live worker dashboard. |
 | [`audit_log`](/modules/audit_log) | `users` | Automatic field-level audit trail for SQLModel entities, with an admin UI to browse change history. |
 | [`dashboard`](/modules/dashboard) | `users` | Authenticated landing page with system overview (user counts, module list, health checks). |

framework/cli/simple_module_cli/templates/host/client_app/app.tsx

@@ -1,5 +1,6 @@
 import { createInertiaApp, router } from '@inertiajs/react';
 import { configureI18n, updateI18n } from '@simple-module-py/i18n';
+import { startSpaLinkInterception } from '@simple-module-py/ui/lib/spa-links';
 import { createRoot } from 'react-dom/client';
 import { resolvePage } from './pages';
 
@@ -28,6 +29,11 @@ createInertiaApp({
         activeLocale = block.locale;
       }
     });
+    // Authored content (pagebuilder widgets, markdown and rich-text fields)
+    // renders author-entered URLs as plain <a href>, which the browser would
+    // follow with a full document load. This app is client-rendered, so that
+    // means a blank page until the bundle boots. Route them through Inertia.
+    startSpaLinkInterception();
     createRoot(el).render(<App {...props} />);
   },
   progress: {

host/client_app/app.tsx

@@ -1,6 +1,7 @@
 import { createInertiaApp, router } from '@inertiajs/react';
 import { ErrorBoundary } from '@simple-module-py/ui/components/ErrorBoundary';
 import { formatTitle, setTitleAppName } from '@simple-module-py/ui/lib/app-title';
+import { startSpaLinkInterception } from '@simple-module-py/ui/lib/spa-links';
 import { useEffect, useRef } from 'react';
 import { createRoot } from 'react-dom/client';
 import { bootI18nFromInitialPage, subscribeI18nToNavigation } from './i18n';
@@ -29,9 +30,14 @@ createInertiaApp({
       useEffect(() => {
         const stopReset = router.on('navigate', () => boundaryRef.current?.reset());
         const stopI18n = subscribeI18nToNavigation();
+        // Authored content renders author-entered URLs as plain <a href>, which
+        // the browser follows with a full document load — a blank page until
+        // this client-rendered app boots again. Route them through Inertia.
+        const stopLinks = startSpaLinkInterception();
         return () => {
           stopReset();
           stopI18n();
+          stopLinks();
         };
       }, []);
 

modules/branding/README.md

@@ -43,10 +43,9 @@ modules to be installed too.
 
 Programmatically, the current branding is available on every page through the
 `branding` Inertia shared prop (`appName`, `primaryColor`, `designPack`,
-`logoUrl`, `logoDarkUrl`, `faviconUrl`, `banner`, `footer`). `banner` and
-`footer` are `null` when unconfigured, which is what makes the frontend fall
-back to rendering nothing and to the framework footer respectively. For a dark
-surface use
+`logoUrl`, `logoDarkUrl`, `faviconUrl`, `banner`). `banner` is `null` when
+unconfigured, which makes the frontend render nothing. Footer content is owned
+by the framework site layouts rather than branding. For a dark surface use
 `darkSurfaceLogo(branding)` from `@simple-module-py/ui/lib/brand`, which applies
 the `logoDarkUrl → logoUrl` fallback in one place.
 
@@ -78,12 +77,6 @@ the `logoDarkUrl → logoUrl` fallback in one place.
   ever sets *appearance* (`PRESET_FIELDS` — primary colour, design pack); it
   can never overwrite the app name, an uploaded logo or a live banner, and
   `BrandingPreset` rejects any other field at construction.
-- **Configurable footer.** Tagline, copyright owner, caption, up to 6 columns
-  of 8 links, and up to 8 social links (`PUT /api/branding/footer`, whole-object
-  replace). Link URLs are restricted to http(s) or a single-leading-slash app
-  path — `javascript:` and `data:` are refused, and `//host` is treated as the
-  off-site absolute URL it is rather than a path. With nothing configured the
-  framework's built-in footer renders unchanged.
 - **Dark-background logo.** The sidebar and mobile bar sit on a near-black
   surface in every theme, while the sign-in card and public page are light — so
   a single logo cannot read on both. Uploading a *Logo (dark backgrounds)*