@o-a/cms-agent 0.4.0 → 0.5.1

package/dist/create-site/generate-site.js

@@ -124,6 +124,17 @@ export function scaffoldSite(targetDir) {
             tunnel: 'node server.js --tunnel',
             dev: 'node --watch-path=../theme server.js',
             check: 'check-site',
+            // seed-media is the package's own installed CLI bin, exposed
+            // as a script for exactly the same reason check is: there is
+            // no package.json or node_modules at the SITE root, only here
+            // in vhost/, so the obvious-looking `npx seed-media` run from
+            // the site directory resolves nothing locally, goes to the
+            // public registry for a package by that name and dies with
+            // E404 - while still exiting 0. That is not hypothetical: it
+            // is what sent a generated site's images into theme/root/
+            // instead of media/. Run it from here as
+            // `npm run seed-media -- .. <file>`.
+            'seed-media': 'seed-media',
         },
         dependencies: {
             // Pinned exact, never a ^range - at v0.x even a minor bump

package/dist/create-site/template/AGENTS.md

@@ -38,7 +38,7 @@ This scaffold already ships real, working examples worth reading before writing
 **Only these keywords are supported**: `type`, `properties`, `required`, `additionalProperties`, `default`, `minLength`, `maxLength`, `minimum`, `maximum`, `pattern`, `enum`, `items`, `minItems`, `maxItems`, plus the custom `format`/`title`/`description`/`allowedBlocks`/`api`/`swatches`/`step`/`unit` keywords documented below. **Never `$ref`, `$defs`, `definitions`, `allOf`, `anyOf`, `oneOf`, `not`, or `if`/`then`/`else`** - every property's schema must be fully self-contained, written out in full where it's used. If the same shape (e.g. an image object) repeats across several properties or several component files, write it out each time rather than trying to share/reference a definition - there is no cross-referencing mechanism here, in a single schema block or across files, regardless of what standard JSON Schema itself supports elsewhere.
 3. Once the theme components exist, compose an actual page by writing a file under `content/pages/` whose `sections` array references those types by filename, with a `settings` object matching each one's schema (see "Content JSON model" below).
 4. **For any page type the site will have more than one of** - a project, an article, a case study, a team member - also write a starting point for it under `theme/templates/<name>.json`. This is easy to skip and worth not skipping: without a template, every new page an editor creates starts completely blank, and they have to rebuild the same section stack by hand every time. A template is just a real page file kept in a different folder - the same shape as anything under `content/pages/` (`schemaVersion`, `name`, `title`, `type`, `layout`, `published`, `sections`), validated identically, using the section types this theme already defines. Its `"title"` is the label an editor picks from, so name it for the page type (`"Project"`, `"Article"`), never `"Untitled"`. **Set its `"type"` to that kind too** (`"project"`, `"article"`) - not `"page"`. Every page an editor creates from a template inherits the template's own `type`, and that value is what listings filter on, so an Article template left at `"type": "page"` silently produces articles no blog index can find. This is easy to get wrong because the template still validates and previews perfectly either way; nothing fails, the listing is simply always empty. Fill each section's settings with short placeholder copy rather than leaving them empty - a template is a starting point to edit, not a blank form. A template that fails validation is skipped silently at boot, so preview a page built from it.
-5. **Put every image through `seed-media` before referencing it - never copy image files into the repo by hand.** Photographs and other content images do not belong in the site root, in `theme/root/`, or in `theme/assets/`; they belong in `media/`, under a content-addressed filename the CMS generates. Run `npx seed-media . <file>...` from the site directory and use the `/media/...` URL it prints. See "Images" below for the detail and for how this changes once a server is running. Getting this wrong is quiet rather than loud: the page still renders, the image is simply missing.
+5. **Put every image through `seed-media` before referencing it - never copy image files into the repo by hand.** Photographs and other content images do not belong in the site root, in `theme/root/`, or in `theme/assets/`; they belong in `media/`, under a content-addressed filename the CMS generates. Run `npm run seed-media -- .. <file>...` from `vhost/` (the same place `npm run check` runs from) and use the `/media/...` URL it prints, as the `url` of a `format: "image"` setting rendered through the `responsive-media` snippet - never a hand-written `<img>`. See "Images" below for the detail and for how this changes once a server is running. Getting this wrong is quiet rather than loud: the page still renders, the image is simply missing.
 6. Preview the result, then run `npm run check` before considering the task done - it renders every page for real and fails on any image or link pointing at a file that does not exist, which is the fastest way to catch a misplaced image. See "Previewing your work".
 
 ### Worked example - a section
@@ -47,6 +47,14 @@ This scaffold already ships real, working examples worth reading before writing
 <section class="hero" data-section-id="{{ section.id }}">
   <h1>{{ section.settings.heading }}</h1>
   {% if section.settings.subheading %}<p>{{ section.settings.subheading }}</p>{% endif %}
+  {% if section.settings.image.url %}
+    {% render 'responsive-media',
+         media: section.settings.image,
+         kind: 'image',
+         field: 'image',
+         alt: section.settings.heading,
+         ratio: '16 / 9' %}
+  {% endif %}
   <div class="hero__blocks">{% for html in blocksHtml %}{{ html | raw }}{% endfor %}</div>
 </section>
 {% schema %}
@@ -56,7 +64,8 @@ This scaffold already ships real, working examples worth reading before writing
   "required": ["heading"],
   "properties": {
     "heading": { "type": "string", "minLength": 1, "default": "New section" },
-    "subheading": { "type": "string" }
+    "subheading": { "type": "string" },
+    "image": { "type": "object", "format": "image" }
   }
 }
 {% endschema %}
