@aiquants/markdown-explorer 0.4.0 → 0.5.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 (36) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +20 -2
  3. package/dist/ExplorerSplit-CWcK1E4I.js +1495 -0
  4. package/dist/ExplorerSplit-ajN3GSdA.cjs +1 -0
  5. package/dist/{MultiLayout-8s7q3-Hm.js → MultiLayout-BtWtCzJV.js} +69 -66
  6. package/dist/MultiLayout-DvkcdO9c.cjs +1 -0
  7. package/dist/{NativeScrollBar-DqkutcGb.cjs → NativeScrollBar-DbzyQ85y.cjs} +1 -1
  8. package/dist/{NativeScrollBar-D3VDRQqf.js → NativeScrollBar-apXjIKRW.js} +1 -1
  9. package/dist/TreeLayout-BcHsv9G8.js +23 -0
  10. package/dist/TreeLayout-rwhJfLmU.cjs +1 -0
  11. package/dist/core/contracts.d.cts +13 -0
  12. package/dist/core/contracts.d.ts +13 -0
  13. package/dist/{dataRoute-Dl6xmEFs.js → dataRoute-Btg4w3vO.js} +70 -65
  14. package/dist/dataRoute-DHpu0fg2.cjs +1 -0
  15. package/dist/{index-Dv9lUZqD.js → index-CIZw73j9.js} +539 -519
  16. package/dist/index-Cie6WPiM.cjs +3 -0
  17. package/dist/index.cjs +1 -1
  18. package/dist/index.js +5 -5
  19. package/dist/{location-2QZADLiv.cjs → location-CSIhx-L4.cjs} +1 -1
  20. package/dist/{location-CaNtUswk.js → location-c1zdeySY.js} +1 -1
  21. package/dist/sanitizeWorker.cjs +1 -1
  22. package/dist/sanitizeWorker.js +1 -1
  23. package/dist/server/errors.d.cts +1 -1
  24. package/dist/server/errors.d.ts +1 -1
  25. package/dist/server.cjs +1 -1
  26. package/dist/server.js +597 -589
  27. package/docs/behavior/security.md +1 -1
  28. package/docs/behavior/url-contract.md +1 -0
  29. package/package.json +1 -1
  30. package/dist/ExplorerSplit-rUVsf5i-.cjs +0 -1
  31. package/dist/ExplorerSplit-uX2ojZe8.js +0 -1479
  32. package/dist/MultiLayout-ZK2V9nms.cjs +0 -1
  33. package/dist/TreeLayout-C7ZNnaOr.js +0 -22
  34. package/dist/TreeLayout-DkTVgxxb.cjs +0 -1
  35. package/dist/dataRoute-DYjYBiXF.cjs +0 -1
  36. package/dist/index-CLe6vRXs.cjs +0 -3
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.5.0 (2026-10-09)
4
+
5
+ ### Added
6
+
7
+ - **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.
8
+ - 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).
9
+ - 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.
10
+ - 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.
11
+ - 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`).
12
+ - `ExplorerOperation` (the operation of a logged failure) gains `"reveal"`, for an unexpected exception of the operation itself.
13
+ - **Demo**: the nested `reference` source only lists (no `ancestors` port), so its documents are revealed in `guide`.
14
+
3
15
  ## 0.4.0 (2026-10-08)
4
16
 
5
17
  ### Breaking
package/README.md CHANGED
@@ -297,6 +297,7 @@ Every source declares where its documents may lie, as `boundary: { contains, con
297
297
  - 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
298
  - 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
299
  - 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.
300
+ - 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
301
  - 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
302
  - 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
303
 
@@ -376,15 +377,32 @@ The reader's tree setting "Reveal the open document" (`revealDocument`, off in `
376
377
  The single view has no tree.
377
378
 
378
379
  - **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).
380
+ - **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).
381
+ - **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)).
382
+ - The shown source answers: the reveal happens there.
383
+ - 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.
384
+ - No source answers: nothing moves and no error is shown; a row the shown tree already lists is still brought into view.
385
+ - **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.
386
+ - 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.
387
+ - 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
388
  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
389
  - **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
390
  - **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.
391
+ 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
392
  `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
393
  - **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
394
  - **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
395
 
396
+ #### The `reveal` operation
397
+
398
+ `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`:
399
+
400
+ - A denied document answers `{ status: "error", failure: { reason: "forbidden" } }` without asking any source.
401
+ - 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`.
402
+ - 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).
403
+ - 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.
404
+ - `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`.
405
+
388
406
  ### `createFileSystemSource(options)`
389
407
 
390
408
  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).