@aiquants/markdown-explorer 0.15.0 → 0.17.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 (58) hide show
  1. package/CHANGELOG.md +173 -15
  2. package/README.md +73 -27
  3. package/dist/EditSurface-0owpPyLE.js +786 -0
  4. package/dist/EditSurface-D-nhilRk.cjs +2 -0
  5. package/dist/{ExplorerSplit-BPLECNpv.js → ExplorerSplit-8c93p1hy.js} +613 -592
  6. package/dist/ExplorerSplit-bpEvHrCo.cjs +1 -0
  7. package/dist/MultiLayout-BXfzR6XC.cjs +1 -0
  8. package/dist/MultiLayout-Dy3DD_09.js +963 -0
  9. package/dist/NativeScrollBar-CI9fTvkt.js +65 -0
  10. package/dist/NativeScrollBar-Ddn0iHjv.cjs +1 -0
  11. package/dist/TreeLayout-CKZ-XQgn.cjs +1 -0
  12. package/dist/TreeLayout-eFQmzpNj.js +72 -0
  13. package/dist/client/storage.d.cts +1 -0
  14. package/dist/client/storage.d.ts +1 -0
  15. package/dist/core/geometry.d.cts +20 -1
  16. package/dist/core/geometry.d.ts +20 -1
  17. package/dist/core/labels.d.cts +17 -0
  18. package/dist/core/labels.d.ts +17 -0
  19. package/dist/core/location.d.cts +3 -0
  20. package/dist/core/location.d.ts +3 -0
  21. package/dist/core/treeSettings.d.cts +3 -1
  22. package/dist/core/treeSettings.d.ts +3 -1
  23. package/dist/index-5gwNJ8CB.cjs +13 -0
  24. package/dist/index-h9e3p5Pd.js +3645 -0
  25. package/dist/index.cjs +1 -1
  26. package/dist/index.js +25 -25
  27. package/dist/location-D85EXiPt.cjs +1 -0
  28. package/dist/location-G7psbmv_.js +499 -0
  29. package/dist/{merge-Bi2VedIr.js → merge-CS3p9BVw.js} +5 -5
  30. package/dist/{merge-BFk7nT59.cjs → merge-C_g05UGC.cjs} +1 -1
  31. package/dist/server.cjs +1 -1
  32. package/dist/server.js +1 -1
  33. package/dist/{storage-BSthKLSG.js → storage-CmGHg7OA.js} +11 -10
  34. package/dist/storage-DM0EvkVf.cjs +1 -0
  35. package/dist/storage.cjs +1 -1
  36. package/dist/storage.js +1 -1
  37. package/dist/styles/markdown-explorer.css +1 -1
  38. package/dist/useSplitPersistence-B1b5Lg5E.js +42 -0
  39. package/dist/useSplitPersistence-DRjsPZdH.cjs +1 -0
  40. package/docs/behavior/dom-hooks.md +19 -11
  41. package/docs/behavior/layout.md +121 -42
  42. package/docs/behavior/localization.md +12 -6
  43. package/docs/behavior/url-contract.md +18 -6
  44. package/package.json +5 -5
  45. package/dist/EditSurface-BLlu5zEt.cjs +0 -2
  46. package/dist/EditSurface-CF2io496.js +0 -705
  47. package/dist/ExplorerSplit-Cjvy0JHP.cjs +0 -1
  48. package/dist/MultiLayout-BjA0k-5n.cjs +0 -1
  49. package/dist/MultiLayout-D8F0BfxA.js +0 -947
  50. package/dist/NativeScrollBar-BFF12oEd.js +0 -59
  51. package/dist/NativeScrollBar-BUWXPvTV.cjs +0 -1
  52. package/dist/TreeLayout-CQUpgsxz.cjs +0 -1
  53. package/dist/TreeLayout-rhyVTfrI.js +0 -29
  54. package/dist/index-Dn7cYy-4.cjs +0 -13
  55. package/dist/index-v997iKxe.js +0 -3464
  56. package/dist/location-D6RE3wAN.cjs +0 -1
  57. package/dist/location-IRD9h42r.js +0 -444
  58. package/dist/storage-Dgi4JXaB.cjs +0 -1
package/README.md CHANGED
@@ -33,14 +33,14 @@ A single-view (embedding) page never downloads the tree and multi-panel views, w
33
33
  - **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.
34
34
  - **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.
