simple-module-pagebuilder 0.0.3__tar.gz → 0.0.4__tar.gz

{simple_module_pagebuilder-0.0.3 → simple_module_pagebuilder-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_pagebuilder
-Version: 0.0.3
+Version: 0.0.4
 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>
@@ -81,6 +81,38 @@ Once installed and migrated, sign in and open `/pagebuilder`:
 Every transition writes a revision, so `/pagebuilder/{id}/edit` can compare any
 two revisions and restore either one as a draft.
 
+## Contributing blocks from another module
+
+A module ships Puck blocks by calling `registerPuckBlocks` from its
+`puck-blocks.ts`; the host imports every module's registration eagerly at app
+start, so the registry is populated before the first render.
+
+Because registration is eager, a block that statically imports a heavy render
+component puts that component's whole dependency graph in the entry chunk —
+on every page of the site, for every visitor. Measured on a consuming site, a
+map block's static import put maplibre-gl (1 MB minified, 62% of the bundle)
+in front of visitors who never opened the map. Register heavy blocks with
+`lazyBlock` instead, which keeps fields and defaults eager but loads the
+component the first time a page actually renders the block:
+
+```tsx
+import { lazyBlock } from '@simple-module-py/pagebuilder/pagebuilder/components/lazyBlock';
+import { registerPuckBlocks } from '@simple-module-py/pagebuilder/pagebuilder/components/blockRegistry';
+
+registerPuckBlocks({
+  blocks: {
+    AtlasMap: lazyBlock(
+      () => import('./components/AtlasMap').then((m) => m.AtlasMapEmbed),
+      { label: 'Atlas map', fields: { /* … */ }, defaultProps: { /* … */ } },
+      (props) => <div className={heightClass[props.height]} aria-busy="true" />,
+    ),
+  },
+});
+```
+
+Light blocks (text, cards, lists) can keep their static imports — the split
+only pays for itself when the component drags in something big.
+
 ## Migrations
 
 This module ships **no** migrations — that is the framework convention. Its

{simple_module_pagebuilder-0.0.3 → simple_module_pagebuilder-0.0.4}/README.md

@@ -59,6 +59,38 @@ Once installed and migrated, sign in and open `/pagebuilder`:
 Every transition writes a revision, so `/pagebuilder/{id}/edit` can compare any
 two revisions and restore either one as a draft.
 
+## Contributing blocks from another module
+
+A module ships Puck blocks by calling `registerPuckBlocks` from its
+`puck-blocks.ts`; the host imports every module's registration eagerly at app
+start, so the registry is populated before the first render.
+
+Because registration is eager, a block that statically imports a heavy render
+component puts that component's whole dependency graph in the entry chunk —
+on every page of the site, for every visitor. Measured on a consuming site, a
+map block's static import put maplibre-gl (1 MB minified, 62% of the bundle)
+in front of visitors who never opened the map. Register heavy blocks with
+`lazyBlock` instead, which keeps fields and defaults eager but loads the
+component the first time a page actually renders the block:
+
+```tsx
+import { lazyBlock } from '@simple-module-py/pagebuilder/pagebuilder/components/lazyBlock';
+import { registerPuckBlocks } from '@simple-module-py/pagebuilder/pagebuilder/components/blockRegistry';
+
+registerPuckBlocks({
+  blocks: {
+    AtlasMap: lazyBlock(
+      () => import('./components/AtlasMap').then((m) => m.AtlasMapEmbed),
+      { label: 'Atlas map', fields: { /* … */ }, defaultProps: { /* … */ } },
+      (props) => <div className={heightClass[props.height]} aria-busy="true" />,
+    ),
+  },
+});
+```
+
+Light blocks (text, cards, lists) can keep their static imports — the split
+only pays for itself when the component drags in something big.
+
 ## Migrations
 
 This module ships **no** migrations — that is the framework convention. Its

{simple_module_pagebuilder-0.0.3 → simple_module_pagebuilder-0.0.4}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simple-module-py/pagebuilder",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "private": true,
   "description": "Frontend assets for the PageBuilder module",
   "peerDependencies": {

simple_module_pagebuilder-0.0.4/pagebuilder/components/lazyBlock.tsx

@@ -0,0 +1,58 @@
+/**
+ * Register a Puck block whose render component loads on demand (issue #16).
+ *
+ * Block registration is eager by design — the host imports every module's
+ * `puck-blocks.ts` before first render so the registry is populated when a
+ * page reads the Puck config. But a registration that statically imports its
+ * render component drags the component's whole dependency graph into the
+ * entry chunk, on every page of the site. Measured on a consuming site, a
+ * map block put maplibre-gl — 1 MB minified, 62% of the bundle — in front
+ * of every visitor.
+ *
+ * `lazyBlock` keeps the cheap parts eager (fields, defaults, labels) and
+ * loads the component the first time a page actually renders the block:
+ *
+ * ```tsx
+ * registerPuckBlocks({
+ *   blocks: {
+ *     CanopyAtlasMap: lazyBlock(
+ *       () => import('./components/CanopyAtlasMap').then((m) => m.CanopyAtlasMapEmbed),
+ *       {
+ *         label: 'Canopy Atlas map',
+ *         fields: { height: { type: 'select', options: HEIGHTS } },
+ *         defaultProps: { height: 'screen' },
+ *       },
+ *       (props) => <div className={heightClass[props.height]} aria-busy="true" />,
+ *     ),
+ *   },
+ * });
+ * ```
+ */
+
+import { type ComponentType, lazy, type ReactNode, Suspense } from 'react';
+
+import type { AnyBlock } from './blockRegistry';
+
+// Typed via AnyBlock rather than a precise ComponentConfig<P>: Puck's config
+// generic carries constraints a pass-through helper cannot restate, and the
+// registry these blocks land in erases the props type anyway.
+// biome-ignore lint/suspicious/noExplicitAny: heterogeneous block props, same as AnyBlock
+type AnyProps = Record<string, any>;
+
+export function lazyBlock<P extends AnyProps>(
+  load: () => Promise<ComponentType<P>>,
+  config: Omit<AnyBlock, 'render'>,
+  /** Rendered while the chunk downloads — size it like the block to avoid
+   *  layout shift. Defaults to nothing. */
+  fallback?: (props: P) => ReactNode,
+): AnyBlock {
+  const Lazy = lazy(async () => ({ default: await load() }));
+  return {
+    ...config,
+    render: (props: AnyProps) => (
+      <Suspense fallback={fallback ? fallback(props as P) : null}>
+        <Lazy {...(props as P)} />
+      </Suspense>
+    ),
+  };
+}

{simple_module_pagebuilder-0.0.3 → simple_module_pagebuilder-0.0.4}/pagebuilder/components/widgets/_shared/background-media.tsx

@@ -1,4 +1,5 @@
 import { cn, decorativeAriaProps } from '../../../utils/widgetUtils';
+import { SIZES_FULL, srcsetAttrs } from './image-srcset';
 
 export type BackgroundMediaOverlay = 'none' | 'subtle' | 'dark';
 export type BackgroundMediaFallback = 'gradient-mesh' | 'solid';
@@ -15,6 +16,8 @@ export type BackgroundMediaProps = {
    * anchors to the top; centered, the sky is cut away). Omitted = centered.
    */
   objectPosition?: string;
+  /** Variant srcset recorded at pick time (see _shared/image-srcset.ts). */
+  imageSrcset?: string;
 };
 
 // The "dark" scrim strength is tenant-tunable: GCA's Figma hero is nearly
@@ -41,6 +44,7 @@ export function BackgroundMedia({
   overlay = 'none',
   fallback = 'gradient-mesh',
   objectPosition,
+  imageSrcset,
 }: BackgroundMediaProps) {
   // data-pb-* attributes are stable selectors for tests and CMS-side analytics.
   return (
@@ -48,6 +52,7 @@ export function BackgroundMedia({
       {imageUrl ? (
         <img
           src={imageUrl}
+          {...srcsetAttrs(imageSrcset, SIZES_FULL)}
           alt={imageAlt ?? ''}
           {...decorativeAriaProps(imageAlt)}
           loading="lazy"

{simple_module_pagebuilder-0.0.3 → simple_module_pagebuilder-0.0.4}/pagebuilder/components/widgets/_shared/content-media.tsx

@@ -1,4 +1,5 @@
 import { cn, decorativeAriaProps } from '../../../utils/widgetUtils';
+import { srcsetAttrs } from './image-srcset';
 
 export type ContentMediaAspect = 'square' | 'video' | 'portrait';
 
@@ -6,6 +7,10 @@ export type ContentMediaProps = {
   imageUrl: string;
   imageAlt: string;
   aspect?: ContentMediaAspect;
+  /** Variant srcset recorded at pick time (see _shared/image-srcset.ts). */
+  imageSrcset?: string;
+  /** `sizes` for the srcset; callers in split layouts pass SIZES_HALF. */
+  sizes?: string;
 };
 
 const ASPECT_CLASSES: Record<ContentMediaAspect, string> = {
@@ -23,13 +28,20 @@ const DOTTED_STYLE = {
   backgroundSize: '16px 16px, 100% 100%',
 } as const;
 
-export function ContentMedia({ imageUrl, imageAlt, aspect = 'video' }: ContentMediaProps) {
+export function ContentMedia({
+  imageUrl,
+  imageAlt,
+  aspect = 'video',
+  imageSrcset,
+  sizes = '100vw',
+}: ContentMediaProps) {
   const wrapperCls = cn('w-full rounded-xl overflow-hidden', ASPECT_CLASSES[aspect], 'shadow-xl');
   if (imageUrl) {
     return (
       <div className={wrapperCls}>
         <img
           src={imageUrl}
+          {...srcsetAttrs(imageSrcset, sizes)}
           alt={imageAlt ?? ''}
           {...decorativeAriaProps(imageAlt)}
           loading="lazy"

simple_module_pagebuilder-0.0.4/pagebuilder/components/widgets/_shared/image-srcset.ts

@@ -0,0 +1,55 @@
+/** Responsive-image support for picker-backed widgets (issue #15).
+ *
+ * The media library generates WebP variants at upload, but widgets that
+ * store a bare `imageUrl` string shipped the full-size original to every
+ * viewport. These helpers let a widget persist the variant srcset next to
+ * the URL the same way the Image block does: `resolveImageSrcset` runs as
+ * Puck's `resolveData` when the picked URL changes, and the value lands in
+ * block data so the public render needs no lookup at all. Old content
+ * without the prop renders exactly as before.
+ */
+
+import { buildSrcset, lookupAsset } from '../../../utils/mediaApi';
+
+/** Full-bleed imagery (background heroes, banners). */
+export const SIZES_FULL = '100vw';
+
+/** Half-width split layouts (side hero, media object) — full width stacked. */
+export const SIZES_HALF = '(min-width: 1024px) 50vw, 100vw';
+
+/** Field for the persisted srcset — visible so an author can override it. */
+export const imageSrcsetField = {
+  type: 'textarea',
+  label: 'Image srcset (auto-filled from the media library)',
+} as const;
+
+/** Spreadable `<img>` attributes; nothing when no srcset is recorded. */
+export function srcsetAttrs(
+  srcset: string | undefined,
+  sizes: string,
+): { srcSet: string; sizes: string } | Record<string, never> {
+  return srcset ? { srcSet: srcset, sizes } : {};
+}
+
+type SrcsetProps = { imageUrl: string; imageSrcset?: string };
+
+/** `resolveData` for any widget with `imageUrl` + `imageSrcset` props.
+ *  `changed` is typed to just the key read here — Puck's own param type
+ *  (which also carries `id: string`) stays assignable. */
+export async function resolveImageSrcset<P extends SrcsetProps>(
+  { props }: { props: P },
+  { changed }: { changed: { imageUrl?: unknown } },
+): Promise<{ props: P }> {
+  if (!changed.imageUrl) return { props };
+  if (!props.imageUrl) return { props: { ...props, imageSrcset: '' } };
+  let asset: Awaited<ReturnType<typeof lookupAsset>>;
+  try {
+    asset = await lookupAsset(props.imageUrl);
+  } catch {
+    // Network failure mid-edit shouldn't break the editor — keep the picked
+    // URL and let the image serve without variants.
+    return { props };
+  }
+  if (!asset) return { props };
+  return { props: { ...props, imageSrcset: buildSrcset(asset) } };
+}

{simple_module_pagebuilder-0.0.3 → simple_module_pagebuilder-0.0.4}/pagebuilder/components/widgets/_shared/index.ts

@@ -26,6 +26,13 @@ export type {
   HeadingTone,
 } from './heading';
 export { Heading } from './heading';
+export {
+  imageSrcsetField,
+  resolveImageSrcset,
+  SIZES_FULL,
+  SIZES_HALF,
+  srcsetAttrs,
+} from './image-srcset';
 export {
   EYEBROW_CASE_STYLE,
   eyebrowTextStyle,

simple_module_pagebuilder-0.0.4/pagebuilder/components/widgets/hero-widget-props.ts

@@ -0,0 +1,33 @@
+/** Prop shape for HeroWidget — extracted so hero-widget.tsx stays under the
+ *  repo's 300-line cap. Re-exported from there, so importers are unaffected. */
+
+export type HeroWidgetProps = {
+  eyebrow: string;
+  title: string;
+  subtitle: string;
+  logoUrl: string;
+  logoAlt: string;
+  imageUrl: string;
+  imageAlt: string;
+  /** Variant srcset recorded at pick time (see _shared/image-srcset.ts). */
+  imageSrcset?: string;
+  /**
+   * Organic mask (SVG url, from the tenant's content) applied to the side
+   * image in the right/left layouts. Empty = the standard rounded media.
+   */
+  imageMaskUrl?: string;
+  /**
+   * "native" renders supplied transparent artwork exactly as-is — no mask, no
+   * crop — for a photo already cut to its final organic shape. Preferred over
+   * `imageMaskUrl`, which re-derives the silhouette from a hand-kept SVG.
+   */
+  imageShape?: 'rounded' | 'native';
+  imagePosition: 'background' | 'right' | 'left';
+  primaryLabel: string;
+  primaryHref: string;
+  secondaryLabel: string;
+  secondaryHref: string;
+  overlay: boolean;
+  align: 'left' | 'center';
+  surface: 'plain' | 'card';
+};

{simple_module_pagebuilder-0.0.3 → simple_module_pagebuilder-0.0.4}/pagebuilder/components/widgets/hero-widget.tsx

@@ -8,38 +8,17 @@ import {
   CTAButton,
   EyebrowText,
   Heading,
+  imageSrcsetField,
   maskStyle,
+  resolveImageSrcset,
   Section,
+  SIZES_HALF,
+  srcsetAttrs,
 } from './_shared';
 
-export type HeroWidgetProps = {
-  eyebrow: string;
-  title: string;
-  subtitle: string;
-  logoUrl: string;
-  logoAlt: string;
-  imageUrl: string;
-  imageAlt: string;
-  /**
-   * Organic mask (SVG url, from the tenant's content) applied to the side
-   * image in the right/left layouts. Empty = the standard rounded media.
-   */
-  imageMaskUrl?: string;
-  /**
-   * "native" renders supplied transparent artwork exactly as-is — no mask, no
-   * crop — for a photo already cut to its final organic shape. Preferred over
-   * `imageMaskUrl`, which re-derives the silhouette from a hand-kept SVG.
-   */
-  imageShape?: 'rounded' | 'native';
-  imagePosition: 'background' | 'right' | 'left';
-  primaryLabel: string;
-  primaryHref: string;
-  secondaryLabel: string;
-  secondaryHref: string;
-  overlay: boolean;
-  align: 'left' | 'center';
-  surface: 'plain' | 'card';
-};
+import type { HeroWidgetProps } from './hero-widget-props';
+
+export type { HeroWidgetProps } from './hero-widget-props';
 
 // Exported so CenteredHeroWidget can render through it without smuggling
 // Puck's ComponentConfig.render signature past the type system.
@@ -51,6 +30,7 @@ export function renderHero({
   logoAlt,
   imageUrl,
   imageAlt,
+  imageSrcset = '',
   imageMaskUrl = '',
   imageShape = 'rounded',
   imagePosition,
@@ -120,6 +100,7 @@ export function renderHero({
         <BackgroundMedia
           imageUrl={imageUrl}
           imageAlt={imageAlt}
+          imageSrcset={imageSrcset}
           overlay={overlay ? 'dark' : 'none'}
           fallback="gradient-mesh"
           objectPosition="var(--pb-hero-image-position, 50% 50%)"
@@ -189,6 +170,7 @@ export function renderHero({
             // Figma's box width. No mask, no crop — the file IS the shape.
             <img
               src={imageUrl}
+              {...srcsetAttrs(imageSrcset, SIZES_HALF)}
               alt={imageAlt || title}
               loading="lazy"
               className="h-auto w-full max-w-[var(--pb-hero-media-max-w,none)]"
@@ -199,6 +181,7 @@ export function renderHero({
             // unset, the image keeps its previous free-flowing size.
             <img
               src={imageUrl}
+              {...srcsetAttrs(imageSrcset, SIZES_HALF)}
               alt={imageAlt || title}
               loading="lazy"
               className="h-auto w-full max-w-[var(--pb-hero-media-max-w,none)] object-cover"
@@ -208,7 +191,13 @@ export function renderHero({
               }}
             />
           ) : (
-            <ContentMedia imageUrl={imageUrl} imageAlt={imageAlt} aspect="square" />
+            <ContentMedia
+              imageUrl={imageUrl}
+              imageAlt={imageAlt}
+              imageSrcset={imageSrcset}
+              sizes={SIZES_HALF}
+              aspect="square"
+            />
           )}
         </div>
       </div>
@@ -226,6 +215,7 @@ export const HeroWidget: ComponentConfig<HeroWidgetProps> = {
     logoAlt: { type: 'text', label: 'Logo alt text' },
     imageUrl: createImageField(mediaLibraryAdapter, 'Image'),
     imageAlt: { type: 'text', label: 'Image alt text' },
+    imageSrcset: imageSrcsetField,
     imageMaskUrl: {
       type: 'text',
       label: 'Image mask URL (organic shape, side layouts — optional)',
@@ -277,6 +267,7 @@ export const HeroWidget: ComponentConfig<HeroWidgetProps> = {
     logoAlt: '',
     imageUrl: '',
     imageAlt: '',
+    imageSrcset: '',
     imageMaskUrl: '',
     imageShape: 'rounded',
     imagePosition: 'background',
@@ -288,5 +279,6 @@ export const HeroWidget: ComponentConfig<HeroWidgetProps> = {
     align: 'center',
     surface: 'plain',
   },
+  resolveData: resolveImageSrcset,
   render: renderHero,
 };

{simple_module_pagebuilder-0.0.3 → simple_module_pagebuilder-0.0.4}/pagebuilder/components/widgets/media-object-layout.ts

@@ -5,6 +5,8 @@ import type { CSSProperties } from 'react';
 export type MediaObjectWidgetProps = {
   imageUrl: string;
   imageAlt: string;
+  /** Variant srcset recorded at pick time (see _shared/image-srcset.ts). */
+  imageSrcset?: string;
   imagePosition: 'left' | 'right';
   heading: string;
   body: string;

{simple_module_pagebuilder-0.0.3 → simple_module_pagebuilder-0.0.4}/pagebuilder/components/widgets/media-object-render.tsx

@@ -9,7 +9,7 @@ import { cn } from '../../utils/widgetUtils';
 import { AccentText } from './_internal/accent-text';
 import { LinkArrow } from './_internal/link-arrow';
 import { RichTextBlock, renderRichText } from './_internal/rich-text';
-import { CTAButton, eyebrowTextStyle, maskStyle } from './_shared';
+import { CTAButton, eyebrowTextStyle, maskStyle, SIZES_HALF, srcsetAttrs } from './_shared';
 
 import { GRID_IMAGE, GRID_TEXT, type MediaObjectWidgetProps } from './media-object-layout';
 import { MediaObjectText } from './media-object-text';
@@ -19,6 +19,7 @@ export type { MediaObjectWidgetProps } from './media-object-layout';
 export const MediaObjectWidgetRender = ({
   imageUrl,
   imageAlt,
+  imageSrcset = '',
   imageMaskUrl = '',
   imageShape = 'rounded',
   imageTag = '',
@@ -86,6 +87,7 @@ export const MediaObjectWidgetRender = ({
   const imageEl = imageUrl ? (
     <img
       src={imageUrl}
+      {...srcsetAttrs(imageSrcset, SIZES_HALF)}
       alt={imageAlt || heading}
       loading="lazy"
       className={cn('w-full h-auto', !masked && !native && 'rounded-lg')}
@@ -196,6 +198,8 @@ export const MediaObjectWidgetRender = ({
             {imageUrl && (
               <img
                 src={imageUrl}
+                // Rendered 68px tall — the smallest variant is plenty.
+                {...srcsetAttrs(imageSrcset, '320px')}
                 alt={imageAlt || heading}
                 loading="lazy"
                 className="mt-8 h-[68px] w-auto max-w-full object-contain object-left"

{simple_module_pagebuilder-0.0.3 → simple_module_pagebuilder-0.0.4}/pagebuilder/components/widgets/media-object-widget.tsx

@@ -5,6 +5,7 @@ import type { ComponentConfig } from '@puckeditor/core';
 
 import { createImageField, mediaLibraryAdapter } from '../../fields';
 
+import { imageSrcsetField, resolveImageSrcset } from './_shared';
 import { type MediaObjectWidgetProps, MediaObjectWidgetRender } from './media-object-render';
 
 export type * from './media-object-render';
@@ -14,6 +15,7 @@ export const MediaObjectWidget: ComponentConfig<MediaObjectWidgetProps> = {
   fields: {
     imageUrl: createImageField(mediaLibraryAdapter, 'Image'),
     imageAlt: { type: 'text', label: 'Image alt text' },
+    imageSrcset: imageSrcsetField,
     imageMaskUrl: {
       type: 'text',
       label: 'Image mask URL (organic shape — optional)',
@@ -145,6 +147,7 @@ export const MediaObjectWidget: ComponentConfig<MediaObjectWidgetProps> = {
   defaultProps: {
     imageUrl: '',
     imageAlt: '',
+    imageSrcset: '',
     imageMaskUrl: '',
     imageShape: 'rounded',
     imageTag: '',
@@ -172,5 +175,6 @@ export const MediaObjectWidget: ComponentConfig<MediaObjectWidgetProps> = {
     surface: 'default',
     surfaceColor: '',
   },
+  resolveData: resolveImageSrcset,
   render: (props) => <MediaObjectWidgetRender {...props} />,
 };

{simple_module_pagebuilder-0.0.3 → simple_module_pagebuilder-0.0.4}/pagebuilder/endpoints/seo.py

@@ -42,7 +42,10 @@ async def sitemap(
     if not settings.sitemap_enabled:
         return Response(status_code=404)
 
-    pages = await PagesService(db).list_indexable_published()
+    # Column-only query: at a few thousand pages, loading full entities
+    # (with both block-JSON columns) made every crawl a multi-second,
+    # tens-of-MB request (issue #11).
+    pages = await PagesService(db).list_sitemap_entries()
     origin = _public_origin(request, settings)
     prefix = settings.public_route_prefix
 

simple_module_pagebuilder-0.0.4/pagebuilder/media_files.py

@@ -0,0 +1,128 @@
+"""Media file serving: root resolution, cache headers, integrity check.
+
+Extracted from ``module.py`` (which sits near the size cap) and shared with
+:class:`~pagebuilder.media_service.MediaService` so the mount that *serves*
+files and the service that *writes* them can never disagree about where the
+media library lives (issue #14).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from fastapi.staticfiles import StaticFiles
+from starlette.exceptions import HTTPException
+from starlette.responses import PlainTextResponse, Response
+from starlette.types import Scope
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+logger = logging.getLogger(__name__)
+
+# Same override + sentinels the hosting package uses to find the project
+# root, so a host and this module always agree on the anchor. Duplicated
+# rather than imported: modules depend on core, not hosting.
+_ENV_PROJECT_ROOT = "SM_PROJECT_ROOT"
+_PROJECT_ROOT_SENTINELS = ("pyproject.toml", ".env", "alembic.ini")
+
+
+def _project_root() -> Path:
+    override = os.environ.get(_ENV_PROJECT_ROOT)
+    if override:
+        return Path(override)
+    cwd = Path.cwd().resolve()
+    for candidate in (cwd, *cwd.parents):
+        if any((candidate / s).exists() for s in _PROJECT_ROOT_SENTINELS):
+            return candidate
+    return cwd
+
+
+def resolve_media_root(configured: Path | str) -> Path:
+    """Anchor a relative ``media_root`` to the project root, not the cwd.
+
+    A cwd-relative default meant every process with a different working
+    directory read and wrote a *different* media directory while sharing one
+    database — rows silently outlived their files (issue #14). Absolute
+    paths pass through untouched.
+    """
+    root = Path(configured)
+    if not root.is_absolute():
+        root = _project_root() / root
+    return root.resolve()
+
+
+class MediaFiles(StaticFiles):
+    """StaticFiles with immutable caching and an honest 404.
+
+    Media filenames are content-addressed at upload (a fresh UUID hex per
+    file, variants included), so a URL never serves different bytes —
+    long-lived immutable caching is as safe here as for hashed Vite assets
+    (issue #13). Missing files answer with a plain-text 404 instead of
+    falling through to the HTML app shell, which hid broken images behind
+    ``text/html`` responses (issue #14).
+    """
+
+    _CACHE_CONTROL = "public, max-age=31536000, immutable"
+
+    async def get_response(self, path: str, scope: Scope) -> Response:
+        try:
+            response = await super().get_response(path, scope)
+        except HTTPException as exc:
+            if exc.status_code == 404:
+                return PlainTextResponse("Not Found", status_code=404)
+            raise
+        if response.status_code in (200, 304):
+            response.headers.setdefault("Cache-Control", self._CACHE_CONTROL)
+        return response
+
+
+async def count_missing_media_files(session: AsyncSession, media_root: Path) -> int:
+    """Rows in the media library whose file (or a variant) is gone from disk."""
+    from sqlmodel import select
+
+    from pagebuilder.models import MediaAsset
+
+    result = await session.execute(select(MediaAsset.filename, MediaAsset.variants))
+    missing = 0
+    for filename, variants in result.all():
+        names = [filename] + [
+            meta["filename"] for meta in (variants or {}).values() if meta.get("filename")
+        ]
+        if any(not (media_root / name).is_file() for name in names):
+            missing += 1
+    return missing
+
+
+async def warn_on_orphaned_media(
+    session_factory: Callable[[], AsyncSession], media_root: Path
+) -> int:
+    """Log a warning when media rows point at files that don't exist.
+
+    Runs once at startup. This drift is otherwise invisible until a visitor
+    sees broken images: the DB says the asset exists, the picker lists it,
+    and only the file request fails. Failures of the check itself (e.g. the
+    table doesn't exist yet on a fresh database) are logged at debug and
+    never block startup.
+    """
+    try:
+        async with session_factory() as session:
+            missing = await count_missing_media_files(session, media_root)
+    except Exception:  # pragma: no cover - defensive: never break boot
+        logger.debug("pagebuilder.media integrity check skipped", exc_info=True)
+        return 0
+    if missing:
+        logger.warning(
+            "pagebuilder.media: %d media row(s) have no file under %s — "
+            "uploads from a different working directory or a missing volume. "
+            "Re-upload the assets or point SM_PAGEBUILDER_MEDIA_ROOT at the "
+            "directory that holds them.",
+            missing,
+            media_root,
+        )
+    return missing