mikser-io 10.11.0 → 10.13.0

package/docs/architecture.md

@@ -11,12 +11,12 @@ mikser-io/
 │
 └── src/
     ├── runtime.js            Singleton object — global state and lifecycle coordination
-    ├── engine.js             setup(), CLI option parsing, render + postprocess dispatchers, lazy Piscina pools
+    ├── engine/               setup() and the lifecycle phases, one file each: boot, dispatch, render-cycle, postprocess-cycle, finalize; plus report-only, checks and workers. index.js wires them in order
     ├── lifecycle.js          Hook registration functions + entity write helpers
     ├── journal.js            Per-cycle queue persisted to mikser_journal (auto-persist on yielded entities; survives crashes so --resume can pick up)
     ├── catalog.js            Persistent entity registry (mikser_entities sqlite table + 10k LRU on findById)
     ├── refs.js               Inverse-reference graph (mikser_refs sqlite table)
-    ├── manifest.js           Render snapshots (mikser_snapshots sqlite table)
+    ├── manifest/            schema, snapshot build/parse, sources, prepared statements, the onLoaded/onFinalize cycle; index.js keeps createManifest
     ├── database/             createSqliteDatabase, registerSchema, useDatabase, sift→SQL translator, queryContext (AsyncLocalStorage)
     ├── subscriptions.js      subscribe() primitive (journal-walk + graph-dispatch modes)
     ├── source.js             useSource — folder-of-files import pattern shared by documents/files (and used by sibling mikser-io-layouts)
@@ -24,11 +24,11 @@ mikser-io/
     ├── config.js             Config file loading
     ├── plugins.js            Plugin resolution and loading
     ├── manager.js            File watching and cron scheduling