35
35
  - **Multi-panel reading** — open documents as panels, rearrange them by dragging (on a touch screen or with a pen, after a long-press on a panel's header), with the move buttons in each panel's header, or with Alt + Shift + arrow keys, hide, maximize (Escape restores), and navigate inside a panel; the arrangement survives reloads, and a document reopened later returns to its column.
36
- - **Accessible and localized** — named landmarks and controls, a keyboard-operable tree with one Tab stop on the shown document, keyboard-operable menus, panel headers and resize handle, polite announcements (spoken from the sheet while it is open), WCAG 2.2 contrast in light and dark; English (default) and Japanese built in — the tree's and the panel headers' strings included —, every string overridable.
36
+ - **Accessible and localized** — named landmarks and controls, a keyboard-operable tree with one Tab stop on the shown document, keyboard-operable menus, panel headers and resize handle, polite announcements (spoken from the sheet while it is open), WCAG 2.2 enhanced contrast (7:1 for text) in light and dark; English (default) and Japanese built in — the tree's and the panel headers' strings included —, every string overridable.
37
37
 
38
38
  ## Requirements
39
39
 
40
40
  - React 19.2.7 or later and React Router 8 in framework mode (route modules with `loader` / `headers`).
41
41
  - Node.js 22.22 or later (the floor React Router 8 declares). The package ships ES modules and CommonJS; the CommonJS entries load the ESM-only `react-router` through `require(esm)`.
42
- - The peer packages, at these versions or later within the caret ranges the package declares: `@aiquants/markdown` ^6.3.0 (document rendering; its math diagnostics, gantt sizing, embeds, link cards and their sizes, the React-free `@aiquants/markdown/embeds` the sanitizer worker loads and `@aiquants/markdown/source-lines` the editor and the sanitizer read, and the Node-only link-card handler of `@aiquants/markdown/server`, which needs Node.js 22.13 or later — below the explorer's own floor),
43
- `@aiquants/directory-tree` ^4.1.1 (reveals of rows under the scroll bar's buttons), `@aiquants/drag-drop-panels` ^0.10.0, `@aiquants/resize-panels` ^2.1.0 (the source of each layout change, by which the tree pane's width is saved) and `@aiquants/virtualscroll` ^3.11.4.
42
+ - The peer packages, at these versions or later within the caret ranges the package declares: `@aiquants/markdown` ^8.0.0 (document rendering; its components' stylesheet without utilities, its Mermaid labels, its math diagnostics, gantt sizing, embeds, link cards and their sizes, the React-free `@aiquants/markdown/embeds` the sanitizer worker loads and `@aiquants/markdown/source-lines` the editor and the sanitizer read, and the Node-only link-card handler of `@aiquants/markdown/server`, which needs Node.js 22.13 or later — below the explorer's own floor),
43
+ `@aiquants/directory-tree` ^4.1.1 (reveals of rows under the scroll bar's buttons), `@aiquants/drag-drop-panels` ^0.11.0 (the panel headers of a coarse pointer and of a one-column stage the behavior docs follow), `@aiquants/resize-panels` ^2.2.0 (the source of each layout change, by which the tree pane's width is saved) and `@aiquants/virtualscroll` ^3.20.0.
44
44
  The client depends on these floors, while a package manager may only warn about an older peer.
45
45
  - A Markdown parser of your choice on the server that produces HTML and its headings (the explorer sanitizes the HTML before it is sent).
46
46
  - Browsers: the multi view's panel-limit notice uses the Popover API (Chrome and Edge 114, Firefox 125, Safari 17 and later). In browsers without it (for example iOS 16), the notice is drawn in place at the stage's corner instead of in the top layer (while the sheet is open it spans the sheet's header, as in every browser).
@@ -86,7 +86,7 @@ The source ids are not part of it: they are the ids of the server's `sources` (a
86
86
  | `documentStyles?` | `readonly { name, className }[]` | Document styles, the first being the default; `@aiquants/markdown`'s `DEFAULT_MARKDOWN_STYLES` (None, GitHub, Zenn; also exported without React from `@aiquants/markdown/viewer-settings`) when omitted. |
87
87
  | `iframeHosts?` | `readonly string[]` | Host names whose `https:` iframes written in documents may load (exact match); none when omitted. They gate only iframes written in documents; provider frames come from `embeds`, and no iframe of the page's own origin ever renders, whatever is listed. |
88
88
  | `embeds?` | `{ providers?, linkCards?, linkCardSize? }` | What `@aiquants/markdown` makes of a link alone in a paragraph. `providers` lists the ids (`EMBED_PROVIDER_IDS` of `@aiquants/markdown/embeds`: `youtube`, `x`, `instagram`, `threads`, `tiktok`, `bluesky`, `linkedin`, `reddit`, `note`, `niconico`) whose posts and videos documents embed as cross-origin frames, whatever the link's text. `linkCards: true` turns a link written as its own URL into a card, which the data route's own `link-card` operation serves (see [Link cards](#link-cards)): no route of yours is needed. `linkCardSize` picks the size of every card, `compact`, `banner` or `full` (`LINK_CARD_SIZES` of `@aiquants/markdown/embeds`; `@aiquants/markdown`'s `banner` when omitted), and needs `linkCards: true`. Each field defaults to none (`[]`, `false`, omitted), also when given as `undefined`, so without the option such a link stays its paragraph. Repeated ids are removed. An unknown id, a `linkCards` that is not a boolean, an unknown size, a size without `linkCards: true` or an unknown key (`linkCardEndpoint` included) throws a `RangeError` (`[markdown-explorer] embeds…`), and anything but a plain object a `TypeError`. The resolved `config.embeds` is the `MarkdownEmbeds` the viewer takes: `linkCardEndpoint` is `<dataPath>/link-card` when link cards are on and `null` otherwise, and `linkCardSize` is present only when given. See `@aiquants/markdown`'s README (Embeds) for the URLs each provider recognizes, the frames' sizes and the cards' sizes. |
89
- | `defaultTreeSettings?` | `Partial<TreeSettings>` | The reader's tree settings before they change any, merged over the package's `DEFAULT_TREE_SETTINGS` (the source's own order, folders mixed among the files, Single selection, a recursive double click, 8 px expand icons, nothing kept expanded, the open document not revealed, the root indent kept, lines, expand icons and folder and file icons on). Each value is one the settings menu offers: `sortMode` `"native"`, `"asc"`, `"desc"`, `"oldest"` or `"newest"` (by the entries' `modifiedAt`); `folderPlacement` `"mixed"`, `"first"` or `"last"`; `selectionMode` `"single"`, `"multiple"` or `"none"`; `doubleClickAction` `"recursive"` or `"toggle"`; `expandIconSize` `8`, `13` or `5`; the other settings (`alwaysExpanded`, `revealDocument`, `removeRootIndent`, `lines`, `expandIcons`, `directoryIcons`, `fileIcons`) `true` or `false`. An unknown key or any other value throws a `RangeError`, and anything but a plain object (a `Map`, a class instance, an object inheriting its settings) throws a `TypeError`; a setting given as `undefined` keeps the package default. The server render and the hydration draw these defaults (see [Tree settings](#tree-settings)). |
89
+ | `defaultTreeSettings?` | `Partial<TreeSettings>` | The reader's tree settings before they change any, merged over the package's `DEFAULT_TREE_SETTINGS` (the source's own order, folders and READMEs mixed among the files, Single selection, a recursive double click, 8 px expand icons, nothing kept expanded, the open document not revealed, the root indent kept, lines, expand icons and folder and file icons on). Each value is one the settings menu offers: `sortMode` `"native"`, `"asc"`, `"desc"`, `"oldest"` or `"newest"` (by the entries' `modifiedAt`); `folderPlacement` `"mixed"`, `"first"` or `"last"`; `readmePlacement` `"mixed"`, `"first"` or `"last"`; `selectionMode` `"single"`, `"multiple"` or `"none"`; `doubleClickAction` `"recursive"` or `"toggle"`; `expandIconSize` `8`, `13` or `5`; the other settings (`alwaysExpanded`, `revealDocument`, `removeRootIndent`, `lines`, `expandIcons`, `directoryIcons`, `fileIcons`) `true` or `false`. An unknown key or any other value throws a `RangeError`, and anything but a plain object (a `Map`, a class instance, an object inheriting its settings) throws a `TypeError`; a setting given as `undefined` keeps the package default. The server render and the hydration draw these defaults (see [Tree settings](#tree-settings)). |
90
90
 
91
91
  For example, `defaultTreeSettings: { sortMode: "desc" }` lists every folder's entries by name, Z to A, until the reader picks another order.
92
92
 
@@ -198,7 +198,7 @@ import dragDropPanels from "@aiquants/drag-drop-panels/styles/drag-drop-panels.s
198
198
  import virtualscroll from "@aiquants/virtualscroll/styles/virtualscroll.standalone.css?url"
199
199
  import directoryTree from "@aiquants/directory-tree/styles/directory-tree.standalone.css?url"
200
200
  import katex from "@aiquants/markdown/styles/katex.min.css?url"
201
- import markdown from "@aiquants/markdown/styles/markdown.css?url"
201
+ import markdown from "@aiquants/markdown/styles/markdown.standalone.css?url"
202
202
  import githubMarkdown from "@aiquants/markdown/styles/github-markdown.css?url"
203
203
  import zennContent from "@aiquants/markdown/styles/zenn-content.css?url"
204
204
  import message from "@aiquants/markdown/styles/message.css?url"
@@ -232,44 +232,71 @@ body {
232
232
  ```
233
233
 
234
234
  - `html` and `body` take the viewport's height (React Router's default root renders the page straight into `body`; give any element your own root puts between them `height: 100%` as well), and `margin: 0` keeps the page from ending below the viewport. The page is a flex column of that height, and the explorer's wrapper takes what the header leaves (`flex: 1`) and may be shorter than its content (`min-height: 0`).
235
- - The `.standalone.css` builds suit hosts without Tailwind CSS. A Tailwind host loads the plain builds (`resize-panels.css`, `@aiquants/drag-drop-panels/css`, `virtualscroll.css`, `directory-tree.css`) and lets Tailwind scan the peers' `dist` with `@source`.
235
+ - The `.standalone.css` builds, `@aiquants/markdown/styles/markdown.standalone.css` among them, suit hosts without Tailwind CSS (or with Tailwind v3). A Tailwind v4 host loads the plain builds (`resize-panels.css`, `@aiquants/drag-drop-panels/css`, `virtualscroll.css`, `directory-tree.css`) and lets Tailwind scan the peers' `dist` with `@source`.
236
+ For `@aiquants/markdown` it links no components sheet (the document styles below are still linked): its Tailwind entry imports `markdown.css` without `layer()` (the sheet's link and link-card rules and the diagram's focus ring must stay outside every cascade layer), scans the package's build output so that its own build generates the utilities the document viewer uses (the path of `@source` is relative to the CSS file that declares it), and declares the `dark` variant those utilities follow.
237
+ Without a declaration Tailwind's `dark` is the `prefers-color-scheme` media query; declare the one that matches how your page signals dark mode. The one below is the standalone sheet's: a `.dark` ancestor, or the `[data-theme="dark"]` the viewer sets from its `theme`:
238
+
239
+ ```css
240
+ /* app/app.css of a Tailwind v4 host */
241
+ @import "tailwindcss";
242
+ @import "@aiquants/markdown/styles/markdown.css";
243
+ @source "../node_modules/@aiquants/markdown/dist/**/*.js";
244
+ @custom-variant dark (&:where(.dark, .dark *, [data-theme="dark"], [data-theme="dark"] *));
245
+ ```
246
+
247
+ Never load both `markdown.css` and `markdown.standalone.css`, nor `markdown.standalone.css` beside a Tailwind v4 build of the host: the standalone sheet's utilities would meet the host's own in the same cascade layer.
236
248
  - A Tailwind host must fix the cascade-layer order before any package stylesheet names a layer: load its own stylesheet (whose `@import "tailwindcss"` declares `theme, base, components, utilities`) first, or `@import` the package stylesheets from it after `@import "tailwindcss"`. Otherwise the first package sheet puts `components` before `base`, and Tailwind's preflight resets the explorer's (and the peers') spacing and borders.
237
249
  `markdown-explorer.css` itself declares `theme`, `base` and `components` in that order before any rule, which fixes the order whenever it is the first sheet to name a layer.
238
250
  - `github-markdown.css` and `zenn-content.css` back the default document styles, and `github-markdown.css`
239
251
  also draws GitHub alerts (`.markdown-alert`); `message.css` and `details.css` draw Zenn's message and
240
252
  details containers (`aside.message`, `details.markdown-details`) under every document style; load these
241
- two when your converter writes that markup (see [Documents](#documents)). `markdown.css` also gives
242
- GitHub alerts a baseline under the other document styles (None, Zenn).
253
+ two when your converter writes that markup (see [Documents](#documents)). The `@aiquants/markdown` sheet
254
+ (`markdown.standalone.css`, or `markdown.css` in a Tailwind v4 host's build) also gives GitHub alerts a baseline
255
+ under the other document styles (None, Zenn).
243
256
  `@aiquants/markdown/styles/katex.min.css` is KaTeX's own stylesheet, shipped with the fonts it points
244
257
  to; load it when your documents contain math.
245
258
  - Every explorer rule sits in `@layer components`, so your own unlayered rules (or a Tailwind host's utilities) override it — except a few declarations that are `!important` inside the layer, which no unlayered rule of yours can override:
246
259
  the document viewer's transparent body background (so the region's `--aqmx-surface` shows through), the outward focus-ring offset of a document's links inside superscripts and subscripts (footnote references:
247
260
  `github-markdown.css`, whose `.markdown-body` the viewer puts around the content of every document style, draws a link's ring 2 px inside its box, which on a footnote reference's one-glyph box paints over the glyph), the zero transitions of the resize handle and of the tree (whose fade `@aiquants/directory-tree` sets on the tree's root element) under `prefers-reduced-motion: reduce`, and, under forced colors, the resize handle's focus ring and the text and icon colour inside highlighted tree rows and checked tree settings.
248
261
  This is the complete list. Change the rings through the `--aqmx-*` tokens they read (`--aqmx-focus-ring-width`, `--aqmx-focus-ring-offset`); the transitions and the forced-colors system colours read no token.
249
- - The multi-panel view styles `@aiquants/drag-drop-panels`' chrome only through that package's neutral custom properties, bound with ordinary declarations on the stage to the explorer's tokens: the stage's block and inline padding and the column gap to `--aqmx-space-7` and `--aqmx-space-6`; the panels' surface and border (and those of the bar of hidden panels, an empty column and a hidden panel's stand-in during a drag) to `--aqmx-surface` and `--aqmx-border`; the panel titles (and the text of those parts) to `--aqmx-text`; the header buttons' icons to `--aqmx-text-muted`, and on hover to `--aqmx-text` over `--aqmx-surface-sunken`; the custom drag mode's badge (and the pressed drag-mode toggle) to `--aqmx-warning-text` on `--aqmx-warning-surface`; the restore buttons of the bar of hidden panels to `--aqmx-surface` on `--aqmx-accent` (`--aqmx-info-text` while hovered); and the drop placeholders of a drag (text, icon and dashed border) to `--aqmx-accent` on `--aqmx-surface`, the placeholder a drop would land on to `--aqmx-accent-surface`.
262
+ - The multi-panel view styles `@aiquants/drag-drop-panels`' chrome only through that package's neutral custom properties, bound with ordinary declarations on the stage to the explorer's tokens: the stage's block and inline padding and the column gap to `--aqmx-space-7` and `--aqmx-space-6`; the panels' surface and border (and those of the bar of hidden panels, an empty column and a hidden panel's stand-in during a drag) to `--aqmx-surface` and `--aqmx-border`; the panel titles (and the text of those parts) to `--aqmx-text`; the header buttons' icons to `--aqmx-text-muted`,
263
+ and on hover to `--aqmx-text` over `--aqmx-surface-sunken`; the custom drag mode's badge (and the pressed drag-mode toggle) to `--aqmx-warning-text` on `--aqmx-warning-surface`; the restore buttons of the bar of hidden panels to `--aqmx-surface` on `--aqmx-accent` (`--aqmx-info-text` while hovered); and the drop placeholders of a drag (text, icon and dashed border) to `--aqmx-accent` on `--aqmx-surface`, the placeholder a drop would land on to `--aqmx-accent-surface`.
250
264
  So the panel chrome follows the explorer's `theme`, not a `dark` class of the page, and you restyle it by changing those tokens on the explorer (or by setting an `--aqdd-*` property yourself on an element inside the stage).
251
- - A maximized multi-view panel covers the viewport inside `--aqdd-maximize-top`, `--aqdd-maximize-right`, `--aqdd-maximize-bottom` and `--aqdd-maximize-left` (all `0px` by default); bind them in your layout to keep your own header or menu visible. Everything of the explorer it covers (the explorer and its handle or the sheet's bar, and the other panels) is inert until the panel is restored. Your own chrome is not: whatever of it the panel covers stays in the Tab order and in the accessibility tree, so either bind the variables so the panel leaves it uncovered, or make it inert (or `visibility: hidden`) while a panel is maximized — the maximized panel's frame carries `data-aqmx-maximized="true"` (`:has([data-aqmx-panel-frame][data-aqmx-maximized="true"])`), and the URL carries `maximized`.
265
+ - A maximized multi-view panel covers the viewport inside `--aqdd-maximize-top`, `--aqdd-maximize-right`, `--aqdd-maximize-bottom` and `--aqdd-maximize-left` (all `0px` by default); bind them in your layout to keep your own header or menu visible. Everything of the explorer it covers (the explorer and its handle or the sheet's bar, and the other panels) is inert until the panel is restored.
266
+ Your own chrome is not: whatever of it the panel covers stays in the Tab order and in the accessibility tree, so either bind the variables so the panel leaves it uncovered, or make it inert (or `visibility: hidden`) while a panel is maximized — the maximized panel's frame carries `data-aqmx-maximized="true"` (`:has([data-aqmx-panel-frame][data-aqmx-maximized="true"])`), and the URL carries `maximized`.
252
267
  - The tree and single views' document bar touches the page's top inline-end corner, where a host may float a control of its own (a menu switch). The bar keeps `--aqmx-page-bar-inset-inline-end` (`0px` by default) free at the end of its button row, beside the focus ring's room, so its last button (Edit while a document is edited, Refresh document otherwise) never sits under that control. The explorer leaves the property undeclared, so a value set on `:root` (or any ancestor of the explorer) reaches the bar.
253
268
 
254
269
  ## Views and URLs
255
270
 
256
271
  | View | URL | What it shows |
257
272
  | --- | --- | --- |
258
- | Tree | `{basePath}/{tree}` or `{basePath}/{tree}/{document}` | The source tree beside the selected document |
273
+ | Tree | `{basePath}/{tree}`, `{basePath}/{tree}/{document}` or `{basePath}/{tree}/{folder}/` | The source tree beside the selected document, or the selected folder's README |
259
274
  | Multi-panel | `{basePath}/{multi}?doc=…&doc=…&maximized=…&markup=…` | Several documents as panels in columns |
260
275
  | Single | `{basePath}/{single}/{document}` | One document over the whole frame (for reading and embedding) |
261
276
 
262
277
  - `?source=<id>` selects the tree's source among the server's sources; the first source is the default and is written by omission. Switching the source never closes open documents — a document path names one document whichever trees list it.
263
278
  - A document path occupies one URL segment. Build links with `explorerHref(config, target)`, the only function that writes explorer URLs; read them back with `resolveExplorerLocation(config, splat, search)`. Both need the server's source ids for the `source` parameter: pass a configuration joined with them, `withExplorerSources(config, sourceIds)` (`ExplorerLocationConfig`; `isExplorerSourceId` is the id rule, and an empty, invalid or repeated id throws a `RangeError`).
264
279
  `explorerHref` also accepts a plain `ExplorerConfig` with a target without `source` (`ExplorerSourcelessHrefTarget`, the default source), such as a host menu's link; a target with a `source` and a configuration without ids throws a `TypeError` naming `withExplorerSources`, as does `resolveExplorerLocation` with such a configuration.
265
- `explorerHref` throws a `RangeError` for a target the resolver would redirect or partly ignore — repeated or more than `multiView.maxPanels` documents, a maximized document or a document shown as written that is not open, an unknown source or document style, an unsupported alignment or embedding value, a tree view without a document shown as written — so every link it writes resolves back to the location given.
280
+ `explorerHref` throws a `RangeError` for a target the resolver would redirect, read as another location or partly ignore — repeated or more than `multiView.maxPanels` documents, a maximized document or a document shown as written that is not open, an unknown source or document style, an unsupported alignment or embedding value, a tree view with both a document and a folder, a document path that ends in a slash, a tree view with neither a document nor a folder shown as written — so every link it writes resolves back to the location given.
281
+ - A folder of the tree view takes the same segment with a slash after its path: `explorerHref(config, { view: "tree", folder: "guide/concepts" })` writes `/docs/tree/guide%2Fconcepts%2F`, and `ExplorerLocation`'s tree view carries `doc` and `folder`, at most one of them not `null` (see [Folders and their READMEs](#folders-and-their-readmes)). The single view shows documents only and redirects a folder to the tree view.
266
282
  - The single view accepts embedding parameters: `showToc=false`, `showStyle=false`, `showAlign=false`, `padding` (0–256 px, written in decimal digits), `width` and `maxWidth` (a CSS length in px, rem, em, ch, vw or %; the column never grows wider than the pane, whatever the value). The tree and single views accept `style` and `align` as display overrides.
267
283
  - `markup` names the Markdown documents shown as written (the Source toggle): `markup=true` for the tree or single view's document, and one `markup=<document>` per open document shown that way in the multi view, in the order of `doc`. In `ExplorerLocation` it is a boolean in the tree and single views and a list in the multi view; a target without it shows every document rendered.
268
- - History: a click in the tree replaces the URL's document; links inside a document, entries of its table of contents (in the tree and single views, to the heading's hash), source switches and view switches push; every multi-view action and the Source toggle replace (hiding and showing a panel leave the URL unchanged).
284
+ - History: a click in the tree replaces the URL's document or folder; links inside a document, entries of its table of contents (in the tree and single views, to the heading's hash), source switches and view switches push; every multi-view action and the Source toggle replace (hiding and showing a panel leave the URL unchanged).
269
285
  - An entry of a document's table of contents links to its heading's own address: the page's URL with the heading's fragment, or, in a multi-view panel, the panel's document in the tree view with that fragment, so a modified or middle click, a new tab or a copied address opens the heading (see [URL contract](docs/behavior/url-contract.md#table-of-contents)).
270
286
 
271
287
  The full contract, including canonicalization, is in [URL contract](docs/behavior/url-contract.md).
272
288
 
289
+ ### Folders and their READMEs
290
+
291
+ In the tree view a folder can be selected as GitHub's file tree does, and the view then shows the folder's README beside the tree.
292
+
293
+ - **Selecting**: a click (or Enter or Space) on a folder other than the shown one selects it: the URL's document is replaced with the folder (no history entry), its row is selected, and a closed folder opens; an open one stays open. A click on the shown folder opens or closes it, as before, and a double click still opens or closes it with its subfolders. The arrow keys move and open folders without selecting them. In the multi-panel view a click on a folder only opens or closes it.
294
+ - **Which README**: a README is a file whose name, ignoring case, is `README` or starts with `README.` (`README.md`, `readme.txt`, `README.ja.md`); a folder named so is not one. Among a folder's READMEs the view shows a plain name (`README` with at most one extension) before a longer one, then by extension — `md`, `markdown`, `mdx`, `txt`, none, any other —, then by name and path in the explorer's collation (`folderReadmeOf`).
295
+ - **Where the folder's files come from**: the children its row has in the shown source's tree; a lazy folder whose children are unknown, or a folder the loaded tree does not reach, is listed by the data route's `children` operation, as when the reader opens it. A folder the source does not have answers that operation's `not-found` (a source without `children` answers `not-found` for every folder its tree does not list).
296
+ - **What shows**: the README as the shown document — its refresh bar, Source toggle, editing, the switch to the multi-panel view and the selection's panels all act on it —, the skeleton while it is looked for, a line saying the folder has none (`folderReadmeMissing`, announced once per folder), or the listing's failure, announced once per failed attempt, with Try again for a transient one.
297
+ - **First paint**: the page loader seeds no document for a folder, because which README it shows depends on the folder's listing: the server renders the skeleton, and the browser finds the README in the tree (the source's tree seeds the first paint) and loads it.
298
+ - **Revealing**: with the reader's `revealDocument` the tree brings a folder's row into view where it lists it, but never opens the folders down to it: the reveal's ports (`ancestors`, `reveal`) answer for documents.
299
+
273
300
  ## Server API
274
301
 
275
302
  ### `createMarkdownExplorer(config)`
@@ -371,6 +398,8 @@ An answer of those kinds that carries a `url` key, or lacks a valid `version`, b
371
398
  A markdown document says how the reader may edit it in `edit` (`ExplorerDocumentEdit`), which every markdown answer must carry: `null` (no editing), `{ kind: "inline" }` (in the explorer, through the server's `edit` ports; without them the answer breaks the contract), `{ kind: "draft" }` (in the explorer without saving, to try changes in the preview: the ports' `source` and `preview` only, and the same contract) or `{ kind: "external", href }` (the document's own editor, an absolute `https:` URL the bar opens in a new tab).
372
399
  Decide it per document and per reader (see [Editing](#editing)); `createFileSystemSource` answers `null`.
373
400
  A `text` document shows the beginning of a file under the file header (its name, Copy the text — offered only when the whole file was read, so the clipboard never gets part of a file — Open in a new tab, which shows the whole file as UTF-8 plain text, and Download, so a truncated preview can still be fetched whole); a `file` document is a file the explorer cannot show, which every view (single, tree, the multi view's panels) shows as a download view: the file header over a note (the label `fileNotShown`) with a download link.
401
+ A `media` document of type `pdf` opens in a frame, in the browser's own PDF viewer; a browser that says it shows no PDF inside a page (`navigator.pdfViewerEnabled` is `false`, as a phone's Chrome does) gets a note instead (the label `pdfNotShown`) with links to open the PDF in a new tab and to download it, since the frame would stay blank.
402
+ Only the browser can say which, so the server's HTML holds neither, and a browser that cannot show the PDF never starts loading it.
374
403
 
375
404
  A markdown document lists at most `EXPLORER_MAX_HEADINGS` (10,000) headings; one that lists more is answered `too-large`, because every listed heading travels with the document (in the data response, the browser's document cache and the viewer's table of contents, one entry each) and a parser can list headings its HTML never renders (`#` lines inside a math block), so none of the HTML's limits bounds the list. A cache of your parser's results can rely on the same bound.
376
405
 
@@ -383,8 +412,9 @@ Every other link with an `href` reaches the explorer's link component with its `
383
412
  The viewer keeps only its own class tokens and fragment targets of your HTML, whatever the sanitizer kept (see [Security](docs/behavior/security.md#the-viewers-allow-list)): a class token survives when it belongs to the markup below, to footnotes (`footnotes`, `footnote-ref`, `footnote-backref`), to formulas (`math`, `inline`, `display`) or to a code block's language (`language-*`),
384
413
  and an `id` on a heading, on a footnote (`fnref:N` or `fnrefK:N` on a reference's `sup`, `fn:N` on a note's `li`, as goldmark writes them) or in the `user-content-` namespace (remark-gfm's footnote ids, which sit on the reference's link and the note). Write any other fragment target as a heading, a `user-content-…` id or `<a name>`.
385
414
  So a footnote reference keeps its id, the target of its back-reference, and its `aria-describedby`, and a back-reference keeps its `aria-label`, in either markup. A formula is `<span class="math inline">\(…\)</span>`, or `<p><span class="math display">\[…\]</span></p>` for display math, which the viewer sets apart by the `display` token (a formula without it is typeset inline). A task list's `contains-task-list` and `task-list-item` classes are dropped, so its items keep their list markers.
386
- Converters may also write GitHub alerts and Zenn's message and details containers; the sanitizer and the viewer keep their markup as written. An alert is `div.markdown-alert.markdown-alert-{type}` (`note`, `tip`, `important`, `warning` or `caution`) whose first child is `p.markdown-alert-title`, holding the type's Octicon as an inline `svg` (its `class`, `viewBox`, `version`, `width`, `height` and `aria-hidden`, and the `d` of its `path`) and then the title. A message is `aside.message` (with `alert`, `info` or `warning` added for those types) holding `span.message-symbol` (`aria-hidden="true"`) and `div.message-content`; a details is `details.markdown-details` holding its `summary` and `div.markdown-details-content`.
387
- `github-markdown.css` draws the alerts under the GitHub document style and `markdown.css` gives them a baseline under the others, and `message.css` and `details.css` draw the containers (see [Load the styles](#5-load-the-styles)). The demo's parser writes all three, and footnotes, task lists and formulas as the Go converter of `@aiquants/markdown` (goldmark) does.
415
+ Converters may also write GitHub alerts and Zenn's message and details containers; the sanitizer and the viewer keep their markup as written. An alert is `div.markdown-alert.markdown-alert-{type}` (`note`, `tip`, `important`, `warning` or `caution`) whose first child is `p.markdown-alert-title`, holding the type's Octicon as an inline `svg` (its `class`, `viewBox`, `version`, `width`, `height` and `aria-hidden`, and the `d` of its `path`) and then the title.
416
+ A message is `aside.message` (with `alert`, `info` or `warning` added for those types) holding `span.message-symbol` (`aria-hidden="true"`) and `div.message-content`; a details is `details.markdown-details` holding its `summary` and `div.markdown-details-content`.
417
+ `github-markdown.css` draws the alerts under the GitHub document style and the `@aiquants/markdown` sheet (`markdown.standalone.css`, or `markdown.css` in a Tailwind v4 host's build) gives them a baseline under the others, and `message.css` and `details.css` draw the containers (see [Load the styles](#5-load-the-styles)). The demo's parser writes all three, and footnotes, task lists and formulas as the Go converter of `@aiquants/markdown` (goldmark) does.
388
418
  Your parser resolves each link and each image; the rules are in [Document links](docs/behavior/url-contract.md#document-links) and [Document images](docs/behavior/url-contract.md#document-images) (a relative image carries its target's document path in `data-asset-src` and no `src`, and the explorer's sanitizer writes the `src`, the explorer's own asset URL;
389
419
  a missing target gets `data-asset-exists="false"`, which the viewer shows as a labelled placeholder; a relative `src` left as written would resolve against the page URL and load an explorer page instead), and the demo's parser (`demo/app/markdown.server.ts` in the source repository) is a complete example.
390
420
  The deny rules are checked on the document's path only: a parser that expands include directives (such as `<!-- @import "…" -->`) must apply them to every file it reads, or leave such directives unexpanded (`@aiquants/markdown`'s `parseMarkdown` leaves them unexpanded unless `resolveImports` is set, and applies the `deniedPathSegments` you give it, the explorer's rules, to every import, image and link target). The explorer serves the files of documents and embedded images itself (see [Serving files](#serving-files)).
@@ -624,7 +654,8 @@ Spread it into the configuration when your application has no sign-in: it provid
624
654
  A canonical redirect keeps the fragment on a page load (the browser carries it across the loader's HTTP redirect) and on the explorer's own client-side replace (it appends the fragment), so loading `/docs#%E6%A6%82%E8%A6%81` ends on the tree view's URL with the same fragment.
625
655
  A client-side navigation from another of your routes to a non-canonical URL loses its fragment, because React Router builds the redirected location from the loader's `Location` alone: link to the canonical URL that `explorerHref` writes, with the fragment appended. A multi-view URL ignores the hash: a panel's fragment-only link scrolls the panel instead.
626
656
  - In a page view the explorer brings a fragment's element to the start of the pane's own scroller and moves every scroller around it only as far as needed (see [The document region](docs/behavior/layout.md#the-document-region)). Two scrolls it does not own can do more:
627
- React Router's `<ScrollRestoration>` scrolls the element whose id is the URL's hash into view itself — page-wide, aligned to the start of every scroller, the page and your own scroll containers included — on a router navigation that carries a hash to a location it has saved no window offset for (a new history entry: it keys the offsets it saves by the location's key, or by your `getKey`), whenever that element is already in the page (a link to a section of the shown document, or an entry of the document viewer's table of contents, which the explorer follows as such a link). On Back or Forward to an entry it saved an offset for, it restores the window's offset instead, as it does for every entry the browser made itself (a fragment-only link) once it has left one, since React Router gives all of those the key `default`. The browser scrolls to the element itself for a fragment-only link and for the hash of a page it loads, and for a link to `#top` or `#` that names no element it scrolls the page itself to its top (HTML's top of the document is the viewport's).
657
+ React Router's `<ScrollRestoration>` scrolls the element whose id is the URL's hash into view itself — page-wide, aligned to the start of every scroller, the page and your own scroll containers included — on a router navigation that carries a hash to a location it has saved no window offset for (a new history entry: it keys the offsets it saves by the location's key, or by your `getKey`), whenever that element is already in the page (a link to a section of the shown document, or an entry of the document viewer's table of contents, which the explorer follows as such a link).
658
+ On Back or Forward to an entry it saved an offset for, it restores the window's offset instead, as it does for every entry the browser made itself (a fragment-only link) once it has left one, since React Router gives all of those the key `default`. The browser scrolls to the element itself for a fragment-only link and for the hash of a page it loads, and for a link to `#top` or `#` that names no element it scrolls the page itself to its top (HTML's top of the document is the viewport's).
628
659
  They move nothing while the explorer fills a container that does not scroll (with `lockDocumentScroll`, for example); in a page that scrolls around a page view, leave `<ScrollRestoration>` off the explorer's routes if your scrollers must not move.
629
660
  - For crawlers, render with `onAllReady` and `progressiveChunkSize: Number.POSITIVE_INFINITY`: even after every boundary is ready, React writes a boundary larger than 12.8 KB as a hidden segment that a script reveals, so a crawler that runs no script would see only the loading state.
630
661
  - The explorer does not set the page title. React Router runs `meta` again on every navigation with the new `params` and `location`, but the loader data it receives stays that of the first paint (`shouldRevalidateExplorer` keeps the loader from running), so derive the title from `resolveExplorerLocation(withExplorerSources(config, sourceIds), params["*"], new URLSearchParams(location.search))` rather than from the loader data's documents (`sourceIds` from the loader data's `sources`, which a navigation does not change).
@@ -637,7 +668,7 @@ Spread it into the configuration when your application has no sign-in: it provid
637
668
  | --- | --- | --- |
638
669
  | `data` | `ExplorerPageData` | `useLoaderData()` of the page route. |
639
670
  | `config` | `ExplorerConfig` | The shared configuration. |
640
- | `storageNamespace` | `string` | Prefix of the browser storage keys (tree settings, expansion state, the multi-view layout): 1–64 letters, digits, `.`, `_` or `-`, starting with a letter or digit (anything else throws a `RangeError`). |
671
+ | `storageNamespace` | `string` | Prefix of the browser storage keys (tree settings, expansion state, the multi-view layout, the editor's side-by-side setting and share): 1–64 letters, digits, `.`, `_` or `-`, starting with a letter or digit (anything else throws a `RangeError`). |
641
672
  | `locale?` | `"en" \| "ja"` | The UI language (default `"en"`). |
642
673
  | `labels?` | `Partial<MarkdownExplorerLabels>` | Per-key overrides; strings that embed a value are functions, except the multi view's templates for `@aiquants/drag-drop-panels` (`MARKDOWN_EXPLORER_LABEL_TEMPLATES`). |
643
674
  | `theme?` | `"light" \| "dark"` | The colour scheme (default `"light"`). |
@@ -650,17 +681,21 @@ Spread it into the configuration when your application has no sign-in: it provid
650
681
 
651
682
  The explorer fills its container's block size, so the container needs a definite block size: for example `height: 100dvh`, or a flex column of definite height whose item has `flex: 1` and `min-height: 0`. The quick start's `app.css` is such a container.
652
683
  A container whose block size is auto or only a minimum (`html` and `body` at their default auto height included) does not size the explorer: the areas that fill the leftover height collapse to 0 px, or the explorer grows with its content.
653
- With `lockDocumentScroll` the explorer must fill a container of definite block size inside the viewport; while the page is locked it logs one `console.error` per mount when the explorer ends below the viewport or a rendered part collapses (its root, the document region of the tree or single view, or the explorer's tree area is less than 1 px tall). Hidden parts — a closed sheet, a collapsed explorer panel, an explorer the host hides — are not checked.
684
+ With `lockDocumentScroll` the explorer must fill a container of definite block size inside the viewport; while the page is locked it logs one `console.error` per mount when, once the layout has settled (no resize of the explorer's root or the window for one second), the explorer ends below the viewport or a rendered part collapses (its root, the document region of the tree or single view, or the explorer's tree area is less than 1 px tall). The intermediate viewports a resize can pass through — switching Chrome DevTools' device toolbar between a desktop and a phone size does — are not judged.
685
+ Hidden parts — a closed sheet, a collapsed explorer panel, an explorer the host hides — are not checked.
654
686
 
655
687
  #### Tree settings
656
688
 
657
689
  The reader's tree settings are kept in memory for the explorer's lifetime and saved to browser storage under `storageNamespace` when the browser allows it; where it cannot write (blocked site data, a full quota) they last until the explorer unmounts (a navigation away from its route, a reload). The server render and the hydration use the defaults — the package's, with the configuration's `defaultTreeSettings` over them — and the stored settings apply right after the hydration.
658
690
  Storage keeps only the settings the reader changed, each with the value they chose: a later change of `defaultTreeSettings` reaches every setting the reader has left alone, the ones they changed stay as they set them (also when a later default happens to equal their choice), and a setting the reader moves back to the default in force at that moment is dropped from storage, so later defaults reach it again.
659
691
  A stored value of another format version is ignored, so its reader starts from the defaults. A stored `directoriesFirst` (from when "Folders first" was a switch) is read as `folderPlacement`: `true` as `"first"`, `false` as `"mixed"` (a stored `false` exists only where the default was `true`), unless a `folderPlacement` is stored too; the next change the reader makes stores the new key only. Folders: Mixed (the package default) keeps the source's order, or interleaves folders and files by name under a name order;
660
- First puts the folders before the files and Last after them, under any sort order (a descending name order reverses the names, not the placement). Reveal the open document: see [Revealing the open document](#revealing-the-open-document). Selection: Single (the package default) selects the shown document; Multiple gathers clicked documents in a tray that opens them as panels; Off shows no row as selected, not even the shown document.
692
+ First puts the folders before the files and Last after them, under any sort order (a descending name order reverses the names, not the placement).
693
+ README: Mixed (the package default) keeps a folder's READMEs in the sort; First puts them before the folder's other files and Last after them — before or after its folders too while folders mix with the files — under any sort order, and the READMEs keep the sort among themselves (what a README is: [Folders and their READMEs](#folders-and-their-readmes)).
694
+ Reveal the open document: see [Revealing the open document](#revealing-the-open-document). Selection: Single (the package default) selects the shown document or folder; Multiple gathers clicked documents in a tray that opens them as panels; Off shows no row as selected, not even the shown document.
661
695
  The tray shrinks and scrolls before the tree does: the tree keeps at least three rows at any text size, the tray keeps its header row and scrolls the rest, and an explorer too short for both scrolls as a whole. Always expanded shows every folder whose contents are known as expanded; a lazy folder stays collapsed until the reader opens it, so the setting never loads folders by itself.
662
696
 
663
- Call `clearExplorerStorage(storageNamespace)` when a reader signs out of a shared browser (it throws a `RangeError` for a malformed namespace instead of clearing the wrong keys). Import it from `@aiquants/markdown-explorer/storage`: that entry imports nothing (no React, no `@aiquants/markdown`), so a layout or root route that runs on every page can call it without loading the explorer; the root entry exports the same function. The explorer also clears the namespace by itself: on every page load, before anything reads it, when the reader recorded there is not the page's reader, and when a data response reports a different reader.
697
+ Call `clearExplorerStorage(storageNamespace)` when a reader signs out of a shared browser (it throws a `RangeError` for a malformed namespace instead of clearing the wrong keys). Import it from `@aiquants/markdown-explorer/storage`: that entry imports nothing (no React, no `@aiquants/markdown`), so a layout or root route that runs on every page can call it without loading the explorer; the root entry exports the same function.
698
+ The explorer also clears the namespace by itself: on every page load, before anything reads it, when the reader recorded there is not the page's reader, and when a data response reports a different reader.
664
699
 
665
700
  #### Expand all and Collapse all
666
701
 
@@ -687,10 +722,12 @@ A save writes the draft back with the line endings of the file it opened (`\r\n`
687
722
  A save that meets changes saved elsewhere merges them line by line: changes on different lines are saved at once; lines both sides changed differently are written between git-style markers with buttons above each conflict (keep my lines, the saved lines, or both), and Next conflict moves the focus to those buttons. A draft with markers left is not saved.
688
723
  The preview renders the draft as the document would be: on every keystroke with a `draftConverter`, else once the reader pauses typing (SERVER_PREVIEW_DELAY_MS, 610 ms).
689
724
  The view switch shows the editor alone, the two side by side (the preview below the editor on a narrow pane), or the preview alone; Ctrl+E (⌘E on a Mac) switches between the editor and the preview from the editor, the preview or the switch and moves the focus there, and a double-click on a word of the preview shown alone opens the editor at that word.
725
+ Side by side, a handle on the gutter between the two resizes them, as the explorer's handle resizes the explorer: drag it, or focus it and press the arrow keys (10 px, 50 px with Shift); either side keeps at least 1/φ³ (≈ 23.6 %) of the surface, and the reader's share (an even split by default) is kept in browser storage under `storageNamespace`, for beside and below alike.
690
726
  Switching is instant: the hidden pane stays rendered and in step, so the block at the top of the view stays the same; a panel that is not maximized shows one pane at a time and puts the next one at the same place on screen. Where the bar is narrower than two reading columns (a phone), the switch shows its icons alone, keeping its 44 px targets.
691
727
  The two scroll together, both ways: the pane the reader works in (the wheel, a press, a key, the focus, typing) leads — the shown one alone while the other is hidden —, and the other keeps the same blocks at the top of its view, moving on continuously — a block taller on one side, such as an image or a heading, is crossed faster there, never with a jump or a step back — and both reach their tops and their bottoms together.
692
728
  Until its first rendering lands it shows the document's own rendering (the skeleton when the document is not loaded), and afterwards the last rendering stays until the next one lands, so it never flashes empty.
693
729
  Whether the preview shows side by side is the reader's choice, kept in browser storage under `storageNamespace` (default off); otherwise the session shows the editor or the preview, starting with the editor. History lists the revisions, shows the one picked and puts it into the draft, to be saved like any draft.
730
+ The confirmation before an unsaved draft is lost and the revisions are modal dialogs centered over the content pane — the document beside the tree, the single view's document, the multi view's panels or the panel maximized over them — and keep clear of the viewport's edges; they place themselves, so a host's base styles that reset a dialog's margins (Tailwind's preflight) do not move them.
694
731
  A draft session (`source` answered `draft`) shows "Draft, not saved" as its status (`data-aqmx-save="draft"`) and neither Save nor History; Ctrl/⌘+S saves nothing and the announcer says the draft is not saved, and closing a changed draft or leaving its document asks with the draft's words, since its changes are lost.
695
732
  Drafts last while the explorer is mounted, across view switches and remounted panels. A navigation that would take a document with an unsaved draft off the page asks first (the explorer holds the router's one blocker, so render one explorer per router), and leaving the page asks through `beforeunload` while a document is edited.
696
733
 
@@ -742,11 +779,14 @@ export const draftConverter: ExplorerDraftConverter = {
742
779
  }
743
780
  ```
744
781
 
745
- - **The contract.** `convert(draft, signal)` receives the document's path as the explorer names it and the draft's text, and resolves to `{ kind: "preview", htmlContent, headings }` (unsanitized, without existence marks), a failure document (shown over the last rendering, as a failed preview is; more than `EXPLORER_MAX_HEADINGS` headings is `too-large`, as on the server), or `{ kind: "unavailable" }` when the converter cannot run, for which the server renders that draft. It rejects only with the signal's reason once the signal aborted. Any other rejection, or an answer outside the contract, is a bug: the explorer reports it once on the console and treats it as `unavailable`.
782
+ - **The contract.** `convert(draft, signal)` receives the document's path as the explorer names it and the draft's text, and resolves to `{ kind: "preview", htmlContent, headings }` (unsanitized, without existence marks), a failure document (shown over the last rendering, as a failed preview is; more than `EXPLORER_MAX_HEADINGS` headings is `too-large`, as on the server), or `{ kind: "unavailable" }` when the converter cannot run, for which the server renders that draft. It rejects only with the signal's reason once the signal aborted.
783
+ Any other rejection, or an answer outside the contract, is a bug: the explorer reports it once on the console and treats it as `unavailable`.
746
784
  - **Loading ahead.** `prepare()`, when given, is called when the reader is about to see the preview — they point at or focus Edit while the preview shows side by side and fits the pane, or point at or focus the view switch's Preview — so the worker and its WebAssembly (about 0.4 s to start in Chromium) load before the first draft. The explorer may call it many times: return at once and do the work once.
747
785
  - **One draft at a time.** The explorer converts the first draft at once; a draft that arrives while another converts waits, and only the latest waiting draft is converted next (a WebAssembly call cannot be interrupted, so the running one is never aborted). It aborts the signal only when the preview goes away. A rendering is shown without `aria-busy`, through a React transition, so typing goes ahead of it.
748
786
  - **The server's rules.** Each rendering is sanitized in the browser with the allow-list rules the server applies to every document (the same module, on a DOMPurify instance of the preview's own from `isomorphic-dompurify`'s browser build, part of the editing chunk), so the instant preview shows what the saved document will.
749
- - **Which targets exist.** Only the server can tell whether an image or a linked document exists. The preview keeps a table of the marks the server answered (`data-asset-exists`, `data-doc-exists`, or none), seeded from the document's own rendering, and writes the known ones onto every rendering. When a rendering names a target the table does not hold, the preview asks the data route's `preview` operation about the newest draft once the reader has paused for VERIFY_DELAY_MS (987 ms), one request at a time, learns the marks of the answer, remembers every asked target the answer left unmarked (or a failed answer did not reach) as having none, and renders the newest draft again. So the server is asked about a target once, and a draft that adds no new image or link causes no request at all; a missing image the reader just added shows as a broken image until the answer lands, then as the viewer's missing-image placeholder.
787
+ - **Which targets exist.** Only the server can tell whether an image or a linked document exists. The preview keeps a table of the marks the server answered (`data-asset-exists`, `data-doc-exists`, or none), seeded from the document's own rendering, and writes the known ones onto every rendering.
788
+ When a rendering names a target the table does not hold, the preview asks the data route's `preview` operation about the newest draft once the reader has paused for VERIFY_DELAY_MS (987 ms), one request at a time, learns the marks of the answer, remembers every asked target the answer left unmarked (or a failed answer did not reach) as having none, and renders the newest draft again.
789
+ So the server is asked about a target once, and a draft that adds no new image or link causes no request at all; a missing image the reader just added shows as a broken image until the answer lands, then as the viewer's missing-image placeholder.
750
790
  - **The server tier.** Without a converter, and for a draft the converter answers `unavailable` (its WebAssembly could not load, for example), the server renders the draft once the reader has paused for SERVER_PREVIEW_DELAY_MS (610 ms); the last rendering stays on screen marked `aria-busy` meanwhile, and a newer draft aborts the request. The preview names the tier of what it shows in `data-aqmx-preview-tier` (`instant` or `server`).
751
791
  - **Content Security Policy.** A page that sets `script-src` needs `'wasm-unsafe-eval'` in it for the WebAssembly, and `worker-src 'self'` (or a `script-src` covering the worker) for the same-origin worker.
752
792
 
@@ -765,12 +805,15 @@ The labels the layout fills with a value are templates with `{name}` placeholder
765
805
  | Explorer maximum | the golden section 1/φ² ≈ 38.197 % |
766
806
  | Explorer minimum | 13rem (208 px at a 16 px root font size; 16 px is assumed until the browser measures it) |
767
807
  | Narrow frames | below 13rem × φ² the explorer leaves the split and opens as a sheet over the content, from a labelled 44 px toggle |
768
- | Resize handle | a band 24 px wide under a fine pointer and 44 px under a coarse one, around a 5 × 34 px grip |
808
+ | Resize handle | a band 24 px wide under a fine pointer and 44 px under a coarse one, around a 5 × 34 px grip (the explorer's and the editor's); the sides keep the band clear, so it covers neither the tree's scroll bar nor the content's edge |
809
+ | Editor beside the preview | an even split by default; either side keeps at least 1/φ³ ≈ 23.607 % of the surface; two columns from 2 × the reading measure + the handle's band, else the preview below the editor |
810
+ | Dialogs | centered over the visible part of the content pane, at least 21 px (`--aqmx-space-7`) from every edge of the viewport |
769
811
  | Multi-view column minimum | 40ch at 1rem (the multi-column reading measure) |
770
812
  | Multi-view panel height | between the stage height / φ³ and the stage height / φ, except that the panel's scroll area always keeps three lines of 1rem × φ text below the panel's header (where the header wraps that far, the panel is the header plus that floor) |
771
813
  | Spacing, controls, durations | Fibonacci numbers (px written in rem; ms), except the pointer targets: 44 px (2.75rem) for every control under a coarse pointer and for the sheet's toggle and close button, and the resize handle's 24 px under a fine pointer |
814
+ | Text sizes | 13, 16 and 21 px (0.8125, 1 and 1.3125rem) for body text, titles and display text; under a coarse pointer the body text is 16 px (1rem) as well; tree rows are in the body size |
772
815
 
773
- The reader's own explorer width is remembered per view as a percentage, and only after the reader moves the handle: a drag that moved it (once, when it ends) or an arrow key that moved it, never a press that moved nothing or a change of the window. The document's column fills its pane; the viewer's alignment control appears only for a column a single-view embed narrows (`?width=` / `?maxWidth=`). See [Layout](docs/behavior/layout.md).
816
+ The reader's own explorer width is remembered per view as a percentage, and only after the reader moves the handle: a drag that moved it (once, when it ends) or an arrow key that moved it, never a press that moved nothing or a change of the window. The editor's share beside the preview is remembered the same way. The document's column fills its pane; the viewer's alignment control appears only for a column a single-view embed narrows (`?width=` / `?maxWidth=`). See [Layout](docs/behavior/layout.md).
774
817
 
775
818
  ### Scroll bars and the tap-scroll circle
776
819
 
@@ -802,7 +845,8 @@ Every scroller of the explorer that the reader browses gets one pointer scroll b
802
845
  - 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)).
803
846
  - 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.
804
847
  - 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`).
805
- - Editing writes only through the host's `edit` ports, after the deny rules and the same admission as a document. A save and a preview need the custom header `X-Markdown-Explorer: edit` and pass the shared cross-origin check, and their draft is read and checked (media type, `editMaxBytes`, UTF-8 without NUL) before any port is called; a grant's `href` must be root-relative and an external editor's `https:`; the preview is sanitized exactly as a document. A draft the host's browser converter renders (`draftConverter`) is sanitized in the browser with the same allow-list rules before it is shown, and never leaves the browser; only the existence marks come from the server's answers. The host checks in every port that the reader may edit the document, and writes only over the version the draft started from.
848
+ - Editing writes only through the host's `edit` ports, after the deny rules and the same admission as a document. A save and a preview need the custom header `X-Markdown-Explorer: edit` and pass the shared cross-origin check, and their draft is read and checked (media type, `editMaxBytes`, UTF-8 without NUL) before any port is called; a grant's `href` must be root-relative and an external editor's `https:`; the preview is sanitized exactly as a document.
849
+ A draft the host's browser converter renders (`draftConverter`) is sanitized in the browser with the same allow-list rules before it is shown, and never leaves the browser; only the existence marks come from the server's answers. The host checks in every port that the reader may edit the document, and writes only over the version the draft started from.
806
850
  - 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).
807
851
  - 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.
808
852
 
@@ -817,10 +861,12 @@ Tests and host styling may rely on the `data-testid` and `data-aqmx-*` attribute
817
861
  - One explorer per page: the drag-and-drop layout looks up its panels document-wide.
818
862
  - Merges are line-based (node-diff3): changes on adjacent lines, or on the same line, conflict even when they would combine. A panel that is not maximized shows the editor or the preview, never both; maximize it to see them side by side.
819
863
  - The browser applies the server sanitizer's allow-list rules and nesting limit (512 levels, which Chromium's own parser never exceeds), but not its other resource limits (parsed nodes, attributes, worker heap, time): the host's converter bounds a draft's HTML with `maxHtmlBytes` instead. The existence marks of a target the reader just added arrive about a second after they pause, so until then a new image that does not exist shows as a broken image, and a new link to a missing document as an ordinary link.
820
- - A held Enter acts once on every control inside the explorer, those of other packages included (the tree's rows, the panel headers' buttons, the document viewer's toolbar and the controls inside a document), except Zoom in and Zoom out, which keep stepping while a press that began on them is held (see [Held keys](docs/behavior/layout.md#held-keys)): a press that hands the focus to them, such as following a link to an image, does not step them. The repeated keydowns end at the explorer's root, so a keydown listener the host attaches outside the explorer for the bubbling phase does not receive them either.
864
+ - A held Enter acts once on every control inside the explorer, those of other packages included (the tree's rows, the panel headers' buttons, the document viewer's toolbar and the controls inside a document), except Zoom in and Zoom out, which keep stepping while a press that began on them is held (see [Held keys](docs/behavior/layout.md#held-keys)): a press that hands the focus to them, such as following a link to an image, does not step them.
865
+ The repeated keydowns end at the explorer's root, so a keydown listener the host attaches outside the explorer for the bubbling phase does not receive them either.
821
866
  - A loop row (a folder met again among its own ancestors) shows an expand glyph and `aria-expanded="false"` like any closed folder, because `@aiquants/directory-tree` has no row that cannot expand; it never opens. The 4 listings in flight are counted per explorer, not across browser tabs.
822
867
  - Document kinds are the five above; `createFileSystemSource` previews only files with a known text extension or name as text and offers any other file as a `file` document (a download).
823
- - HTML larger than `sanitizer.maxHtmlBytes` (4 MiB), placed deeper than 512 levels while it is parsed, making the parser create more elements than it has characters, more nodes than the worker's heap holds (81,920 elements, attributes and comments by default) or more than 4,096 comments, holding a tag with more than 1,024 attributes (counted before parsing for every `<` or `</` followed by a letter, so text in a script, a comment or an attribute value that looks like such a tag counts too), giving `html` or `body` more than 1,024 attributes through repeated tags, carrying attributes whose characters, counting every copy of a reopened formatting element, exceed `maxHtmlBytes`, sanitizing to HTML longer than four characters per byte of `maxHtmlBytes`, or not sanitized within `sanitizer.deadlineMs` (30 s) shows as `too-large`.
868
+ - HTML larger than `sanitizer.maxHtmlBytes` (4 MiB), placed deeper than 512 levels while it is parsed, making the parser create more elements than it has characters, more nodes than the worker's heap holds (81,920 elements, attributes and comments by default) or more than 4,096 comments, holding a tag with more than 1,024 attributes (counted before parsing for every `<` or `</` followed by a letter, so text in a script, a comment or an attribute value that looks like such a tag counts too), giving `html` or `body` more than 1,024 attributes through repeated tags,
869
+ carrying attributes whose characters, counting every copy of a reopened formatting element, exceed `maxHtmlBytes`, sanitizing to HTML longer than four characters per byte of `maxHtmlBytes`, or not sanitized within `sanitizer.deadlineMs` (30 s) shows as `too-large`.
824
870
  - All anonymous readers share one scope, so they share the admission budget as well as the running share: with `anonymousAccess`, the `jobsPerScope` documents running or waiting are counted for all visitors together, and panels beyond that budget come back `failed` until a reload or "Try again". For a public deployment, set `jobsPerScope` to the number of visitors expected to open a multi view at the same moment times `multiView.maxPanels`; `maxQueuedJobs` then defaults to four times that.
825
871
  - Each sanitizer worker runs with `workerHeapMb` (512 MiB) of old generation and a fixed 32 MiB young generation, about 1.1 GiB for the default two workers. A process-wide `--max-old-space-size` (for example in `NODE_OPTIONS`) overrides the workers' old-generation limit, because V8 gives the flag precedence; the nesting guard's node budget still keeps every document it accepts within about `workerHeapMb`, but the hard stop at the limit no longer applies.
826
872
  - The Top/Bottom buttons of the tree's pointer scroll bar (`@aiquants/virtualscroll`, hidden from assistive technology and kept out of the Tab order because the tree owns keyboard scrolling with its arrow keys, Home and End)