mikser-io 9.40.3 → 9.42.0

package/docs/api-reference.md

@@ -483,6 +483,68 @@ Query types throughout: function, lodash match object, or `undefined` for all.
 
 ---
 
+## Search
+
+`queryEntities` sifts **meta**. `searchEntities` answers the other question —
+*where does this text appear?* — across structured values, source files and
+built output.
+
+### `searchEntities(options)`
+
+```js
+import { searchEntities } from 'mikser-io'
+
+const { hits, count, truncated } = await searchEntities({
+    query: 'NOVAPRESS',
+    in: ['meta', 'content'],   // default
+})
+```
+
+| Option | Meaning |
+| --- | --- |
+| `query` | Text to find. A plain substring unless `regex` is true. Required. |
+| `in` | `'meta'`, `'content'`, `'output'`. Default `['meta', 'content']`. |
+| `collection` | Restrict to one collection. |
+| `filter` | Sift filter narrowing **what may be searched at all** — see below. |
+| `regex` | Treat `query` as a JavaScript regular expression. |
+| `ignoreCase` | Case-insensitive matching. Default false. |
+| `limit` | Maximum hits (default 50). `truncated` says when it stopped early. |
+
+The three scopes answer different questions and none implies another. `meta`
+walks structured values as dotted paths and touches no files. `content` reads
+the **source**. `output` walks the **built** folder and reports `occurrences`
+per destination — the blast-radius question, and the one where a string can be
+present because a layout writes it, with no source entity containing it
+anywhere.
+
+Whether a file is text is decided by reading its bytes, not by its extension,
+so a `.njk` source or a `.webmanifest` output is searched without first being
+added to a list of known formats.
+
+`truncated` is load-bearing: it separates "these are the hits" from "these are
+the first N", which a caller acting on a blast radius cannot afford to guess.
+
+> **Unscoped by default.** A bare call reads every entity and every source
+> file — drafts, unpublished documents, layouts, sidecar JavaScript. The `api`
+> plugin narrows `list` through each endpoint's own sift scope; nothing
+> narrows this. Anything that puts search behind a request **must** pass that
+> same scope as `filter`, or a public endpoint listing only published
+> documents will happily search the unpublished ones. There is deliberately no
+> `search` operation in the `api` plugin and no route in this module.
+
+### Primitives
+
+Exported so a caller building a different question out of the same parts does
+not reimplement them: `countMatches`, `snippetAround`, `lineOfFirstMatch`,
+`flattenMeta`, `findOccurrences`, `walkFiles`.
+
+`findOccurrences(text, needle)` returns every occurrence with `line`, `col`,
+the line's `text`, and `leading` — whether the match begins its line. That one
+flag separates the file **declaring** something from the files merely using
+it, in any text format, with no per-language grammar involved. It returns the
+line rather than a verdict about it, so where the heuristic is wrong the
+evidence is in the result.
+
 ## Database
 
 ```js

package/index.js

@@ -11,6 +11,7 @@ export * from './src/lifecycle.js'
 export * from './src/database/index.js'
 export * from './src/journal.js'
 export * from './src/catalog.js'
+export * from './src/search.js'
 export * from './src/refs.js'
 export * from './src/manifest.js'
 export * from './src/provenance.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io",
-  "version": "9.40.3",
+  "version": "9.42.0",
   "description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
   "main": "index.js",
   "exports": {
@@ -46,6 +46,7 @@
     "is-url": "^1.2.4",
     "line-reader": "^0.4.0",
     "lodash": "^4.18.1",
+    "mime-types": "^3.0.2",
     "minimatch": "^10.2.5",
     "node-cron": "^4.2.1",
     "p-map": "^7.0.4",

package/src/builtin-tools.js

@@ -96,6 +96,45 @@ export function registerBuiltinTools() {
         },
     )
 
+    registerTool(
+        'search',
+        {
+            description:
+                'Find a string across the catalog in ONE call — "where does this appear?". Searches entity meta '
+                + 'values and, when asked, the source files themselves and the built output, returning '
+                + '{ id, collection, path, field, snippet } per hit.\n\n'
+                + 'This is how you locate content you can only describe by what it says: a menu label, a phone '
+                + 'number, a sentence you were asked to change. Paging the catalog to find it means reading '
+                + 'everything, most of which is fonts and image derivatives, and finding a SECOND copy of the same '
+                + 'label somewhere else is then a matter of luck.\n\n'
+                + 'in: ["meta"] searches structured values, no file I/O. in: ["content"] reads source files, '
+                + 'binaries skipped. Default is both. in: ["output"] searches the BUILT files instead and reports '
+                + '`occurrences` per destination — the blast-radius question, which is what you want before editing '
+                + 'anything shared. The scopes answer different questions and none implies another: a string can be '
+                + 'in the output because a layout writes it, with no source entity containing it anywhere.',
+            inputSchema: {
+                query: { type: 'string', required: true,
+                    description: 'Text to find. A plain substring unless `regex` is true. Case-sensitive by default.' },
+                collection: { type: 'string',
+                    description: 'Restrict to one collection (e.g. "documents"). Omit to search all.' },
+                in: { type: 'array',
+                    description: 'Where to look: "meta", "content", "output". Default is meta + content.' },
+                regex: { type: 'boolean',
+                    description: 'Treat `query` as a JavaScript regular expression rather than a literal substring.' },
+                ignoreCase: { type: 'boolean', description: 'Case-insensitive matching. Default false.' },
+                limit: { type: 'number', description: 'Maximum hits to return (default 50).' },
+            },
+        },
+        async (args) => {
+            try {
+                const { searchEntities } = await import('./search.js')
+                return ok(await searchEntities(args ?? {}))
+            } catch (err) {
+                return fail(err.message)
+            }
+        },
+    )
+
     registerTool(
         'sources',
         {

package/src/search.js

@@ -0,0 +1,284 @@
+// Find a string across the catalog and the built output.
+//
+// `queryEntities` sifts META. This answers the other question — "where does
+// this text appear?" — over structured values, source files and built output,
+// which is what locating a phone number in a document body or a class name in
+// the shipped CSS requires.
+//
+// Three scopes, answering three different questions, none implying another:
+//
+//   meta     — structured values, walked as dotted paths. No file I/O.
+//   content  — the SOURCE files. What an editor is going to change.
+//   output   — the BUILT files. The blast radius: a string can be in the
+//              output because a layout writes it, with no source entity
+//              containing it anywhere.
+//
+// UNSCOPED BY DEFAULT, and that is a security property, not a detail. A bare
+// call reads every entity and every source file — drafts, unpublished
+// documents, layouts, sidecar JavaScript. The `api` plugin's public endpoints
+// narrow `list` through the endpoint's own sift scope; nothing narrows this.
+// So anything that puts search behind a request MUST pass that same scope as
+// `filter`, or a public endpoint that lists only published documents will
+// happily search the unpublished ones. There is deliberately no `search`
+// operation in the api plugin, and no route here.
+//
+// The primitives are exported alongside `searchEntities` so a caller building
+// a different question out of the same parts does not reimplement counting,
+// snippets or line numbers to do it.
+
+import path from 'node:path'
+import { readdir, readFile } from 'node:fs/promises'
+
+import runtime from './runtime.js'
+import { findEntities } from './catalog.js'
+import { readEntityContent, looksTextual } from './utils.js'
+
+// How much of an output file to read before deciding it is text. Same rule
+// the source read uses, so the two scopes cannot disagree about a file that
+// appears in both.
+const SNIFF_BYTES = 8 * 1024
+
+// Every leaf value under meta as [dottedPath, value], arrays included.
+// The same shape refs_inbound reports, so a hit here and a referrer there
+// name the same field.
+export function* flattenMeta(node, prefix = '') {
+    if (node === null || node === undefined) return
+    if (Array.isArray(node)) {
+        for (let i = 0; i < node.length; i++) yield* flattenMeta(node[i], `${prefix}[${i}]`)
+        return
+    }
+    if (typeof node === 'object') {
+        for (const [key, value] of Object.entries(node)) {
+            yield* flattenMeta(value, prefix ? `${prefix}.${key}` : key)
+        }
+        return
+    }
+    yield [prefix, node]
+}
+
+// How many times the needle appears. A count, not a boolean, because "this
+// class is on nine pages" and "this class is on nine pages and seven times on
+// one of them" are different facts, and the second one names the component.
+export function countMatches(text, query, regex, ignoreCase) {
+    if (regex) {
+        const re = new RegExp(query, ignoreCase ? 'gi' : 'g')
+        let n = 0
+        // Guard the zero-width case: /a*/g on a non-matching position returns
+        // an empty match forever and never advances.
+        for (let m = re.exec(text); m; m = re.exec(text)) {
+            n++
+            if (m.index === re.lastIndex) re.lastIndex++
+        }
+        return n
+    }
+    const haystack = ignoreCase ? text.toLowerCase() : text
+    const needle = ignoreCase ? query.toLowerCase() : query
+    if (!needle) return 0
+    let n = 0
+    for (let at = haystack.indexOf(needle); at !== -1; at = haystack.indexOf(needle, at + needle.length)) n++
+    return n
+}
+
+// Offset of the first match, or -1. The one place the regex/substring
+// difference is resolved, so the line number and the snippet cannot end up
+// pointing at different matches.
+function firstMatchAt(text, query, regex, ignoreCase) {
+    if (regex) {
+        const m = new RegExp(query, ignoreCase ? 'i' : '').exec(text)
+        return m ? m.index : -1
+    }
+    const haystack = ignoreCase ? text.toLowerCase() : text
+    return haystack.indexOf(ignoreCase ? query.toLowerCase() : query)
+}
+
+// 1-based line of the first match, so a hit is somewhere to go rather than
+// something to grep for again.
+export function lineOfFirstMatch(text, query, regex, ignoreCase) {
+    const at = firstMatchAt(text, query, regex, ignoreCase)
+    if (at < 0) return null
+    let line = 1
+    for (let i = 0; i < at; i++) if (text.charCodeAt(i) === 10) line++
+    return line
+}
+
+// Enough text around the match to recognise it without returning the file.
+export function snippetAround(text, query, regex, ignoreCase) {
+    const at = firstMatchAt(text, query, regex, ignoreCase)
+    if (at < 0) return text.slice(0, 120)
+    const start = Math.max(0, at - 60)
+    const end = Math.min(text.length, at + query.length + 60)
+    return (start > 0 ? '…' : '') + text.slice(start, end).replace(/\s+/g, ' ') + (end < text.length ? '…' : '')
+}
+
+// Every occurrence of a needle in a text, with the one signal that separates
+// "this file DECLARES it" from "this file uses it" without knowing the
+// language: a declaration begins its line in nearly every text format, while a
+// use sits mid-line.
+//
+// The LINE is returned rather than a computed verdict about it. A caller can
+// tell a declaration from something that merely starts with the same token by
+// reading it, which needs no grammar here at all — and where the heuristic is
+// wrong, the evidence for that is right there in the result.
+export function findOccurrences(text, needle, { limit = 200 } = {}) {
+    const sites = []
+    if (!needle || typeof text !== 'string') return sites
+    let line = 1
+    let lineStart = 0
+    let scanned = 0
+    for (let at = text.indexOf(needle); at !== -1; at = text.indexOf(needle, at + needle.length)) {
+        while (scanned < at) {
+            if (text.charCodeAt(scanned) === 10) { line++; lineStart = scanned + 1 }
+            scanned++
+        }
+        const lineEnd = text.indexOf('\n', at)
+        sites.push({
+            line,
+            col: at - lineStart,
+            leading: text.slice(lineStart, at).trim() === '',
+            text: text.slice(lineStart, lineEnd === -1 ? text.length : lineEnd).trim().slice(0, 160),
+        })
+        if (sites.length >= limit) break
+    }
+    return sites
+}
+
+// Every file under a folder, depth-first. A generator so a search that hits
+// its limit stops walking rather than materializing the tree.
+export async function* walkFiles(folder) {
+    let entries
+    try {
+        entries = await readdir(folder, { withFileTypes: true })
+    } catch {
+        return
+    }
+    for (const entry of entries) {
+        const full = path.join(folder, entry.name)
+        if (entry.isDirectory()) yield* walkFiles(full)
+        else if (entry.isFile()) yield full
+    }
+}
+
+// Read a built file as text, or null when it is not text.
+//
+// Decided by the bytes, so a `.webmanifest`, a `.map` or whatever a renderer
+// plugin emits is searchable without first being added to a list of known
+// extensions — and a font still comes back null rather than as convincing
+// garbage.
+async function readOutputText(file) {
+    let buf
+    try {
+        buf = await readFile(file)
+    } catch {
+        return null
+    }
+    if (!looksTextual(buf.subarray(0, Math.min(buf.length, SNIFF_BYTES)))) return null
+    return buf.toString('utf8')
+}
+
+// Build the test used for meta values and for a whole-file contains check.
+// Throws on an invalid regex so the caller can report it as bad input rather
+// than as an empty result.
+function buildMatcher(query, regex, ignoreCase) {
+    if (regex) {
+        const re = new RegExp(query, ignoreCase ? 'i' : '')
+        return { test: (value) => re.test(String(value)) }
+    }
+    const needle = ignoreCase ? query.toLowerCase() : query
+    return {
+        test: (value) => (ignoreCase ? String(value).toLowerCase() : String(value)).includes(needle),
+    }
+}
+
+// Find `query` across the catalog and, when asked, the built output.
+//
+// Returns { query, scopes, count, truncated, searched, hits }. Each hit
+// carries where it was found and enough to go there:
+//
+//   meta     { id, collection, path, where, field, snippet }
+//   content  { id, collection, path, where, field: null, occurrences, line, snippet }
+//   output   { destination, where, occurrences, snippet }
+//
+// `truncated` says the limit stopped the walk, which is the difference
+// between "these are the hits" and "these are the first N" — a distinction a
+// caller acting on a blast radius cannot afford to guess at.
+export async function searchEntities({
+    query,
+    collection,
+    filter,
+    in: where,
+    regex = false,
+    ignoreCase = false,
+    limit = 50,
+} = {}) {
+    if (!query) throw new Error('searchEntities: query is required')
+    const scopes = where?.length ? where : ['meta', 'content']
+    const matcher = buildMatcher(query, regex, ignoreCase)
+
+    const hits = []
+    let truncated = false
+
+    // The output scope walks the deployed folder rather than the catalog, so
+    // it runs on its own. Counting is the point here rather than first-match:
+    // seven occurrences on one page and one on nine others is the shape of a
+    // shared component, and a list of nine equal-looking filenames hides it.
+    if (scopes.includes('output')) {
+        const outputFolder = runtime.options?.outputFolder
+        if (!outputFolder) throw new Error('No output folder configured, so there is no built output to search.')
+        for await (const file of walkFiles(outputFolder)) {
+            if (hits.length >= limit) { truncated = true; break }
+            const text = await readOutputText(file)
+            if (text === null) continue
+            const occurrences = countMatches(text, query, regex, ignoreCase)
+            if (!occurrences) continue
+            hits.push({
+                destination: '/' + path.relative(outputFolder, file).split(path.sep).join('/'),
+                where: 'output',
+                occurrences,
+                snippet: snippetAround(text, query, regex, ignoreCase),
+            })
+        }
+        hits.sort((a, b) => b.occurrences - a.occurrences || a.destination.localeCompare(b.destination))
+    }
+
+    // `filter` is how a caller narrows what may be searched at all. It merges
+    // with `collection` and pushes into the catalog query, so a scoped caller
+    // never materializes a row it is not allowed to see rather than filtering
+    // one out after reading it off disk.
+    const searchesCatalog = scopes.some(scope => scope !== 'output')
+    const catalogQuery = { ...(filter ?? {}), ...(collection ? { collection } : {}) }
+    const entities = searchesCatalog
+        ? await findEntities(Object.keys(catalogQuery).length ? catalogQuery : undefined)
+        : []
+
+    for (const entity of entities) {
+        if (hits.length >= limit) { truncated = true; break }
+        if (scopes.includes('meta') && entity.meta) {
+            for (const [field, value] of flattenMeta(entity.meta)) {
+                if (!matcher.test(value)) continue
+                hits.push({
+                    id: entity.id, collection: entity.collection ?? null, path: entity.uri ?? null,
+                    where: 'meta', field, snippet: snippetAround(String(value), query, regex, ignoreCase),
+                })
+                break
+            }
+        }
+        if (hits.length >= limit) { truncated = true; break }
+        if (scopes.includes('content')) {
+            // readEntityContent owns the text/binary decision and makes it by
+            // reading the bytes, so a .njk or .toml is searched like anything
+            // else. Deciding it a second time here on an extension would make
+            // a skipped format indistinguishable from a real absence.
+            const { content } = await readEntityContent(entity)
+            if (typeof content !== 'string' || !matcher.test(content)) continue
+            hits.push({
+                id: entity.id, collection: entity.collection ?? null, path: entity.uri ?? null,
+                where: 'content', field: null,
+                occurrences: countMatches(content, query, regex, ignoreCase),
+                line: lineOfFirstMatch(content, query, regex, ignoreCase),
+                snippet: snippetAround(content, query, regex, ignoreCase),
+            })
+        }
+    }
+
+    return { query, scopes, count: hits.length, truncated, searched: entities.length, hits }
+}

package/src/utils.js

@@ -8,6 +8,7 @@ import { minimatch } from 'minimatch'
 import path from 'path'
 import fm from 'front-matter'
 import yaml from 'yaml'
+import { contentType } from 'mime-types'
 import runtime from './runtime.js'
 import { trackedInfo, untrack, recordReads } from './track.js'
 
@@ -188,32 +189,31 @@ export function refFilter(refValue) {
 // else that produces Content-Type from an entity). Pure function; no
 // engine state — lives here rather than inside one plugin so other
 // plugins don't have to reach across the plugin folder for it.
-const MIME_BY_EXT = {
-    pdf:   'application/pdf',
-    html:  'text/html; charset=utf-8',
-    xml:   'application/xml; charset=utf-8',
-    xhtml: 'application/xhtml+xml; charset=utf-8',
-    rss:   'application/rss+xml; charset=utf-8',
-    atom:  'application/atom+xml; charset=utf-8',
-    json:  'application/json; charset=utf-8',
-    css:   'text/css; charset=utf-8',
-    js:    'application/javascript; charset=utf-8',
-    svg:   'image/svg+xml',
-    png:   'image/png',
-    jpg:   'image/jpeg',
-    jpeg:  'image/jpeg',
-    webp:  'image/webp',
-    gif:   'image/gif',
-    mp4:   'video/mp4',
-    webm:  'video/webm',
-    txt:   'text/plain; charset=utf-8',
-    md:    'text/markdown; charset=utf-8',
+// Content types come from `mime-types` — the IANA registry via mime-db —
+// rather than the nineteen-entry table this used to carry. That table was
+// wrong by omission for everything it had not been taught: a .woff2, .avif,
+// .wasm, .ico or .mp3 in the output got no content type at all, and a caller
+// serving it had to guess.
+//
+// One deliberate change came with the swap: `.js` is `text/javascript`, which
+// RFC 9239 made the registered type and `application/javascript` obsolete.
+// Browsers have accepted both for years.
+function mimeForExtension(ext) {
+    const type = contentType(ext)
+    if (!type) return null
+    // mime-db assigns charsets from its own `charset` field, which the XML
+    // family does not carry — so `application/rss+xml` came back bare where
+    // the old table said `; charset=utf-8`. Restored as a RULE about XML
+    // rather than as four more rows to keep. Deliberately not applied to
+    // `image/svg+xml`, which the old table also served without a charset.
+    return /charset=/i.test(type) || !/^application\/(xml$|.*\+xml$)/.test(type)
+        ? type
+        : `${type}; charset=utf-8`
 }
 
 export function mimeForEntity(entity) {
     if (!entity?.destination) return null
-    const ext = path.extname(entity.destination).toLowerCase().replace(/^\./, '')
-    return MIME_BY_EXT[ext] ?? null
+    return mimeForExtension(path.extname(entity.destination).toLowerCase())
 }
 
 // File-extension allowlist for "is this source readable as utf8?". Used
@@ -237,12 +237,81 @@ const TEXT_EXTENSIONS = new Set([
 // Returns false for binaries (png/pdf/mp4/etc.) and for entities
 // without a uri. Pass the entity, not a bare extension — keeps the
 // call site readable and lines up with mimeForEntity's signature.
+//
+// A HINT, not a verdict. The list above is hand-maintained, so it is wrong
+// about every extension nobody has added yet — `.njk`, `.scss`, `.toml`, and
+// `.ect`, which is an engine mikser itself ships a renderer for. Anything
+// deciding whether content can be READ should ask looksTextual about the
+// bytes instead; this stays for callers that want a cheap guess with no I/O.
 export function isTextEntity(entity) {
     if (!entity?.uri) return false
     const ext = path.extname(entity.uri).slice(1).toLowerCase()
     return TEXT_EXTENSIONS.has(ext)
 }
 
+// How much of a file is enough to tell text from binary. A binary format that
+// hides every NUL and every invalid sequence for 8KB is not one anybody
+// stores in a content repository.
+const SNIFF_BYTES = 8 * 1024
+
+// Is this text? Asked of the BYTES, not of the extension.
+//
+// An extension allowlist is a list that goes stale silently, and it fails in
+// the direction that costs most: it refuses a file it has no opinion about.
+// That is how reading a `.liquid` template — from an engine that renders
+// Liquid — came back "Non-text format".
+//
+// Bytes do not go stale. A file with no NUL that decodes as UTF-8 is text,
+// whether it is Nunjucks, TOML, SQL or something nobody has written yet.
+export function looksTextual(buf) {
+    if (buf.includes(0)) return false
+    try {
+        new TextDecoder('utf8', { fatal: true }).decode(trimPartialTail(buf))
+        return true
+    } catch {
+        return false
+    }
+}
+
+// Drop a trailing codepoint a bounded read cut in half — and ONLY that.
+//
+// The tempting version retries the decode while chopping bytes off the end
+// until it succeeds. That also chops away genuinely corrupt bytes: `74 65 78
+// 74 C3 28` is invalid UTF-8, but drop two bytes and `text` decodes clean, so
+// a JPEG whose tail happens to be bad reads as text. The tail is forgiven only
+// when it is a valid multi-byte sequence that has not finished yet.
+function trimPartialTail(buf) {
+    // A lead byte is 11xxxxxx and starts a sequence of a known length; the
+    // bytes after it are continuations, 10xxxxxx. Walk back over at most 3
+    // continuations — a 4-byte sequence is the longest UTF-8 has.
+    for (let back = 1; back <= 4 && back <= buf.length; back++) {
+        const byte = buf[buf.length - back]
+        if (byte < 0x80) return buf                       // ASCII: nothing pending
+        if ((byte & 0xc0) === 0x80) continue              // continuation, keep walking
+        const expected = (byte & 0xe0) === 0xc0 ? 2
+                       : (byte & 0xf0) === 0xe0 ? 3
+                       : (byte & 0xf8) === 0xf0 ? 4
+                       : 0                                // not a lead byte at all
+        // `back` bytes run from the lead to the end. Fewer than the sequence
+        // needs means it was cut; anything else is complete, or corrupt, and
+        // corrupt is the decoder's call to make rather than ours.
+        return expected && back < expected ? buf.subarray(0, buf.length - back) : buf
+    }
+    return buf
+}
+
+// Read the first `limit` bytes of a file, for sniffing.
+async function readPrefix(file, limit) {
+    const handle = await open(file, 'r')
+    try {
+        const buf = Buffer.alloc(limit)
+        const { bytesRead } = await handle.read(buf, 0, limit, 0)
+        return buf.subarray(0, bytesRead)
+    } finally {
+        await handle.close()
+    }
+}
+
 // Cache resolved provider modules so we don't re-import per read.
 // Keyed by URI scheme — same scheme → same module → same auth state.
 const providerModuleCache = new Map()
