@glw907/cairn-cms 0.56.2 → 0.57.1

package/CHANGELOG.md

@@ -2,6 +2,140 @@
 
 All notable changes to this project are recorded here, most recent first.
 
+## 0.57.1
+
+Media polish and cutover DX, the first follow-on after the `0.57.0` media stack. The Media Library
+gains the action feedback it lacked: a delete, a rename, and a commit conflict now land on a strip
+that confirms the result or shows the error, instead of a silent page. With the detail slide-over open
+and focus in the search box, Escape now clears the search and leaves the panel open, rather than doing
+both at once. A frontmatter hero marked decorative persists that choice as an additive `decorative` key
+on the `image` object, so a deliberately decorative hero stops reading as needs-alt after a reload (a
+decorative body image still cannot persist the choice, since markdown alt text has no slot for it). The
+reserved-`figure` build error now names the colliding component and points at the fix.
+
+The rest is documentation. The public media resolver wiring moved into the required media setup steps
+in both the upgrade guide and the wire-the-delivery guide, since a published `media:` token ships bare
+without it. The reserved-`figure` collision is now a prominent breaking callout. A new
+[content authoring syntax reference](docs/reference/authoring-syntax.md) documents the `cairn:` and
+`media:` token schemes together. The guides now show the `wrangler.toml` binding dialect, the
+`@glw907/cairn-cms/media` import path, the empty-`media.json` bootstrap, and the `.site-main` re-scope
+for the figure placement CSS.
+
+No consumer action is required. The `decorative` key is additive and optional, so existing content
+parses and builds unchanged, and the feedback strip, the Escape fix, and the registry error message
+are admin or build-time with no public surface change.
+
+## 0.57.0
+
+Images become first-class. An editor can paste, drag, or insert an image straight into a post, and
+cairn stores it, names it by its content, commits it with the entry, and serves it from the site's
+own R2 bucket. This is the whole media stack landing together: the foundation that models a stored
+image, the infrastructure that ingests and delivers the bytes, and the insert UI that puts it in an
+editor's hands. It is additive to the public API, but it needs per-site wiring, so it is a minor.
+
+The foundation models an image as a logical reference, not a path. Content commits a `media:` token
+keyed to the first 16 hex characters of the bytes' sha256, so the same image resolves no matter where
+it is stored or what it is named, and identical bytes always land at one key. A small git-committed
+manifest (`media.json`) carries the human layer the bytes cannot: the display name, the alt text, the
+original filename, and the pixel facts. A render-time resolver reads that manifest and rewrites each
+`media:` token to its delivery URL, optionally through a Cloudflare Images transform URL when a site
+turns transforms on. The adapter's `AssetConfig` grew to declare the R2 bucket binding, the URL form,
+the upload limits, and the named variants.
+
+The infrastructure ingests and serves the bytes. A locked-down `/media` delivery route, built from
+`createMediaRoute`, streams content-addressed bytes from R2: it validates the hash and extension
+before any read, derives the object key from the validated values alone, carries the load-bearing
+security headers (nosniff, inline disposition, a `default-src 'none'; sandbox` CSP, a one-year
+immutable cache), and forwards `If-None-Match` and `Range` for 304 and 206 responses. An admin
+`uploadAction` takes the editor's bytes, hashes them, dedups against the manifest with a put-first
+head check, and rejects a hash collision with a 409. A client ingest helper normalizes a HEIC to a
+web format before upload. A save merges the editor's optimistic records into `media.json` at commit
+time, and the edit load hands the admin preview a lean `mediaTargets` projection so an in-session
+image renders before it is committed.
+
+The insert UI puts it in an editor's hands. Three gestures start an insert: paste from the clipboard,
+drag a file onto the editor, or the toolbar's Insert image button. A paste or drag opens an at-caret
+popover on the capture card with the dropped file; the button opens a chooser with upload first and a
+combobox picker below it for reusing an image already on the site. The capture card pre-fills the name
+from the filename and never blocks on alt text, so an editor can insert now and describe later. The
+inserted reference renders in the editor as an atomic chip (thumbnail, name, and a needs-alt marker),
+and an upload still in flight shows a widget-only placeholder with a determinate progress bar that
+writes no document text until it resolves. A non-blocking needs-alt notice on the edit page counts the
+images still waiting for a description and jumps to each one, never blocking a save or a Publish. The
+edit-page preview renders inserted images through the same resolver the live site uses.
+
+Figures land in the same release. An inline image can carry a caption and a placement through a
+cairn-reserved `:::figure` directive that wraps the image as a child node. The caption is the
+directive's body text, rendered to a real `<figcaption>`, and the placement is a closed role set
+(`center`, `wide`, `full`, plus the bare measure default) carried as a class on the `<figure>`. A
+persistent editor control wraps a bare image, edits an existing figure's caption and role, or unwraps
+it, writing the markdown source the author can read and hand-edit, and the source chip shows the
+figure's role so the decoration agrees with the source. `figure` and `figcaption` join the base
+sanitize floor, so a captioned figure survives on every site, and `figure` is a reserved directive
+name the registry refuses to let a site component shadow. cairn ships default `.cairn-place-*` CSS in
+the showcase reference, and a site restyles those classes to own the placement pixels. A guide section
+covers it in [add an image](docs/guides/add-an-image.md).
+
+Hero images land in the same release. A Post or Page carries a lead image in frontmatter as a nested
+`image: { src, alt, caption }` object, where `src` is a `media:` reference, `alt` is the screen-reader
+description, and `caption` is an optional line the template may show. `image` is a new built-in field
+type declared through `defineFields` like `text` or `date`. The editor renders it in the details panel
+as a one-row resting field that opens the same picker and capture flow the body insert uses. Alt stays
+debt, and the needs-alt notice now counts a hero with an empty alt alongside the body images. One
+image serves two jobs: the delivery read path resolves the frontmatter reference into a derived
+`heroImage` projection the template lays out, and the SEO head reads the same resolved image as the
+`og:image` and `twitter:image`. The on-disk `media:` token stays canonical, since resolution is a
+separate projection that is never written back. `resolveImageUrl` now rejects a non-http(s) result, so
+an unresolved `media:` token degrades to no social image rather than shipping a broken tag. The site
+template owns the hero layout: cairn ships the resolved data and the social-card wiring, not a hero
+render step. A required `image` field is enforced on the presence of its `src`, never on its alt.
+
+The Media Library lands in the same release. A first-class admin screen at `/admin/media`, a peer of
+Posts and Pages, browses every committed asset, shows where each one is used, edits its name and
+default alt, and deletes it safely. The resting surface is a contact-sheet grid with a list-density
+toggle; a non-modal detail slide-over carries the preview, the alt editor, the grouped where-used
+list, and the actions. The Library computes where-used by content hash across `main` and every open
+edit branch, so a not-yet-published upload still shows and a renamed slug still resolves. The content
+manifest gained an additive `mediaRefs` field per entry to feed the `main` side of that index; an
+existing manifest without it still parses and builds. Safe-delete rechecks usage server-side against
+a fresh read at delete time, refuses an in-use asset (the in-use face names what would break and
+requires typing the slug), commits the manifest row removal before deleting the R2 object, and fails
+closed if it cannot verify usage. Rename and default-alt are a single `media.json` row commit with no
+reference rewrite, since the resolver and route key on the hash; the default alt is the value
+prefilled into the next placement, not a rewrite of alt already committed. Replace, bulk actions, and
+tags are deferred.
+
+Consumers must: bind an R2 bucket and mount the delivery route before media works. Add an
+`r2_buckets` binding named `MEDIA_BUCKET` in `wrangler.jsonc`, and mount the delivery route at
+`src/routes/media/[...path]/+server.ts` with `createMediaRoute(runtime.resolvedAssets)`. Declare the
+adapter's `assets` block naming that binding, and regenerate nothing else; media stays off until the
+`assets` block is present. Cloudflare Images transforms stay behind the `transformations: false`
+default, so a site serves full-size bytes until it opts in. The wiring steps are in
+[the upgrade guide](docs/guides/upgrade-cairn.md) and the
+[wire the delivery surface guide](docs/guides/wire-the-delivery-surface.md); the surface is documented
+in [the media reference](docs/reference/media.md) and
+[the sveltekit reference](docs/reference/sveltekit.md).
+
+Consumers must also wire the public media resolver for any public image. The bucket, route, and
+`assets` block make media work for the editor, but a published `![](media:...)` (a body image or a
+frontmatter hero) ships a bare token to the live page unless the site threads a resolver into the
+render path and `createPublicRoutes`. Build one with
+`makeMediaResolver(mediaManifest, normalizeAssets({ bucketBinding: 'MEDIA_BUCKET' }))` from
+`@glw907/cairn-cms/media`, where `mediaManifest` is the committed `src/content/.cairn/media.json`
+(create it as `{}` on a fresh site so the import resolves). The
+[upgrade guide](docs/guides/upgrade-cairn.md) gives the full snippet.
+
+Breaking: `figure` is now a reserved directive name. `defineRegistry` throws if a site registers a
+component named `figure`, which hard-fails both `cairn-manifest` and the build. A custom `figure` that
+the engine's built-in figure now covers should be removed so the site adopts the engine's; a `figure`
+that does something else should be renamed. Check too for any hand-authored `:::figure` block in your
+content, which now renders as an engine figure.
+
+Recommended, not required: regenerate the content manifest (`cairn-manifest`) and commit it so the
+Media Library's `main` where-used is accurate. The `mediaRefs` field is additive, so a site builds
+without it, but an un-regenerated manifest reads every published media reference as absent until it
+is regenerated. Save and publish keep the field current from then on.
+
 ## 0.56.2
 
 The component insert picker gains a live preview and round-trip editing, and the component contract

