@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/CHANGELOG.md CHANGED
@@ -1,5 +1,139 @@
1
1
  # Changelog
2
2
 
3
+ ## Unreleased
4
+
5
+ ### Changed
6
+
7
+ - **Follows `@aiquants/markdown` 8.0.0 and `@aiquants/drag-drop-panels` 0.11.0.** The viewer's labels gain the ten new
8
+ Mermaid keys in English and Japanese, which the explorer passes to the viewer: the touch menu's name and its four items
9
+ (`viewerMermaidInteractionModeTouch`, `viewerMermaidModeNoneTouch`, `viewerMermaidModeZoomTouch`,
10
+ `viewerMermaidModePanTouch`, `viewerMermaidModeBothTouch`), the four pan buttons (`viewerMermaidPanUp`,
11
+ `viewerMermaidPanDown`, `viewerMermaidPanLeft`, `viewerMermaidPanRight`) and the name of the diagram's frame
12
+ (`viewerMermaidDiagram`); the Japanese catalog writes the viewer's `+` as `+` (`拡大縮小+移動`), in
13
+ `viewerMermaidModeBoth` and `viewerMermaidModeBothShift` too. A host without Tailwind CSS links
14
+ `@aiquants/markdown/styles/markdown.standalone.css` instead of `markdown.css` (the demo does), and a Tailwind v4 host
15
+ imports `markdown.css` in its Tailwind entry without `layer()`, adds
16
+ `@source "../node_modules/@aiquants/markdown/dist/**/*.js";` and declares the `dark` variant the viewer's utilities
17
+ follow, `@custom-variant dark (&:where(.dark, .dark *, [data-theme="dark"], [data-theme="dark"] *));` to match the
18
+ standalone sheet (Tailwind's own is the `prefers-color-scheme` media query), never loading both sheets (see
19
+ [Load the styles](README.md#5-load-the-styles)). The behavior docs and the tests follow drag-drop-panels 0.11.0's
20
+ panel headers: a stage of one column renders only Move up and Move down (Alt + Shift + ← / → announce that the move is
21
+ unavailable), a panel in the normal mode shows no drag-mode toggle where no fine pointer exists, and under a coarse
22
+ pointer the header buttons are 44 px targets on a line of their own below the title, rows 22 px apart and Close 22 px
23
+ from every other button; and a Mermaid diagram that fits its frame takes `touch-action: pan-x pan-y`, so a finger on it
24
+ scrolls the document. The peer floors are `@aiquants/markdown` ^8.0.0 and `@aiquants/drag-drop-panels` ^0.11.0.
25
+
26
+ ### Fixed
27
+
28
+ - **A document no longer raises `ResizeObserver loop completed with undelivered notifications` while a Mermaid diagram
29
+ is drawn.** The scroll bar's store of the scroller's sizes notified React from inside its ResizeObserver callback, so
30
+ React rendered the bar synchronously in the microtasks of the browser's delivery of the observations, and that render
31
+ first ran the page's pending effects and updates — among them the viewer's effect that inserts a diagram's SVG. The
32
+ document's content grew after its observers had been notified, which the browser reports as a loop error (seen
33
+ intermittently on a phone in the single view). The bar now measures resizes of the scroller and its children, and
34
+ changes of its children, on the next animation frame (once however many arrive before it, cancelled when the bar
35
+ unmounts); a `scroll` event still updates it at once.
36
+ - **Switching Chrome DevTools' device toolbar between a desktop and a phone size no longer logs `the explorer collapsed
37
+ to 0px while lockDocumentScroll stops the page from scrolling`.** The check measured the explorer at the instant of
38
+ the mount and of every resize of its root or the window, and reported the first problem for the rest of the mount. A
39
+ resize can pass through intermediate viewports before it ends, and in one shorter than the host's own bars (a 30 px
40
+ one under a 44 px footer, for example) the explorer's root measures 0 px for a moment although its container has a
41
+ definite block size, so a layout that settled at full height left a false report. The explorer is now measured once
42
+ its root and the window have kept their size for one second after the mount or their last resize
43
+ (`PLACEMENT_SETTLE_MILLISECONDS`; every resize starts the wait over, and unmounting cancels it): an overflow or a
44
+ collapse that persists is still reported once per mount, a moment of one is not.
45
+
46
+ ## 0.16.0 (2026-10-22) — folders that show their README, a resizable editor split, and fixes from a phone audit
47
+
48
+ ### Added
49
+
50
+ - **The editor and the preview shown side by side can be resized.** A handle on the gutter between them — the explorer
51
+ split's band, grip, keys and target sizes, a `separator` named by the new label `editViewSplitResize` that controls the
52
+ editor — moves the boundary by dragging or with the arrow keys (10 px, 50 px with Shift), in both orientations; either
53
+ side keeps at least 1/φ³ (≈ 23.6 %) of the surface. The reader's share (an even split by default) is kept in browser
54
+ storage under `storageNamespace` (`<namespace>:edit-split`, cleared by `clearExplorerStorage` like the other keys),
55
+ written only after the reader moved the handle. The editor and the preview stay where they were, so switching views is
56
+ as instant as before. See [The editor's split](docs/behavior/layout.md#the-editors-split).
57
+ - **A folder can be selected in the tree view, which then shows the folder's README, as GitHub's file tree does.** A
58
+ click (or Enter or Space) on a folder other than the shown one selects it — its row is selected, a closed folder
59
+ opens and an open one stays open — and replaces the URL's document with the folder: `explorerHref` takes a tree
60
+ target's new `folder` and writes its path with a slash after it (`/docs/tree/guide%2Fconcepts%2F`), and
61
+ `ExplorerLocation`'s tree view carries `folder` beside `doc`. The view shows the folder's README — a file named
62
+ `README` or `README.*`, ignoring case, the plain names first, then by extension: `md`, `markdown`, `mdx`, `txt`,
63
+ none, any other — as the shown document, the skeleton while it is looked for, a line saying the folder has none (the
64
+ new label `folderReadmeMissing`), or the failure of the folder's listing. A lazy folder, or one the loaded tree does
65
+ not reach, is listed through the `children` operation. See
66
+ [Folders and their READMEs](README.md#folders-and-their-readmes) and the
67
+ [Folder segment](docs/behavior/url-contract.md#folder-segment).
68
+ - **README placement:** a tree setting (`readmePlacement`: `"mixed"` by default, `"first"` or `"last"`; labels
69
+ `settingReadmePlacement`, `readmePlacementMixed`, `readmePlacementFirst`, `readmePlacementLast`) puts a folder's
70
+ READMEs before or after its other files once they are sorted, under any sort order; hosts set it for every reader with
71
+ `defaultTreeSettings`.
72
+ - **DOM hooks:** `data-aqmx-content-pane` marks the content pane (the tree view's document column, the single view's
73
+ frame, the multi view's stage, a maximized panel's frame, a view's loading placeholder);
74
+ `markdown-explorer-edit-split` is the split laid over the editing surface, which carries `data-aqmx-edit-split`
75
+ (`beside` / `stacked`) while side by side; `markdown-explorer-folder-empty` and `markdown-explorer-folder-failure`
76
+ are a folder without a README and the failure of a folder's listing.
77
+
78
+ ### Changed
79
+
80
+ - **A click on a folder in the tree view selects it** (above) instead of only opening or closing it; a click on the
81
+ shown folder still opens or closes it, and the multi-panel view's folders only open and close.
82
+ - **A tree or single view's document path that ends in a slash has no URL any more:** such a segment names a folder.
83
+ `explorerHref` throws a `RangeError` for it, and the single view redirects a folder's segment to the tree view.
84
+ - **Side by side, the editor and the preview sit in two columns from 2 × the reading measure + the handle's band**
85
+ (24 px, 44 px under a coarse pointer), each keeping the measure at an even share; below it the preview sits under the
86
+ editor. The two are parted by a gutter as wide as the band with a hairline at its middle (it was a 1 px hairline), and
87
+ the view switch drops its words below the same width.
88
+ - **Text colours reach WCAG 2.2's enhanced 7:1 contrast** (they reached 4.5:1) against every surface and tint they are
89
+ drawn on, in both colour schemes: in the light scheme `--aqmx-text-muted`, `--aqmx-accent` and the editor's
90
+ `--aqmx-syntax-heading`, `--aqmx-syntax-link`, `--aqmx-syntax-code` and `--aqmx-syntax-mark` are darker; in the dark
91
+ scheme `--aqmx-text-muted`, `--aqmx-accent` and `--aqmx-syntax-heading`, `--aqmx-syntax-link` and `--aqmx-syntax-url`
92
+ are lighter. The multi view's restore buttons, drop placeholders and header icons follow, as they are drawn in
93
+ `--aqmx-accent` and `--aqmx-text-muted`.
94
+ - **Text is larger under a coarse pointer, and the tree's rows are in the body size.** Under a coarse pointer (a phone, a
95
+ tablet) the body text — the explorer's header and tree, the document bar, the sheet's toggle, menus and notes — is
96
+ 16 px (1rem, the reader's root size) instead of 13 px, as the controls grow to 44 px there, and Safari on iOS no longer
97
+ zooms the page into the source switch when it takes focus; titles keep 16 px and stand out by their weight. The tree's
98
+ rows take the body size (13 px under a fine pointer) instead of `@aiquants/directory-tree`'s 12 px.
99
+ - **The sheet's close button sits beside the source switch.** On a frame too narrow for the split, the sheet no longer
100
+ gives its close button a row of its own: the sheet's header overlays the explorer's first line, which leaves the button
101
+ its room at the end, beside the source switch (beside the header's actions when there is one source), and takes its
102
+ 44 px height, so the tree starts a row higher. The button is still the first stop in the sheet and takes the focus
103
+ when the sheet opens. The panel-limit notice spans that band, so on one line it now covers the source switch (a
104
+ focus moving onto the switch ends it).
105
+
106
+ ### Fixed
107
+
108
+ - **The explorer's dialogs no longer sit in the viewport's top-left corner under a host's base styles.** The
109
+ confirmation before unsaved changes are lost and the revisions relied on the user agent's `margin: auto`, which a
110
+ host's reset (Tailwind's preflight) removes; they now place themselves, centered over the visible part of the content
111
+ pane and clear of the viewport's edges, and follow the window, the pane and their own size while open. See
112
+ [Dialogs](docs/behavior/layout.md#dialogs).
113
+ - **A dialog the browser closes on its own opens again.** A platform's close request that a page may not cancel (a back
114
+ gesture) closed the confirmation or the revisions while the explorer still held them open, so they could not open
115
+ again until the explorer remounted; such a close now counts as dismissing the dialog.
116
+ - **Pinching an image zooms the image, not the page.** Two fingers on an image's canvas take the zoom one level up or
117
+ down each time the distance between them grows or shrinks by φ, as Zoom in and Zoom out would, and keep the point
118
+ between them under them; one finger still pans the canvas. See [Layout](docs/behavior/layout.md).
119
+ - **A PDF no longer leaves the pane blank in a browser that shows no PDF inside a page** (a phone's Chrome, where
120
+ `navigator.pdfViewerEnabled` is `false`): a note (the new label `pdfNotShown`) takes the frame's place, with links to
121
+ open the PDF in a new tab and to download it (DOM hooks `markdown-explorer-pdf-not-shown`,
122
+ `markdown-explorer-pdf-not-shown-open` and `markdown-explorer-pdf-not-shown-download`). Only the browser can say which
123
+ it is, so the server's HTML holds neither the frame nor the note, and such a browser no longer starts loading the PDF.
124
+ - **The explorer's resize handle no longer covers the tree's scroll bar or the start of the content.** The handle's band
125
+ lies over the boundary, so the explorer and the content now keep half of it clear on their sides (12 px under a fine
126
+ pointer, 22 px under a coarse one); on a landscape phone the 44 px band covered both.
127
+ - **A multi-view panel keeps the reader's line when the column count changes.** The element at the top of the panel was
128
+ put back as far above the top as it had been, so when its text rewrapped shorter in a wider column the panel showed
129
+ the next paragraph instead; an element that crossed the top now keeps the same share of its height above it (one that
130
+ started below the top keeps its distance). The panel also put the place back before the rebuilt panel had its new
131
+ width, leaving the browser's re-anchoring (which keeps a distance) to finish; it now puts the reader's place back at
132
+ every change of the panel's width (the explorer's handle resizing the columns included).
133
+ - **The README names the peer floors the package declares** (`@aiquants/markdown` ^7.0.0, `@aiquants/resize-panels`
134
+ ^2.2.0, `@aiquants/virtualscroll` ^3.20.0); it named older ones. A unit test now holds the README to the floors the
135
+ package publishes.
136
+
3
137
  ## 0.15.0 (2026-10-21) — an `asset` port that may answer a short-lived URL, and `@aiquants/markdown` 7
4
138
 
5
139
  ### Added
@@ -193,12 +327,14 @@
193
327
 
194
328
  - **Tap-scroll circle on the document**: in the tree and single views, markdown and text documents get a pointer scroll bar with the tree's tap-scroll circle (`@aiquants/virtualscroll`'s `ScrollBar`, one shared circle setting), driving the viewer's native scroller through `@aiquants/markdown`'s `renderScrollBar` seam: the native vertical scrollbar is hidden, the bar is hidden from assistive technology and has no Tab stops, and keyboard, wheel and touch scrolling are unchanged. Multi-view panels have none (the panel's area scrolls).
195
329
  The bar's module loads on first use; if it fails to load (a chunk gone after a redeploy) or the bar throws, the slot stays empty, the document keeps its native scroller and the failure is reported with `console.error`, instead of the error reaching the route.
196
- - **Tap-scroll circle on every scroller that needs one**: the same bar and circle (one shared component) now also drive, in the tree and single views, a zoomed image's canvas (its native horizontal scrollbar stays), a medium's and a file view's stage and the failure view, each laid out with `@aiquants/markdown`'s `HostedScrollArea`; in the multi view, each panel's scroll area, maximized or not (drag-drop-panels' `renderPanelScrollArea`; the bar is exempt from panel drags). The stage gets the same bar without a circle (drag-drop-panels' `renderStageScrollBar`), in 8 px it adds to the inline end of its padding: a circle there would sit on the right-most panel next to that panel's own circle, and a gutter for it would cost the stage a column at common widths. A bar shows only while its content overflows. Inside a panel, the viewer and the image, media, file and failure views keep no bar of their own. Menus, popovers, nested horizontal scrollers and embedded frames (a PDF's included) get no circle.
330
+ - **Tap-scroll circle on every scroller that needs one**: the same bar and circle (one shared component) now also drive, in the tree and single views, a zoomed image's canvas (its native horizontal scrollbar stays), a medium's and a file view's stage and the failure view, each laid out with `@aiquants/markdown`'s `HostedScrollArea`; in the multi view, each panel's scroll area, maximized or not (drag-drop-panels' `renderPanelScrollArea`; the bar is exempt from panel drags).
331
+ The stage gets the same bar without a circle (drag-drop-panels' `renderStageScrollBar`), in 8 px it adds to the inline end of its padding: a circle there would sit on the right-most panel next to that panel's own circle, and a gutter for it would cost the stage a column at common widths. A bar shows only while its content overflows. Inside a panel, the viewer and the image, media, file and failure views keep no bar of their own. Menus, popovers, nested horizontal scrollers and embedded frames (a PDF's included) get no circle.
197
332
  Requires the `@aiquants/markdown` release that exports `HostedScrollArea` and the `@aiquants/drag-drop-panels` release with `renderPanelScrollArea`, `renderStageScrollBar`, `SCROLL_AREA_SELECTOR` and `NO_PANEL_DRAG_ATTRIBUTE`; the peer floors in the README follow those releases.
198
333
 
199
334
  ### Fixed
200
335
 
201
- - **The tree's reveal checks where the row landed**: bringing the open document's row into the tree's view (the shown document, and the `revealDocument` setting, in the tree and multi views) is finished only when the drawn row is measured wholly inside the tree's scroll window; until then it tries again once per frame, and a row already inside is never scrolled. It stops trying after 8 tries in a row that bring the row no nearer, and starts again when the rows or the tree's area change before the row has been seen inside; the reader's input in the tree, the next document and Collapse all still end it.
336
+ - **The tree's reveal checks where the row landed**: bringing the open document's row into the tree's view (the shown document, and the `revealDocument` setting, in the tree and multi views) is finished only when the drawn row is measured wholly inside the tree's scroll window; until then it tries again once per frame, and a row already inside is never scrolled.
337
+ It stops trying after 8 tries in a row that bring the row no nearer, and starts again when the rows or the tree's area change before the row has been seen inside; the reader's input in the tree, the next document and Collapse all still end it.
202
338
  Before, a reveal ended as soon as the tree's `scrollToPath` answered `true`, which says only that the row is in the list, not where the scroll landed: with a source that lists every folder at once (all the folders down to the document open in one render), a host saw the document's row left about 13 rows below the window.
203
339
 
204
340
  ## 0.3.0 (2026-10-08)
@@ -265,7 +401,8 @@ The first release: a Markdown document explorer for React Router 8 framework mod
265
401
  Each source declares a `boundary` (`contains`, pure and synchronous, and an optional storage `confirm` answering `{ inside: false }` or `{ inside: true, readPath }`): its tree and children list only paths inside it, a children request reaches `children(context, path, readPath)` only after the named source's `contains` and `confirm` passed, and a document reaches `document(context, path, readPath)` only when the boundary of at least one source admits it (documents carry no source; a path no source contains is `forbidden` without a host or storage call).
266
402
  The tree refresh reloads the tree and answers it (200, the same body as a tree request); refreshes arriving while a walk runs share one trailing walk that begins after them, every tree carries `loadedAt` (when its walk began), sources and the document port receive `refresh: true` for a refresh and for the document requests it triggers (`X-Markdown-Explorer: refresh`), and `onTreeRefreshed(key)` with `forgetTree(key)` let a multi-process host drop the other processes' copies of a refreshed tree
267
403
  (the hook may return a promise, which the response does not wait for; a throw or that promise's rejection is logged, as is the rejection of a promise a broken `contains` answers).
268
- - **Client half**: `<MarkdownExplorer>` with per-instance stale-while-revalidate stores, streamed first paint, lazily loaded tree and multi-panel views (a single-view page never downloads them), `shouldRevalidateExplorer` for the page route, `clearExplorerStorage` for sign-out (also from the dependency-free entry `@aiquants/markdown-explorer/storage`, for sign-out handlers that run on every page), and `lockDocumentScroll`, which logs one `console.error` per mount when the explorer ends below the viewport or collapses because its container has no definite block size (it measures only rendered parts, so a collapsed explorer panel, a closed sheet or an explorer the host hides is never reported as collapsed).
404
+ - **Client half**: `<MarkdownExplorer>` with per-instance stale-while-revalidate stores, streamed first paint, lazily loaded tree and multi-panel views (a single-view page never downloads them), `shouldRevalidateExplorer` for the page route, `clearExplorerStorage` for sign-out (also from the dependency-free entry `@aiquants/markdown-explorer/storage`, for sign-out handlers that run on every page), and `lockDocumentScroll`,
405
+ which logs one `console.error` per mount when the explorer ends below the viewport or collapses because its container has no definite block size (it measures only rendered parts, so a collapsed explorer panel, a closed sheet or an explorer the host hides is never reported as collapsed).
269
406
  The URL codec in the browser reads the shared configuration joined with the page data's source ids (`withExplorerSources`), so the browser learns the server's runtime sources from the page and no source id is built into the client. `onMathDiagnostics(path, diagnostics)` hands a markdown document's KaTeX diagnostics (`MarkdownMathDiagnostic` of `@aiquants/markdown`) to the host once the document rendered, never to the reader's console, through one stable function (a host passing a new function on every render receives each document's diagnostics once).
270
407
  The tree's **Refresh** (a visible label that is also its accessible name) shows the tree the server's refresh answers, never replacing a tree with one of an earlier `loadedAt` (a seed or background answer that lands meanwhile never discards the reader's refresh; only a later refresh or a reader switch does), and then reads the documents again with the refresh header (each cached document once: the shown ones at once — one still loading as soon as its request settles —, the others when next opened), whether or not the tree reloaded;
271
408
  a reloaded tree is announced (`treeRefreshed`), a failed reload keeps the tree under an alert naming the failure (`treeRefreshFailed`, `markdown-explorer-refresh-failure`), and the other sources' trees are fetched again in the background when the reader switches to them.
@@ -289,8 +426,10 @@ The first release: a Markdown document explorer for React Router 8 framework mod
289
426
  (the host duties name what a document can still reach: credentialed same-origin GET requests through its images, media and frames without the reader's interaction and through its links once followed, and what a state-changing GET must refuse: a speculative request (`Sec-Purpose`) and any destination but a document or a same-origin script's `fetch`); a reader switch seen in a data response reloads the page data once, without cancelling a loader that is running.
290
427
  The scope is a pseudonym (an HMAC of the principal key under `scopeSecret`); the sanitizer runs in worker threads with limits on size, nesting (checked by the sanitizer's own parser, parse5, as it builds the tree: an element placed deeper than 512 levels, or more elements than the input has characters, stops the parse) and time and a byte-bounded cache of outcomes,
291
428
  admits at most `jobsPerScope` documents per reader (by default `multiView.maxPanels` + max(1, `workers` − 1) + 3, never less than `maxPanels`) and `maxQueuedJobs` waiting in all (by default four times `jobsPerScope`, never less than `maxPanels`), never runs one reader on every worker when there are two or more and hands a free worker to the reader running the fewest,
292
- runs each worker in a bounded heap (`workerHeapMb`, a document that exhausts it is `too-large`) and refuses a document whose elements, attributes and comments exceed a node budget derived from the heap and `maxHtmlBytes` (81,920 by default) or that holds more than 4,096 comments (bounding jsdom's quadratic time for comments placed before `<html>` or after `</html>`), refuses before parsing any tag of more than 1,024 attributes (and `html`/`body` collecting more through repeated tags), bounds the attribute characters the parser materializes, copies included, by `maxHtmlBytes`, never answers sanitized HTML longer than four characters per byte of `maxHtmlBytes`, keeps the first outcome remembered for an input, sends a document to a worker only after the worker reports ready (so a crash while sanitizing is always cached as that document's `failed`), and never caches the failure of a worker that could not start,
293
- keeps `data-*` only for the renderer's link, image and footnote contract, removes `data:` URLs everywhere and reduces iframes' `allow` and `referrerpolicy` to safe values; deny rules decode leniently, match every decoding level both whole and split on `\` as well as `/` (a literal `my-credentials\backup.json` is denied like `*credentials*.json`) and cover more credential files by default, every name starting with `.env` (`.envelope.md` included), and the backups and variants of `*.env` files (`*.env.*`, `*.env~*`, `*.env-*`, `*.env_*`, `*.env#*`, documents such as `deploy.env.md` included); the file-system source opens files without following links and checks they are the files it validated;
429
+ runs each worker in a bounded heap (`workerHeapMb`, a document that exhausts it is `too-large`) and refuses a document whose elements, attributes and comments exceed a node budget derived from the heap and `maxHtmlBytes` (81,920 by default) or that holds more than 4,096 comments (bounding jsdom's quadratic time for comments placed before `<html>` or after `</html>`), refuses before parsing any tag of more than 1,024 attributes (and `html`/`body` collecting more through repeated tags), bounds the attribute characters the parser materializes, copies included, by `maxHtmlBytes`,
430
+ never answers sanitized HTML longer than four characters per byte of `maxHtmlBytes`, keeps the first outcome remembered for an input, sends a document to a worker only after the worker reports ready (so a crash while sanitizing is always cached as that document's `failed`), and never caches the failure of a worker that could not start,
431
+ keeps `data-*` only for the renderer's link, image and footnote contract, removes `data:` URLs everywhere and reduces iframes' `allow` and `referrerpolicy` to safe values; deny rules decode leniently, match every decoding level both whole and split on `\` as well as `/` (a literal `my-credentials\backup.json` is denied like `*credentials*.json`) and cover more credential files by default, every name starting with `.env` (`.envelope.md` included), and the backups and variants of `*.env` files (`*.env.*`, `*.env~*`, `*.env-*`, `*.env_*`, `*.env#*`, documents such as `deploy.env.md` included);
432
+ the file-system source opens files without following links and checks they are the files it validated;
294
433
  fixed-position markup stays inside the document pane.
295
434
  The data route refuses a React Router single-fetch request (`<dataPath>/<operation>.data`) with a `not-found` failure before authenticating or calling a source, since React Router would answer it by reading the whole response and dropping every header but `Set-Cookie`.
296
435
  A markdown document listing more than `EXPLORER_MAX_HEADINGS` (10,000, exported) headings is refused as `too-large`: every listed heading travels with the document (the data response, the browser's document cache and the table of contents), and a parser can list headings its HTML never renders.
@@ -298,7 +437,8 @@ The first release: a Markdown document explorer for React Router 8 framework mod
298
437
  the parsed tree kept beside each takes roughly as much again), with at most one walk of a tree at a time per cache key and no tree answered past its time to live (counted from its walk's start: a request after it waits for one new walk); tree and children entries the contract cannot carry (an empty name, a path the browser cannot address) are left out with their subtrees and logged instead of failing the listing;
299
438
  the exported types `ExplorerPageLoaderResult` (named through React Router's public `data()`), `ExplorerLogger`, `ExplorerLogDetail`, `ExplorerOperation`, `ExplorerPathRules`, `HtmlSanitizerOptions`, `FileSystemSkippedEntry` and `FileSystemSkipReason`.
300
439
  `createFileSystemSource` gains `walkConcurrency` (default 8), `cacheScope` (default `"principal"`) and `reportSkipped`, and previews only files with a known text extension or name.
301
- - **Reading**: documents opened again within 55 s are used as they are and older ones revalidated in the background; nothing is fetched while React renders, so a loader value that missed its deadline renders as loading on the server and is fetched by the browser; the work behind a late tree or document keeps running for another `deferredTimeoutMs`, so the browser's data request can join it, and its `signal` then aborts (late notices, never fetched again, at once), because the page request's own signal never aborts after its response has finished; a revalidated tree or document stays on screen and is replaced only by a different value; the tree's Refresh reads documents again instead of dropping them (a shown document stays on screen and is replaced only when it changed); shown documents are never evicted from the cache; a pane never suspends after its first commit (the shown document stays with a progress line and `aria-busy`);
440
+ - **Reading**: documents opened again within 55 s are used as they are and older ones revalidated in the background; nothing is fetched while React renders, so a loader value that missed its deadline renders as loading on the server and is fetched by the browser; the work behind a late tree or document keeps running for another `deferredTimeoutMs`, so the browser's data request can join it, and its `signal` then aborts (late notices, never fetched again, at once), because the page request's own signal never aborts after its response has finished;
441
+ a revalidated tree or document stays on screen and is replaced only by a different value; the tree's Refresh reads documents again instead of dropping them (a shown document stays on screen and is replaced only when it changed); shown documents are never evicted from the cache; a pane never suspends after its first commit (the shown document stays with a progress line and `aria-busy`);
302
442
  tree rows and document links the pointer or the focus rests on for 89 ms are prefetched one request at a time.
303
443
  The default document styles and alignment are `@aiquants/markdown`'s own (`DEFAULT_MARKDOWN_STYLES`, `CONTENT_ALIGNS` and `DEFAULT_CONTENT_ALIGN`, read from its React-free `@aiquants/markdown/viewer-settings`, which the server half loads too), with no copy in the explorer.
304
444
  The document viewer's table of contents makes the explorer's own jump to the heading (`onHeadingSelect`): a closed `details` around it opens, the scroll is instant, the focus moves to the heading so the next Tab continues in its section, and a page view pushes the heading's hash through the router (nothing when the URL already names it), while a panel keeps its URL;
@@ -312,12 +452,24 @@ The first release: a Markdown document explorer for React Router 8 framework mod
312
452
  settled at once under a host's `scroll-behavior: smooth`, and nothing moved and moved back when an element no taller than the scrollport already starts a scroller without scroll padding; one taller than the scrollport is always moved past and back, so a scroll padding is honoured for it too), after opening a closed `details` and showing a `hidden="until-found"` ancestor around the element as the browser does (an element that still has no box does not move its pane's own scroller) — and in a panel the stage then shows the element with the panel's header by the least distance,
313
453
  as it shows the first heading the focus moves to after a link followed in place, so neither stays above the stage's view; a fragment-only link or a table-of-contents entry in a panel opens the panel's document at that section in the tree view in a new tab or a copied address; reading positions are kept per panel and document; a plain wheel over a long panel scrolls the stage while it can move and the panel after that, and Ctrl/⌘ + wheel scrolls the panel; `data-aqmx-visible-columns` sits on the stage; the panel-limit notice is spoken by the announcer only,
314
454
  and inside the open sheet it spans the header with its whole text wrapped around the close button, which stays above it (one line covers exactly the header's band; more lines spill over the top of the sheet's body for its three seconds), without changing the header's size, so no tree row moves while it is shown or when it goes and the focused row stays visible;
315
- panels also move without a drag, with the four move buttons of each panel's header or Alt + Shift + arrow keys (both `@aiquants/drag-drop-panels`'), mapped back like a drop, announced by the layout in the explorer's words and with the focus kept on the control that held it, and a shortcut that cannot move the panel is announced instead of being swallowed; the header's buttons show while the panel is hovered or one of them is focused, and always on a device that cannot hover; touch and pen drag a panel by a long-press on its header outside its buttons, which `@aiquants/drag-drop-panels` runs itself (the stage wires nothing for touch) and reports through the same `onColumnPanelsChange` as the move buttons, so a touch drop is mapped back, written and announced like a move, and the lift and a cancel (`touchcancel`, Escape, leaving the layout, a release where nothing would move) are announced too, while a swipe on a header or a finger on a panel's body only scrolls; a change of the visible column count keeps an image's zoom and returns the focus to the same zoom button, and focus on an element made focusable only temporarily (the heading a followed link focused) returns to that element; Zoom in and Zoom out keep the focus at the zoom limits; a panel's document links carry the router's basename in their `href`.
316
- While a panel is maximized everything of the explorer it covers is inert (the explorer and its handle or the sheet's bar, the other panels, drag-drop-panels' list of hidden panels), so Tab never leaves it for a hidden control; the host's own chrome is the host's to keep uncovered (`--aqdd-maximize-*`, which the demo binds to its header) or make inert while a maximized panel's frame carries `data-aqmx-maximized="true"`; a restore that removes the focused element (the viewer's toolbar or table of contents) hands the focus to the panel's frame; the panel-limit notice sits in the open sheet's header (over it, never in flow, and inside the modal dialog, so presses land on it) and otherwise in the top layer at the stage's corner, above a maximized panel, or in place in browsers without the Popover API (which no longer crash the explorer at the limit), and it ends early when the focus moves onto an element it is painted over (a control painted above it, such as the sheet's close button, keeps it, so closing the sheet with that button moves the notice to the stage's corner); a panel opened or closed from the sheet is announced once the URL it wrote has rendered, so the root's region speaks it after the sheet closes, toggles the router renders as one navigation are all announced, and picking a hidden panel's document closes the sheet like any other pick.
317
- - **Accessibility**: tree rows expose the selection through `aria-selected` (the shown document by default, the gathered documents in Multiple, the open panels in the multi-panel view) and the shown document through `aria-current="page"` (also while documents are gathered), and the tree has its own name (`treeRegion`); the tree is one Tab stop — the row last focused by the keyboard, a press or a script, else the shown document's row — which Tab reaches through `@aiquants/directory-tree`'s stand-in stop while that row is outside the render window, and the shown document's row is brought into the tree's view on load and when a link changes the shown document, without moving the focus; a panel's document region is named after its document, and the panel frame, which receives the focus in the multi view's hand-offs, is a `group` named after its document; the header's links name the view they open ("Open in the tree view", "Open in the multi-panel view"); the document region is not focusable, so the keyboard scrolls the document clicked in; controls and tree rows are one control high (34 px, 44 px under a coarse pointer), the resize handle is a 24 px band (44 px under a coarse pointer), and the header wraps instead of cutting a control off;
318
- the failure callout offers "Try again" only for `failed` and a page reload for `unauthorized`; Reload keeps the focus while the tree reloads (`aria-disabled` and `aria-busy`, never `disabled`), Expand all and Collapse all are `aria-disabled` while unavailable (Expand all also while a press runs, with `aria-busy`), Zoom out is `aria-disabled` while a fitted image with a natural size is already at or below the smallest zoom level (1/φ² ≈ 38.2 %), following the pane's size, an image without a natural size (an SVG whose root has no absolute `width` and `height`) zooms relative to its fitted size, so Zoom in and Zoom out both act from Fit and the level is a percentage of that size, the zoom level is a polite status read when it changes,
319
- removing or clearing gathered documents moves the focus to the next document or the tree instead of dropping it, and a failed folder's Try again moves the focus to the folder's row before the children load again; every failed load of a lazy folder's children (an expansion, a restored expansion, Expand all or a retry that fails again) is announced once through the announcer, naming the folder (`foldersLoadFailedNamed`; folders whose loads fail within one animation frame are named together in one sentence, in the place of the first), and Try again is described by the failure text; the announcer speaks every message posted within one animation frame, in order, joined as separate sentences (`announcementSequence`), never only the last, and starts empty in a new reader's explorer; it speaks through the root's live region, and through a live region inside the sheet while the sheet is open (the modal sheet hides the root's region), without speaking a message twice when the sheet opens or closes; the zoom level (`output`) and failure callouts (`role="alert"`) are live regions of their own; a failed folder's row keeps Try again wholly visible, its focus ring included (drawn inside the button), at any width, text size and language: the failure text gives way first, then the folder's name down to 3em, then Try again's text down to its icon, then the rest of the name, so in the sheet at 320 px with 200 % text, two levels deep, the icon and part of the name stay; a multi-view panel's header keeps its drag-mode toggle, Hide, Maximize and Close buttons inside the panel at a phone width with 200 % text, and its title readable: the buttons wrap below the title when the title would get less than 6em, and the custom drag mode's badge stays beside the title instead of under the buttons;
320
- one guard at the explorer's root ignores every repeated keydown of a held Enter inside the explorer — on the controls it renders and on those other packages render inside it (the tree's rows, the panel headers' buttons, the document viewer's toolbar and its popups, the controls inside a document) — except on controls that opt in with `data-aqmx-key-repeat="allow"` (Zoom in and Zoom out, which keep stepping), and those receive only the repeats of a press that began on them while the focus stays there (a followed link or a Try again that focuses an image's Zoom out does not step it), so one press no longer runs on through the remove button, menu item, menu button, sheet control or tree row that receives the focus, and no toggle or popup flips once per repeat; a held Space toggles a tree row once;
455
+ panels also move without a drag, with the four move buttons of each panel's header or Alt + Shift + arrow keys (both `@aiquants/drag-drop-panels`'), mapped back like a drop, announced by the layout in the explorer's words and with the focus kept on the control that held it, and a shortcut that cannot move the panel is announced instead of being swallowed; the header's buttons show while the panel is hovered or one of them is focused, and always on a device that cannot hover; touch and pen drag a panel by a long-press on its header outside its buttons,
456
+ which `@aiquants/drag-drop-panels` runs itself (the stage wires nothing for touch) and reports through the same `onColumnPanelsChange` as the move buttons, so a touch drop is mapped back, written and announced like a move, and the lift and a cancel (`touchcancel`, Escape, leaving the layout, a release where nothing would move) are announced too, while a swipe on a header or a finger on a panel's body only scrolls; a change of the visible column count keeps an image's zoom and returns the focus to the same zoom button,
457
+ and focus on an element made focusable only temporarily (the heading a followed link focused) returns to that element; Zoom in and Zoom out keep the focus at the zoom limits; a panel's document links carry the router's basename in their `href`.
458
+ While a panel is maximized everything of the explorer it covers is inert (the explorer and its handle or the sheet's bar, the other panels, drag-drop-panels' list of hidden panels), so Tab never leaves it for a hidden control; the host's own chrome is the host's to keep uncovered (`--aqdd-maximize-*`, which the demo binds to its header) or make inert while a maximized panel's frame carries `data-aqmx-maximized="true"`; a restore that removes the focused element (the viewer's toolbar or table of contents) hands the focus to the panel's frame;
459
+ the panel-limit notice sits in the open sheet's header (over it, never in flow, and inside the modal dialog, so presses land on it) and otherwise in the top layer at the stage's corner, above a maximized panel, or in place in browsers without the Popover API (which no longer crash the explorer at the limit), and it ends early when the focus moves onto an element it is painted over (a control painted above it, such as the sheet's close button, keeps it, so closing the sheet with that button moves the notice to the stage's corner);
460
+ a panel opened or closed from the sheet is announced once the URL it wrote has rendered, so the root's region speaks it after the sheet closes, toggles the router renders as one navigation are all announced, and picking a hidden panel's document closes the sheet like any other pick.
461
+ - **Accessibility**: tree rows expose the selection through `aria-selected` (the shown document by default, the gathered documents in Multiple, the open panels in the multi-panel view) and the shown document through `aria-current="page"` (also while documents are gathered), and the tree has its own name (`treeRegion`); the tree is one Tab stop — the row last focused by the keyboard, a press or a script, else the shown document's row — which Tab reaches through `@aiquants/directory-tree`'s stand-in stop while that row is outside the render window,
462
+ and the shown document's row is brought into the tree's view on load and when a link changes the shown document, without moving the focus; a panel's document region is named after its document, and the panel frame, which receives the focus in the multi view's hand-offs, is a `group` named after its document; the header's links name the view they open ("Open in the tree view", "Open in the multi-panel view"); the document region is not focusable, so the keyboard scrolls the document clicked in; controls and tree rows are one control high (34 px, 44 px under a coarse pointer),
463
+ the resize handle is a 24 px band (44 px under a coarse pointer), and the header wraps instead of cutting a control off;
464
+ the failure callout offers "Try again" only for `failed` and a page reload for `unauthorized`;
465
+ Reload keeps the focus while the tree reloads (`aria-disabled` and `aria-busy`, never `disabled`), Expand all and Collapse all are `aria-disabled` while unavailable (Expand all also while a press runs, with `aria-busy`), Zoom out is `aria-disabled` while a fitted image with a natural size is already at or below the smallest zoom level (1/φ² ≈ 38.2 %), following the pane's size, an image without a natural size (an SVG whose root has no absolute `width` and `height`) zooms relative to its fitted size, so Zoom in and Zoom out both act from Fit and the level is a percentage of that size,
466
+ the zoom level is a polite status read when it changes,
467
+ removing or clearing gathered documents moves the focus to the next document or the tree instead of dropping it, and a failed folder's Try again moves the focus to the folder's row before the children load again; every failed load of a lazy folder's children (an expansion, a restored expansion, Expand all or a retry that fails again) is announced once through the announcer, naming the folder (`foldersLoadFailedNamed`; folders whose loads fail within one animation frame are named together in one sentence, in the place of the first), and Try again is described by the failure text;
468
+ the announcer speaks every message posted within one animation frame, in order, joined as separate sentences (`announcementSequence`), never only the last, and starts empty in a new reader's explorer; it speaks through the root's live region, and through a live region inside the sheet while the sheet is open (the modal sheet hides the root's region), without speaking a message twice when the sheet opens or closes; the zoom level (`output`) and failure callouts (`role="alert"`) are live regions of their own; a failed folder's row keeps Try again wholly visible,
469
+ its focus ring included (drawn inside the button), at any width, text size and language: the failure text gives way first, then the folder's name down to 3em, then Try again's text down to its icon, then the rest of the name, so in the sheet at 320 px with 200 % text, two levels deep, the icon and part of the name stay; a multi-view panel's header keeps its drag-mode toggle, Hide, Maximize and Close buttons inside the panel at a phone width with 200 % text, and its title readable: the buttons wrap below the title when the title would get less than 6em,
470
+ and the custom drag mode's badge stays beside the title instead of under the buttons;
471
+ one guard at the explorer's root ignores every repeated keydown of a held Enter inside the explorer — on the controls it renders and on those other packages render inside it (the tree's rows, the panel headers' buttons, the document viewer's toolbar and its popups, the controls inside a document) — except on controls that opt in with `data-aqmx-key-repeat="allow"` (Zoom in and Zoom out, which keep stepping), and those receive only the repeats of a press that began on them while the focus stays there (a followed link or a Try again that focuses an image's Zoom out does not step it),
472
+ so one press no longer runs on through the remove button, menu item, menu button, sheet control or tree row that receives the focus, and no toggle or popup flips once per repeat; a held Space toggles a tree row once;
321
473
  under forced colors the shown, open and gathered rows, checked settings and open toggles are drawn in `Highlight`, focus rings (the resize handle's included) in `Highlight`, unavailable buttons in `GrayText`, and the loading cues that are otherwise only a background stay visible (the progress line in `Highlight`, every loading skeleton — the tree's, the multi stage's and a pane's — in `GrayText`);
322
474
  when a followed link, a back or forward navigation, a successful Try again or a background revalidation that removes the focused element replaces the content that holds the focus, the focus moves into the replacement (its fragment's target, first heading, scroller or first control) instead of falling to the page, and a jump within the shown document (a section link in any view, a page view's link to the hash its URL already has included, or Back and Forward between two of its sections, entries the browser made itself included) moves the focus to the section without scrolling again,
323
475
  also when the browser's own fragment navigation dropped it from the link to the page, so Tab and Shift+Tab continue from there, while focus the reader moved away from the document region — to an element or into a frame outside it, or to the page by pressing outside the region, also after the focus had already fallen to the page or while it was in a frame inside the region —
@@ -326,8 +478,12 @@ The first release: a Markdown document explorer for React Router 8 framework mod
326
478
  and every element of a document keeps the focus ring's extent as its scroll margin, so an element a fragment or the focus brings to a scroller's edge shows its whole ring,
327
479
  as do tree rows (their ring drawn inside the row) and the viewer's toolbar buttons (placed a ring's extent below the clipping edge), every ring reading `--aqmx-focus-ring-width` and `--aqmx-focus-ring-offset`; a link to HTML's top of the document (`#top` in any ASCII case with no element of that id, or the empty `#`) takes a page view or a panel back to the document's start without moving the focus;
