@aiquants/markdown-explorer 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/CHANGELOG.md +31 -0
  2. package/README.md +30 -4
  3. package/dist/ExplorerSplit-CN5TvRj6.js +1495 -0
  4. package/dist/ExplorerSplit-CUIbSLQm.cjs +1 -0
  5. package/dist/MultiLayout-BDcQSpa6.cjs +1 -0
  6. package/dist/{MultiLayout-8s7q3-Hm.js → MultiLayout-hPmV-bae.js} +69 -66
  7. package/dist/{NativeScrollBar-DqkutcGb.cjs → NativeScrollBar-CHEQgaVx.cjs} +1 -1
  8. package/dist/{NativeScrollBar-D3VDRQqf.js → NativeScrollBar-DYEv2GLV.js} +1 -1
  9. package/dist/TreeLayout-BDaIyoGT.cjs +1 -0
  10. package/dist/TreeLayout-CqzxLpoM.js +23 -0
  11. package/dist/core/contracts.d.cts +23 -7
  12. package/dist/core/contracts.d.ts +23 -7
  13. package/dist/core/labels.d.cts +4 -0
  14. package/dist/core/labels.d.ts +4 -0
  15. package/dist/dataRoute-CUXlMhUJ.cjs +1 -0
  16. package/dist/{dataRoute-Dl6xmEFs.js → dataRoute-Ce6EIuu4.js} +69 -63
  17. package/dist/index-B3nShkkt.cjs +3 -0
  18. package/dist/{index-Dv9lUZqD.js → index-gJp1iXTc.js} +1020 -916
  19. package/dist/index.cjs +1 -1
  20. package/dist/index.js +3 -3
  21. package/dist/{location-CaNtUswk.js → location-CtM94G0O.js} +1 -1
  22. package/dist/{location-2QZADLiv.cjs → location-FavgY_gB.cjs} +1 -1
  23. package/dist/sanitizeWorker.cjs +1 -1
  24. package/dist/sanitizeWorker.js +1 -1
  25. package/dist/server/errors.d.cts +1 -1
  26. package/dist/server/errors.d.ts +1 -1
  27. package/dist/server/ports.d.cts +1 -0
  28. package/dist/server/ports.d.ts +1 -0
  29. package/dist/server.cjs +1 -1
  30. package/dist/server.js +753 -716
  31. package/dist/styles/markdown-explorer.css +1 -1
  32. package/docs/behavior/dom-hooks.md +6 -3
  33. package/docs/behavior/layout.md +6 -0
  34. package/docs/behavior/localization.md +4 -1
  35. package/docs/behavior/security.md +11 -4
  36. package/docs/behavior/url-contract.md +1 -0
  37. package/package.json +4 -3
  38. package/dist/ExplorerSplit-rUVsf5i-.cjs +0 -1
  39. package/dist/ExplorerSplit-uX2ojZe8.js +0 -1479
  40. package/dist/MultiLayout-ZK2V9nms.cjs +0 -1
  41. package/dist/TreeLayout-C7ZNnaOr.js +0 -22
  42. package/dist/TreeLayout-DkTVgxxb.cjs +0 -1
  43. package/dist/dataRoute-DYjYBiXF.cjs +0 -1
  44. package/dist/index-CLe6vRXs.cjs +0 -3
package/CHANGELOG.md CHANGED
@@ -1,5 +1,36 @@
1
1
  # Changelog
2
2
 
