@o-a/cms-agent 0.3.0 → 0.4.0

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

@@ -21,7 +21,7 @@ theme/
   sections/   *.liquid, flat, one per section type - markup + embedded settings schema
   blocks/     *.liquid, flat, one per block type - markup + embedded settings schema
   snippets/   *.liquid, flat, no schema - small reusable partials, invoked with {% render %}
-  assets/     static files (CSS, JS, images) - served as-is at /assets/<path>
+  assets/     design assets only (CSS, JS, icons, sprites) - served as-is at /assets/<path>. NOT content images: photographs and any image an editor would ever replace belong in media/, see "Images" below
   root/       static files served at the bare site root (robots.txt, favicon.ico, etc.)
   templates/  *.json, flat, optional - prebuilt starting pages an editor can pick from
 ```
@@ -37,8 +37,9 @@ 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"`. 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. Preview the result before considering the task done - see "Previewing your work".
+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.
+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
 
@@ -109,6 +110,7 @@ Every setting is plain JSON Schema (`string`, `integer`, `number`, `boolean`, `a
 |---|---|---|
 | `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 |
 | `textarea` | `string` | Multi-line `<textarea>` |
 | `uri` | `string` | `<input type="url">` |
 | `date` | `string` | `<input type="date">`, value as `YYYY-MM-DD` |
@@ -186,6 +188,11 @@ Every type/format combination above needs nothing beyond what triggers it - no `
   "format": "image"
 }
 
+"backgroundLoop": {
+  "type": "object",
+  "format": "video"
+}
+
 "tags": {
   "type": "array",
   "items": { "type": "string" }
@@ -260,7 +267,7 @@ Required fields, `additionalProperties: false`:
 | `schemaVersion` | integer | Always `6` for new content |
 | `name` | string | Internal label (shown in the admin's page tree) |
 | `title` | string | Rendered as `{{ page.title }}` |
-| `type` | string | Free-form (e.g. `"page"`, `"blog-article"`) - use `pageType` filtering below to distinguish kinds |
+| `type` | string | **The field that decides which listings a page appears in.** Free-form (e.g. `"page"`, `"project"`, `"article"`), lowercase by convention. It is indexed as `pageType` and is what `GET /search.json?pageType=...` filters on, so a project listing, a blog index and a team directory each depend on their pages carrying the right value here. Give every kind of page its own type; `"page"` is for ordinary one-off pages only |
 | `layout` | string | A filename in `theme/layouts/` (no extension) - `"theme"` unless a different layout exists |
 | `published` | boolean | `false` behaves as if the page doesn't exist on the live site at all |
 | `sections` | array | Section instances - see below |
@@ -308,7 +315,11 @@ Each entry in `sections` requires `id` (any non-empty string, unique within the
 
 ## Images
 
-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:
+**Every content image lives in `media/`, named by the CMS itself - never placed there, or anywhere else in the repo, by hand.** If you are generating a site and have image files to use, `seed-media` (below) is the way to get them in; it is step 5 of the workflow above. Images do not go in the site root, in `theme/root/`, or in `theme/assets/` (that folder is for design assets - CSS, JS, icons).
+
+**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:
 
 ```json
 { "type": "string", "default": "" }

package/dist/media/filename.js

@@ -21,8 +21,15 @@ import { basename, extname } from 'node:path';
 // lowercase, non [a-z0-9-] runs collapsed to a single "-", trimmed -
 // not a second, independently-invented convention.
 const HASH_LENGTH = 12;
-// Images only - confirmed with the user, not a general document
-// library. .svg is rejected regardless of this list even though it's
+// Images and short videos - not a general document library. Video was
+// added deliberately (confirmed with the user) for silent looping
+// clips used where a hero image would otherwise go; long-form video
+// belongs on YouTube/Vimeo and needs nothing from here. The upload cap
+// (site.config.json's media.maxUploadBytes, 10MB by default) is what
+// keeps that distinction honest - it comfortably fits a well-compressed
+// 10-15s loop and comfortably rejects a real film.
+//
+// .svg is rejected regardless of this list even though it's
 // technically an image format - docs/cms-build-plan.md's own "SVG
 // rejected outright, not sanitised" decision (a real stored-XSS path
 // otherwise: mime-types.ts maps .svg to a real image/svg+xml content
@@ -33,7 +40,7 @@ const HASH_LENGTH = 12;
 // constant, specifically so seed-media.ts (an offline tool with no
 // HTTP request to validate) enforces the exact same rule rather than
 // a second, independently-maintained copy of it.
-export const ALLOWED_UPLOAD_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp']);
+export const ALLOWED_UPLOAD_EXTENSIONS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp', '.mp4', '.webm']);
 export function buildMediaFilename(originalFilename, bytes) {
     const hash = createHash('sha256').update(bytes).digest('hex').slice(0, HASH_LENGTH);
     const base = basename(originalFilename, extname(originalFilename));

package/dist/routes/media-public.d.ts

@@ -1,5 +1,11 @@
 import type { FastifyPluginAsync } from 'fastify';
 import type { SiteConfig } from '../config.ts';
+type ResolvedRange = {
+    start: number;
+    end: number;
+} | null | 'unsatisfiable';
+export declare function resolveRange(header: string | undefined, size: number): ResolvedRange;
 export declare const mediaPublicRoutes: FastifyPluginAsync<{
     config: SiteConfig;
 }>;
+export {};

package/dist/routes/media-public.js

@@ -1,5 +1,40 @@
 import { openLocalFsMediaDriver } from "../media/drivers/local-fs-driver.js";
 import { mimeTypeFor } from "../services/mime-types.js";
+export function resolveRange(header, size) {
+    if (header === undefined) {
+        return null;
+    }
+    const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+    if (!match) {
+        return null;
+    }
+    const [, rawStart, rawEnd] = match;
+    if (rawStart === '' && rawEnd === '') {
+        return null;
+    }
+    // "bytes=-500" means the LAST 500 bytes, not "from 0 to 500" - a
+    // classic misreading, and one that silently serves the wrong part of
+    // a file rather than failing.
+    if (rawStart === '') {
+        const suffixLength = Number(rawEnd);
+        if (suffixLength === 0) {
+            return 'unsatisfiable';
+        }
+        return { start: Math.max(0, size - suffixLength), end: size - 1 };
+    }
+    const start = Number(rawStart);
+    if (start >= size) {
+        return 'unsatisfiable';
+    }
+    // An end past the last byte is clamped, not rejected: browsers
+    // routinely ask for more than exists (e.g. bytes=0-999999 on a small
+    // file) and expect the server to simply return what it has.
+    const end = rawEnd === '' ? size - 1 : Math.min(Number(rawEnd), size - 1);
+    if (end < start) {
+        return 'unsatisfiable';
+    }
+    return { start, end };
+}
 async function handleMediaRequest(request, reply, config) {
     const relativePath = request.params['*'];
     // Never read: Fastify doesn't require query params to be declared or
@@ -30,12 +65,48 @@ async function handleMediaRequest(request, reply, config) {
     // because filenames are content-addressed (a hash of the file's own
     // bytes, see media/filename.ts): a given URL's content can never
     // change, so there is no invalidation case to ever design for here.
+    // Accept-Ranges on every media response, not just ranged ones - it is
+    // how a client learns ranges are available at all before asking.
+    //
+    // This matters far beyond scrubbing: Safari and iOS open a <video>
+    // with "Range: bytes=0-1" and will refuse to play at all if answered
+    // with a plain 200, so range support is what makes video work in
+    // those browsers rather than an optimisation. It also lets
+    // preload="metadata" fetch just the header instead of pulling the
+    // whole file down to read a duration.
+    //
+    // Sliced from the already-buffered read rather than streamed: the
+    // driver's own get() contract returns a whole Buffer (drivers/
+    // driver.ts) and assets.ts documents reply.send(stream) returning an
+    // empty body in this Fastify version, verified there with a minimal
+    // repro. With uploads capped (10MB by default) the memory held per
+    // request is bounded and no worse than this route's existing
+    // behaviour, so slicing buys correct semantics without taking on
+    // that risk or widening the driver interface a future object-storage
+    // driver would have to satisfy.
     reply
         .header('X-Content-Type-Options', 'nosniff')
         .header('Access-Control-Allow-Origin', '*')
         .header('Cache-Control', 'public, max-age=31536000, immutable')
-        .type(mimeTypeFor(relativePath))
-        .send(bytes);
+        .header('Accept-Ranges', 'bytes')
+        .type(mimeTypeFor(relativePath));
+    const range = resolveRange(request.headers.range, bytes.length);
+    if (range === 'unsatisfiable') {
+        // 416 carries its own required Content-Range naming the real size,
+        // which is how a client corrects itself rather than retrying blind.
+        reply.code(416).header('Content-Range', `bytes */${bytes.length}`).send();
+        return;
+    }
+    if (range !== null) {
+        const slice = bytes.subarray(range.start, range.end + 1);
+        reply
+            .code(206)
+            .header('Content-Range', `bytes ${range.start}-${range.end}/${bytes.length}`)
+            .header('Content-Length', slice.length)
+            .send(slice);
+        return;
+    }
+    reply.send(bytes);
 }
 // Deliberately and permanently unauthenticated, same reasoning as
 // assets.ts: uploaded media must be fetchable by any visitor's browser

package/dist/routes/media.js

@@ -30,7 +30,7 @@ async function handleUploadMedia(request, reply, config) {
         reply.code(415).send({
             statusCode: 415,
             error: 'Unsupported Media Type',
-            message: `"${extension}" is not an accepted image type`,
+            message: `"${extension}" is not an accepted media type`,
         });
         return;
     }

package/dist/services/mime-types.js

@@ -22,6 +22,13 @@ export const MIME_TYPES = {
     '.gif': 'image/gif',
     '.svg': 'image/svg+xml',
     '.webp': 'image/webp',
+    // Video: without these an uploaded .mp4 serves as the
+    // DEFAULT_MIME_TYPE below (application/octet-stream), which every
+    // browser treats as "download this" rather than playing it - and
+    // media-public.ts sets X-Content-Type-Options: nosniff, so nothing
+    // rescues it by sniffing. Same failure robots.txt already hit.
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
     '.ico': 'image/x-icon',
     '.woff': 'font/woff',
     '.woff2': 'font/woff2',

package/dist/services/validation.js

@@ -5,18 +5,18 @@ import { Ajv } from 'ajv';
 // authors, not agent code, and are validated the same lenient way
 // everywhere (see theme-schemas.ts).
 const ajv = new Ajv({ allErrors: true, strict: false });
-// The six format values guide-theme-authoring.md/AGENTS.md actually
-// document (richtext/image/textarea/uri/date/color/range/toggle - uri
-// and date are real standard JSON Schema formats already understood
+// The nine format values guide-theme-authoring.md/AGENTS.md actually
+// document (richtext/image/video/textarea/uri/date/color/range/toggle -
+// uri and date are real standard JSON Schema formats already understood
 // without this) are still, correctly, UI hints only: registering them
 // as a literal no-op format (the `true` here, not a real validator
 // function) doesn't make Ajv enforce anything about them, it only
 // stops it printing "unknown format \"x\" ignored" for values that are
 // completely expected. A theme author's genuine typo (e.g. "iamge")
 // still isn't in this list, so it still warns - this only silences the
-// six we ourselves tell theme authors to use, not unknown-format
+// ones we ourselves tell theme authors to use, not unknown-format
 // warnings in general.
-for (const format of ['richtext', 'image', 'textarea', 'color', 'range', 'toggle']) {
+for (const format of ['richtext', 'image', 'textarea', 'color', 'range', 'toggle', 'video']) {
     ajv.addFormat(format, true);
 }
 const schemasDir = join(import.meta.dirname, '..', 'schemas');

package/package.json

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