@wxxb789/anc 0.0.1 → 0.0.3

package/src/lib/markdown.js

@@ -32,6 +32,8 @@ import { MATH_MODE } from "./math-mode.js";
 import { RENDERED_DIAGRAM, RENDERED_MARKER, RENDERED_MATH } from "./rendered-marker.js";
 import { NAV_LANGUAGE, translate } from "./translations.js";
 import { slugFromSegment } from "./route-path.js";
+import { classifyImageSource } from "./media.js";
+import { deliveredMediaUrl, mediaDeliveryOrigin } from "./media-delivery.js";
 /**
  * Today's route shape, which the producer already emits. Keeping it as the
  * default means rendering is unchanged until TK-04 injects its own mapping.
@@ -937,6 +939,94 @@ function asClassList(value) {
         return value.filter((item) => typeof item === 'string');
     return typeof value === 'string' ? value.split(/\s+/) : [];
 }
+/**
+ * A standalone, captioned image becomes `figure > img + figcaption`.
+ *
+ * **Only the title becomes a caption.** `alt` is the accessible alternative and
+ * stays on the image; ordinary alt text never turns into reader-visible prose.
+ * A title is the author's explicit visible label, which is what Markdown's
+ * `![alt](path "Caption")` and a reference definition's title already mean.
+ *
+ * The shape is deliberately narrow:
+ *
+ * - a paragraph **or list item** must contain exactly one meaningful child, and
+ *   it must be an `img` — so `Prose ![alt](x) prose` keeps its inline image, and
+ *   a link-wrapped image (`[![badge](x)](target)`) is not promoted because its
+ *   child is the anchor;
+ * - the image must have a non-empty title; an uncaptioned image keeps the exact
+ *   container it had, so no empty `<figcaption>` and no invented "Figure 1";
+ * - a decorative `alt=""` image with no title is therefore untouched, and a
+ *   title is authored content rather than something derived from `alt`.
+ *
+ * A tight list item (`- ![alt](x "Cap")`) has the image as the item's direct
+ * child, while a loose one carries a paragraph; both must become the same
+ * figure. Promoting a paragraph that is already inside a list item and then
+ * re-checking the item is safe because the item's meaningful child is then the
+ * promoted `figure`, not an `img`, so it is not wrapped twice.
+ *
+ * A blockquote's own paragraph is promoted too: a figure is a block, so it
+ * remains valid there. A table cell holds no paragraph here, and a fenced code
+ * block's content is text, so neither can reach this visitor with an element
+ * `img` child.
+ */
+function imageFigurePlugin() {
+    const titledOnlyImage = (node) => {
+        const meaningful = (node.children ?? []).filter((child) => !(child.type === 'text' && /^\s*$/.test(child.value)));
+        if (meaningful.length !== 1)
+            return undefined;
+        const image = meaningful[0];
+        if (image.type !== 'element' || image.tagName !== 'img')
+            return undefined;
+        const title = image.properties?.['title'];
+        if (typeof title !== 'string' || title.trim() === '')
+            return undefined;
+        return { image, title };
+    };
+    const figureFor = (image, title) => {
+        const { title: _caption, ...properties } = image.properties ?? {};
+        return {
+            type: 'element',
+            tagName: 'figure',
+            properties: { className: ['image-figure'] },
+            children: [
+                { ...image, properties },
+                {
+                    type: 'element',
+                    tagName: 'figcaption',
+                    properties: {},
+                    children: [{ type: 'text', value: title }],
+                },
+            ],
+        };
+    };
+    return {
+        name: 'anc-image-figures',
+        element: [
+            {
+                filter: ['p'],
+                visit(node, ctx) {
+                    const found = titledOnlyImage(node);
+                    if (found === undefined)
+                        return;
+                    ctx.replaceNode(node, figureFor(found.image, found.title));
+                },
+            },
+            {
+                filter: ['li'],
+                visit(node) {
+                    const found = titledOnlyImage(node);
+                    if (found === undefined)
+                        return;
+                    const figure = figureFor(found.image, found.title);
+                    return {
+                        ...node,
+                        children: (node.children ?? []).map((child) => (child === found.image ? figure : child)),
+                    };
+                },
+            },
+        ],
+    };
+}
 /**
  * The fence info string satteri records on a code node, or `undefined` for an
  * unlabelled fence. hast's `ElementData` is an open record with no declared
@@ -967,7 +1057,8 @@ const POLICY = {
     /**
      * satteri and this module's own plugins emit only: `a blockquote code del em
      * h1`–`h6 hr img input li ol p pre section strong sup table tbody td th thead
-     * tr ul`, plus `figure` and `span` from the code-block transform.
+     * tr ul`, plus `figure`/`figcaption` from the code-block, diagram, and image
+     * transforms, and `span` from the math source path.
      *
      * The remainder are reachable only through raw HTML in a note body. They are
      * kept because requirements 15.1 promises a "safe HTML subset", and because a
@@ -998,7 +1089,7 @@ const POLICY = {
             'href', 'title', 'class', 'rel', 'aria-label', 'aria-describedby',
             'data-footnote-ref', 'data-footnote-backref', 'id',
         ],
-        img: ['src', 'alt', 'title'],
+        img: ['src', 'alt', 'title', 'width', 'height', 'loading', 'decoding'],
         h1: ['id'],
         h2: ['id', 'class'],
         h3: ['id'],
@@ -1016,7 +1107,6 @@ const POLICY = {
         section: ['class', 'data-footnotes'],
         blockquote: ['class', 'cite', 'data-callout'],
         figure: ['class', 'data-code-language', 'data-diagram'],
-        figcaption: ['class'],
         div: ['class', 'tabindex'],
         input: ['type', 'checked', 'disabled', 'aria-label'],
         th: ['colspan', 'rowspan', 'scope', 'data-align'],
@@ -1051,10 +1141,10 @@ const POLICY = {
         section: ['footnotes'],
         blockquote: ['callout', 'callout-*'],
         // `diagram` is the figure a rendered diagram sits in; `code-block` the one a
-        // fence sits in. `diagram-canvas` and `diagram-source` are the two shapes a
-        // diagram takes, one per mode.
-        figure: ['code-block', 'diagram'],
-        figcaption: [],
+        // fence sits in; `image-figure` a standalone image with an authored caption.
+        // `diagram-canvas` and `diagram-source` are the two shapes a diagram takes,
+        // one per mode.
+        figure: ['code-block', 'diagram', 'image-figure'],
         div: ['diagram-canvas'],
         pre: ['diagram-source'],
         strong: ['callout-title'],
@@ -1080,6 +1170,50 @@ const POLICY = {
         'iframe', 'object', 'embed', 'form', 'svg', 'math', 'title',
     ],
 };
+/**
+ * Whether `sanitize-html` will keep this `src` after the transforms run.
+ *
+ * This mirrors the policy the sanitizer actually applies, for the one decision
+ * that must not be made before it: which image is the article's lead. A
+ * transform runs before the scheme allowlist, so treating any present `src` as
+ * surviving spent the eager image on a `javascript:`, `file:`, `mailto:`, `ftp:`
+ * or protocol-relative URL the sanitizer then removed, leaving the real first
+ * image lazy.
+ *
+ * The predicates are the policy's own (`allowedSchemesByTag.img`,
+ * `allowProtocolRelative`, and the safe-`data:` test the transform applies),
+ * and the laundering is the sanitizer's: remove every character at or below
+ * U+0020, then remove complete HTML comments before reading a scheme.
+ */
+function imageSourceSurvivesPolicy(source) {
+    if (source === undefined)
+        return false;
+    // The transform turns an unsafe `data:` URI into an empty `src`, which the
+    // sanitizer then drops because `src` is a non-boolean attribute.
+    if (/^data:/i.test(source) && !SAFE_IMAGE_DATA_URI.test(source))
+        return false;
+    let href = Array.from(source, (character) => (character <= ' ' ? '' : character)).join('');
+    for (;;) {
+        const first = href.indexOf('<!--');
+        if (first === -1)
+            break;
+        const last = href.indexOf('-->', first + 4);
+        if (last === -1)
+            break;
+        href = href.slice(0, first) + href.slice(last + 3);
+    }
+    if (href === '')
+        return false;
+    const allowProtocolRelative = POLICY.allowProtocolRelative !== false;
+    if (!allowProtocolRelative && /^[/\\]{2}/.test(href))
+        return false;
+    const scheme = /^([a-zA-Z][a-zA-Z0-9.\-+]*):/.exec(href)?.[1]?.toLowerCase();
+    if (scheme === undefined)
+        return true;
+    const byTag = typeof POLICY.allowedSchemesByTag === 'object' ? POLICY.allowedSchemesByTag : undefined;
+    const allowed = byTag?.['img'] ?? (Array.isArray(POLICY.allowedSchemes) ? POLICY.allowedSchemes : []);
+    return allowed.includes(scheme);
+}
 /**
  * The rendering policy's terminal step. Transforms that must observe *every*
  * anchor and image live here rather than in a hast plugin, because raw HTML in
@@ -1088,7 +1222,7 @@ const POLICY = {
  * `<a href="/other/">` written as raw HTML. `sanitize-html` parses the final
  * HTML, so it sees all of them, and its allowlist runs after `transformTags`.
  */
