@wxxb789/anc 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,7 @@
 # anc — a privacy-preserving static site generator for Markdown notes and digital gardens
 
 [![status: pre-release](https://img.shields.io/badge/status-pre--release-orange)](#status)
+[![npm](https://img.shields.io/npm/v/@wxxb789/anc?label=npm)](https://www.npmjs.com/package/@wxxb789/anc)
 [![node: >=22.18](https://img.shields.io/badge/node-%E2%89%A522.18-brightgreen)](#working-on-the-tool)
 [![verify](https://github.com/wxxb789/anc/actions/workflows/verify.yml/badge.svg)](https://github.com/wxxb789/anc/actions/workflows/verify.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
@@ -22,7 +23,8 @@ Ordinary reading needs no JavaScript, and nothing is sent to a third party.
 ![A note page built by anc: breadcrumbs, published and updated dates from git, tags, aliases, a table of contents, and a callout, in the dark theme](docs/assets/screenshot-note.webp)
 
 *anc* is short for **A**ctive **N**oise **C**ancelling. The command it installs is
-`anc`; the package is named `@wxxb789/anc` and is not yet published to npm.
+`anc`; the package is [`@wxxb789/anc`](https://www.npmjs.com/package/@wxxb789/anc) on
+npm.
 
 ## Contents
 
@@ -43,12 +45,15 @@ Ordinary reading needs no JavaScript, and nothing is sent to a third party.
 
 ## Status
 
-**Pre-release.** The tool builds, previews, and ships the GitHub Action and the `init`
-command. It is named `@wxxb789/anc`, because the unscoped `anc` is already taken on
-npm, and it is not on the registry yet; install from a checkout or from the tarball the
-repository builds. [`docs/adoption.md`](docs/adoption.md) gives both, along with
-configuration, exclusion, links, and hosting. ANC is not yet 0.1.0-ready or
-1.0.0-ready and makes no backward-compatibility promise.
+**Pre-release.** The tool builds, previews, ships the GitHub Action, and is on the
+registry. [`@wxxb789/anc`](https://www.npmjs.com/package/@wxxb789/anc) publishes from a
+`vX.Y.Z` tag through the `release` workflow, and each release carries SLSA provenance
+generated by npm's trusted publishing. `0.0.1` was published by hand for one reason: a
+trusted publisher is configured on a package page that has to exist first. The name is
+scoped because the unscoped `anc` already belongs to an unrelated package.
+[`docs/adoption.md`](docs/adoption.md) covers configuration, exclusion, links, and
+hosting. ANC is not yet 0.1.0-ready or 1.0.0-ready and makes no backward-compatibility
+promise.
 
 ## Why anc
 
@@ -103,23 +108,15 @@ Every image below is a real page built by anc from a small synthetic garden;
 
 ## Quick start
 
-From a checkout of this repository, against your own notes:
+Install it in the notes repository you want to publish:
 
 ```bash
-node /path/to/anc/bin/anc.mjs build --content ~/notes --out ~/notes/dist
-node /path/to/anc/bin/anc.mjs preview --dist ~/notes/dist
+npm install -D @wxxb789/anc       # or: pnpm add -D @wxxb789/anc
+npx @wxxb789/anc init             # seed .gitignore and write publish.config.yaml
 ```
 
-Or install the tarball the repository builds:
-
-```bash
-cd /path/to/anc && pnpm run pack:tarball
-cd ~/notes
-pnpm add -D /path/to/anc/wxxb789-anc-*.tgz   # or: npm install -D /path/to/anc/wxxb789-anc-*.tgz
-```
-
-Then name the commands in your notes repository's `package.json`; the same scripts
-work under pnpm and npm:
+Then name the commands in that repository's `package.json`; the same scripts work
+under pnpm and npm:
 
 ```json
 {
@@ -139,12 +136,19 @@ pnpm run review    # write .publish-set.json for inspection
 pnpm run release   # exact publish set + pinned Gitleaks on PATH
 ```
 
-To call the binary directly, use `pnpm exec anc build`, or `npx --no anc build` under
-npm: `--no` makes `npx` refuse rather than fetch from the registry when the local
-install is missing. After publication the registry form will be
-`npx @wxxb789/anc build`. **Do not type bare `npx anc`:** outside a project with the
-tarball installed it falls back to the registry, where the unscoped `anc` is an
-unrelated third-party package that `npx` would offer to download and run.
+Without installing, `npx @wxxb789/anc build --content ~/notes --out ~/notes/dist` runs
+the published release, and `npx @wxxb789/anc preview --dist ~/notes/dist` serves the
+result. **Do not type bare `npx anc`:** the unscoped `anc` on npm is an unrelated
+third-party package, and `npx` would offer to download and run it.
+
+To try an unreleased commit instead, build the tarball from a checkout and install that;
+the scripts above apply to it too:
+
+```bash
+cd /path/to/anc && pnpm run pack:tarball
+cd ~/notes
+pnpm add -D /path/to/anc/wxxb789-anc-*.tgz   # or: npm install -D …
+```
 
 ## How publication is decided
 
@@ -190,8 +194,31 @@ a disclosure there; that is why the names and the counts are split.
 - Frontmatter can set `slug`, `language`, `description`, `tags`, and `aliases`.
   Aliases are public, searchable metadata with no route of their own — deliberately
   not alternate link targets.
-- Non-Markdown files are never published. There is no asset pipeline, so an embedded
-  image degrades to text and is reported.
+- Local images referenced by a published note are published under
+  `/_assets/<sha256>-<name>`, identified by the **emitted** bytes and deduplicated by content,
+  so one picture is one file however many notes embed it. A JPEG photograph becomes lossy
+  WebP only when the candidate is smaller; a PNG screenshot, diagram, or alpha graphic
+  becomes lossless WebP only when that is smaller. Existing WebP/AVIF and every animation
+  are published unchanged, with every frame and delay. A local, self-contained **static SVG**
+  is build-only input: it is validated against a fail-closed XML/CSS subset, rasterized from
+  its bytes to lossless WebP at twice its logical size, and its source is never served. Every
+  external reference, `data:` payload, script, animation, foreign namespace, DTD and CSS
+  at-rule is refused; text no installed font covers fails the build rather than publishing
+  tofu. No resize, crop, responsive matrix, image CDN, browser script, per-image setting, or
+  bundled font exists. A reference resolves relative to the note, then the content root; a
+  missing, excluded, escaping, corrupt, over-limit, or unsupported one fails the build rather
+  than shipping a broken picture. Remote images are left as written and never fetched. A
+  standalone image's explicit Markdown title becomes a visible `<figcaption>` while `alt`
+  stays the accessible alternative; dimensions come from the emitted bytes — half the emitted
+  raster for a 2× SVG (the logical size unless the output budget clamped it, in which case the
+  layout shrinks with the raster) — so layout space is reserved, and the first image loads
+  eagerly while later ones defer.
+- The encoder and SVG rasterizer are the pinned `sharp` package, installed as an ordinary
+  dependency with its prebuilt platform binary: no system CLI, `cwebp`, `librsvg`, `resvg`,
+  or `libvips` install step. SVG text uses the build host's fonts, and missing coverage fails
+  rather than adding a bundled font. Linux x64 is the platform exercised by this repository's
+  gates; Windows and macOS use sharp's prebuilt packages but were not exercised here, and
+  cross-platform byte equality is not promised.
 
 ## Architecture
 
@@ -239,12 +266,14 @@ notes, both exclusion mechanisms, links and backlinks, rich Markdown, math, and
 ## Adoption and hosting
 
 The GitHub Action at the repository root runs a release build on a supported Linux
-runner, installs the checksum-pinned secret scanner, and writes a static `dist/`. Any
-static host serves that directory, at the root of a domain: a site under a path such
-as `https://<user>.github.io/<repo>/` is not supported. `dist/_headers` carries a
-Content-Security-Policy and three other security headers in Cloudflare Pages' format;
-a host that ignores that file still gets the policy from each page's `<meta>` tag,
-except `frame-ancestors`, and serves the other headers only if configured to.
+runner, installs the checksum-pinned secret scanner, and writes a static `dist/`. Pin it
+to `@v0.0.2` for one exact release, `@v0` to follow the latest 0.x, or a full commit SHA
+for the strongest pin. Any static host serves that directory, at the root of a domain:
+a site under a path such as `https://<user>.github.io/<repo>/` is not supported.
+`dist/_headers` carries a Content-Security-Policy and three other security headers in
+Cloudflare Pages' format; a host that ignores that file still gets the policy from each
+page's `<meta>` tag, except `frame-ancestors`, and serves the other headers only if
+configured to.
 
 Publication is an explicit external side effect. Building does not deploy, and nothing
 in this repository can. [`docs/adoption.md`](docs/adoption.md) covers both the Action

package/bin/anc.mjs

@@ -125,6 +125,15 @@ import { failureFor, isDisclosureChecked, openReport, BuildFailure } from '../sc
 /** This package's own root — the directory holding `astro.config.mjs`. */
 const PACKAGE_ROOT = fileURLToPath(new URL('../', import.meta.url));
 
+// **No command in this tool reports telemetry.** Astro reports anonymous usage
+// over the network unless this variable is set, and both `build` and `preview`
+// reach Astro. Every workflow in this repository already set it, so the shipped
+// binary was the one path still making an outbound request the user did not ask
+// for — and `docs/adoption.md` now says plainly that ordinary builds and
+// previews are offline. Set before any command imports Astro, because the
+// telemetry module reads it when it loads.
+process.env['ASTRO_TELEMETRY_DISABLED'] = '1';
+
 const USAGE = `anc — build a static site from a directory of Markdown
 
 Usage
@@ -140,6 +149,9 @@ Options for build
   --content <dir>  directory holding the Markdown (default: the working directory)
   --out <dir>      where to write the site (default: <working directory>/dist)
   --release        require a non-loopback origin and committed exact publish-set review
+  --media r2       publish referenced images to the Cloudflare R2 bucket configured
+                   under the media: table in publish.config.yaml, and point the site
+                   at its public custom domain. Requires --release.
 
 Options for preview
   --dist <dir>     the built site to serve (default: <working directory>/dist)
@@ -188,7 +200,7 @@ function packageVersion() {
  * does not take the third argument as a promise that it is stored somewhere.
  */
 function parseArguments(argv) {
-  const options = { content: undefined, out: undefined, release: false };
+  const options = { content: undefined, out: undefined, release: false, media: undefined };
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
     if (argument === '--help' || argument === '-h') return 'help';
@@ -196,16 +208,38 @@ function parseArguments(argv) {
       options.release = true;
       continue;
     }
-    const key = argument === '--content' ? 'content' : argument === '--out' ? 'out' : undefined;
+    const key =
+      argument === '--content'
+        ? 'content'
+        : argument === '--out'
+          ? 'out'
+          : argument === '--media'
+            ? 'media'
+            : undefined;
     if (key === undefined) {
       throw new BuildFailure('unknown-option', `unrecognised option\n\n${USAGE}`, argument);
     }
     const value = argv[index + 1];
-    // `argument` is `--content` or `--out` by construction here — the ternary
-    // above has already rejected everything else — so it is a literal of this
-    // tool's own source rather than a user-supplied string.
+    // `argument` is `--content`, `--out`, or `--media` by construction here —
+    // the ternary above has already rejected everything else — so it is a
+    // literal of this tool's own source rather than a user-supplied string.
     if (value === undefined || value.startsWith('--')) {
-      throw new BuildFailure('missing-value', `${argument} needs a directory\n\n${USAGE}`);
+      throw new BuildFailure(
+        'missing-value',
+        `${argument} needs ${key === 'media' ? 'a provider name' : 'a directory'}\n\n${USAGE}`,
+      );
+    }
+    // **The value is not echoed, even though it looks like a closed set.** A
+    // user who mistypes `--media` and then pastes a path is showing this tool a
+    // withheld name, and the refusal's job is to tell them the one supported
+    // value, not to repeat what they typed. Anything other than the literal
+    // `r2` is refused here so a misspelling cannot silently fall back to a
+    // local build.
+    if (key === 'media' && value !== 'r2') {
+      throw new BuildFailure(
+        'unknown-media-provider',
+        `unrecognised media provider; the only supported value is r2\n\n${USAGE}`,
+      );
     }
     options[key] = value;
     index += 1;
@@ -216,8 +250,9 @@ function parseArguments(argv) {
 function parseReviewArguments(argv) {
   const options = parseArguments(argv);
   if (options === 'help') return options;
-  if (options.out !== undefined || options.release) {
-    const option = options.out !== undefined ? '--out' : '--release';
+  if (options.out !== undefined || options.release || options.media !== undefined) {
+    const option =
+      options.out !== undefined ? '--out' : options.release ? '--release' : '--media';
     throw new BuildFailure('unknown-option', `review does not accept ${option}\n\n${USAGE}`, option);
   }
   return { content: options.content };
@@ -327,6 +362,19 @@ async function build(options) {
   const contentDirectory = resolve(userDirectory, options.content ?? '.');
   const outDirectory = resolve(userDirectory, options.out ?? 'dist');
 
+  // **Remote writes require both halves of the opt-in.** `--media r2` alone is
+  // refused before a report exists or a note is read: the release gate (public
+  // origin, committed exact publish set) is what makes the run deployable, and a
+  // media publication whose HTML was never released is the shape that produces
+  // remote objects nobody references. The reverse is fine — `--release` without
+  // `--media` is the ordinary offline release.
+  if (options.media !== undefined && !options.release) {
+    throw new BuildFailure(
+      'media-requires-release',
+      `--media r2 is only available with --release; an ordinary build cannot write remotely`,
+    );
+  }
+
   // Opened before anything can fail, and it writes its stub immediately. The
   // diagnostic is worth most on the run that failed, and a report written where
   // the counts are convenient — after validation — cannot exist on the run that
@@ -343,7 +391,7 @@ async function build(options) {
     }
     assertSafeOutput(outDirectory, contentDirectory, userDirectory);
 
-    await buildInto(contentDirectory, outDirectory, report, options.release);
+    await buildInto(contentDirectory, outDirectory, report, options.release, options.media);
     return report;
   } catch (error) {
     // Recording the failure must not *replace* it. If this second write throws —
@@ -361,7 +409,7 @@ async function build(options) {
   }
 }
 
-async function buildInto(contentDirectory, outDirectory, report, release) {
+async function buildInto(contentDirectory, outDirectory, report, release, media) {
   // Build inside the package, then copy out. Not an ad-hoc workaround but the
   // shape the two constraints in this file's header force: cwd must be inside
   // the package for prerender chunks to resolve their imports, Astro stages
@@ -409,6 +457,28 @@ async function buildInto(contentDirectory, outDirectory, report, release) {
       );
     }
 
+    // **The delivery location crosses into the renderer here, and only here.**
+    // The pages are evaluated by Astro after the `chdir` below; this environment
+    // variable is the same seam `CONFIG_DIRECTORY_VARIABLE` uses, and it is set
+    // before `astroBuild()` so every note renders the final absolute URL.
+    //
+    // Clearing it on an ordinary build is deliberate rather than defensive
+    // tidiness: the variable is this tool's internal channel, and a stale value
+    // left in a shell must not silently turn a same-origin build into a page
+    // that points at somebody's CDN without any object being uploaded.
+    const { MEDIA_BASE_URL_VARIABLE } = await import('../src/lib/media-delivery.js');
+    if (media === undefined) {
+      delete process.env[MEDIA_BASE_URL_VARIABLE];
+    } else {
+      if (config.media === undefined) {
+        throw new BuildFailure(
+          'media-config-missing',
+          '--media r2 requires a `media:` table in publish.config.yaml',
+        );
+      }
+      process.env[MEDIA_BASE_URL_VARIABLE] = config.media.publicBaseUrl;
+    }
+
     // Tell `astro.config.mjs` where to read the same file from, and this line is
     // the difference between a configured site and a silently ignored
     // configuration. Measured without it: a `publish.config.yaml` naming
@@ -522,6 +592,13 @@ async function buildInto(contentDirectory, outDirectory, report, release) {
     const { copyWasmToOutput } = await import('../scripts/copy-wasm.js');
     copyWasmToOutput(staging, snapshotDirectory);
 
+    // The image assets the producer authorized and staged beside the artifact,
+    // moved into the output after Astro emptied it. No count on the stream: a
+    // build's reading surface is fixed, and the report already carries what was
+    // published.
+    const { copyAssetsToOutput, assetSourceDirectory } = await import('../scripts/copy-assets.js');
+    copyAssetsToOutput(staging, validated, assetSourceDirectory(artifact));
+
     const { emitRedirects } = await import('../scripts/emit-redirects.js');
     emitRedirects(staging);
 
@@ -539,7 +616,39 @@ async function buildInto(contentDirectory, outDirectory, report, release) {
     const { assertNoResidue } = await import('../scripts/scan-residue.js');
     console.log(`residue scan ok: ${assertNoResidue(staging)} files, 0 findings`);
 
-    // Only now is the output fit to hand over. Copying after the scan rather than
+    // **Ordered publication, not a transaction.** Everything above qualified a
+    // private candidate: the publish set, the schema and route contract, the
+    // exact output inventory, the secret scan and the residue scan all ran over
+    // `staging`, and the user's `--out` has not been touched. Only now, with the
+    // gates passed and the HTML already carrying the final custom-domain URLs,
+    // may an object be written remotely. `publishMedia` uploads or reuses every
+    // declared asset and then reads each one back through the public domain and
+    // hashes it; a failure here throws before the promotion below, so the last
+    // good local output survives and no candidate with broken links is handed
+    // over.
+    //
+    // An ablation property, not a comment: `publish-media.ts` is imported
+    // dynamically only on this branch, and it imports `aws4fetch` only inside
+    // its publish function. `tests/media-r2-build.test.ts` records a
+    // child-process module trace proving an ordinary build resolves no signer.
+    if (media !== undefined) {
+      const { publishMedia, resolveMediaCredentials } = await import('../scripts/publish-media.js');
+      const credentials = resolveMediaCredentials(config.media);
+      const result = await publishMedia({
+        assets: validated.assets ?? [],
+        assetDirectory: assetSourceDirectory(artifact),
+        config: config.media,
+        credentials,
+      });
+      // Integers and literals only. The object keys are public asset paths, but
+      // a stream is not the place to enumerate them — the site's own HTML is.
+      console.log(
+        `media: ${result.referenced} referenced, ${result.uploaded} uploaded, ` +
+          `${result.reused} already present, ${result.verified} verified`,
+      );
+    }
+
+    // Only now is the output fit to hand over. Copying after the scans rather than
     // before means a build that fails a gate leaves the user's `dist/` untouched,
     // holding whatever last passed — the same property `validate-content.ts`
     // argues for at the front of the chain.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wxxb789/anc",
   "type": "module",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Build a static, privacy-preserving site from a directory of Markdown",
   "keywords": [
     "static-site-generator",
@@ -74,12 +74,17 @@
     "!scripts/benchmark-workload-ui.ts",
     "!scripts/benchmark-workload.ts",
     "!scripts/release-changelog.ts",
+    "!scripts/media-corpus.ts",
+    "!scripts/measure-media.ts",
+    "!scripts/measure-svg.ts",
     "!scripts/smoke-tarball.ts"
   ],
   "dependencies": {
     "@astrojs/prism": "4.1.2",
     "@sqlite.org/sqlite-wasm": "3.53.4-build1",
     "astro": "7.4.5",
+    "aws4fetch": "1.0.20",
+    "css-tree": "3.2.1",
     "github-slugger": "2.0.0",
     "happy-dom": "20.14.5",
     "mermaid": "12.2.0",
@@ -87,6 +92,8 @@
     "prismjs": "1.30.0",
     "sanitize-html": "2.18.1",
     "satteri": "0.11.6",
+    "saxes": "6.0.0",
+    "sharp": "0.35.5",
     "temml": "0.14.0",
     "yaml": "2.9.1"
   }

package/scripts/copy-assets.js

@@ -0,0 +1,141 @@
+/**
+ * Copy the artifact's image assets into the built output.
+ *
+ * Goal 0009's emission step, and deliberately the only one: the producer decides
+ * *which* images publish (it reads, authorizes, hashes and rewrites them), and
+ * this step asks the artifact for the resulting URL list and moves those bytes
+ * into `dist/_assets/`. No second decision lives here — no image is inferred from
+ * a directory, no reference is re-parsed out of Markdown, and nothing is
+ * transformed. Under Goal 0011 the staged bytes may already be a WebP candidate;
+ * this step still only verifies and copies them, because identity is the emitted
+ * bytes the producer hashed.
+ *
+ * ## Why the bytes come from beside the artifact
+ *
+ * The artifact carries the public URL plus the header-declared pixel size; never
+ * bytes or source paths. Its bytes live in
+ * `<artifact directory>/assets/<digest>-<name>` — the published filename — so this
+ * step runs identically for the packaged build (a temporary workspace) and for
+ * this repository's fixture build (a committed directory) without either being
+ * told where the author's notes are. That is also what keeps the content root out
+ * of every gate downstream of the producer: the output inventory never learns a
+ * source path.
+ *
+ * ## What it refuses
+ *
+ * - a declared asset whose bytes are absent, non-regular (a symlink), of a
+ *   different content digest, or of a format its extension does not name — a
+ *   content-addressed URL that no longer describes its bytes is the one property
+ *   this scheme cannot tolerate;
+ * - a source directory holding files the artifact does not declare, because that
+ *   is a stale asset from another build sitting where a publication step reads;
+ * - silently copying fewer files than declared. The returned count is the
+ *   assertion the tests and the inventory both use.
+ *
+ * The public half of every failure is a count and a literal; the file is the
+ * report's. A staged asset name is already public — it is the URL a reader
+ * fetches — but the rule is kept uniform rather than reasoned per message.
+ */
+import { createHash } from 'node:crypto';
+import { lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ASSET_DIRECTORY, imageExtension, parseAssetUrl, sniffImageFormat } from "../src/lib/media.js";
+import { artifactPath, loadArtifact } from "../src/lib/artifact-source.js";
+import { BuildFailure } from "./write-report.js";
+const DIST = fileURLToPath(new URL('../dist', import.meta.url));
+/**
+ * The directory the artifact's bytes are staged beside, under the published name.
+ *
+ * A fixed sibling name rather than a field in the artifact: the pair
+ * `<artifact>.json` plus `assets/` is the contract, and one name in one place is
+ * what lets the producer, the emission step, and every test agree without a
+ * lookup table.
+ */
+export function assetSourceDirectory(artifactFile) {
+    return join(dirname(artifactFile), 'assets');
+}
+/** The published filename one declared asset URL names. */
+function publishedName(url) {
+    const parsed = parseAssetUrl(url);
+    if (parsed === undefined) {
+        throw new Error(`the artifact declares an asset URL this build cannot parse: ${url}`);
+    }
+    return { ...parsed, file: `${parsed.digest}-${parsed.fileName}` };
+}
+/**
+ * Copy every declared asset into `<root>/_assets/` and return how many were written.
+ *
+ * @param root The built output directory.
+ * @param artifact The validated artifact, whose `assets` list is the exact set.
+ * @param sourceDirectory Where the producer staged the bytes; see
+ *   {@link assetSourceDirectory}.
+ */
+export function copyAssetsToOutput(root, artifact, sourceDirectory) {
+    const assets = artifact.assets ?? [];
+    if (assets.length === 0)
+        return 0;
+    const declared = assets.map((asset) => ({ url: asset.url, ...publishedName(asset.url) }));
+    const accepted = new Set(declared.map((asset) => asset.file));
+    let present;
+    try {
+        present = readdirSync(sourceDirectory);
+    }
+    catch (error) {
+        throw new BuildFailure('asset-source-missing', `the build declares ${assets.length} image asset${assets.length === 1 ? '' : 's'} but staged none`, `could not read the asset staging directory: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // A file the artifact does not declare is a stale asset from an earlier build
+    // sitting in the one directory a publication step reads. Refused rather than
+    // ignored: the next reader would be the output inventory, and the finding would
+    // name the output instead of the stale input.
+    const extra = present.filter((name) => !accepted.has(name));
+    if (extra.length > 0) {
+        throw new BuildFailure('asset-source-mismatch', `${extra.length} staged image file${extra.length === 1 ? '' : 's'} match no asset this build publishes`, extra.sort().join('\n'));
+    }
+    const directory = join(root, ASSET_DIRECTORY);
+    rmSync(directory, { recursive: true, force: true });
+    mkdirSync(directory, { recursive: true });
+    let written = 0;
+    for (const asset of declared) {
+        const path = join(sourceDirectory, asset.file);
+        let bytes;
+        try {
+            if (!lstatSync(path).isFile()) {
+                throw new BuildFailure('asset-source-missing', 'a declared image asset is not a regular file in the staging directory', `${asset.file}: not a regular file`);
+            }
+            bytes = readFileSync(path);
+        }
+        catch (error) {
+            if (error instanceof BuildFailure)
+                throw error;
+            throw new BuildFailure('asset-source-missing', 'the build declares an image asset its staging directory does not contain', asset.file);
+        }
+        const digest = createHash('sha256').update(bytes).digest('hex');
+        if (digest !== asset.digest) {
+            throw new BuildFailure('asset-source-digest', 'a staged image does not hash to the digest its published URL names', `${asset.file}: expected ${asset.digest}, found ${digest}`);
+        }
+        const format = sniffImageFormat(bytes);
+        const extension = asset.fileName.slice(asset.fileName.lastIndexOf('.'));
+        if (format === undefined || imageExtension(format) !== extension) {
+            throw new BuildFailure('asset-source-format', 'a staged image is not the format its published URL names', `${asset.file}: detected ${format ?? 'no supported image format'}, URL extension ${extension}`);
+        }
+        writeFileSync(join(directory, asset.file), bytes);
+        written += 1;
+    }
+    return written;
+}
+/** This repository's own build may print a count; see `verify-output-inventory.ts`. */
+function main() {
+    try {
+        const artifact = loadArtifact();
+        const count = copyAssetsToOutput(DIST, artifact, assetSourceDirectory(artifactPath()));
+        console.log(`image assets ok: ${count} files`);
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof BuildFailure ? error.detail : error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+if (process.argv[1] === fileURLToPath(import.meta.url))
+    process.exit(main());

package/scripts/init-repository.js

@@ -122,6 +122,24 @@ export const CONFIG_TEMPLATE = `# ${CONFIG_FILENAME} — every key is optional,
 # sentences. Without it, the default is English.
 # language: zh-CN
 
+# Optional managed image hosting (Cloudflare R2). This table is read only by
+# the installed command's "build --release --media r2"; every ordinary build
+# and preview stays offline even when this table and the credentials exist. Images publish under
+# their content-addressed /_assets/ path, the same path a same-origin build
+# uses, and the site then points at the public custom domain below. r2.dev is
+# refused: it is development-only, rate-limited, and not normally cached.
+#
+# Create an R2 API token with Object Read & Write for this bucket, connect a
+# custom domain to the bucket, and export the two variables in the build
+# environment. Never put their values in this file.
+# media:
+#   provider: r2
+#   bucket: my-images
+#   endpoint: https://<account-id>.r2.cloudflarestorage.com
+#   public_base_url: https://media.example.org
+#   access_key_id_env: R2_ACCESS_KEY_ID
+#   secret_access_key_env: R2_SECRET_ACCESS_KEY
+
 # A single note can also withhold itself, which no glob can re-include:
 #
 #   ---