@@ -102,6 +111,8 @@ Write the description as one short sentence about what the section **is**, not w
 
 Flat `.liquid` files in `snippets/`, invoked with `{% render 'name', param1: value %}` - never `{% include %}`. A snippet only sees parameters explicitly passed to it; the calling scope never leaks in.
 
+This scaffold ships one you must use: **`snippets/responsive-media.liquid`, through which every content image and video is rendered.** It emits the attribute that lets an editor drag a file from the media library straight onto the picture in the live preview. See "Making an image or video droppable" below, and `theme/sections/hero.liquid` / `theme/sections/cta-banner.liquid` for real call sites.
+
 ## Field format hints
 
 Every setting is plain JSON Schema (`string`, `integer`, `number`, `boolean`, `array`, with `minLength`/`minimum`/`enum`/etc. for real validation). One extra keyword, `"format"`, is a UI hint only (never validated server-side) that the admin reads to choose a richer input widget:
@@ -109,8 +120,8 @@ Every setting is plain JSON Schema (`string`, `integer`, `number`, `boolean`, `a
 | `format` | On type | Effect |
 |---|---|---|
 | `richtext` | `string` | Rich-text editor; render with `{{ ... | raw }}`, not plain `{{ }}` |
-| `image` | `object` | Image picker with focal point; object shape is exactly `{ "url": "...", "focalX": 0.5, "focalY": 0.5 }` - render `{{ section.settings.<field>.url }}` |
-| `video` | `object` | Video picker for a short, silent background loop; object shape is exactly `{ "url": "...", "poster": "..." }` - render the `url` as the `<video>` source and always set `poster="{{ section.settings.<field>.poster }}"`, since the poster is what shows before the clip loads and whenever it cannot play. Only `.mp4`/`.webm` can be uploaded, under the same 10MB media cap - long-form video belongs on YouTube/Vimeo as an embed, not here. No focal point: a loop is played as a background rather than cropped around a subject |
+| `image` | `object` | Image picker with focal point; object shape is exactly `{ "url": "...", "focalX": 0.5, "focalY": 0.5 }`. **Render it with `{% render 'responsive-media' %}`, never a hand-written `<img>`** - see "Making an image or video droppable" below |
+| `video` | `object` | Video picker for a short, silent background loop; object shape is exactly `{ "url": "...", "poster": "..." }`. **Render it with `{% render 'responsive-media' %}`, never a hand-written `<video>`** - see "Making an image or video droppable" below. The snippet sets the poster for you, which matters because the poster is what shows before the clip loads and whenever it cannot play. Only `.mp4`/`.webm` can be uploaded, under the same 10MB media cap - long-form video belongs on YouTube/Vimeo as an embed, not here. No focal point: a loop is played as a background rather than cropped around a subject |
 | `textarea` | `string` | Multi-line `<textarea>` |
 | `uri` | `string` | `<input type="url">` |
 | `date` | `string` | `<input type="date">`, value as `YYYY-MM-DD` |
@@ -319,26 +330,77 @@ Each entry in `sections` requires `id` (any non-empty string, unique within the
 
 **One image is one file and one URL. The CMS does not generate resized variants, and you must not hand-build them.** Do not produce fixed-width copies of a photo, do not write a `srcset` listing several generated files, and do not add a build step that emits them. Server-side resizing is a deliberately deferred feature - there is no image processing in the CMS at all - so hand-made variants are files nothing manages: the media library cannot show them as one image, and an editor replacing the picture gets the original swapped while every variant silently keeps the old photo. Reference the single `/media/` URL and let the browser scale it, with CSS (`max-width: 100%`, `object-fit`) doing the responsive work. `width`/`height` attributes and `loading="lazy"` are worth setting; multiple sources are not available.
 
-Once a server is running, uploads go through `POST /v1/media` (multipart, requires a token with `media` scope) or the admin's own media library UI - never write directly into `media/` from an agent, since the CMS names files by content hash. A successful upload returns `{ "url": "/media/<name>" }`. In theme content, an image is just a plain string setting holding that URL:
+Once a server is running, uploads go through `POST /v1/media` (multipart, requires a token with `media` scope) or the admin's own media library UI - never write directly into `media/` from an agent, since the CMS names files by content hash. A successful upload returns `{ "url": "/media/<name>" }`. In theme content, **an image is a `format: "image"` object setting, never a plain string** - and a short silent loop is a `format: "video"` one:
 
 ```json
-{ "type": "string", "default": "" }
+"image": { "type": "object", "format": "image" }
+```
+
+This is not a stylistic preference. The admin's picker, the focal point, and drag-and-drop replacement all work on that object shape (`{ "url", "focalX", "focalY" }`; a video stores `{ "url", "poster" }`). A plain string setting gets a bare text box and nothing else - and since dropping an image writes the object shape, dragging onto a field declared as a string fails validation outright. Use a plain string only for a path that is never editable content, such as a theme asset bundled under `theme/assets/`.
+
+### Making an image or video droppable
+
+Render every content image and video through the `responsive-media` snippet the scaffold ships in `theme/snippets/` - see `hero.liquid` and `cta-banner.liquid` for working call sites:
+
+```liquid
+{% if section.settings.image.url %}
+  {% render 'responsive-media',
+       media: section.settings.image,
+       kind: 'image',
+       field: 'image',
+       alt: 'What is actually in the picture',
+       ratio: '16 / 9' %}
+{% endif %}
+```
+
+A video is the same call with `kind: 'video'` and the video setting - the snippet handles the `<video>`, the poster and the autoplay/muted/loop attributes itself:
+
+```liquid
+{% if section.settings.backgroundLoop.url %}
+  {% render 'responsive-media',
+       media: section.settings.backgroundLoop,
+       kind: 'video',
+       field: 'backgroundLoop',
+       ratio: '21 / 9' %}
+{% endif %}
 ```
 
-unless the design needs a focal point for a cropped image, in which case use `"format": "image"` (see the table above) instead of a plain string.
+Parameters:
+
+| Parameter | Effect |
+|---|---|
+| `media` | **Required.** The whole setting object, not its `.url` - the snippet reads `url`, and `focalX`/`focalY` or `poster` from it |
+| `field` | **Required.** The schema property name this renders. A drop writes the new URL back to exactly this key, so a wrong value silently writes to the wrong setting |
+| `kind` | `'image'` (the default) or `'video'` |
+| `alt` | Real alt text describing what is in the picture. On a video it becomes an `aria-label`; omit it for a purely decorative loop and the clip is marked `aria-hidden` instead |
+| `ratio` | Any CSS `aspect-ratio` value, e.g. `'16 / 9'`. Defaults to `'3 / 2'` |
+| `loading` | `'eager'` for anything above the fold, otherwise omit - it defaults to `lazy`. Lazy-loading a hero image delays the largest thing on the page |
+| `priority` | `true` adds `fetchpriority="high"`. The hero image only, never more than one per page |
+| `class` | Extra classes on the wrapper element |
+
+The snippet puts `data-cms-media="<field>"` on the element it renders (plus `data-cms-image` for images). **That attribute is the whole contract.** The admin finds a drop target by searching the previewed page for it, and uses its value to know which setting to write the new URL into, so `field` must match the schema property name exactly. A hand-written `<img>` without it renders perfectly and is simply never droppable - a silent gap, because nothing about the page looks wrong, which is exactly how a real generated site shipped with every image un-editable.
+
+Guard the call on the url, as above. An unset image renders nothing at all rather than a placeholder: a theme cannot tell whether it is rendering for the admin preview or the public site, so an editor-only affordance would show to real visitors. The first image is set through the Fields panel's own picker; drag-and-drop replaces it from then on.
 
 If you're writing starter content before a server is even running - so `POST /v1/media` isn't reachable yet - use the `seed-media` CLI instead of placing images under `theme/root/`. It computes the exact same content-addressed filename a real upload would, so the result is indistinguishable from one:
 
 ```
-npx seed-media <site-directory> photo.jpg another.png
+cd vhost
+npm run seed-media -- .. photo.jpg another.png
 # photo.jpg -> /media/photo-3f9a2b7c1e04.jpg
 # another.png -> /media/another-91cd4a08f2b1.png
 ```
 
-Then use the printed URL exactly like a real upload's:
+Run it from `vhost/`, not the site root. There is no `package.json` or `node_modules` at the site root - the CMS is installed under `vhost/` - so a bare `npx seed-media` there resolves nothing locally, goes to the public npm registry looking for a package called "seed-media", and fails with a 404 while still exiting 0.
+
+Then use the printed URL as the `url` of a `format: "image"` setting, exactly like a real upload's - not as a plain string:
 
 ```json
-{ "type": "string", "default": "/media/photo-3f9a2b7c1e04.jpg" }
+"image": {
+  "type": "object",
+  "format": "image",
+  "default": { "url": "/media/photo-3f9a2b7c1e04.jpg", "focalX": 0.5, "focalY": 0.5 }
+}
 ```
 
 This is only for seeding starter content offline - once a server is running, a later image change from an editor still goes through `POST /v1/media` or the admin's media library as normal.
@@ -381,6 +443,8 @@ From `vhost/`, with the site's dependencies already installed (no need for the s
 npm run check
 ```
 
-Renders every published page for real and reports, in one pass: any theme component excluded at boot (same warnings the server itself prints, see "Minimal form" above); any `<img src>`/`srcset`/`<a href>` in the rendered HTML pointing at a `/media/`, `/assets/`, or root-static file that doesn't actually exist on disk; and any internal link that doesn't point at a real, published page. Exits non-zero if it finds anything - safe to run after generating content, not just as a manual spot-check.
+Renders every published page for real and reports, in one pass: any theme component excluded at boot (same warnings the server itself prints, see "Minimal form" above); any `src`/`srcset`/`poster`/`href` in the rendered HTML pointing at a `/media/`, `/assets/`, or root-static file that doesn't actually exist on disk; any internal link that doesn't point at a real, published page; and **any content image or video being served from `theme/root/` or `theme/assets/` instead of `media/`**. Exits non-zero if it finds anything - safe to run after generating content, not just as a manual spot-check.
+
+That last one has no other way of being noticed: the file exists, so the page renders perfectly. It is simply invisible to the media library and an editor can never replace it.
 
 This catches the specific failure mode a snippet like `responsive-image` can introduce silently: a `widths` list that includes a size nothing was actually uploaded/generated for renders a perfectly normal-looking page with one broken image at that breakpoint - nothing about the page itself is wrong, so nothing else would ever flag it.

package/dist/create-site/template/theme/assets/style.css

@@ -1000,6 +1000,74 @@ section {
 }
 
 /* ----- CTA banner ----- */
+/* responsive-media snippet -------------------------------------------
+   One wrapper for both an image and a video, so a section does not care
+   which it was given. The aspect ratio comes in as a custom property
+   from the snippet's own `ratio` parameter. */
+.media {
+  position: relative;
+  overflow: hidden;
+  aspect-ratio: var(--media-ratio, 3 / 2);
+  border-radius: 12px;
+  background: rgba(255, 255, 255, 0.04);
+}
+
+.media img,
+.media video {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+/* The empty slot. Visibly a placeholder rather than a broken image, and
+   still a drop target - dragging a file onto it is how it gets filled. */
+.media--empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 1rem;
+  border: 1px dashed rgba(255, 255, 255, 0.25);
+  background: rgba(255, 255, 255, 0.02);
+}
+
+.media__hint {
+  max-width: 22ch;
+  text-align: center;
+  font-size: 0.8rem;
+  line-height: 1.4;
+  opacity: 0.6;
+}
+
+/* An autoplaying loop is motion the viewer did not ask for, and no
+   amount of CSS can stop a video element autoplaying - but hiding it
+   and painting its own poster in its place gets the same result, so a
+   reduced-motion viewer sees the still rather than the movement. */
+@media (prefers-reduced-motion: reduce) {
+  .media--has-poster {
+    background-image: var(--media-poster);
+    background-size: cover;
+    background-position: center;
+  }
+
+  .media--has-poster video {
+    display: none;
+  }
+}
+
+.hero__media {
+  width: 100%;
+}
+
+/* Sits behind the banner's own copy rather than beside it. */
+.cta-banner__media {
+  position: absolute;
+  inset: 0;
+  z-index: 0;
+  border-radius: inherit;
+  opacity: 0.35;
+}
+
 .cta-banner {
   background: var(--color-dark);
   color: var(--color-dark-ink);
@@ -1019,6 +1087,8 @@ section {
 }
 
 .cta-banner__inner {
+  position: relative;
+  z-index: 1;
   position: relative;
   z-index: 1;
   max-width: 560px;

package/dist/create-site/template/theme/sections/cta-banner.liquid

@@ -1,6 +1,14 @@
 <section data-section-id="{{ section.id }}">
   <div class="container">
     <div class="cta-banner reveal">
+      {% if section.settings.backgroundLoop.url %}
+        {% render 'responsive-media',
+             media: section.settings.backgroundLoop,
+             kind: 'video',
+             field: 'backgroundLoop',
+             ratio: '21 / 9',
+             class: 'cta-banner__media' %}
+      {% endif %}
       <div class="cta-banner__inner">
         <h2>{{ section.settings.heading }}</h2>
         {% if section.settings.subheading %}<p>{{ section.settings.subheading }}</p>{% endif %}
@@ -20,7 +28,8 @@
   "required": ["heading"],
   "properties": {
     "heading": { "type": "string", "minLength": 1, "default": "Ready to get started?" },
-    "subheading": { "type": "string" }
+    "subheading": { "type": "string" },
+    "backgroundLoop": { "type": "object", "format": "video" }
   },
   "allowedBlocks": ["button"]
 }

package/dist/create-site/template/theme/sections/hero.liquid

@@ -6,7 +6,18 @@
       {% if section.settings.subheading %}<p>{{ section.settings.subheading }}</p>{% endif %}
       <div class="hero__actions">{% for html in blocksHtml %}{{ html | raw }}{% endfor %}</div>
     </div>
-    {% if section.settings.codeSnippet %}
+    {% if section.settings.image.url %}
+      {% render 'responsive-media',
+           media: section.settings.image,
+           kind: 'image',
+           field: 'image',
+           alt: section.settings.heading,
+           ratio: '4 / 3',
+           loading: 'eager',
+           priority: true,
+           need: 'The main hero image',
+           class: 'hero__media reveal' %}
+    {% elsif section.settings.codeSnippet %}
       <div class="code-panel reveal">
         <div class="code-panel__bar">
           <span></span><span></span><span></span>
@@ -28,6 +39,7 @@
     "eyebrow": { "type": "string" },
     "heading": { "type": "string", "minLength": 1, "default": "New Section" },
     "subheading": { "type": "string" },
+    "image": { "type": "object", "format": "image" },
     "codeTitle": { "type": "string" },
     "codeSnippet": { "type": "string" }
   },

package/dist/create-site/template/theme/snippets/responsive-media.liquid

@@ -0,0 +1,107 @@
+{%- comment -%}
+  responsive-media - the only way a content image or video should reach a page.
+
+  Renders a `format: "image"` or `format: "video"` setting, and marks the
+  result as a drag-and-drop target so an editor can drag a file from the
+  admin's media library straight onto it in the live preview.
+
+    {% render 'responsive-media',
+         media: section.settings.image,   the whole setting object, not .url
+         kind: 'image',                   'image' or 'video'
+         field: 'image',                  REQUIRED - the settings key this
+                                          renders, which is what a drop writes
+                                          back to
+         alt: 'What is actually in the picture',
+         ratio: '16 / 9',                 any CSS aspect-ratio value
+         loading: 'eager',                'eager' above the fold, else lazy
+         priority: true,                  adds fetchpriority=high
+         need: 'Wide shot of the still house',   shown in the empty slot
+         class: 'extra-class' %}
+
+  Why `field` matters
+  -------------------
+  The admin finds a drop target by looking for data-cms-media, and uses its
+  value to know which setting to write the new URL into. Get it wrong and the
+  drop silently writes to the wrong field; omit it and the image simply is not
+  droppable. It must match the schema property name exactly.
+
+  An empty slot is NOT a drop target (decided directly). A theme has no way to
+  tell whether it is rendering for the admin preview or for the public site -
+  the renderer does not expose that - so an editor-only affordance would leak
+  onto the live site as a dashed box in front of real visitors. Guard the call
+  instead, exactly as hero.liquid and cta-banner.liquid do:
+
+    {% if section.settings.image.url %}{% render 'responsive-media', ... %}{% endif %}
+
+  so a section with nothing set renders nothing at all. Set the first image
+  through the Fields panel's own picker; drag-and-drop then replaces it.
+
+  No srcset, on purpose
+  ---------------------
+  The CMS names uploaded files by a hash of their own bytes, so a resized
+  variant gets a completely different name - "photo-480w.webp" is not
+  derivable from "photo-3f9a2b7c1e04.jpg". Hand-built variant URLs therefore
+  point at files that do not exist, which renders a page that looks perfectly
+  fine except at one breakpoint. Do not add a srcset here. One image is one
+  file and one URL; let CSS do the responsive work.
+{%- endcomment -%}
+{%- assign media_kind = kind | default: 'image' -%}
+{%- assign media_field = field | default: 'image' -%}
+{%- assign media_url = media.url -%}
+{%- capture ratio_style -%}--media-ratio: {{ ratio | default: '3 / 2' }};{%- endcapture -%}
+
+{%- if media_url == nil or media_url == '' -%}
+  {%- comment -%}
+    Reached only if a caller renders this without guarding on a url - the
+    scaffold's own call sites guard, so this never appears on a real page.
+    Kept as a graceful fallback for a theme that genuinely wants a visible
+    placeholder, and deliberately carrying NO drag attributes: see above.
+  {%- endcomment -%}
+  <div class="media media--empty {{ class }}"
+       style="{{ ratio_style }}"
+       role="img"
+       aria-label="Placeholder. {{ need | default: alt }}">
+    <span class="media__hint">{{ need | default: alt | default: 'Drag a file here' }}</span>
+  </div>
+{%- elsif media_kind == 'video' -%}
+  {%- comment -%}
+    No data-cms-image on a video: an older admin understands only that
+    attribute and would write an image-shaped value ({url, focalX, focalY})
+    over this field's own {url, poster}. Better it ignores the slot entirely
+    than corrupts it.
+
+    A background loop is muted and looping by definition, so it may autoplay.
+    The poster is what shows before the clip loads and wherever it will not
+    play at all, which is why it is worth setting rather than optional.
+  {%- endcomment -%}
+  <div class="media {{ class }}{% if media.poster and media.poster != '' %} media--has-poster{% endif %}"
+       style="{{ ratio_style }}{% if media.poster and media.poster != '' %} --media-poster: url('{{ media.poster }}');{% endif %}"
+       data-cms-media="{{ media_field }}"
+       data-cms-media-kind="video">
+    <video
+      src="{{ media_url }}"
+      {% if media.poster and media.poster != '' %}poster="{{ media.poster }}"{% endif %}
+      autoplay
+      muted
+      loop
+      playsinline
+      preload="metadata"
+      {% if alt and alt != '' %}aria-label="{{ alt }}"{% else %}aria-hidden="true"{% endif %}></video>
+  </div>
+{%- else -%}
+  {%- assign fx = media.focalX | default: 0.5 | times: 100 | round: 1 -%}
+  {%- assign fy = media.focalY | default: 0.5 | times: 100 | round: 1 -%}
+  <div class="media {{ class }}"
+       style="{{ ratio_style }}"
+       data-cms-media="{{ media_field }}"
+       data-cms-media-kind="image"
+       data-cms-image="{{ media_field }}">
+    <img
+      src="{{ media_url }}"
+      alt="{{ alt }}"
+      loading="{{ loading | default: 'lazy' }}"
+      decoding="async"
+      {% if priority %}fetchpriority="high"{% endif %}
+      style="object-position: {{ fx }}% {{ fy }}%;">
+  </div>
+{%- endif -%}

package/dist/site-check/cli.js

@@ -10,6 +10,7 @@ const KIND_LABELS = {
     'render-error': 'Render error',
     'missing-asset': 'Missing asset',
     'broken-link': 'Broken link',
+    'misplaced-media': 'Misplaced media',
 };
 function printGrouped(findings) {
     const byKind = new Map();

package/dist/site-check/run-check.d.ts

@@ -1,4 +1,4 @@
-export type CheckFindingKind = 'schema' | 'render-error' | 'missing-asset' | 'broken-link';
+export type CheckFindingKind = 'schema' | 'render-error' | 'missing-asset' | 'broken-link' | 'misplaced-media';
 export interface CheckFinding {
     kind: CheckFindingKind;
     message: string;

package/dist/site-check/run-check.js

@@ -4,6 +4,7 @@ import { renderPage } from "../renderer/render-page.js";
 import { PathSafetyError, sanitisePath } from "../services/path-safety.js";
 import { buildSitemapUrls } from "../routes/sitemap.js";
 import { urlToPagePath } from "../services/urls.js";
+import { ALLOWED_UPLOAD_EXTENSIONS } from "../media/filename.js";
 // A reference this project's own theme conventions actually produce:
 // src="...", srcset="w1 480w, w2 960w" (comma-separated, each entry a
 // url then a space then a width descriptor - strip the descriptor),
@@ -11,25 +12,46 @@ import { urlToPagePath } from "../services/urls.js";
 // "the schema surface here is narrow and flat... a library would be
 // heavier than the problem warrants" precedent for the equivalent
 // choice on the admin side.
-const ATTR_PATTERN = /\b(?:src|href)="([^"]*)"|\bsrcset="([^"]*)"/g;
+// poster is included deliberately: a video's poster is a real content
+// image and was not being checked at all before.
+const ATTR_PATTERN = /\b(src|href|poster|srcset)="([^"]*)"/g;
 function extractReferences(html) {
     const refs = [];
     for (const match of html.matchAll(ATTR_PATTERN)) {
-        const [, single, srcset] = match;
-        if (single !== undefined) {
-            refs.push(single);
+        const attribute = match[1] ?? '';
+        const value = match[2] ?? '';
+        if (attribute !== 'srcset') {
+            refs.push({ url: value, attribute });
         }
-        else if (srcset !== undefined) {
-            for (const entry of srcset.split(',')) {
+        else {
+            for (const entry of value.split(',')) {
                 const url = entry.trim().split(/\s+/)[0];
                 if (url) {
-                    refs.push(url);
+                    refs.push({ url, attribute });
                 }
             }
         }
     }
     return refs;
 }
+// Any scheme at all that is not http(s). The previous version listed
+// data: explicitly and nothing else, so mailto: (and tel:, and anything
+// future) fell through to the static-file branch below and was reported
+// as a missing file under theme/root/, purely because the text after
+// the "@" contains a dot. One real site produced 39 such findings and
+// not one true one, which is worse than no check: it teaches whoever
+// reads the output to ignore it.
+function hasExternalScheme(ref) {
+    return ref.startsWith('//') || /^[a-z][a-z0-9+.-]*:/i.test(ref);
+}
+// A content photograph or clip, as opposed to a design asset. Keyed off
+// the same extension list the media upload route accepts, so the two
+// cannot drift; .svg is absent from it, which is what keeps an inline
+// logo or icon from being mistaken for misplaced content.
+function isUploadableMedia(path) {
+    const lower = path.toLowerCase();
+    return [...ALLOWED_UPLOAD_EXTENSIONS].some((extension) => lower.endsWith(extension));
+}
 // True for a root-relative static path that looks like a real file
 // (has a "." in its last path segment - /favicon.ico, /robots.txt),
 // as opposed to a page URL like /about or /blog/hello-world, which
@@ -48,6 +70,17 @@ function looksLikeStaticFile(path) {
 // escaping root) is exactly as real a finding as one that's simply
 // missing - reported the same way, not silently skipped.
 function checkStaticReference(findings, root, relativePath, originalPath, rootLabel, pageUrl) {
+    // sanitisePath realpaths its root unconditionally, so a site that has
+    // no media/, theme/assets/ or theme/root/ directory at all threw a
+    // raw ENOENT out of the whole check rather than reporting anything -
+    // the check crashing with a stack trace on exactly the sites most
+    // likely to hold a broken reference. A root that does not exist means
+    // the file underneath it does not exist either, which is an ordinary
+    // finding, not an error.
+    if (!existsSync(root)) {
+        findings.push({ kind: 'missing-asset', message: `${originalPath} does not exist under ${rootLabel}`, pageUrl });
+        return;
+    }
     try {
         const filePath = sanitisePath(root, relativePath);
         if (!existsSync(filePath)) {
@@ -62,6 +95,13 @@ function checkStaticReference(findings, root, relativePath, originalPath, rootLa
         throw error;
     }
 }
+// The file exists, so nothing else would ever flag it - which is
+// precisely why this needs saying. A content image outside media/ is
+// invisible to the media library, cannot be replaced by an editor, and
+// is not what the CMS manages.
+function misplacedMessage(path, where) {
+    return `${path} is a content image served from ${where} - it belongs in media/ (run \`npm run seed-media -- .. <file>\` from vhost/ and use the /media/... URL it prints)`;
+}
 export async function runSiteCheck(siteRoot) {
     const booted = bootSite(siteRoot);
     const findings = [];
@@ -86,18 +126,27 @@ export async function runSiteCheck(siteRoot) {
             findings.push({ kind: 'render-error', message: detail, pageUrl });
             continue;
         }
-        for (const ref of extractReferences(html)) {
-            if (ref.startsWith('http://') || ref.startsWith('https://') || ref.startsWith('data:') || ref.startsWith('//')) {
+        for (const { url: ref, attribute } of extractReferences(html)) {
+            if (hasExternalScheme(ref)) {
                 continue;
             }
             const path = ref.split(/[?#]/)[0] ?? ref;
+            // Only src/srcset/poster can carry a content image. An href is a
+            // link or a favicon, and flagging those would make this useless.
+            const rendersMedia = attribute !== 'href' && isUploadableMedia(path);
             if (path.startsWith('/media/')) {
                 checkStaticReference(findings, booted.config.mediaRoot, path.slice('/media/'.length), path, 'media/', pageUrl);
             }
             else if (path.startsWith('/assets/')) {
+                if (rendersMedia) {
+                    findings.push({ kind: 'misplaced-media', message: misplacedMessage(path, 'theme/assets/'), pageUrl });
+                }
                 checkStaticReference(findings, booted.config.assetsRoot, path.slice('/assets/'.length), path, 'theme/assets/', pageUrl);
             }
             else if (looksLikeStaticFile(path)) {
+                if (rendersMedia) {
+                    findings.push({ kind: 'misplaced-media', message: misplacedMessage(path, 'theme/root/'), pageUrl });
+                }
                 checkStaticReference(findings, booted.config.rootMirrorRoot, path.slice(1), path, 'theme/root/', pageUrl);
             }
             else if (path !== '' && !publishedUrlSet.has(path)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o-a/cms-agent",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "publishConfig": {
     "access": "public"