328
480
  focus inside a multi-view panel returns to the same element (else the panel's frame) when a change of the visible column count or a move to another column rebuilds the panel; switching views with the header's link or the tray's Open in panels keeps the focus in the explorer (on the new view's link — the sheet's toggle on a narrow frame — or the first panel opened), whether or not the browser fires `focusout` when it removes the focused control; the tree's arrow keys, Home and End keep the focused row in view;
329
- the content stays mounted when the frame crosses the sheet threshold, and focus on the explorer's side moves to the sheet's toggle or back to the tree; the sheet closes only on a press that started on its backdrop, and picks made while gathering documents (Multiple selection) keep it open, so the tray fills without reopening the sheet for each document; the gathered documents and the tree settings (kept in memory, saved to browser storage when it can be written) survive the explorer's move into or out of the sheet (a phone rotated), a tree drawn after the page hydrated starts from the reader's settings instead of drawing the defaults once, and focus on a tree row returns to the same row, as the tree's only Tab stop, when the frame widens past the threshold, also after a round trip (split, sheet, split); the selection tray shrinks and scrolls before the tree, which keeps at least three rows at any text size (WCAG 1.4.4).
330
- an Escape the explorer or the document viewer handles (closing the sheet, the tree settings menu, or the viewer's table of contents, style or alignment menu) is marked handled (`preventDefault()`), which drag-drop-panels honours — also in framework mode, where React's root listener sits on the document —, so in a maximized panel the first Escape closes the menu and keeps the panel maximized and the next one restores it; a document that fails — in every view, multi-view panels included — is announced through the announcer (`documentFailed(name, title)`, spoken from the sheet while it is open, a panel's once the URL it wrote has rendered), once for each failed attempt (a Try again that fails again is announced again, while a document visited again or a panel opened again does not repeat the cached failure it shows until its new fetch settles, nor announces a cached failure no pane showed that opening it fetches again — a prefetch older than 55 s, or any failure after the tree's reload button), and its callout is no alert; a host's `renderTreeFailure` view replaces only the callout, inside the element that keeps the tree failure's hooks; the panel chrome and the stage's spacing are bound to the explorer's tokens through drag-drop-panels' `--aqdd-*` properties, so the headers' icons (3:1), titles and custom drag mode's badge (4.5:1), the restore buttons of the bar of hidden panels (4.5:1, also hovered) and the drop placeholders of a drag (4.5:1 text, also on the target, and a 3:1 dashed border against the stage) follow `theme` rather than a page's `dark` class; a panel's header keeps its title at least 6em wide and wraps the badge and buttons below it instead, every button inside the panel; and the stage scrolls in a `div`, adding no `main` landmark inside a host's own.
481
+ the content stays mounted when the frame crosses the sheet threshold, and focus on the explorer's side moves to the sheet's toggle or back to the tree; the sheet closes only on a press that started on its backdrop, and picks made while gathering documents (Multiple selection) keep it open, so the tray fills without reopening the sheet for each document; the gathered documents and the tree settings (kept in memory, saved to browser storage when it can be written) survive the explorer's move into or out of the sheet (a phone rotated),
482
+ a tree drawn after the page hydrated starts from the reader's settings instead of drawing the defaults once, and focus on a tree row returns to the same row, as the tree's only Tab stop, when the frame widens past the threshold, also after a round trip (split, sheet, split); the selection tray shrinks and scrolls before the tree, which keeps at least three rows at any text size (WCAG 1.4.4).
483
+ an Escape the explorer or the document viewer handles (closing the sheet, the tree settings menu, or the viewer's table of contents, style or alignment menu) is marked handled (`preventDefault()`), which drag-drop-panels honours — also in framework mode, where React's root listener sits on the document —, so in a maximized panel the first Escape closes the menu and keeps the panel maximized and the next one restores it; a document that fails — in every view, multi-view panels included — is announced through the announcer (`documentFailed(name, title)`, spoken from the sheet while it is open,
484
+ a panel's once the URL it wrote has rendered), once for each failed attempt (a Try again that fails again is announced again, while a document visited again or a panel opened again does not repeat the cached failure it shows until its new fetch settles, nor announces a cached failure no pane showed that opening it fetches again — a prefetch older than 55 s, or any failure after the tree's reload button), and its callout is no alert; a host's `renderTreeFailure` view replaces only the callout, inside the element that keeps the tree failure's hooks;
485
+ the panel chrome and the stage's spacing are bound to the explorer's tokens through drag-drop-panels' `--aqdd-*` properties, so the headers' icons (3:1), titles and custom drag mode's badge (4.5:1), the restore buttons of the bar of hidden panels (4.5:1, also hovered) and the drop placeholders of a drag (4.5:1 text, also on the target, and a 3:1 dashed border against the stage) follow `theme` rather than a page's `dark` class; a panel's header keeps its title at least 6em wide and wraps the badge and buttons below it instead, every button inside the panel; and the stage scrolls in a `div`,
486
+ adding no `main` landmark inside a host's own.
331
487
  - **Host guidance**: [Document images](docs/behavior/url-contract.md#document-images) states how a parser emits images (a relative image's document path in `data-asset-src` and no `src`, which the explorer writes; a missing target marked with `data-asset-exists="false"` for the viewer's labelled placeholder; author-written marks stripped; and why a `src` left as written loads an explorer page);
332
488
  the README lists every `!important` declaration a host cannot override, the forced-colors ones included, and the `--aqdd-*` properties the stage binds to the explorer's tokens;
333
489
  the README and [Security](docs/behavior/security.md#what-the-host-must-do) require code run before the data route's functions, and every resource route of the host, to refuse React Router single-fetch requests (`.data`) before authenticating or reading; `isAcceptableDocumentPath` is exported from the server entry with `MAX_DOCUMENT_PATH_LENGTH`;
@@ -342,4 +498,6 @@ The first release: a Markdown document explorer for React Router 8 framework mod
342
498
  The browser accepts the `url` of those documents only root-relative on the page's origin and in visible ASCII.
343
499
  - **Files the explorer cannot show**: the `file` document kind shows, in every view, the file header over a note (the label `fileNotShown`) with a download link; a `text` document carries its file's `url` and shows the file header (Open in a new tab, Download) above its preview. `failureDocument` returns `ExplorerFailureDocument`, exported as a type.
344
500
  `createFileSystemSource` requires `pathPrefix` (`""` for a source over the whole root), refuses unknown option keys, answers a file of an unknown extension (and a text file whose preview holds a NUL) as a `file` document, reports `version` (`<size>-<mtimeNs>`) for every kind but Markdown, and serves every regular file its checks admit through its `asset` port, so its deny rules are the only filter of what downloads; the port opens a file only while it keeps the device, inode, size and modification time the checks saw (`not-found` otherwise).
345
- - **Localization**: English and Japanese catalogs with strict per-key overrides, including every control of the document viewer (`viewer…`: its toolbar, the table of contents, the style and alignment menus and each Mermaid diagram's controls, which carry no `lang` of their own), the tree's row kinds and scroll bar strings passed to `@aiquants/directory-tree` (`treeEntryKindDirectory`, `treeEntryKindFile`, `treeScrollUp`, `treeScrollDown`, `treeScrollToTop`, `treeScrollToBottom`), the tree's name (`treeRegion`), the failed-folders announcement (`foldersLoadFailedNamed`, a list of names in the language's list format), the joining of messages announced together (`announcementSequence`), the hide and show announcements (`panelHidden`, `panelShown`), and every string the multi view's `@aiquants/drag-drop-panels` layout shows, which carry no `lang` of their own: the panel headers' buttons and badge (`panelHide`, `panelMaximize`, `panelRestore`, `panelClose`, `panelSwitchToCustomDrag`, `panelSwitchToNormalDrag`, `panelCustomDragBadge`, `panelMovePreviousColumn`, `panelMoveNextColumn`, `panelMoveUp`, `panelMoveDown`), the move announcements, a touch or pen drag's lift and cancel announcements, the columns' region names (`panelMoved`, `panelMoveUnavailable`, `panelDragStarted`, `panelDragCancelled` and `multiColumnRegion`, templates whose `{name}` placeholders the layout fills, listed in `MARKDOWN_EXPLORER_LABEL_TEMPLATES` and checked when the labels are resolved), the bar of hidden panels and a hidden panel's stand-in (`hiddenPanelsTitle`, `hiddenPanelBadge`, `hiddenPanelNotice`), an empty column (`multiColumnEmpty`) and the drop placeholders (`panelDropHere`).
501
+ - **Localization**: English and Japanese catalogs with strict per-key overrides, including every control of the document viewer (`viewer…`: its toolbar, the table of contents, the style and alignment menus and each Mermaid diagram's controls, which carry no `lang` of their own), the tree's row kinds and scroll bar strings passed to `@aiquants/directory-tree` (`treeEntryKindDirectory`, `treeEntryKindFile`, `treeScrollUp`, `treeScrollDown`, `treeScrollToTop`, `treeScrollToBottom`), the tree's name (`treeRegion`), the failed-folders announcement (`foldersLoadFailedNamed`,
502
+ a list of names in the language's list format), the joining of messages announced together (`announcementSequence`), the hide and show announcements (`panelHidden`, `panelShown`), and every string the multi view's `@aiquants/drag-drop-panels` layout shows, which carry no `lang` of their own: the panel headers' buttons and badge (`panelHide`, `panelMaximize`, `panelRestore`, `panelClose`, `panelSwitchToCustomDrag`, `panelSwitchToNormalDrag`, `panelCustomDragBadge`, `panelMovePreviousColumn`, `panelMoveNextColumn`, `panelMoveUp`, `panelMoveDown`), the move announcements,
503
+ a touch or pen drag's lift and cancel announcements, the columns' region names (`panelMoved`, `panelMoveUnavailable`, `panelDragStarted`, `panelDragCancelled` and `multiColumnRegion`, templates whose `{name}` placeholders the layout fills, listed in `MARKDOWN_EXPLORER_LABEL_TEMPLATES` and checked when the labels are resolved), the bar of hidden panels and a hidden panel's stand-in (`hiddenPanelsTitle`, `hiddenPanelBadge`, `hiddenPanelNotice`), an empty column (`multiColumnEmpty`) and the drop placeholders (`panelDropHere`).