-function sanitize(html, routeForSlug, generatedIds, rawIds) {
+function sanitize(html, routeForSlug, generatedIds, rawIds, publishedAssets, assetDimensions) {
     // Each generated id survives exactly once. `headingPlugin` has already made
     // the generated set disjoint from every raw-HTML id, so this no longer
     // arbitrates a collision — it only stops a raw duplicate of a generated id
@@ -1097,8 +1231,32 @@ function sanitize(html, routeForSlug, generatedIds, rawIds) {
     const usedFootnoteIds = new Set();
     // One deny token per raw-HTML claim on that id; see the note below.
     const denials = new Map(rawIds);
+    // The first image that actually keeps a `src` is the article's lead, and the
+    // rest are below it. This closure advances in parse order, which is document
+    // order for the one sanitizer pass; an `<img>` with no surviving source is not
+    // a content image and does not spend the lead.
+    let leadImagePending = true;
+    // A minimal open-element stack, used by the one structural rule the allowlist
+    // cannot express: a `figcaption` outside a `figure` is a shape this renderer
+    // never emits, so a raw-HTML one is renamed to an inert `span` rather than
+    // left claiming caption semantics. `onOpenTag` runs before the tag's own
+    // transform, so the current tag is the stack's last entry and its parent is
+    // the one before it.
+    const openTags = [];
+    // The public custom-domain origin, when this build was explicitly opted into
+    // a managed image host (`anc build --release --media r2`). `undefined` is the
+    // ordinary same-origin build, and then every image `src` below is untouched.
+    // Read once per render, not per image: the environment cannot change while
+    // one note is being rendered.
+    const deliveryOrigin = mediaDeliveryOrigin();
     return sanitizeHtml(html, {
         ...POLICY,
+        onOpenTag: (name) => openTags.push(name),
+        onCloseTag: (name) => {
+            const index = openTags.lastIndexOf(name);
+            if (index !== -1)
+                openTags.length = index;
+        },
         transformTags: {
             // Element ids are page-global names, and the layout owns hooks such as
             // `#search-toggle`. Only ids this pipeline generated survive, and each
@@ -1171,20 +1329,107 @@ function sanitize(html, routeForSlug, generatedIds, rawIds) {
             // only for the base64 raster types TK-01's artifact scanner allowlists.
             // The scheme allowlist alone is too coarse: it would also admit
             // `data:image/svg+xml`, which can carry a script, and `data:text/html`.
+            //
+            // **A local `src` must name an asset this build published.** The producer
+            // rewrites every image reference it authorizes to a `/_assets/<digest>-<name>`
+            // URL, and refuses an unauthorized one, so anything else local here is a
+            // reference that bypassed the pipeline — a raw-HTML `<img>` the producer
+            // missed, or an artifact path that names no emitted file. Shipping it would
+            // be a broken picture and, in the second case, a request for a file this
+            // build never wrote. It throws instead, which stops the build; the message
+            // names the source for the report and never reaches a stream, because a
+            // plain `Error` is not disclosure-checked.
+            //
+            // Remote and `data:` sources keep their existing treatment: they are never
+            // fetched, never mirrored, and their forms did not change in this goal.
             img: (tagName, attribs) => {
                 const source = attribs['src'];
+                // **The producer and this transform share one classifier.** See
+                // {@link classifyImageSource} in `media.ts`: it strips every character
+                // at or below U+0020 before reading a scheme, the same way
+                // `sanitize-html`'s `launder` does. Testing the raw bytes here used to
+                // call `<img src=" https://…">` local while the producer called it an
+                // unpublished image, so one URL got two answers; the shared function
+                // makes both sides read it as remote. `refused` and `remote` are both
+                // non-local here, which keeps the sanitizer's scheme policy deciding
+                // the fate of `file:`/`javascript:`/`vbscript:` and protocol-relative
+                // values exactly as before. `data:` keeps its separate body below.
+                const external = source !== undefined && classifyImageSource(source) !== 'local';
+                // An `<img>` with no `src` at all is not a reference to anything, and the
+                // producer refuses that form outright (`html-form`); the renderer leaves
+                // the element as the allowlist always has. A *present* src that is not
+                // remote has to name a published asset.
+                if (source !== undefined && !external && !publishedAssets.has(source)) {
+                    throw new Error('a local image reference reached the renderer without being published: ' +
+                        JSON.stringify(source) +
+                        '. The producer publishes an image by rewriting it to its /_assets/<digest>-<name> URL; ' +
+                        'a local src anywhere else names no file this build emits.');
+                }
                 const src = source !== undefined && /^data:/i.test(source) && !SAFE_IMAGE_DATA_URI.test(source)
                     ? undefined
                     : source;
+                // **Delivery is not identity.** An authorized asset keeps its canonical
+                // `/_assets/<digest>-<name>` path in the artifact, the staged file, the
+                // output inventory, and the remote object key. Only when the build was
+                // opted into a managed host does the emitted `src` become the absolute
+                // custom-domain URL; the path after the origin is byte-identical, which
+                // is what lets the upload plan and the HTML agree without a second
+                // naming scheme. Remote author-supplied URLs and `data:` URIs are never
+                // rewritten. The value was validated when it crossed into the process
+                // (`media-delivery.ts`), so `https:` here is a checked fact rather than
+                // an assumption about the environment.
+                const delivered = src !== undefined && publishedAssets.has(src) && deliveryOrigin !== undefined
+                    ? deliveredMediaUrl(src, deliveryOrigin)
+                    : src;
+                // The lead is the first image whose source the sanitizer will actually
+                // keep. A transform runs before the scheme allowlist, so testing only
+                // `src !== undefined` spent it on a URL that was about to be stripped.
+                const survives = imageSourceSurvivesPolicy(delivered);
+                let dimensions;
+                let loading;
+                if (survives && src !== undefined) {
+                    // The intrinsic size the producer read from these exact bytes, if its
+                    // header yielded one. Serialized as strings because that is what an
+                    // HTML attribute is; `CSS height: auto` plus `max-width: 100%` keeps
+                    // the ratio responsive after the browser reserves the space.
+                    dimensions = assetDimensions.get(src);
+                    // Lead-versus-deferred is decided by rendered document order, not by a
+                    // guess about position: the first image that keeps a source is the one
+                    // a reader meets first, so it stays eager. Everything after it defers.
+                    // `decoding="async"` is assigned to both; it is a hint about the
+                    // decode thread, not a delay, and it cannot slow the lead's fetch.
+                    loading = leadImagePending ? 'eager' : 'lazy';
+                    leadImagePending = false;
+                }
+                // A stripped source carries no layout or loading claim: author-supplied
+                // `loading`, `decoding`, `width` and `height` would otherwise survive
+                // the allowlist on an element with no picture.
+                const { loading: _loading, decoding: _decoding, width: _width, height: _height, ...withoutImageClaims } = attribs;
                 return {
                     tagName,
                     attribs: {
-                        ...attribs,
-                        ...(src === undefined ? { src: '' } : { src }),
+                        ...(survives ? attribs : withoutImageClaims),
+                        ...(delivered === undefined ? { src: '' } : { src: delivered }),
                         alt: typeof attribs['alt'] === 'string' ? attribs['alt'] : '',
+                        ...(dimensions === undefined
+                            ? {}
+                            : { width: String(dimensions.width), height: String(dimensions.height) }),
+                        ...(loading === undefined ? {} : { loading, decoding: 'async' }),
                     },
                 };
             },
+            // A `figcaption` is a valid caption only as a direct child of a `figure`.
+            // This renderer emits exactly that shape (the image transform above and
+            // the two diagram modes), so a raw-HTML caption elsewhere is markup this
+            // pipeline does not produce and must not survive with caption semantics.
+            // Renaming it to an inert `span` keeps the author's text instead of
+            // silently deleting it, while ensuring the page has no orphan caption.
+            figcaption: (tagName) => {
+                const parent = openTags[openTags.length - 2];
+                return parent === 'figure'
+                    ? { tagName, attribs: {} }
+                    : { tagName: 'span', attribs: {} };
+            },
             // Task-list checkboxes are visual state, not controls. Forcing the shape
             // here also neutralizes any other raw-HTML input (a text field, a hidden
             // field) instead of relying on the tag allowlist alone. `checked` and
@@ -1423,11 +1668,12 @@ export async function renderMarkdown(markdown, options = {}) {
             calloutPlugin(),
             mathPlugin(collected, maths),
             codePlugin(collected, diagrams, chrome.diagramCaption),
+            imageFigurePlugin(),
             taskListPlugin(),
             tablePlugin(),
         ],
     });
-    const sanitized = sanitize(html, routeForSlug, new Set(collected.headings.map((heading) => heading.id)), collected.rawIds);
+    const sanitized = sanitize(html, routeForSlug, new Set(collected.headings.map((heading) => heading.id)), collected.rawIds, options.publishedAssets ?? new Set(), options.assetDimensions ?? new Map());
     // Rendered after sanitization, at markers the sanitizer preserved. Both
     // renderers are the trust boundary for their own output; see the note on
     // `DIAGRAM_TOKEN_PREFIX`. A render failure throws and stops the build, which