@glw907/cairn-cms 0.56.1 → 0.57.0

package/CHANGELOG.md

@@ -2,6 +2,154 @@
 
 All notable changes to this project are recorded here, most recent first.
 
+## 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).
+
+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
+grows the optional fields that make a good picker possible. These refine the existing
+component-editing surface and are all additive, so it is a patch; existing definitions compile
+unchanged with no action required.
+
+How the design was reached. Two research arms ran first. One surveyed how comparable systems build
+their insert pickers (Gutenberg, Sanity, Wagtail, Payload, Contentful, Builder, and the git-backed and
+document tools). The other hunted documented complaints from both the editor and the developer, then
+paired each with a correction. Five pains recur across systems that share no code, and cairn already
+beats four of them by its existing architecture: a single `ComponentDef` co-locates render and schema
+(no schema-render drift), content is markdown in git (no database-migration tax), and the parser reads
+real directives (lossless re-edit stays reachable). The fifth pain, configuring a block without seeing
+the result, no system has solved. An adversarial critique of the first mockup then caught the preview
+faked with static HTML and an ironic "Untitled" placeholder, which the shipped design corrects.
+
+What an editor gets. The picker lists components in one column, grouped under headings, each row a
+glyph, a description, and a line on when to reach for it; a search box appears once a site declares
+more than eight. Picking a component that declares a `preview` opens a two-pane configure step: the
+fill form on the left, and on the right the configured component rendered through the site's own
+pipeline, the same machinery the edit page preview uses. This is the part no comparable CMS offers,
+and cairn can offer it because it already owns the render path. The preview settles on a debounce
+rather than re-rendering on every keystroke, and it stays honest: a still-empty required field shows
+the skeleton with the empty region called out rather than a fabricated result, and a render that
+throws shows a failed-to-render surface and keeps the form. A component that declares no `preview`
+keeps the single-column form. Required fields are marked and block Insert with inline messages, and
+the modal collapses to one column on a narrow screen.
+
+Round-trip editing closes the loop. With the cursor in a placed component, an Edit block control opens
+it back into the same guided form, pre-filled, and Update rewrites that block in place. It is offered
+only when the round-trip is provably lossless for that block: one that carries an attribute or a child
+the component does not declare is left for hand-editing rather than silently rewritten, the failure
+that corrupts content in the git-backed editors the research surveyed. A guided edit that does run
+preserves content and normalizes formatting to the canonical serialization. A consumer site that
+mounts `CairnAdmin` gets this with no change.
+
+For consumers, the `ComponentDef` contract gains optional fields, so existing definitions compile
+unchanged with no action required:
+
+- `icon` shows a glyph from the site icon set beside the label in the picker.
+- `group` puts a component under a category heading, in declaration order.
+- `hidden` keeps a component out of the top-level picker (for a nested-only component).
+- `preview` is a structured sample (`attributes` and `slots`) the picker seeds the form with and
+  renders. Declaring it is what opts a component into the two-pane preview layout.
+- `pattern` and `validate` on an attribute field add inline validation, the regex case and a pure
+  cross-field escape hatch.
+- `itemLabel` on a repeatable slot derives a row's label, so a list of items is not a column of blanks.
+
+Round-trip editing of a placed component, a persistent catalog rail, and a slash-trigger are designed
+for but deferred to a later pass.
+
 ## 0.56.1
 
 Test and CI reliability only; the published library is unchanged from 0.56.0. The component test job

package/README.md

@@ -52,10 +52,16 @@ doesn't, cairn is the wrong tool and will not try to meet you halfway.
 
 ## Status
 
-cairn-cms runs the two production sites above. It is `0.x`, and the version position signals scale:
-a minor bump (`0.X.0`) carries a significant new feature and may break, while a patch (`0.X.Y`) is a
-safe fix, polish, or tooling change. Pin a caret range and read the [CHANGELOG](./CHANGELOG.md)
-before taking a minor; every breaking entry carries a "Consumers must" line. The author is still working through the core-feature
+cairn-cms runs the two production sites above. It is `0.x`, and the version position signals scale.
+A minor bump (`0.X.0`) is reserved for a new subsystem or public surface that did not exist before,
+such as a new entry point, a new content concept, or the scaffolder, and it may break. Everything
+that refines, extends, or adds an affordance to a surface that already exists (the editor, the admin,
+auth, delivery) is a patch (`0.X.Y`), even when it gives an editor a new thing to do; a redesign, a
+round-trip edit on an existing surface, or a new optional config field is a patch. When the call is
+unclear, it is a patch. A minor release carries a `<!-- release-size: minor -->` marker in its
+CHANGELOG entry, which the `check:version` gate requires, so a minor is always a deliberate,
+documented choice. Pin a caret range and read the [CHANGELOG](./CHANGELOG.md) before taking a minor;
+every breaking entry carries a "Consumers must" line. The author is still working through the core-feature
 [ROADMAP](./ROADMAP.md), and the project stays closely held until that core lands. A
 contributor who feels inspired is welcome to open an issue or a discussion; there is no
 formal contribution process yet, so this is not an open call for pull requests.

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;