@rigel-cms/rigel 1.4.0-rc.3 → 1.5.0-rc.1

package/docs/content-model.md

@@ -75,7 +75,7 @@ A schema reference declares `to: ["callout"]` and stores `{ "_ref": "callout:not
 
 Schema `markdown` fields store Markdown strings. Article collection bodies store Lexical state in `{ frontmatter, body }` JSON and have a read-only Markdown view. Keep those formats separate. Custom article blocks and widgets are covered in [Extensions](extensions.md).
 
-Markdown fields open in the article block editor when the source survives a conversion round trip. Set `sidebarOnly: true` on a `markdown` field to keep it in the properties panel even when its preview binding is available, for example a FAQ answer edited beside the question that owns it:
+In Inline preview mode, clicking an eligible bound Markdown field on a non-shared schema page opens the article block editor when the source survives a conversion round trip. Unbound fields and shared-document forms keep their properties-panel editor. Set `sidebarOnly: true` on a `markdown` field to keep it in the properties panel even when its preview binding is available, for example a FAQ answer edited beside the question that owns it:
 
 ```ts
 const faqAnswer = { key: "answer", label: "Answer", type: "markdown", sidebarOnly: true };

package/docs/extensions.md

@@ -44,7 +44,7 @@ export default defineExtension({
       if (typeof data.label !== 'string' || !data.label.trim()) {
         throw new Error('Enter a button label.');
       }
-      if (typeof data.href !== 'string' || !/^\/[a-z0-9/-]*$/.test(data.href)) {
+      if (typeof data.href !== 'string' || !/^\/(?!\/)[a-z0-9/-]*$/.test(data.href)) {
         throw new Error('Choose a local path such as /contact/.');
       }
     },

package/docs/media.md

@@ -48,17 +48,17 @@ Metadata lives in `.rigel-media.json` inside the configured media folder, keyed
 
 New uploads use random UUID filenames.
 
-Open an asset in Media, edit its display name, title, description or image alt text, then press Save. Metadata writes validate the listed asset URL, reject unknown fields and use an atomic sidecar replacement. Display names allow safe filename-like characters up to 120 characters without requiring an extension. Titles are capped at 200 characters; descriptions and alt text at 1,000. Nonimages cannot receive alt metadata.
+On the local backend, open an asset in Media, edit its display name, title, description or image alt text, then press Save. Metadata writes validate the listed asset URL, reject unknown fields and use an atomic sidecar replacement. Display names allow safe filename-like characters up to 120 characters without requiring an extension. Titles are capped at 200 characters; descriptions and alt text at 1,000. Nonimages cannot receive alt metadata.
 
 Local file uploads send a browser-supplied author label through `X-Rigel-Author`. Rigel uses the browser identity's name or nickname, falling back to `Local user`. This is a descriptive label, not verified ownership or an audit identity. The metadata editor cannot change it. Existing files and URL or stock imports may have no captured author; the interface displays `Local user` as a fallback.
 
-Saved repository-image alt text supplies an insertion default. You can override it for each use, or leave it empty for a decorative image. Rigel does not rewrite alt text already stored in content. Rich-text insertions remain unsaved until the document's Save action.
+For rich-text image insertion, saved repository-image alt text supplies a default that you can override per use, or leave empty for a decorative image. Image fields store the URL; declare and render a separate alt field where your site needs one. Store the original URL rather than a path your build generates. [Preview](preview.md) covers the `data-rigel-src` binding for optimized Astro images. Rigel does not rewrite alt text already stored in content. Rich-text insertions remain unsaved until the document's Save action.
 
 ## Image URLs and stock providers
 
 Image pickers offer Library, Upload, URL and Lorem Picsum. Pexels, Pixabay and Unsplash appear when their keys are configured in Settings under Media. Repository Upload excludes Unsplash.
 
-URL, Picsum, Pexels and Pixabay image imports download bytes through the browser and upload them locally. Remote image downloads require HTTPS and browser CORS permission. The import path accepts JPEG, PNG and WebP responses within the configured size limit. Download failures stay visible. The server accepts validated bytes rather than fetching arbitrary remote URLs.
+Remote URL, Picsum, Pexels and Pixabay image imports download bytes through the browser and upload them locally. In a content picker, a root-relative URL can be used directly without making a copy. Remote image downloads require HTTPS and browser CORS permission. The import path accepts JPEG, PNG and WebP responses within the configured size limit. Download failures stay visible. The server accepts validated bytes rather than fetching arbitrary remote URLs.
 
 Unsplash selections keep the provider's hotlink and record the download through its API. They do not become repository files. Rich-text stock insertions retain credit links; check the provider's current licensing and [Unsplash hotlinking requirements](https://unsplash.com/documentation#hotlinking) for your use.
 

package/docs/menus.md

@@ -90,6 +90,6 @@ The local menu endpoint supports reading and updating existing regular files. It
 
 GitHub-backed menus use the configured repository, content root and draft branch. The remote store validates the same menu shape and maximum depth, disallows menu creation, and checks the expected file state before writing. See [GitHub](github.md) for authentication, conflicts and publishing.
 
-URL validation accepts HTTP, HTTPS, mailto and tel protocols, including relative paths and fragments resolved against the site. It rejects protocol-relative URLs, backslashes, whitespace, control characters and unsafe protocols such as `javascript:`. It does not check whether the destination exists or is trustworthy. Keep the `noopener noreferrer` attributes when rendering new-tab links.
+URL validation accepts HTTP, HTTPS, mailto and tel protocols, along with relative paths and fragments whose destinations your website renderer and browser determine. It rejects protocol-relative URLs, backslashes, leading/trailing whitespace, ASCII spaces and ASCII control characters, and unsafe protocols such as `javascript:`. It does not check whether the destination exists or is trustworthy. Keep the `noopener noreferrer` attributes when rendering new-tab links.
 
 For navigation inside the CMS rather than website links, use [sidebar configuration](sidebar.md). See the [documentation index](README.md) for the other guides.

package/docs/preview-hosts.md

@@ -33,9 +33,9 @@ Bases accept HTTPS with an optional path prefix. For example, `https://www.examp
 
 ## Separate templates from public routes
 
-The canvas resolves a configured `template` first. It is a static root-relative path on the editor's own origin, unaffected by either host base. Both new and saved content use it. A page mapping can use `{ url: "/about/", template: "/rigel/preview/about/" }`; document and collection mappings accept `template` too. The host must emit the route. Inside the CMS, only `/rigel/preview/` and its descendants are allowed as templates.
+The canvas resolves a configured `template` first. It is a static root-relative path on the editor's own origin, unaffected by either host base. Saved schema pages and new or saved articles use it; new schema pages have no canvas until their first Save, even with a template configured. A page mapping can use `{ url: "/about/", template: "/rigel/preview/about/" }`; document and collection mappings accept `template` too. The host must emit the route. Inside the CMS, only `/rigel/preview/` and its descendants are allowed as templates.
 
-Without `template`, article canvases use the collection's `new` route even after Save or when reopening an existing article. This lets a prepared empty layout display an in-memory draft without waiting for deployment. Schema pages and legacy copy pages use their mapped routes; a new schema page needs an existing route or a prepared template to load successfully.
+Without `template`, article canvases use the collection's `new` route even after Save or when reopening an existing article. This lets a prepared empty layout display an in-memory draft without waiting for deployment. With neither `template` nor `new`, an article has no canvas, even if its `url` is mapped. Saved schema pages and legacy copy pages use their mapped routes when no template is configured.
 
 Live links always use the real content route, including a new article's eventual URL. Draft website links also use the real route, rather than the canvas template. These links can lead to a page that has not been deployed yet. Edited URL slugs apply to website/live destinations; the prepared canvas can keep using its stable template.
 

package/docs/preview.md

@@ -24,9 +24,9 @@ rigel({
 
 `pages` maps legacy copy-page slugs. `documents` maps schema type names; `index` is the route for the effective slug `home`. `collections` maps article collection names. Every configured route must actually exist in your host output.
 
-`template` is a static editor-local route used by the canvas, for both new and saved content. It stays on the editor's origin even when `draftUrl` is set. `/rigel/preview/` is the permitted template namespace inside the CMS, not a route generator. The host must supply the prepared page.
+`template` is a static editor-local route used by the canvas for saved schema pages and new or saved articles. It stays on the editor's origin even when `draftUrl` is set. `/rigel/preview/` is the permitted template namespace inside the CMS, not a route generator. The host must supply the prepared page.
 
-A collection can instead use `new: "/preview/blog/"`. Without `template`, the article canvas uses `new` for saved articles too, while the public link uses `url`. Schema pages without `template` use their mapped document route. Set a template when a new page must preview before its public route exists. See [Preview hosts](preview-hosts.md) for the full destination rules.
+A collection can instead use `new: "/preview/blog/"`. Without `template`, the article canvas uses `new` for saved articles too, while the public link uses `url`. Article canvases require `template` or `new`; a `url` mapping alone provides website links but no canvas. Saved schema pages without `template` use their mapped document route. New schema pages have no canvas until their first Save, even with a configured template. See [Preview hosts](preview-hosts.md) for the full destination rules.
 
 ## Bind rendered fields
 
@@ -44,6 +44,21 @@ These HTML excerpts illustrate the scalar anchors. Render the saved values throu
 
 Paths use object keys and stable array `_key` values. Array positions are not preview bindings. For schema content, put `data-rigel-doc="page:about"` on each bound element and on section/list containers. It identifies the source document for that element; a parent attribute does not substitute for attributes on descendant anchors. Referenced records use their own IDs and local field paths.
 
+### Keep optimized images editable
+
+Astro's `Image` and `Picture` components replace `src` with hashed, responsive candidates, so changing `src` alone changes nothing while `srcset` still lists the old files. Mark an editable image with `data-rigel-src` to show the draft instead:
+
+```astro
+<Image src={cover} alt={hero.alt} widths={[480, 960]} sizes="100vw" data-rigel-image="hero.image" data-rigel-alt="hero.alt" data-rigel-src={hero.image} />
+<Picture src={cover} formats={["avif", "webp"]} alt={hero.alt} data-rigel-image="hero.image" data-rigel-src={hero.image} />
+```
+
+`data-rigel-image` names the field, as before. `data-rigel-src` holds the original browser-addressable URL that the field stores, and it marks the element as optimized. In preview, a marked image loses its `srcset` and `sizes`, and the surrounding `picture` sources lose theirs, so the field value is the file the browser loads. The attribute is not a second source of truth: preview renders the field value, and a value that fails the image URL check is dropped rather than loaded.
+
+Public pages are untouched. Rigel patches only the editor iframe, so built markup keeps its hashed URLs, `srcset` and AVIF or WebP sources. Images without `data-rigel-src` keep their previous behavior: the `src` changes and any `srcset` stays.
+
+Store the original reference in content, never a generated path. `/images/cover.jpg`, a media URL or an HTTPS URL work; `/_astro/cover.BnV1MXKY.webp` does not, because Astro derives it at build time. An imported file is not addressable either: `src/assets/cover.jpg` has no URL a browser can request. Serve the file from a public path or the media folder and bind that URL, even when the template imports the same file for optimization. Preview shows the original at its own size, not a resized or converted variant, and the built `width` and `height` stay as they were, so check a replacement with different proportions against the template's layout. An upload becomes reachable at its media URL once the host serves it or rebuilds.
+
 ## Prepare changing sections and lists
 
 Scalar anchors update existing elements. Adding sections needs inert templates for each allowed section type. This HTML excerpt uses the `intro` section from [Content model](content-model.md):
@@ -81,11 +96,13 @@ These bindings patch declared regions, not arbitrary component logic. Conditiona
 
 Browse mode is read-only. Edit mode lets editors select bound regions, work with section structure and open properties. The page remains visible with a notice if the required bindings are missing. A double-click on a supported single-line text binding opens inline editing; Enter accepts the draft value and Escape reverts that inline edit. Neither action writes content.
 
-Clicking a bound schema `markdown` region opens the same block editor the article body uses, mounted on that rendered element. Root-level fields, section fields and fields nested in objects or array items all take this path. Editors get block handles with duplicate, delete and move actions, drag reordering, insertion between blocks, table and media insertion, inline formatting, and undo and redo. The toolbar and the block handle float beside the prose, which keeps the website's typography and flow. Edits write back to the same in-memory Markdown string, and the active rich-text region belongs to its editor until editing ends rather than being overwritten by the DOM patcher.
+In Inline preview mode, clicking an eligible bound schema `markdown` region on a non-shared page opens the same block editor the article body uses, mounted on that rendered element. Root-level fields, section fields, nested objects and single-shape object arrays can use this path. Nested-array lookup uses the first declared object shape; fields exclusive to other item types in a heterogeneous array cannot be edited inline. Editors get block handles with duplicate, delete and move actions, drag reordering, insertion between blocks, table and media insertion, inline formatting, and undo and redo. The toolbar and the block handle float beside the prose, which keeps the website's typography and flow. Edits write back to the same in-memory Markdown string, and the active rich-text region belongs to its editor until editing ends rather than being overwritten by the DOM patcher.
+
+A field uses the fallback Markdown editor when its source cannot round-trip through the block format without loss, such as raw HTML, a Markdown table, a fenced block with a language, or a hard-wrapped paragraph. The fallback has its own round-trip check: a language-tagged fence can remain visual there, while unsupported syntax opens in source view. Nothing is converted or written until an editor actually changes the field, and the stored value stays a Markdown string either way. The shared toolbar does not make every article block or format losslessly representable in Markdown; edited content may reopen in the fallback editor. Set `sidebarOnly: true` on a field to keep it in the properties panel, as described in [content model](content-model.md).
 
-A field keeps the inline Markdown editor when its source cannot round-trip through the block format without loss, such as raw HTML, a Markdown table, a fenced block with a language, or a hard-wrapped paragraph. That editor falls back to its source view for the same reasons. Nothing is converted or written until an editor actually changes the field, and the stored value stays a Markdown string either way. Set `sidebarOnly: true` on a field to keep it in the properties panel, as described in [content model](content-model.md).
+Settings > Content > Article body editing selects Inline preview (the default) or Sidebar. Eligible schema Markdown regions use Inline preview in place; the properties panel offers Edit in preview instead of a second editor. Unbound fields, shared-document forms and fields declared `sidebarOnly` keep their properties-panel editor. Sidebar moves eligible rich-text editing back into the panel.
 
-Articles use the same canvas. Settings > Content > Article body editing selects Inline preview (the default) or Sidebar. Inline preview mounts the body editor on the prepared `$body` element and opens bound rich-text Markdown regions in place; the properties panel then offers Edit in preview for those regions instead of a second editor. Fields without a preview binding, and fields declared `sidebarOnly`, keep their sidebar editor, and Sidebar moves rich-text editing back into the panel. If the `$body` region is unavailable, the body editor stays in the sidebar. Only one editor owns the draft at a time, and the preview patcher leaves its active region alone. Article Markdown view is read-only.
+Articles use the same canvas, but their body and frontmatter follow separate paths. Inline preview mounts the article body editor on the prepared `$body` element; if that region is unavailable, the body stays in the sidebar. Article frontmatter Markdown fields remain sidebar-edited even when bound in the preview. Only one editor owns an active region, and the preview patcher leaves it alone. Article Markdown view is read-only.
 
 Explicit Save writes content through the configured backend. Navigation guards and failed-save handling apply to canvas edits too. Browser preferences save independently. See [GitHub](github.md) for saved drafts and publishing, and [Extensions](extensions.md) for custom article content.
 
@@ -95,6 +112,6 @@ The iframe uses `sandbox="allow-same-origin"` without `allow-scripts`. The trust
 
 Same-origin pages load directly in the iframe. Cross-origin pages are fetched with CORS, sanitized and displayed in a same-origin `srcdoc` snapshot. There is no draft postMessage bridge. See [Preview hosts](preview-hosts.md) for credentials, headers, CSP and subresource limits before using a remote host.
 
-Markdown preview disables raw HTML and passes its rendered output through a DOMPurify allowlist before inserting a DOM fragment. Article preview uses the shared article renderer and sanitizes its output. URL bindings reject script/data schemes, protocol-relative URLs, backslashes, whitespace and control characters; image bindings accept relative or HTTP(S) URLs, and links also accept `mailto:`. Host-specific Markdown plugins and JavaScript syntax highlighting are outside this renderer's scope.
+Markdown preview disables raw HTML and passes its rendered output through a DOMPurify allowlist before inserting a DOM fragment. Article preview uses the shared article renderer and sanitizes its output. URL bindings reject script/data schemes, protocol-relative URLs, backslashes, ASCII whitespace and ASCII control characters; image bindings accept relative or HTTP(S) URLs, and links also accept `mailto:`. Host-specific Markdown plugins and JavaScript syntax highlighting are outside this renderer's scope.
 
 The host remains responsible for safe public rendering. Preview sanitization does not sanitize your Astro templates, create public routes or implement draft filtering for visitors. Verify both the editor canvas and the public output when adding a field or section.

package/docs/seo.md

@@ -68,7 +68,7 @@ const socialImage = imageUrl && ["https:", "http:"].includes(imageUrl.protocol)
 </html>
 ```
 
-Set Astro's `site` to your real public base URL so relative image paths produce production URLs; `Astro.url` is the development fallback in this example. Choose your own description fallback, title suffix and document language. The starter uses its shared Site settings for the default description and site-name suffix, rather than a fixed product name.
+Set Astro's `site` to your real public base URL so relative image paths produce production URLs; this example falls back to `Astro.url` whenever `site` is unset, including production builds. Choose your own description fallback, title suffix and document language. The starter uses its shared Site settings for the default description and site-name suffix, rather than a fixed product name.
 
 Canonical links, social title/description tags, structured data, sitemaps and language alternates remain host-template work. The example emits only the tags shown. Check the built HTML, including absolute image URLs and empty-image behavior, rather than treating the editor canvas as proof that public metadata is correct.
 

package/docs/sidebar.md

@@ -34,7 +34,7 @@ sidebar: [
 
 Entries appear in configured order. Use headings for labels and separators for plain dividers; these groups are flat, not nested or collapsible. A link's optional `label` overrides its content-derived label.
 
-Targets use stable identifiers rather than display labels:
+Targets use content IDs or configured names. Category targets use the exact declared category string:
 
 | Target | Opens |
 | --- | --- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigel-cms/rigel",
-  "version": "1.4.0-rc.3",
+  "version": "1.5.0-rc.1",
   "description": "A CMS for Astro sites. You edit the text, Git keeps the history.",
   "keywords": [
     "astro",

package/src/preview.ts

@@ -217,7 +217,22 @@ export function patchPreview(doc: Document, values: Record<string, unknown>, bod
     if (blocks) previews.set(el, mountExtensionPreviews(el));
     rendered.set(el, source);
   }
-  for (const [anchor, attr, tag] of [["image", "src", "IMG"], ["alt", "alt", "IMG"], ["href", "href", "A"]]) {
+  for (const el of doc.querySelectorAll<HTMLImageElement>("[data-rigel-image]")) {
+    if (el.tagName !== "IMG") continue;
+    const result = get(el, el.getAttribute("data-rigel-image")!);
+    if (!result.found) continue;
+    const value = result.value === null || result.value === undefined ? "" : String(result.value);
+    const safe = safePreviewUrl(value, true);
+    if (el.hasAttribute("data-rigel-src")) {
+      el.removeAttribute("srcset");
+      el.removeAttribute("sizes");
+      for (const source of el.closest("picture")?.querySelectorAll("source") ?? []) { source.removeAttribute("srcset"); source.removeAttribute("sizes"); }
+      if (safe) el.setAttribute("data-rigel-src", value);
+    }
+    if (safe) { if (el.getAttribute("src") !== value) el.setAttribute("src", value); }
+    else el.removeAttribute("src");
+  }
+  for (const [anchor, attr, tag] of [["alt", "alt", "IMG"], ["href", "href", "A"]]) {
     for (const el of doc.querySelectorAll(`[data-rigel-${anchor}]`)) {
       if (el.tagName !== tag) continue;
       const result = get(el, el.getAttribute(`data-rigel-${anchor}`)!);