3
+ ## Unreleased
4
+
5
+ ### Added
6
+
7
+ - **Source of a Markdown document** (minor): the document bar offers a **Source** toggle before Refresh document while its document is a loaded Markdown document — labelled beside a page view's pane (`showMarkupLabel` «Source» / 「ソース」, tooltip `showMarkup`), icon-only and named after the document in a multi-view panel (`showMarkupNamed`) — a toggle button (`aria-pressed`) that shows the document as written instead of rendered, in place, keeping the focus on the toggle.
8
+ - The pane reads the document's file through the data route's new `text` operation and shows it like a text file (the file header with Open and Download, `textTruncated` when the file was cut, the text never interpreted): the skeleton until the first answer (`markupLoading` for screen readers), a failure announced once (`documentFailed`) with Try again for a `failed` read, and the text read again on every new answer for the document (Refresh document, Refresh tree, a revalidation) while the previous text stays.
9
+ - The choice belongs to the reader and the document (one choice per reader): every view showing the document follows it, a document the reader comes back to keeps it, and nothing is saved. The document region carries `data-aqmx-document-view` (`rendered` / `markup`) for a Markdown document; new DOM hooks `markdown-explorer-document-markup`, `markdown-explorer-markup-skeleton` and `markdown-explorer-markup-failure`.
10
+ - The data route's `text` operation (`GET <dataPath>/text?path=<document>`, GET and HEAD) answers a text document (`name`, `text`, `truncated`, the asset `url`) or a failure document, behind the same authentication, deny rules (a refusal logged with the operation `text`) and admission as `asset`,
11
+ reading the file through the host's `asset` port: at most `textMaxBytes` bytes (a range when the reported size is larger, one byte past the limit when the size is unknown), decoded as UTF-8 (a leading byte order mark dropped, a multi-byte character the limit cuts left out), `unsupported` for bytes holding NUL, `failed` (logged) for a stream short of its reported size.
12
+ No host change is needed.
13
+ - The server option `textMaxBytes` (a positive integer up to 256 MiB; default 2 MiB) bounds it; `ExplorerOperation` gains `"text"`.
14
+ - New labels `showMarkupLabel`, `showMarkup`, `showMarkupNamed` and `markupLoading` (English and Japanese).
15
+
16
+ ### Changed
17
+
18
+ - **The refresh's proof of origin is the shared cross-origin check of server routes** (`crossOriginRefusal` of `@aiquants/request-isolation`, a new dependency, serving no navigation from another origin): the tree refresh and a document request marked as a refresh still need the custom header `X-Markdown-Explorer: refresh`, and now pass that one check instead of the explorer's own reading of `Sec-Fetch-Site`.
19
+ - A refresh `POST` without Fetch Metadata is now refused (403) when its `Origin` names another host or port, is `null` or is not a URL; before, any request without `Sec-Fetch-Site` passed. A request without `Origin` still passes, and so does a marked document `GET` without Fetch Metadata, whatever its `Origin`.
20
+ - `Sec-Fetch-Site: none` (a load the user started, which a fetch never sends) now passes, as `same-origin` does. `same-site` and `cross-site` are refused as before.
21
+
22
+ ## 0.5.0 (2026-10-09)
23
+
24
+ ### Added
25
+
26
+ - **The reveal finds the source that holds the document** (minor): with the reader's `revealDocument` setting, when the shown source's tree does not hold the open document, the tree moves to the first other source that does, and reveals the document there.
27
+ - Covers a document opened by a URL that names another source or none (the default source), reached by a link from a document of another source, or by Back and Forward, in the tree view and the multi view (for the document the reveal follows: the maximized panel's, else the last opened).
28
+ - The move replaces the URL's `source` only (no history entry; the view, the documents, the maximized document, the overrides and the fragment stay), happens at most once per change of the open document, and the new tree opens the chain it was handed without asking again. With no source holding the document, nothing moves and no error is shown.
29
+ - It never moves for a document the reader opened from the tree, for the document open while the reader picked a source by hand, or again for a document it already moved for; such a document is asked of the shown source alone (`ancestors`). The usual ends of a reveal (the reader's input in the tree, Collapse all, a source switch, closing the sheet, a newer document) also cancel the move.
30
+ - The data route's new `reveal` operation (`GET <dataPath>/reveal?source=<shown source>&path=<document>`, answering `{ status: "ok", source, ancestors }`, both `null` when no source answers) asks the shown source first, then the others in configuration order, one after another, behind the same authentication, deny rules, boundary checks, validation and `maxDepth` as `ancestors`. A source without `ancestors`, or whose `contains` refuses the path, is passed over without calling any of its ports; a source's failure counts as `null` (logged as in `ancestors`).
31
+ - `ExplorerOperation` (the operation of a logged failure) gains `"reveal"`, for an unexpected exception of the operation itself.
32
+ - **Demo**: the nested `reference` source only lists (no `ancestors` port), so its documents are revealed in `guide`.
33
+
3
34
  ## 0.4.0 (2026-10-08)
4
35
 
5
36
  ### Breaking
package/README.md CHANGED
@@ -18,6 +18,9 @@ document. The document stays on screen while it reloads and is replaced in place
18
18
  reloaded document is announced, and a failed reload keeps the document under a notice naming the failure, which is
19
19
  announced too and stays until a newer copy of the document replaces or confirms it, the reader moves to another
20
20
  document, or the next refresh starts.
21
+ Beside it, a Markdown document offers **Source**: a toggle that shows the document as written instead of rendered
22
+ (its file read through the data route's `text` operation, shown like a text file), for every view the document
23
+ appears in, until the reader toggles it back; the choice is never saved.
21
24
  A single-view (embedding) page never downloads the tree and multi-panel views, which load on demand.
22
25
  - **Embeds and link cards** — with `embeds` in the configuration, a link alone in a paragraph shows its post or video from up to ten providers (YouTube, X, Instagram, Threads, TikTok, Bluesky, LinkedIn, Reddit, note and niconico) in a cross-origin frame, with no provider script in the page, or a link card the explorer's own data route reads (`{dataPath}/link-card`, through `@aiquants/markdown`'s link-card handler: internal addresses never become cards); the link itself always stays, under the frame, as the card or as the paragraph.
23
26
  - **Secure by default** — Markdown HTML is sanitized on the server with an allow-list (scripts, event handlers, `srcdoc` and foreign iframes never reach the browser), and the document viewer applies its own on every render (a document keeps only the converter's class tokens, and ids only on headings, footnotes and `user-content-…` targets); document paths are validated, and deny rules hide environment files, keys and version-control metadata through up to three percent-decoding levels; tokens, principals, server paths and raw error messages never leave the server.
@@ -268,7 +271,7 @@ The full contract, including canonicalization, is in [URL contract](docs/behavio
268
271
  | `scopeSecret` | `string` | The deployment's secret for the readers' scopes: at least 32 characters (a shorter one throws a `RangeError`) and the same on every server instance. |
269
272
  | `sources` | `ExplorerSource<P>[]` | The sources in switcher order (at least one; the first is the default): `id` (lowercase letters, digits and `-`, starting with a letter or digit, unique; the URL's `source` value), `label` (a string, or a function of the principal), `boundary` (where the source's documents may lie, see [Source boundaries](#source-boundaries)), `tree(context)` (lists the source's roots), `children?(context, path, readPath)` for lazy folders (asked only while the tree shows the folder open — the reader opened it, Expand all opened it (a press keeps opening folders as their listings land, within `expandAll`), or a remembered expansion opened it — and only for a path inside the source's boundary; a listing no tree wants any more is aborted through `context.signal`, which the source should honour), `ancestors?(context, path, readPath, options)` (the folders down to a document, for the reader's reveal; see [Revealing the open document](#revealing-the-open-document)), `cacheScope?` (`"principal"`, the default, or `"shared"`). The `context` is described under [Entries and notices](#entries-and-notices). |
270
273
  | `document` | `(context, path, readPath) => Promise<ExplorerHostDocument>` | Resolves a document path. Called only for a path inside at least one source's boundary; `readPath` is what the admitting source's `confirm` answered (`path` when that source has no `confirm`), so read `readPath` and show the document as `path`. An image, media, text or file document reports its file's `version`; the explorer writes its URL (see [Documents](#documents)). |
271
- | `asset` | `(context, path, readPath) => Promise<ExplorerAssetFile>` | Finds the file behind the data route's `asset` operation: any regular file the document admission admits, whatever its kind. Called only after the path passed the deny rules and the same union admission as a document, with the same `readPath`; see [Serving files](#serving-files). |
274
+ | `asset` | `(context, path, readPath) => Promise<ExplorerAssetFile>` | Finds the file behind the data route's `asset` operation (and its `text` operation, which reads a Markdown document's source through it): any regular file the document admission admits, whatever its kind. Called only after the path passed the deny rules and the same union admission as a document, with the same `readPath`; see [Serving files](#serving-files). |
272
275
  | `signedOutPage` | `(request, headers) => Response` | The page response for a signed-out reader, usually a redirect to sign-in. Data requests answer 401 instead. |
273
276
  | `forbiddenPage?` | `(request, headers) => Response` | The page response for a reader without access (default: a 403 for the route's error boundary). |
274
277
  | `notices?` | `(context) => Promise<ExplorerNotice[]>` | Callouts above the tree (a missing permission with a link that grants it, for example). |
@@ -276,6 +279,7 @@ The full contract, including canonicalization, is in [URL contract](docs/behavio
276
279
  | `treeCache?` | `{ ttlMs?, maxEntries?, maxBytes? } \| false` | The server's tree cache, each limit defaulting on its own (5 minutes, 64 entries, 64 MiB of the trees' JSON, counted at two bytes per character). The time to live counts from the moment the tree's walk began, and an expired tree is never answered: a page load or tree request after it waits for one new walk, which every concurrent request shares. Each cached tree is also kept parsed beside its JSON, which `maxBytes` does not count; its share falls as names get longer and is higher for non-ASCII names (measured on trees of 20,000 entries: about 1.0 to 1.9 times the counted bytes for ASCII names of 40 down to 4 characters, 1.4 to 2.2 times for non-ASCII names), and a tree with any non-ASCII name keeps a two-byte JSON as large as its count, so plan for up to about 2.4 times `maxBytes` of memory per process with ASCII names and up to about 3.2 times with short non-ASCII names. `false` turns the cache off. |
277
280
  | `sanitizer?` | `{ workers?, deadlineMs?, maxHtmlBytes?, cacheBytes?, workerHeapMb?, jobsPerScope?, maxQueuedJobs? }` | The HTML sanitizer, each field defaulting on its own: 2 worker threads, a 30 s deadline per document, HTML up to 4 MiB, a 64 MiB cache of outcomes, 512 MiB of heap per worker (`workerHeapMb`), at most `multiView.maxPanels` + max(1, `workers` − 1) + 3 documents per reader running or waiting (`maxPanels` + 4 with the default two workers, 16 with the default 12 panels) and four times `jobsPerScope` waiting in all, also when `jobsPerScope` is set. Neither `jobsPerScope` nor `maxQueuedJobs` may be set below `multiView.maxPanels`, because a page sends the document of every panel at once and a reader who finds every worker busy waits with all of them; a smaller value throws a `RangeError` naming both options at startup, as does a `workerHeapMb` that leaves room for fewer than 4,096 parsed nodes beside HTML of `maxHtmlBytes`. A document over the size, nesting, node, comment or attribute limits, whose sanitized HTML is longer than four characters per byte of `maxHtmlBytes` (16,777,216 by default), past the deadline, or one that runs a worker out of heap is `too-large`; one beyond either admission limit, or one whose worker could not start, is `failed` (logged without the principal) and a later request tries again. A reader runs at most `workers` − 1 documents at once (one when there is a single worker): with the default two workers, one reader — or all anonymous readers, who share one scope and so one admission budget — uses one. |
278
281
  | `deferredTimeoutMs?` | `number` | How long the page loader waits for a streamed value (default 4000 ms; keep it below your server entry's `streamTimeout`). A late value renders the loading state on the server (never a failure) and is fetched by the browser once a pane shows it. The work behind a late tree or document keeps running for another `deferredTimeoutMs`, so the browser's data request for it can join that work instead of starting over (a host that joins requests for the same work keeps it for that request), and its `signal` aborts then; the work behind late notices, which the browser never fetches again, is aborted as soon as they are given up. |
282
+ | `textMaxBytes?` | `number` | The most bytes of a file the data route's `text` operation reads and answers (a positive integer up to 256 MiB; default 2 MiB): a longer file answers its beginning, marked truncated. The explorer shows a Markdown document's source with it, so a host that renders larger Markdown sets it to its own source limit. |
279
283
  | `logger?` | `{ error(message, detail) }` | Where adapter failures and malformed source output are reported (default `console.error`). A tree or children entry with an empty name, or with a path the browser cannot address (empty, too long, a lone surrogate, a control character or a backslash — for example macOS's `Icon\r`), or outside its source's boundary, is left out together with its subtree and reported with the message `[markdown-explorer] <operation> left out an entry` and the detail `{ operation, sourceId, path, error }`, whose `error` names the reason; any other malformed listing becomes `failed`. A boundary that throws or answers malformed values is reported with the operation `boundary`, and so is the rejection of a promise a `contains` answers (it is not awaited and counts as outside). A failed authentication of a data request is reported with the operation `authenticate` and never quotes a header: `headers` that `Headers` cannot read are reported by a fixed message, and a `Response` that `authenticate` throws (React Router's `throw redirect(...)`) by its status alone; any other exception of your adapters is logged as thrown, so keep secrets out of it. |
280
284
  | `onTreeRefreshed?` | `(key: string) => void` | Called once per tree refresh, after its reload settled (whatever its result) unless the request went away, with the refreshed tree's cache key (opaque). A multi-process host relays the key to its other processes, which call `forgetTree(key)` (see [Hosting notes](#hosting-notes)). Its return value is ignored, but a promise it returns (an asynchronous relay) is observed, never awaited: a throw, or the rejection of that promise, is logged with the operation `refresh` and does not change the response. |
281
285
 
@@ -297,6 +301,7 @@ Every source declares where its documents may lie, as `boundary: { contains, con
297
301
  - A source's tree and children list only paths inside its own boundary: an entry outside it is left out with its subtree and logged.
298
302
  - A children request is checked against the named source alone: the deny rules, then `contains` (outside answers `forbidden`), then `confirm` (outside answers `forbidden`, a thrown `ExplorerError` its reason); `children(context, path, readPath)` is called only after both passed.
299
303
  - An ancestors request is checked against the named source alone as well: the deny rules (a denied path answers `forbidden`), then `contains` and `confirm`, where outside answers `{ status: "ok", ancestors: null }` without calling the host (the open document may lie in another source) and a thrown `ExplorerError` its reason; `ancestors(context, path, readPath, options)` is called only after both passed.
304
+ - A reveal request checks the deny rules once, then each source in turn as an ancestors request does — the shown source first, then the others in configuration order —, passing over a source without `ancestors` or whose `contains` refuses the path without calling any of its ports.
300
305
  - A document — of any view, panel, document link or seeded page — carries no source: it opens when the boundary of at least one source admits its path (the union of every source's boundary). The deny rules come first; a path no source contains answers `forbidden` without calling the host or storage; a containing source without `confirm` admits it at once with `readPath` equal to the path; otherwise the containing sources confirm it in configuration order and the first inside admits it with its `readPath`. When none does, the first confirmation's failure answers, else `forbidden`.
301
306
  - The union is exactly what the deployment exposes: a source whose boundary admits every document a reader can read in a store (an entry point listing everything the reader sees) opens every such document through every view, link and asset URL, so documents of that store are confined only when every source over it has a confined boundary. Asset URLs are admitted by the same union, because the explorer serves them itself.
302
307
 
@@ -376,15 +381,32 @@ The reader's tree setting "Reveal the open document" (`revealDocument`, off in `
376
381
  The single view has no tree.
377
382
 
378
383
  - **When**: on load, and whenever that document changes from outside the tree (a link in the document, Back and Forward, opening or maximizing a panel). A document the reader opens by clicking or pressing Enter in the tree is not revealed again: the tree already has the focus there.
379
- - **How**: the browser asks the data route's `ancestors` operation (`GET <dataPath>/ancestors?source=<shown source>&path=<document>`) for the folders of the **shown** source, opens them all at once, and keeps bringing the row into view while their listings land (each lazy folder is listed as soon as its parent's contents are known, ahead of bulk work).
384
+ - **How**: the browser asks the data route's `reveal` operation (`GET <dataPath>/reveal?source=<shown source>&path=<document>`) which source reveals the document, opens the folders of that source's answer all at once, and keeps bringing the row into view while their listings land (each lazy folder is listed as soon as its parent's contents are known, ahead of bulk work).
385
+ - **Which source**: the server asks the **shown** source first, then the other sources in configuration order, one after another (never all at once: each call of a cloud source costs storage requests), and answers the first source whose `ancestors` answers a chain, with that chain (see [the `reveal` operation](#the-reveal-operation)).
386
+ - The shown source answers: the reveal happens there.
387
+ - Another source answers: the tree moves to it. The URL's `source` is replaced (no history entry; the view, the documents, the maximized document, the overrides and the fragment stay), and the new tree opens the chain it was handed without asking again.
388
+ - No source answers: nothing moves and no error is shown; a row the shown tree already lists is still brought into view.
389
+ - **When the tree may move**: only for a change of the open document (load, a link in a document, Back and Forward, opening or maximizing a panel), once per change.
390
+ - It never moves for a document the reader opened from the tree (by click, Enter or Space), for the document that was open while the reader picked a source by hand, or again for a document it already moved for. The explorer remembers that document across remounts of the tree and the pane, until another document is settled.
391
+ - Such a document is asked of the shown source alone, through the `ancestors` operation (`GET <dataPath>/ancestors?source=<shown source>&path=<document>`), so a source the reader picked is never left by itself and costs no search of the others.
380
392
  It stops at the reader's next input in the tree (a press, a wheel, a touch, a key or a focus), at the next document or source, at Collapse all, when the explorer is hidden during the reveal (closing the sheet, collapsing the explorer panel), when a folder's listing fails, or when every folder of the chain has loaded and the row is not there — so it waits for at most one listing per folder. A chain deeper than `revealDocument.maxDepth` (16 by default) opens nothing: the server answers `null` for it.
381
393
  - **Stored state**: the folders a reveal opens are part of the reader's remembered expansion for that source, exactly as if the reader had opened them, so a reload shows them open and the reader closes them as any other folder.
382
394
  - **The port**: `ExplorerSource.ancestors?(context, path, readPath, options): Promise<readonly string[] | null>` answers the folder row paths from the source's top level down to the document's direct parent, exactly as that source's `tree` and `children` name them (`[]` for a document at the top level), or `null` when the document is not in this source or cannot be revealed there (for example a document reached only through a shortcut, whose row has the shortcut's path).
383
- It is called only for a document path inside the source's boundary that passed the deny rules, with the confirmed `readPath` (see [Source boundaries](#source-boundaries)). A source without it answers `not-found`, and its documents are not revealed.
395
+ It is called only for a document path inside the source's boundary that passed the deny rules, with the confirmed `readPath` (see [Source boundaries](#source-boundaries)). Without it, the source's documents are not revealed in it: the `ancestors` operation answers `not-found` for the source, and the `reveal` operation passes it over without calling any of its ports (a source that only lists, such as an entry point onto what others shared, reveals its documents through a source that answers them).
384
396
  `options` (`ExplorerAncestorsOptions`) is always `{ maxDepth }`, the configuration's `revealDocument.maxDepth`. The server answers `{ status: "ok", ancestors: null }` for a chain of more folders than that, without validating it, so a source whose climb costs requests (a parent climb in a cloud drive, for example) may stop once the chain is longer and answer `null` itself; a source that ignores `options` gets the same answer.
385
397
  - **Validation**: every path of a chain within `maxDepth` must be acceptable (non-empty, within the length limit, no control character, lone surrogate or backslash), pass the deny rules, lie inside the source's boundary, differ from the document and appear once. Any other answer (not `null` or an array, or one bad path) is logged with the operation `ancestors` and answered `{ status: "error", failure: { reason: "failed" } }`, and the tree opens nothing; the browser checks the answer's shape again. A thrown `ExplorerError` answers its reason, any other exception is logged and answers `failed`.
386
398
  - **Answers**: `200` with `{ status: "ok", ancestors: string[] | null }` or `{ status: "error", failure }`, `400` for a missing or malformed `source` or `path`, `404` for an unknown source or one without `ancestors`, `405` for anything but `GET` and `HEAD`, and the usual `401` and `403`.
387
399
 
400
+ #### The `reveal` operation
401
+
402
+ `GET <dataPath>/reveal?source=<shown source>&path=<document>` (and `HEAD`) answers which source reveals a document, behind the same authentication, deny rules, boundary checks, validation and `maxDepth` as `ancestors`:
403
+
404
+ - A denied document answers `{ status: "error", failure: { reason: "forbidden" } }` without asking any source.
405
+ - The sources are asked one after another: the shown source first, then the others in configuration order. A source without `ancestors`, or whose `contains` refuses the path, is passed over without calling any of its ports; the others are checked and called exactly as by `ancestors`.
406
+ - A source's failure counts as `null` and the search goes on to the next source: a failed confirmation, a thrown exception or a malformed answer (logged as in `ancestors`; a thrown `ExplorerError` is the host's own answer and is not logged), and a chain deeper than `maxDepth` (neither validated nor logged).
407
+ - The first chain answers `{ status: "ok", source: "<id>", ancestors: string[] }`; when no source answers one, `{ status: "ok", source: null, ancestors: null }`. A request that went away ends the search.
408
+ - `400` for a missing or malformed `source` or `path`, `404` for an unknown source (a shown source without `ancestors` is passed over, not refused), `405` for anything but `GET` and `HEAD`, and the usual `401` and `403`.
409
+
388
410
  ### `createFileSystemSource(options)`
389
411
 
390
412
  A reference source over a folder on disk: lexical containment checked before any filesystem call and again after resolving the real path, symbolic links refused, a file read only when the opened file is the one the checks saw, denied branches pruned while walking, a cap on the number of entries (`too-large` above it), a size cap on Markdown files, and a bounded streamed preview for files with a known text extension or name (any other file is a `file` document, offered for download).
@@ -473,6 +495,9 @@ and `Cache-Control: private, max-age=60, stale-while-revalidate=600, no-transfor
473
495
  The body of a 200 or 206 with a `Content-Length` carries exactly that many bytes: the explorer drops the bytes past it and cancels the stream `open` returned, and fails the response when that stream ends short, so a file that changes while it is served never gets a body that disagrees with its length and ETag.
474
496
  The URL carries the path in its query, so no name needs an extra escape and the request's own path never ends in `.data`; a document's URL carries `v=<version>` as a cache-buster, which the server never reads (the ETag is always the current version).
475
497
 
498
+ The data route's `text` operation reads a file through the same port for the Source toggle: `<dataPath>/text?path=<document path>` (GET and HEAD) takes the same authentication, deny rules (a refusal logged once with the operation `text`) and admission as `asset`, then answers JSON like a document request — status 200 with a text document (`name`, `text`, `truncated`, and the file's asset `url` with its version) or a failure document, and the reader's scope header.
499
+ It reads at most `textMaxBytes` bytes (the first ones as a range when `size` is larger, the whole file otherwise, an empty file never, a file of unknown `size` one byte past the limit to learn whether more follows), cancels the stream once enough was read, decodes them as UTF-8 (a leading byte order mark dropped, a multi-byte character the limit cuts left out), and answers `unsupported` for bytes holding NUL and `failed` (logged) for a stream that ends before the `size` the port reported. It sends no refresh mark: the port receives `refresh: false`.
500
+
476
501
  ### Link cards
477
502
 
478
503
  With `embeds: { linkCards: true }`, the data route has a `link-card` operation: `GET` or `HEAD` `<dataPath>/link-card?url=<href>`, which `@aiquants/markdown`'s link card asks (same-origin, in the background, once the card nears the viewport). It is the only route of the cards: the explorer creates `@aiquants/markdown`'s `createLinkCardHandler` once, in `createMarkdownExplorer`, behind the read-only authentication, and passes every answer of it through unchanged — status, headers and cache headers. In order:
@@ -629,7 +654,8 @@ Every scroller of the explorer that the reader browses gets one pointer scroll b
629
654
  - Document paths from URLs are limited to 4096 characters without lone surrogates, control characters or backslashes; deny rules are matched through up to three lenient percent-decoding levels, against each level whole and split on `/` or `\` (a storage may read either as part of a name or as a separator), and after full Unicode case folding.
630
655
  - Every source is confined to its boundary: its tree and children list only paths inside it, a children request reaches the host only for a path the named source's boundary admits, and a document or a file's bytes reach the host only when the boundary of at least one source admits its path (see [Source boundaries](#source-boundaries)). A source whose boundary admits everything a reader can read in a store confines nothing in that store.
631
656
  - File bytes are served only by the explorer's `asset` operation, after the deny rules and the document admission, inline only for raster images, audio, video and PDF, always with `nosniff` and a `same-origin` resource policy, and with a sandboxing policy except for PDF, under which inline audio and video keep the URL's origin (`allow-same-origin`, no `allow-scripts`) (see [Serving files](#serving-files)).
632
- - Data responses are `private, no-store` JSON with `nosniff`, a sandboxing content security policy and `same-origin` resource policy, and the data route refuses React Router's single-fetch requests (`.data`), whose answers would carry none of those headers; the tree refresh, and a document request marked as triggered by a refresh (`X-Markdown-Explorer: refresh`, which makes the host skip its caches), require the custom request header and a same-origin fetch.
657
+ - A Markdown document's source (the Source toggle) is read only by the explorer's `text` operation, through the same `asset` port after the same deny rules and admission, so it serves nothing the reader could not already download: at most `textMaxBytes` of the file's beginning, decoded as UTF-8 into JSON, which the browser shows as text and never interprets.
658
+ - Data responses are `private, no-store` JSON with `nosniff`, a sandboxing content security policy and `same-origin` resource policy, and the data route refuses React Router's single-fetch requests (`.data`), whose answers would carry none of those headers; the tree refresh, and a document request marked as triggered by a refresh (`X-Markdown-Explorer: refresh`, which makes the host skip its caches), require the custom request header and pass the shared cross-origin check of server routes (`@aiquants/request-isolation`).
633
659
  - Link cards are read by `@aiquants/markdown`'s handler behind a read-only authentication (no token refresh, no `Set-Cookie`; an authentication that carries headers is refused and logged), and its guards keep every internal address from becoming a card; see [Link cards](#link-cards).
634
660
  - Each data response carries an opaque, pseudonymous scope (an HMAC of the principal key under `scopeSecret`); when it changes, the browser drops every cache and remembered path. Browser storage is also checked against the page's scope on every page load, before anything reads it.
635
661