package/dist/components/AdminLayout.svelte

@@ -20,6 +20,7 @@ identical on every host regardless of the site's own theme.
   import SignpostIcon from '@lucide/svelte/icons/signpost';
   import SettingsIcon from '@lucide/svelte/icons/settings';
   import UsersIcon from '@lucide/svelte/icons/users';
+  import ImageIcon from '@lucide/svelte/icons/image';
   import BlocksIcon from '@lucide/svelte/icons/blocks';
   import ExternalLinkIcon from '@lucide/svelte/icons/external-link';
   import './cairn-admin.css';
@@ -56,6 +57,8 @@ identical on every host regardless of the site's own theme.
   // the owner-only Editors.
   const coreItems: NavItem[] = $derived([
     ...data.concepts.map((c) => ({ label: c.label, icon: FileTextIcon, href: `/admin/${c.id}` })),
+    // Media is a content peer, immediately after the concepts.
+    { label: 'Media', icon: ImageIcon, href: '/admin/media' },
     ...(data.navLabel ? [{ label: data.navLabel, icon: SignpostIcon, href: '/admin/nav' }] : []),
     { label: 'Settings', icon: SettingsIcon, href: '/admin/settings' },
     ...(data.canManageEditors ? [{ label: 'Editors', icon: UsersIcon, href: '/admin/editors' }] : []),

package/dist/components/CairnAdmin.svelte

@@ -13,11 +13,13 @@ mount inside `AdminLayout`. No styling or wrapper elements of its own.
   import EditPage from './EditPage.svelte';
   import ManageEditors from './ManageEditors.svelte';
   import NavTree from './NavTree.svelte';
+  import CairnMediaLibrary from './CairnMediaLibrary.svelte';
   import type { AdminData } from '../sveltekit/cairn-admin.js';
   import type { ContentFormFailure } from '../sveltekit/content-routes.js';
   import type { ComponentRegistry } from '../render/registry.js';
   import type { IconSet } from '../render/glyph.js';
   import type { LinkResolve } from '../content/links.js';
+  import type { MediaResolve } from '../render/resolve-media.js';
 
   interface Props {
     /** The discriminated view data from `createCairnAdmin`'s load. */
@@ -33,7 +35,10 @@ mount inside `AdminLayout`. No styling or wrapper elements of its own.
         })
       | null;
     /** The site's design-accurate render pipeline, for the edit view's preview pane. */
-    render?: (md: string, opts?: { stagger?: boolean; resolve?: LinkResolve }) => string | Promise<string>;
+    render?: (
+      md: string,
+      opts?: { stagger?: boolean; resolve?: LinkResolve; resolveMedia?: MediaResolve },
+    ) => string | Promise<string>;
     /** The site's component registry, for the edit view's insert palette. */
     registry?: ComponentRegistry;
     /** The site's icon set, for the edit view's guided form fields. */
@@ -62,6 +67,8 @@ mount inside `AdminLayout`. No styling or wrapper elements of its own.
       <ManageEditors data={data.page} {form} />
     {:else if data.view === 'nav'}
       <NavTree data={data.page} />
+    {:else if data.view === 'media'}
+      <CairnMediaLibrary data={data.page} {form} />
     {/if}
   </AdminLayout>
 {/if}

package/dist/components/CairnAdmin.svelte.d.ts

@@ -3,6 +3,7 @@ import type { ContentFormFailure } from '../sveltekit/content-routes.js';
 import type { ComponentRegistry } from '../render/registry.js';
 import type { IconSet } from '../render/glyph.js';
 import type { LinkResolve } from '../content/links.js';
+import type { MediaResolve } from '../render/resolve-media.js';
 interface Props {
     /** The discriminated view data from `createCairnAdmin`'s load. */
     data: AdminData;
@@ -18,6 +19,7 @@ interface Props {
     render?: (md: string, opts?: {
         stagger?: boolean;
         resolve?: LinkResolve;
+        resolveMedia?: MediaResolve;
     }) => string | Promise<string>;
     /** The site's component registry, for the edit view's insert palette. */
     registry?: ComponentRegistry;