@@ -306,9 +375,20 @@ async function loadProviderModule(scheme, workingFolder) {
 // Usage:
 //
 //   Object.assign(entity, await readEntityContent(entity))
-export async function readEntityContent(entity) {
+export async function readEntityContent(entity, { reload = false } = {}) {
     if (!entity) return {}
-    if (typeof entity.content === 'string') return { content: entity.content }
+    // The fast path exists to avoid re-FETCHING a remote document a source
+    // plugin already pulled in, and it short-circuits before any of the
+    // dispatch below. That makes it a correctness problem for a caller asking
+    // to see the SOURCE: between builds the catalog copy and the file on disk
+    // part ways, and this handed back the catalog's — under a name that says
+    // it read the file. An agent then rewrites the whole file from a version
+    // it never saw, silently discarding whatever changed underneath it.
+    //
+    // `reload` is how a caller says it wants the bytes as they are now. An
+    // entity with no uri has nothing fresher to offer, so it keeps what it
+    // has rather than falling through to an error.
+    if (typeof entity.content === 'string' && (!reload || !entity.uri)) return { content: entity.content }
     if (!entity.uri) return { contentError: 'entity has no uri' }
 
     const m = URI_SCHEME_RE.exec(entity.uri)
@@ -324,14 +404,19 @@ export async function readEntityContent(entity) {
 
     // Built-in filesystem read: no scheme (plain path) or `file://`.
     if (!scheme || scheme === 'file') {
-        if (!isTextEntity(entity)) {
-            const ext = path.extname(entity.uri).slice(1).toLowerCase()
-            return {
-                contentSkipped: `Non-text format (.${ext}). Read the file directly at entity.uri, or use a render API to materialize output.`,
-            }
-        }
+        const target = scheme === 'file' ? entity.uri.replace(/^file:\/\//i, '') : entity.uri
         try {
-            const target = scheme === 'file' ? entity.uri.replace(/^file:\/\//i, '') : entity.uri
+            // Decided by the bytes, not by the extension. The extension list
+            // refused `.njk`, `.scss`, `.toml` and `.ect` — the last of which
+            // mikser ships a renderer for — so reading a layout depended on
+            // which engine it happened to be written in.
+            if (!looksTextual(await readPrefix(target, SNIFF_BYTES))) {
+                const ext = path.extname(entity.uri).slice(1).toLowerCase()
+                return {
+                    contentSkipped: `Not text${ext ? ` (.${ext})` : ''} — the bytes are binary, not an unrecognised `
+                        + 'extension. Read the file directly at entity.uri, or use a render API to materialize output.',
+                }
+            }
             return { content: await readFile(target, 'utf8') }
         } catch (err) {
             return { contentError: err.message }