-    ├── logger.js             Progress bars and log formatting (wraps pino so progress lines don't get mangled); pino.multistream for third-party shipping
+    ├── logger/               streams.js (pino + pretty + multistream), levels.js (which level is in force), progress.js (the gauge and the records that replace it); index.js is the barrel
     ├── render.js             Render worker function (runs in main or Piscina threads); ensureWorkerDb gives each worker a read-only sqlite handle
     ├── postprocess.js        Postprocess worker function (runs in main or Piscina threads)
     ├── track.js              Render-time dependency tracking (catalog queries auto-report via queryContext)
-    ├── utils.js              Checksum, normalize, matchEntity, changeExtension, AbortError, ExpandError, mimeForEntity, isTextEntity, readEntityContent, extractRefs, writeEntity, formatErrorContext
+    ├── utils/               entity, refs, hash, expand, output, errors, junk, net, library; index.js re-exports all 37
     ├── constants.js          OPERATION, ACTION, TASKS enums
     │
     ├── plugins/              Built-in content source and transform plugins
@@ -72,13 +72,13 @@ runtime
 ├── state              Arbitrary plugin state — catalog/refs/manifest are NOT here; they live as their own sqlite-backed facades below
 ├── catalog            entity catalog facade (set by catalog.js) — findEntity / findEntities / iterateEntities / queryEntities / readEntity / subscribe / assertExpand. Backed by mikser_entities + 10k LRU on findById.
 ├── refs               inverse-ref graph facade (set by refs.js) — inboundFor / outboundFor / allRefs / size / rename / subscribeGraph / inverseClosureOf. Backed by mikser_refs.
-├── manifest           render snapshot facade (set by manifest.js) — shouldSkip / record / recordedHashes. Backed by mikser_snapshots.
+├── manifest           render snapshot facade (set by manifest/cycle.js) — shouldSkip / record / recordedHashes. Backed by mikser_snapshots.
 ├── lookupHref         Sync href→entity lookup; available inside Piscina workers (each opens its own read-only sqlite handle on first task)
 ├── validators[]       Array of validation functions
 ├── mutex              Semaphore for process() serialisation
 ├── abortController    Current run's AbortController
 │
-├── engine             Service objects (set by engine.js)
+├── engine             Service objects (set by engine/index.js)
 │   ├── logger              pino instance
 │   ├── commander           Commander instance
 │   ├── renderWorkers       Lazy Piscina pool (minThreads: 0, idleTimeout: 30_000)
@@ -155,7 +155,7 @@ mikser_journal  (RENDER rows)
      │
      ▼
 [RENDER phase]
-  engine.js dispatches RENDER rows → render() per row, dispatch mode
+  engine/render-cycle.js dispatches RENDER rows → render() per row, dispatch mode
   picked per row from { INLINE, SERIAL, WORKER }
      │
      ▼
@@ -173,7 +173,7 @@ mikser_journal  (POSTPROCESS rows)
      │
      ▼
 [POSTPROCESS phase]
-  engine.js dispatches POSTPROCESS rows → postprocess() per row
+  engine/render-cycle.js dispatches POSTPROCESS rows → postprocess() per row
   (same INLINE/SERIAL/WORKER dispatch model as render)
      │
      ▼
@@ -322,7 +322,7 @@ export { default as runtime } from './src/runtime.js'
 export * as constants from './src/constants.js'
 
 // Utilities
-export * from './src/utils.js'         // checksum(), normalize(), matchEntity(), AbortError, etc.
+export * from './src/utils/index.js'         // checksum(), normalize(), matchEntity(), AbortError, etc.
 
 // Lifecycle hooks and entity operations
 export * from './src/lifecycle.js'     // onXxx(), createEntity(), updateEntity(), deleteEntity(), renderEntity(), etc.
@@ -332,7 +332,7 @@ export * from './src/database/index.js' // useDatabase, registerSchema
 export * from './src/journal.js'        // addEntry, addEntries, updateEntry, useJournal, clearJournal
 export * from './src/catalog.js'        // findEntity, findEntities, iterateEntities, queryEntities, readEntity, assertExpand
 export * from './src/refs.js'           // refExists (runtime.refs.* is the main surface)
-export * from './src/manifest.js'       // (runtime.manifest.* is the main surface)
+export * from './src/manifest/index.js'       // (runtime.manifest.* is the main surface)
 
 // Dependency tracking + subscriptions
 export * from './src/track.js'
@@ -346,10 +346,10 @@ export * from './src/plugins.js'
 export * from './src/manager.js'        // watch(), schedule(), createdHook/updatedHook/deletedHook/triggeredHook
 
 // Logger / progress
-export * from './src/logger.js'         // useLogger, trackProgress, stopProgress, updateProgress, etc.
+export * from './src/logger/index.js'   // trackProgress, stopProgress, updateProgress, setLogLevel, etc.
 
 // setup() and render dispatcher entry
-export * from './src/engine.js'         // setup()
+export * from './src/engine/index.js'         // setup()
 export * from './src/render.js'         // useRenderer
 
 // Folder-of-files import helper

package/docs/configuration.md

@@ -53,8 +53,8 @@ These options are part of `runtime.options` and apply to the engine itself.
 | `watch` | `-w, --watch` | boolean | `false` | Watch source folders for changes and rebuild incrementally. |
 | `force` | `-f, --force` | boolean | `false` | Rebuild everything; disable incremental dispatch. |
 | `resume` | `-R, --resume` | boolean | `false` | Continue from journal entries left by a previous interrupted run; skip the initial filesystem scan. The journal table survives crashes, so an interrupted cycle can be picked up by re-running with `--resume`. |
-| `verify` | `--audit-output` | boolean | `false` | Verify the output folder against the manifest snapshot — report drift instead of building. |
-| `log` | `-l, --log` | string | — | Log level for this run: `trace`, `debug`, `info`, `notice`, `warn`, `error`, `fatal`, `silent`. Replaces the old `--debug` / `--trace` booleans, which could not express "warnings only" and, in `--debug`'s case, did nothing at all — it moved the logger's level while the terminal stream kept the one it was built with. |
+| — | `--audit-output` | boolean | `false` | Check every tree mikser writes into against the manifest snapshots — report drift instead of building. Command line only; there is no config key. |
+| `log` | `-l, --log` | string | — | Log level for this run: `trace`, `debug`, `info`, `notice`, `warn`, `error`, `fatal`, `silent`. A level above `info` suppresses the version banner too. |
 | `logInstall` | `--log-install` | string | — | Set the level on a **running** instance, so its own rebuilds are verbose too — the case a per-request flag cannot serve. Expires after 30 minutes, dies with the process, and is disclosed in the build report under `logLevel`. |
 | `logReset` | `--log-reset` | boolean | `false` | Return a running instance to its configured level. |
 | `threads` | — | number | `4` | Worker thread count for the Piscina pools (`renderWorkers`, `postprocessWorkers`). Both pools are lazy (`minThreads: 0` + `idleTimeout: 30_000`) so INLINE-only workloads spin up zero workers. |
@@ -232,40 +232,29 @@ The renderers (`render-hbs`, `render-eta`, `render-liquid`) consume the stripped
 
 ECT layouts (`mikser-io-render-ect`) still file-load via ECT's own resolver — YAML at the top of `.ect` files renders as literal text. Pick `hbs` / `eta` / `liquid` for layouts that need self-describing metadata.
 
-### `assets`
+### `assets` *(moved to `mikser-io-assets`)*
+
+Preset derivatives are a sibling package as of 10.12.0. There is no `assets`
+key in `mikser.config.js`: options are factory arguments like every other
+plugin (ADR-0010).
 
 ```js
-export default {
-  assets: {
-    assetsFolder: 'assets',     // Source folder for assets. Default: 'assets'
-    outputFolder: '',           // Output subfolder. Default: root
-
-    // Preset definitions: preset name → match patterns (and optional config).
-    // Two shapes accepted:
-    presets: {
-      // 1. Bare string or array — backwards-compatible match patterns.
-      'thumbnail': ['@/images/*'],
-      'hero': '@/images/hero*',
-
-      // 2. Object with `match` and per-preset `options` — options merge
-      //    over the preset module's own defaults at render time
-      //    (config-side overrides win on overlap).
-      'medium-image': {
-        match: ['@/images/*', '@/files/photos/*'],
-        options: {
-          width: 800,
-          height: 600,
-          quality: 80,
-        },
-      },
-    }
-  }
-}
-```
+import { assets, renderPreset, assetUrlHelper } from 'mikser-io-assets'
 
-Per-preset `options` from config let a generic preset module (e.g. a `resize` package that reads `options.width` / `options.height`) be reused with different parameters per project — no need to fork the module for each variant. Module-side defaults under `options` still apply for anything the config doesn't override.
+plugins: [
+    assets({
+        presets: { web: { match: ['/files/media/**'] } },
+        // auditIgnore: ['**/*.poster.jpg'],   // extras a preset writes
+    }),
+    renderPreset(),
+    assetUrlHelper(),
+]
+```
 
-Caveat: changing config-side options doesn't automatically invalidate already-rendered assets on disk. Bump the preset module's `revision` export to force a re-render, or run `mikser --clear`.
+`--assets <folder>`, `--presets <folder>` and `--render-presets [name]` are
+declared by that package, so a config without `assets()` does not have them —
+the flag is refused by name rather than accepted and ignored. Full reference:
+[mikser-io-assets](https://github.com/almero-digital-marketing/mikser-io-assets#readme).
 
 ### `resources`
 

package/docs/diagnostics.md

@@ -344,8 +344,18 @@ sentence someone may later reword.
 
 ### `--audit-output`
 
-Walks the output folder against the recorded snapshots and reports drift
-instead of building. Four categories, and the split matters:
+Walks every tree mikser writes into, against the recorded snapshots, and
+reports drift instead of building.
+
+Every tree, not just the output folder: preset derivatives live at the
+working-folder root and reach the site through a symlink the walk does not
+follow, so anything unclaimed there used to be invisible to the one check
+whose job is "what is on disk that mikser did not record". Plugins declare
+their trees on `runtime.options.auditRoots` as `{ path, ignore }`, which is
+also how a plugin states what is bookkeeping rather than output — a `.md5`
+beside every derivative would otherwise be one orphan per derivative.
+
+Five categories, and the split matters:
 
 | Category | Meaning | Severity |
 | --- | --- | --- |
@@ -367,9 +377,17 @@ missing or mismatched, `1` if only warnings, `0` when clean, and `2` when
 there is no manifest to check against.
 
 ```bash
-npx mikser --audit-output || echo "output folder has drifted"
+npx mikser --audit-output || echo "the output has drifted"
 ```
 
+A preset that writes **more than one file** — a poster frame beside a video —
+leaves the extras genuinely unclaimed, because the engine records the one
+destination it handed over. They are reported, correctly, and that would be a
+permanent non-zero exit for a legitimate preset. `assets({ auditIgnore: [...] })`
+is how a project says those are expected. Stated rather than inferred:
+guessing which unclaimed files are intentional is how a check learns to cry
+wolf.
+
 A destination is resolved against the output folder first and, when that
 finds nothing, treated as a filesystem path — assets carry an absolute
 destination built from `assetsFolder`, which may sit outside the output
@@ -957,6 +975,107 @@ that follows is what clears it — an engine deciding on a subsystem's behalf
 that it has recovered would be inventing the one fact this surface exists to
 report honestly.
 
+## Codes
+
+Every warning and fault carries a `code`, and the code is the stable part —
+`--json` keys `warnings` and `faults` by it, `mikser_ping` surfaces faults by
+it, and a check that greps message text breaks the first time someone
+improves the wording. Assert on codes.
+
+```bash
+npx mikser --json | jq '[.warnings[].code] | group_by(.) | map({(.[0]): length}) | add'
+npx mikser --json | jq -e '[.warnings[] | select(.code == "reference-broken")] | length == 0'
+```
+
+Severity is the level the record was logged at: `warn` becomes a warning in
+the report, `error` **with a code** becomes a fault. An error without a code
+is one render that threw, not a subsystem declaring it cannot work — that
+distinction is the whole of [Faults](#faults) above.
+
+### What was written
+
+| Code | Severity | Means |
+| --- | --- | --- |
+| `reference-broken` | warn | A `src` / `href` / `url()` in the emitted output resolves to no file. |
+| `reference-over-deep` | warn | It resolves only because a `..` run was floored at the site root. Loads today; breaks one nesting level deeper. |
+| `reference-wrong-base` | warn | Nothing at the path written, but the file exists elsewhere — resolved against the wrong site root. |
+| `reference-no-derivative` | warn | A reference to a preset derivative that nothing produced. |
+| `reference-broken-summary`, `reference-over-deep-summary` | warn | The counts, so a check can assert on one line rather than N. |
+| `asset-missing` | warn | A template asked for an asset URL that is not in the output. Complements the reference scan: this one sees URLs that never reach an HTML file — a feed, a sitemap — and knows the entity. |
+| `asset-missing-summary` | warn | The count. |
+| `destination-collision` | warn | Two or more entities wrote the same destination this cycle. Usually produces **no** mismatch, because each render hashes the file after writing and the loser reads the winner's bytes. |
+| `empty-output` | warn | A render succeeded and produced a zero-byte file. |
+| `output-drift` | warn | The same inputs produced different bytes than last time — a non-deterministic renderer, or an input nothing is tracking. |
+| `output-drift-summary` | warn | The count. |
+
+### Derivatives (`mikser-io-assets`)
+
+| Code | Severity | Means |
+| --- | --- | --- |
+| `preset-unfinished` | warn | A derivative the manifest claims is on disk with no completed-render marker beside it — a derive that was killed. It is being re-derived; the file that was there is not trustworthy. |
+| `preset-no-match` | warn | A configured preset matched none of the entities evaluated this run. Phrased as what was observed: an incremental cycle legitimately evaluates a handful. |
+| `preset-unknown` | warn | `--render-presets` named a preset that is not configured. |
+
+### Configuration and stores
+
+| Code | Severity | Means |
+| --- | --- | --- |
+| `config-coverage-partial` | warn | This Node build has no module loader hooks, so the config stamp covers the entry file alone. Editing an imported module will not invalidate the cache. |
+| `durable-open` | error | The durable store could not be opened. Auth grants and the change-set log are unavailable. |
+| `durable-migration` | error | A registered migration failed. |
+| `durable-gitignore` | error | The durable store could not be added to `.gitignore` — it holds credentials and the working folder is usually a repo. |
+| `change-set-log` | error | Writes still land on disk but cannot be listed or undone. |
+
+### Process and control
+
+| Code | Severity | Means |
+| --- | --- | --- |
+| `instance-listen-failed` | warn | The control socket could not be opened, so other mikser commands in this folder will start their own engine instead of forwarding. |
+| `command-from-cli` | warn | A hook command was supplied on the command line. Deliberately loud: this build is running code that is not in the config. |
+| `command-hook-not-reached` | warn | A command was attached to a hook the cycle never reached. |
+| `command-install-without-instance` | warn | `--command-install` with nothing listening to install it on. |
+| `log-level-installed` | warn | This instance is running at a level installed with `--log-install` — not the configured level, and not this build asking for it. Carries its expiry. |
+
+### Sources and progress
+
+| Code | Severity | Means |
+| --- | --- | --- |
+| `observer-bad-uri` | warn | An observer's `uri` is not an absolute URL, so no webhook can be routed to it. |
+| `untracked-file-read` | warn | A template read a file outside every folder mikser takes entities from, so it has no entity and changing it invalidates nothing. |
+| `progress` | info | A long phase reporting where it has got to. See [Progress](#progress). |
+| `progress-finished` | info | A phase completed: what it was, how much it carried, what it cost. |
+| `progress-unfinished` | warn | A phase stopped before finishing. |
+
+## Progress
+
+Progress is **tracked always, drawn only where a bar belongs, and narrated
+only for phases that run long**. Off a TTY — CI, a pipe, `--json` — there is
+no bar, and the same facts arrive as records:
+
+```
+[progress-finished] Documents import finished: 5 in 1ms
+[progress] Rendering: 4500/6000 — /documents/p2356.md
+[progress-finished] Rendering finished: 6000 in 3.2s
+```
+
+Three rules, and each exists because the obvious alternative was wrong:
+
+- **`progress-finished` is never gated.** Every phase says it ran and what it
+  cost, at any duration. With the commentary throttled it is the only record
+  most phases produce, and off a TTY it is the only place phase timings come
+  from at all.
+- **The running commentary is one line per 30 seconds**, not per item and not
+  per quartile. A quartile is a fraction of the *work*, so it says nothing
+  about how often a line appears — four records in three seconds on a fast
+  phase, four across an hour on a slow one.
+- **A duration is a measurement, never a zero.** Phases are timed with
+  `performance.now()`, so `0.12ms` rather than the `0s` that a whole class of
+  phases used to report.
+
+A bar never starts while stdout carries a document (`--json`, `--tool`,
+`--tools`): the gauge writes to stdout, and forwarded to an instance it landed
+inside the JSON.
+
 ## When mikser is silent
 
 Silence is this engine's characteristic failure mode: a declaration that

package/docs/lifecycle.md

@@ -286,9 +286,9 @@ onFinalized(async () => {
 ```
 
 **What Mikser does here:**
-- `catalog.js` / `refs.js` / `manifest.js` commit their per-cycle
+- `catalog.js` / `refs.js` / `manifest/` commit their per-cycle
   transaction against `mikser.sqlite` (skipped if no changes)
-- `engine.js` cleans up broken symlinks in the output folder
+- `engine/finalize.js` cleans up broken symlinks in the output folder
 - `journal.js` clears the per-cycle queue: `DELETE FROM mikser_journal`.
   Anything still in the table when the process exits is left for the
   next `--resume` run.

package/docs/overview.md

@@ -98,7 +98,7 @@ The most common confusion when starting out is *which artifact lives where, at w
 | Asset variants | `assets/<preset>/` (preset outputs) | `assets` plugin | `onRender` |
 | Persistent entity registry | `mikser_entities` table in `runtime/mikser.sqlite` | `catalog.js` | `onPersist` |
 | Inverse-reference graph | `mikser_refs` table in `runtime/mikser.sqlite` | `refs.js` | `onPersist` |
-| Render snapshots (manifest) | `mikser_snapshots` table in `runtime/mikser.sqlite` | `manifest.js` | `onPersist` / `onFinalize` |
+| Render snapshots (manifest) | `mikser_snapshots` table in `runtime/mikser.sqlite` | `manifest/` | `onPersist` / `onFinalize` |
 | Per-cycle operations (journal) | `mikser_journal` table in `runtime/mikser.sqlite` | every plugin | every phase |
 | Front-matter schemas | `schemas/` | `mikser-io-schemas` | `onValidate` |
 | Rendered HTML | `out/<route>.html` | post plugins + http server | `onRender` |

package/docs/plugins.md

@@ -250,221 +250,44 @@ See the [mikser-io-layouts README](https://github.com/almero-digital-marketing/m
 
 ---
 
-### `assets`
+### `assets` *(sibling: `mikser-io-assets`)*
 
-The assets plugin runs **user-authored preset modules** over binary inputs (images, video, audio, anything) and writes processed outputs. Each preset is a plain Node module — whatever you can call from Node, you can run as a build step. No DSL, no constrained options bag, no vendor pipeline to fight with.
+Runs **user-authored preset modules** over binary inputs — images, video,
+audio, anything — and writes the derived files. A preset is a plain Node
+module: whatever you can call from Node you can run as a build step. No DSL,
+no constrained options bag, no vendor pipeline to fight with. Image resizing
+with sharp, video transcoding with ffmpeg, AI upscaling via Replicate,
+watermarking with canvas — each is a preset. The plugin does not decide what
+is possible; the preset does.
 
-That makes the assets plugin **the most powerful primitive in mikser**: an open-ended build-time processing layer with full Node capabilities. Image resizing with sharp, video transcoding with ffmpeg, AI upscaling via Replicate, watermarking with canvas, custom multi-output pipelines composed across all of the above — each is a preset module. The plugin doesn't decide what's possible; the preset does.
-
-#### Config
-
-```js
-assets: {
-    assetsFolder: 'assets',         // working folder for presets — default 'assets'
-    outputFolder: 'public',         // where the processed outputs land — default root
-
-    // Each preset name maps to a list of source globs. A source matches
-    // multiple presets if needed (one image → thumbnail + hero + og-card).
-    presets: {
-        thumbnail: ['/files/images/*.{jpg,png}',  '/resources/**/*.{jpg,png}'],
-        hero:      ['/files/images/hero-*.jpg'],
-        'video-web': ['/files/videos/*.mp4',       '/resources/**/*.mp4'],
-        'image-2x': ['/files/images/*.jpg'],
-        upscaled:  ['/files/photos/raw-*.jpg'],
-    },
-}
-```
-
-`presets/<name>.js` next to your `mikser.config.js` is the preset module for that name.
-
-#### Where a preset comes from
-
-A preset name resolves in two places, local first:
-
-1. **`presets/<name>.js`** in your project — the common case.
-2. **An npm package `mikser-io-preset-<name>`** — when no local file exists, the plugin resolves the name from your project's `node_modules`. Install a shared preset (`npm install mikser-io-preset-thumbnail`) and reference it by name in `assets.presets` with no local file. Same resolution convention as `post-*` plugins.
-
-A local file always wins over an npm package of the same name — drop `presets/thumbnail.js` to override one preset from a package while leaving the rest. The two have different update lifetimes: local presets reload on file change in watch mode; npm presets are versioned by their package (bump the dependency to update). `node_modules` is never watched.
-
-If a configured preset name resolves to neither a local file nor an npm package, the plugin logs `Preset not found: <name> ...` and skips it — the rest of the build proceeds.
-
-#### Preset module shape
-
-A preset is a default-exported async function. It receives the entity being processed (with `source`, `destination`, `preset`, `name`, etc.), runs whatever code it needs, and resolves (or rejects) when done.
-
-```js
-export const revision = 1     // bump to force re-render (cache-bust)
-export const format = 'webp'  // output format hint (used in the destination filename)
-
-export default async ({ entity, runtime, logger }) => {
-    // entity.source       — input file on disk
-    // entity.destination  — where to write the result
-    // entity.preset       — config of the matching preset (name, source, options)
-    // entity.name         — original entity name (e.g. '/files/images/hero.jpg')
-    // runtime / logger    — mikser context, including runtime.options for paths
-}
-```
-
-That's the whole contract. Three real examples follow.
-
-#### Example 1 — Video transcoding via ffmpeg
-
-A 720×1080 portrait MP4 at 600kbps for the web. fluent-ffmpeg streams progress events back into mikser's logger so the build progress bar reflects encoder progress in real time.
-
-```js
-// presets/video-web.js
-import ffmpeg from 'fluent-ffmpeg'
-
-export const revision = 7
-export const format = 'mp4'
-
-export default ({ entity: { name, source, destination, preset }, logger }) => {
-    return new Promise((resolve, reject) => {
-        ffmpeg(source)
-            .videoCodec('libx264')
-            .size('810x1080')
-            .videoBitrate(600)
-            .outputOptions('-strict -2')
-            .on('progress', ({ percent }) =>
-                logger.trace(`Progress: [${preset.name}] ${name} ${Math.round(percent)}%`))
-            .on('error', reject)
-            .on('end', resolve)
-            .save(destination)
-    })
-}
-```
-
-10 lines of glue around ffmpeg. Every published video in the catalog gets transcoded; rebuilds skip unchanged inputs because the journal tracks file mtimes; bumping `revision` re-encodes everything (useful when you change the bitrate).
-
-#### Example 2 — Image variants via sharp
-
-Resize + format negotiation. Most projects want srcset variants in WebP and AVIF; this preset emits both with a single sharp pipeline.
-
-```js
-// presets/image-2x.js
-import sharp from 'sharp'
-import { dirname, basename, extname, join } from 'node:path'
-import { mkdir } from 'node:fs/promises'
-
-export const revision = 3
-
-export default async ({ entity: { source, destination }, logger }) => {
-    const dir   = dirname(destination)
-    const stem  = basename(destination, extname(destination))
-    await mkdir(dir, { recursive: true })
-
-    const pipeline = sharp(source).rotate()       // honor EXIF orientation
-    // 2× variants for each format
-    await Promise.all([
-        pipeline.clone().resize({ width: 1600 }).webp({ quality: 85 }).toFile(join(dir, `${stem}@2x.webp`)),
-        pipeline.clone().resize({ width: 1600 }).avif({ quality: 60 }).toFile(join(dir, `${stem}@2x.avif`)),
-        pipeline.clone().resize({ width: 800  }).webp({ quality: 85 }).toFile(join(dir, `${stem}.webp`)),
-        pipeline.clone().resize({ width: 800  }).avif({ quality: 60 }).toFile(join(dir, `${stem}.avif`)),
-    ])
-    logger.trace('image-2x emitted 4 variants for %s', source)
-}
+```bash
+npm install mikser-io-assets
 ```
 
-One preset, four output files per input image. The render-href plugin can then rewrite `<img src="hero.jpg">` to the `@2x.webp` URL with a fallback `<source>` chain — but that's a render-time concern, not the asset plugin's.
-
-#### Example 3 — AI enhancement via Replicate
-
-The interesting one. Hand a raw photo to a model on Replicate (here, an image upscaler), poll for completion, fetch the result, write it to disk. The preset is a normal Node module — `fetch` is just `fetch`, no special bridging.
-
 ```js
-// presets/upscaled.js
-import { writeFile } from 'node:fs/promises'
-
-export const revision = 2
-export const format = 'jpg'
-
-const REPLICATE_MODEL = 'nightmareai/real-esrgan'
-const REPLICATE_VERSION = '...'   // pin a model version
-
-export default async ({ entity: { source, destination }, logger }) => {
-    // 1. Upload source — Replicate accepts a public URL or base64 data URI
-    const data = await readFile(source)
-    const dataUri = `data:image/jpeg;base64,${data.toString('base64')}`
-
-    // 2. Kick off the prediction
-    const start = await fetch('https://api.replicate.com/v1/predictions', {
-        method: 'POST',
-        headers: {
-            'authorization': `Token ${process.env.REPLICATE_TOKEN}`,
-            'content-type':  'application/json',
-        },
-        body: JSON.stringify({
-            version: REPLICATE_VERSION,
-            input:   { image: dataUri, scale: 4 },
-        }),
-    }).then(r => r.json())
-
-    // 3. Poll until succeeded
-    let prediction = start
-    while (prediction.status === 'starting' || prediction.status === 'processing') {
-        await new Promise(r => setTimeout(r, 1500))
-        prediction = await fetch(start.urls.get, {
-            headers: { authorization: `Token ${process.env.REPLICATE_TOKEN}` },
-        }).then(r => r.json())
-        logger.trace('replicate %s: %s', start.id, prediction.status)
-    }
-    if (prediction.status !== 'succeeded') {
-        throw new Error(`Replicate failed: ${prediction.error}`)
-    }
+import { assets, renderPreset, assetUrlHelper } from 'mikser-io-assets'
 
-    // 4. Download the result and write it where mikser expects
-    const buffer = Buffer.from(await fetch(prediction.output).then(r => r.arrayBuffer()))
-    await writeFile(destination, buffer)
-}
+plugins: [
+    assets({ presets: { web: { match: ['/files/media/**'] } } }),
+    renderPreset(),          // the renderer presets dispatch through
+    assetUrlHelper(),        // runtime.asset() for templates
+]
 ```
 
-What's unique here is that **none of this required a plugin to mikser**. The preset *is* the plugin code. You can call any third-party service, run any local model (via `@xenova/transformers`, llama.cpp, ONNX runtime, whatever), shell out to anything (`child_process` to a custom binary), or compose multiple steps:
+`renderPreset()` is not optional. It was resolved implicitly while this code
+lived in the engine, whose renderer lookup falls back to a path inside its own
+`src/plugins/render/` — that path no longer holds it.
 
-```js
-// presets/hero-deluxe.js — multi-step pipeline
-import sharp from 'sharp'
-import { upscaleViaReplicate } from './_replicate.js'
-import { applyWatermark } from './_watermark.js'
-
-export const revision = 1
-export default async ({ entity: { source, destination } }) => {
-    const upscaled  = await upscaleViaReplicate(source)
-    const watermark = await applyWatermark(upscaled, { text: '© Acme Co 2026' })
-    await sharp(watermark).resize({ width: 2400 }).avif({ quality: 70 }).toFile(destination)
-}
-```
-
-This is the property no other SSG / CMS exposes at this level. Astro's `<Image>` resizes; that's it. Hugo's image processing has a fixed set of operations. Sanity's image CDN runs the transforms it decided to support. mikser's preset is whatever you write — including operations that don't exist anywhere else (upscaling specific to your domain, watermarks driven by per-image rules, multi-format outputs with vendor-specific encoders).
-
-#### Composition with `resources`
-
-The assets plugin processes whatever's on disk. Source files don't have to start in your repo — the **resources plugin** (next section) pulls them from external systems (company content servers, S3, vendor APIs) into the working folder so assets can then process them. That composition is where the "advanced pipeline" idea pays off — see the end-of-section example for the full chain.
-
-#### Watch support
+Split out of core in 10.12.0: it encodes one recipe for producing files from
+files, the way `layouts` encodes one for producing render tasks. What stayed
+in the engine is substrate — the render track that records which asset URLs a
+template asked for, and the finalize check that reports the ones nothing
+produced, both of which work whether or not this package is installed.
 
-Yes — the plugin watches both the source files and the preset modules. Editing a preset re-processes every input that matches it; editing a source re-processes just that input.
-
-
-**Derivatives with no source are removed.** A derivative outlived its source:
-deleting a file removed its catalog row and its published copy and left the
-derived file, because the delete handler dropped the in-memory mapping and
-nothing on disk. Narrowing a preset's `match` left one the same way. A stale
-derivative passes every check — the url resolves and the bytes are there —
-so the only cleanup was `--clear`, or deleting it by hand.
-
-The post-cycle pass that already walks the revision markers now also asks, per
-derivative, whether it still has a source that this preset still covers. It is
-answered from the **catalog**, not from the delete event: a delete entry is
-sparse (`{ id, type, collection }`) in every source plugin, so it cannot say
-where the derivative went, while the catalog answers whatever route the orphan
-arrived by — including ones that predate the fix. Reported as
-`Assets removed: N derivative(s) with no source`.
-
-It does nothing when the catalog is empty. Every check concludes "no source,
-therefore orphan", and an empty catalog answers that for every derivative on
-the site, so a failed import would otherwise delete the whole assets folder.
-
----
+See the [mikser-io-assets README](https://github.com/almero-digital-marketing/mikser-io-assets#readme)
+for the full reference: preset module shape, `revision` and the
+completed-render marker, recovery from an interrupted derive, `auditIgnore`,
+`--render-presets`, and worked ffmpeg / sharp examples.
 
 ### `resources`
 
@@ -527,7 +350,8 @@ With this config:
 
 ```js
 // mikser.config.js
-import { files, resources, assets, api } from 'mikser-io'
+import { files, resources, api } from 'mikser-io'
+import { assets, renderPreset } from 'mikser-io-assets'
 
 export default {
     plugins: [

package/docs/rendering.md

@@ -10,7 +10,7 @@ Rendering is triggered by RENDER operations in the journal. Each entry describes
 RENDER journal entries
         │
         ▼
-   onRender hook (engine.js)
+   onRender hook (engine/render-cycle.js)
         │
         ├── For each unique entity:destination pair
         │