@aiquants/markdown-explorer 0.33.0 → 0.34.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 (57) hide show
  1. package/CHANGELOG.md +280 -0
  2. package/README.md +31 -18
  3. package/dist/{EditSurface-BPqqykro.cjs → EditSurface-CF82jZQg.cjs} +5 -5
  4. package/dist/{EditSurface-CWq35IWQ.js → EditSurface-CqHk2R3k.js} +73 -63
  5. package/dist/ExplorerSplit-D325YGEf.cjs +1 -0
  6. package/dist/ExplorerSplit-DGH9bckm.js +1500 -0
  7. package/dist/MultiLayout-CzR7yJ0m.cjs +1 -0
  8. package/dist/{MultiLayout-DYNGlNy0.js → MultiLayout-kcZyVnvK.js} +176 -176
  9. package/dist/NativeScrollBar-UNed10Na.js +62 -0
  10. package/dist/NativeScrollBar-pUbA4Zq3.cjs +1 -0
  11. package/dist/TreeLayout-BnIU87HX.js +96 -0
  12. package/dist/TreeLayout-DtvIpuOe.cjs +1 -0
  13. package/dist/core/geometry.d.cts +1 -0
  14. package/dist/core/geometry.d.ts +1 -0
  15. package/dist/core/labels.d.cts +10 -0
  16. package/dist/core/labels.d.ts +10 -0
  17. package/dist/core/location.d.cts +2 -0
  18. package/dist/core/location.d.ts +2 -0
  19. package/dist/core/viewSettings.d.cts +2 -0
  20. package/dist/core/viewSettings.d.ts +2 -0
  21. package/dist/{dataRoute-DLhQfdoW.js → dataRoute-D6KiSHIc.js} +20 -20
  22. package/dist/index-BDCbvHDs.cjs +15 -0
  23. package/dist/{index-CO-RgTml.js → index-DR31S_-4.js} +2029 -1929
  24. package/dist/index.cjs +1 -1
  25. package/dist/index.js +17 -17
  26. package/dist/{location-perTmwct.js → location-C44b9H1S.js} +291 -278
  27. package/dist/location-hGLhCCg4.cjs +1 -0
  28. package/dist/{merge-DZI4pkWI.cjs → merge-BziXxZkE.cjs} +1 -1
  29. package/dist/{merge-D7L_pINl.js → merge-C1MWvhCS.js} +1 -1
  30. package/dist/{sanitizePolicy-By0tKOpZ.js → sanitizePolicy-CwvyPpp5.js} +1 -1
  31. package/dist/sanitizeWorker.js +1 -1
  32. package/dist/server.cjs +1 -1
  33. package/dist/server.js +4 -4
  34. package/dist/styles/markdown-explorer.css +1 -1
  35. package/dist/tapScrollCircle-D_BpaLwY.js +14 -0
  36. package/dist/tapScrollCircle-DigcJCsu.cjs +1 -0
  37. package/dist/useSplitPersistence-DCeYbJMx.js +38 -0
  38. package/dist/useSplitPersistence-QGcvyMAa.cjs +1 -0
  39. package/docs/behavior/dom-hooks.md +12 -3
  40. package/docs/behavior/layout.md +64 -16
  41. package/docs/behavior/localization.md +4 -3
  42. package/docs/behavior/security.md +2 -1
  43. package/docs/behavior/url-contract.md +11 -5
  44. package/package.json +11 -11
  45. package/dist/ExplorerSplit-BRY4uy6x.js +0 -1493
  46. package/dist/ExplorerSplit-CQxr6b0v.cjs +0 -1
  47. package/dist/MultiLayout-TXbet9k3.cjs +0 -1
  48. package/dist/NativeScrollBar-BsWdvkHa.js +0 -64
  49. package/dist/NativeScrollBar-UpjxjLlB.cjs +0 -1
  50. package/dist/TreeLayout-BQEgZhz9.js +0 -72
  51. package/dist/TreeLayout-C0O1OGi4.cjs +0 -1
  52. package/dist/index-DSkK8iLE.cjs +0 -15
  53. package/dist/location-BxiJRTyw.cjs +0 -1
  54. package/dist/tapScrollCircle-CRKZremf.js +0 -12
  55. package/dist/tapScrollCircle-Cbf17x8g.cjs +0 -1
  56. package/dist/useSplitPersistence-Du01PHNg.js +0 -42
  57. package/dist/useSplitPersistence-pPmE4GTT.cjs +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,285 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.34.0 (2026-11-06) — The explorer closes to a rail, the tree view's document maximizes over the page, and a touch screen gives the content its whole width
4
+
5
+ ### Breaking
6
+
7
+ - **The peers `@aiquants/virtualscroll`, `@aiquants/directory-tree`, `@aiquants/drag-drop-panels`,
8
+ `@aiquants/spreadsheet` and `@aiquants/markdown` are `^3.24.0`, `^6.1.1`, `^0.14.0`, `^0.20.0` and `^12.3.0`
9
+ (hosts).** The explorer shows a touch screen's tap-scroll circles only while the reader scrolls and draws no arrows
10
+ on its bars there (virtualscroll 3.24.0's `tapScrollCircleOptions.visibility` and `showArrowButtons`), the tables'
11
+ bars included (spreadsheet 0.20.0's `scrollBarControls`, which markdown 12.3.0 passes on as
12
+ `spreadsheetScrollBarControls` and its table block as `scrollBarControls`), starts a tree it rebuilds at the row it showed first
13
+ (directory-tree 6.1.1 applies the expansion from the first render of a mount, so a remembered row inside an open
14
+ folder is in the list the tree starts from), restores the tree view's maximized document by the rule a maximized
15
+ panel follows (drag-drop-panels 0.14.0's `isMaximizeEscape`), and hands the viewer its circle's gutter and its bar's
16
+ slot width as CSS lengths that a media query sets (markdown 12.3.0's `scrollBarGutter` and `scrollBarInlineSize`, and
17
+ `HostedScrollArea`'s `barInlineSize`), the viewer reserving the band its toolbar covers before it measures the
18
+ toolbar where the explorer opts in (`--aqmd-toolbar-reserve-before-measure`). markdown 12.3.0 also moves a code
19
+ block's Copy button into a header row above the code, renders no front matter, keeps a server-highlighted code
20
+ block's lines and height through hydration (the explorer's split changed a context right after hydration, which
21
+ turned every such block into its loading line), and leaves a formula's DOM alone while the document re-renders (the
22
+ editing preview rewrote every formula on each keystroke). Through virtualscroll 3.24.0 the bars also take 3.23.0's
23
+ colours, written with `light-dark()` only, so a browser before Chrome and Edge 123, Firefox 120 and Safari 17.5 draws
24
+ their tracks, arrows and thumbs transparent (the README's browser note says so beside the tree's icons). A host
25
+ updates the six packages together.
26
+ - **The maximize insets are the explorer's own `--aqmx-maximize-*` (hosts).** A maximized multi-view panel covers the
27
+ viewport inside `--aqmx-maximize-top`, `--aqmx-maximize-right`, `--aqmx-maximize-bottom` and `--aqmx-maximize-left`
28
+ (`0px` by default), which the stage hands to drag-drop-panels' `--aqdd-maximize-*` on its own element, and the tree
29
+ view's maximized document covers the page inside the same insets, so one binding serves both views. The stage's
30
+ declaration wins over an `--aqdd-maximize-*` a host sets on an ancestor: a host that bound those binds the `--aqmx-`
31
+ names instead.
32
+ - **`ExplorerLocation`'s tree view carries `maximized: boolean` (hosts).** `resolveExplorerLocation` reads
33
+ `maximized=true` and ignores any other value, as well as the flag on a tree location with neither a document nor a
34
+ folder; a host that builds a tree location itself adds the property. A tree `ExplorerHrefTarget` takes an optional
35
+ `maximized`, for which `explorerHref` writes `maximized=true` after `style` and `align` and before `markup`, and
36
+ throws a `RangeError` for a tree target with neither a document nor a folder.
37
+ - **The explorer takes its inline size from its container (hosts).** The split's frame is an inline-size container
38
+ (`container: aqmx-split-frame / inline-size`), so the stylesheet lays the first paint out from the frame's own width;
39
+ the containment also keeps the explorer from taking its width from its content. A container that shrinks to fit (an
40
+ absolutely positioned or fixed box without a width, `width: fit-content` or `max-content`, a float, an `auto` grid
41
+ track with `justify-content: start`) now sizes the explorer to 0 px instead of its content's width: give such a
42
+ container a width (README, Sizing). Block containers and stretched flex and grid items are unaffected.
43
+
44
+ ### Added
45
+
46
+ - **Closing the explorer (readers).** In the tree and multi-panel views a close button at the end of the explorer's
47
+ first line (`markdown-explorer-split-close`, named by `hideExplorer`, 44 px under every pointer, where the sheet has
48
+ its own), the handle dragged to the split's edge and released there, and the arrow keys pressed past the minimum close
49
+ the explorer. A rail 55 px wide (`markdown-explorer-rail`: a 44 px toggle between 5 px of padding, and a 1 px border)
50
+ then holds its side, and its toggle (`markdown-explorer-rail-toggle`, named by `showExplorer`, with
51
+ `aria-expanded="false"`) opens the explorer again at the width the reader last chose. Focus on the explorer's side
52
+ moves between the close button and the rail's toggle, and between the rail's and the sheet's toggles when the frame
53
+ crosses the sheet threshold; after a view switch from the header's link into a view whose explorer is closed it
54
+ lands on the rail's toggle. The frame's `data-aqmx-explorer-mode` is `rail` while the explorer is closed.
55
+ The tree that opens again starts at the row it showed first, at the same height, as a tree does when the frame
56
+ moves between the split and the sheet: the split keeps that row per source while its tree is away.
57
+ - **The choice is remembered per view (hosts).** `ExplorerViewSettings` has `treeExplorerHidden` and
58
+ `multiExplorerHidden`, written to the display-settings cookie only as `true` and read as `=== true` (a cookie without
59
+ them reads as an open explorer), so the server renders the rail on the first paint. The sheet starts closed whatever
60
+ the choice says.
61
+ - **The tree view's maximized document (readers).** The document's bar ends with Maximize
62
+ (`markdown-explorer-document-maximize`, icon-only, named and titled by `documentMaximize`, and by `documentRestore`
63
+ while the document is maximized, with no pressed state, the same element in every state). A press replaces the URL
64
+ with the same location maximized or restored, keeping the scroll and leaving the fragment behind, reads nothing again,
65
+ and is announced (`documentMaximized(name)`, `documentRestored(name)`). Maximized, the document's column
66
+ (`data-aqmx-maximized="true"`) covers the page, the split's frame carries `data-aqmx-content-covers-page="true"` (as
67
+ it does while a panel is maximized) and the explorer's side underneath is inert. Escape restores the document by the
68
+ rule a maximized panel's Escape follows. A maximized folder covers the page while it looks for its README; a folder
69
+ without one and the empty state cover nothing. The maximize stays through a source switch, the reveal's move of the
70
+ tree, and the document links and table-of-contents entries it follows, which read it at the moment of the click (their
71
+ hrefs never carry it); a pick in the tree and the switches between the views drop it.
72
+ - **One bar on a phone (readers).** Below the sheet threshold, while the tree view shows a document, the sheet's bar
73
+ (`markdown-explorer-sheet-bar`, `data-aqmx-sheet-bar-merged="true"`) lies over the start of the document's bar, which
74
+ takes the sheet's look (`data-aqmx-sheet-bar="merged"`): one 55 px bar instead of two, its labelled buttons showing
75
+ their icons only, their labels kept as their accessible names. Both bars keep their places in the DOM, so the toggle
76
+ stays the same element, first in the Tab order. While the document is maximized the document's bar keeps the look
77
+ without the toggle's lane (`data-aqmx-sheet-bar="covering"`), so nothing below it moves.
78
+ - **Labels for the copy buttons of the code blocks and the display formulas (hosts, readers).** `viewerCodeBlockCopy`
79
+ («Copy the code» / 「コードをコピー」), `viewerCodeBlockCopied` («Copied the code.» / 「コードをコピーしました。」) and
80
+ `viewerCodeBlockCopyFailed` («Could not copy the code.» / 「コードをコピーできませんでした。」) name a code block's
81
+ copy button and announce its outcomes; `viewerDisplayMathCopy` («Copy the formula» / 「数式をコピー」),
82
+ `viewerDisplayMathCopied` («Copied the formula.» / 「数式をコピーしました。」) and `viewerDisplayMathCopyFailed`
83
+ («Could not copy the formula.» / 「数式をコピーできませんでした。」) do so for a display formula's. The viewer receives
84
+ them as its `codeBlock*` and `displayMath*` labels, so the buttons follow the UI language.
85
+
86
+ ### Changed
87
+
88
+ - **A touch screen gives the content its whole width (readers).** Under `(pointer: coarse)` a content scroller's bar
89
+ lies over the scroller's inline end and lets every press but its circle's through to the content, and the scrollers
90
+ keep no gutter for the circle (`--aqmx-tap-circle-gutter-size` on the root, `54px`, and `0px` under a coarse pointer,
91
+ set by a media query, so the server's markup is the same on every device). Every bar, the tree's, the stage's and
92
+ the tables' grids' (a document's tables and a table file's grid) included, leaves out its thumb drag and track click
93
+ there and draws no arrows (virtualscroll 3.24.0's `showArrowButtons`, the track then running the bar's whole length;
94
+ for the tables spreadsheet 0.20.0's `scrollBarControls`), none of them a target for a finger, and every
95
+ tap-scroll circle, the tables' included, shows only while the reader scrolls: from a scroll within 2 s of the reader's
96
+ own press, touch, wheel turn or key, until 2 s after the scroll's last change. The multi-panel view's stage bar lets
97
+ every press through to the stage, so a finger's pan that starts on its strip scrolls the stage; the tree's bar and
98
+ the tables' vertical bars let them through to the box of their scroll pane, which takes them as presses on its rows
99
+ (virtualscroll 3.24.0), so a pan that starts on their strip scrolls the tree or the table's rows, and a table's
100
+ horizontal bar, below its rows, passes them to the browser. The tree's bar keeps its Top and Bottom buttons, and the server's fine-pointer tree bar, whose arrows hydration removes, stays hidden in
101
+ its place until then, so no arrow or circle appears and vanishes. The viewer's toolbar keeps clear of the overlaid
102
+ bar.
103
+ - **Every bar of the explorer is 55 px (readers).** The sheet's bar is one control inset by 5 px on each side with a
104
+ 1 px border, 55 px high (`--aqmx-space-9`; it was 51 px), the rail is as wide, and the document's bar places its
105
+ buttons 5 px from its edges (it was 4 px), where the explorer's first line and its close button sit.
106
+ - **The first paint has the layout the measure settles on (readers, hosts).** The server knows neither the frame's
107
+ width nor the pointer, and the split measures its frame only after the page hydrates; the frame now carries
108
+ `data-aqmx-measured` (`false` until that measure), and meanwhile the stylesheet lays it out from its own width (a
109
+ container query in rem): narrower than 13rem × φ², no explorer, handle or rail, the content the whole width, the tree
110
+ view's document bar in the sheet bar's look with the toggle's lane, and one bar's room above the other frames; wider,
111
+ the explorer at its 13rem floor at least. The handle's band is the stylesheet's (`--aqmx-split-handle-size`: 24 px,
112
+ 44 px under `(pointer: coarse)`), so the sides keep its halves clear from the first paint. Before, a phone showed the
113
+ explorer beside the content until the page hydrated (22 frames, from 115 ms to 716 ms, on a CPU slowed 4×), a tablet
114
+ drew the explorer narrower than its floor, and both moved the content when they hydrated; now the explorer, the rail,
115
+ the content's panel and the document bar keep their places.
116
+ - **The document's text keeps its place when the page hydrates (readers).** The viewer's bar slot is as wide as its bar
117
+ from the server's render on (`--aqmx-scroll-bar-slot-size` on the root: `8px`, and `0px` under a coarse pointer,
118
+ where the bar lies over the text's end; the explorer's own scrollers and the multi-view panels' areas take the same
119
+ slot), and a viewer that is its region's first child opts in to the band its toolbar covers before the toolbar is
120
+ measured (`--aqmd-toolbar-reserve-before-measure: 1` on the viewer's frame), which markdown 12.3.0 reserves where the
121
+ content spans the column. Before, the text moved 50 px down once the toolbar was measured and, under a fine pointer,
122
+ its column narrowed by 8 px when the bars' module arrived. A viewer under a file header (a text file's) or given a
123
+ `width` or `maxWidth` (a single-view embed) reserves nothing before the measure.
124
+ - **Class names (styling only).** `aqmx-sheet-toggle` is `aqmx-explorer-toggle`, `aqmx-sheet-close` is
125
+ `aqmx-explorer-close` and `aqmx-sheet-header` is `aqmx-explorer-chrome`; class names stay internal (see
126
+ [DOM hooks](docs/behavior/dom-hooks.md)).
127
+
128
+ ### Fixed
129
+
130
+ - **Copy the text reports a failed write to the developer, and only its latest press decides the outcome (readers,
131
+ hosts).** The text viewer's copy button dropped the reason a browser gave for refusing the write, and a clipboard
132
+ that throws before it returns its promise threw out of the press, leaving the button and the live region silent; a
133
+ late answer to an earlier press could also replace the outcome of the press after it. A refused or thrown write is
134
+ now a failure, announced and shown as before and logged to the console with its reason (a browser without the
135
+ asynchronous clipboard is a condition of an insecure origin, not an error, and is not logged), and an answer to a
136
+ press a later press replaced shows and announces nothing.
137
+
138
+ ### Tests
139
+
140
+ - `tests/components/explorerSplit.test.tsx`: a drag that holds the explorer panel collapsed keeps it mounted but not
141
+ displayed, and one dragged back before the release does not close it; a drag released at the edge closes the
142
+ explorer to the rail, remembers the choice per view and not the collapsed width; a drag that widens the explorer and
143
+ then closes it through the minimum reopens at the widened width; Shift+ArrowLeft stops at the minimum and keeps the
144
+ explorer open, the next press closes it, and the toggle reopens at the width remembered before; the arrow keys close
145
+ it, and the focus moves between the handle, the rail's toggle and the close button; the first paint follows the
146
+ cookie, per view,
147
+ and the rail is inert while the content covers the page; the sheet ignores the choice, and the focus crosses the
148
+ threshold between the rail's and the sheet's toggles; the frame is `data-aqmx-measured="false"` until its first
149
+ measure, and the split sets no band of its own under either pointer.
150
+ - `tests/components/treeLayout.test.tsx`, `tests/components/folderReadme.test.tsx`: Maximize replaces the URL, covers
151
+ the page, makes the explorer inert, keeps the button and its focus, renames it, announces each press and renders
152
+ nothing anew; a press at an address with a fragment, maximizing or restoring, replaces the URL without it; a
153
+ maximized address covers from the first paint and Escape restores it once, while a handled Escape does not and one
154
+ inside a block's non-modal dialog (an open `dialog`) does; the reveal keeps the maximize and the fragment; a
155
+ maximized lazy folder covers while it loads and an empty one covers nothing.
156
+ - `tests/components/documentLinks.test.tsx`: a maximized tree view's document link and table-of-contents entry carry
157
+ the maximize when followed, and their hrefs do not.
158
+ - `tests/components/explorerSheet.test.tsx`: the sheet's bar and the document's bar are one while a document shows
159
+ (the toggle the same element, its title only while merged), `covering` while the document is maximized with the
160
+ sheet's bar inert, and never on a multi-view panel's bar. `tests/components/singleView.test.tsx`,
161
+ `tests/components/multiLayout.test.tsx`: no Maximize and no sheet look there.
162
+ - `tests/components/viewSwitchFocus.test.tsx`: a view switch into a closed explorer hands the focus to the rail's
163
+ toggle.
164
+ - `tests/components/nativeScrollBar.test.tsx`: the stage's bar is in the content bars' wrapper and has no circle; the
165
+ coarse-pointer circle is the fine one shown while scrolling, and a content bar's starts hidden; a fine bar, content or
166
+ stage, draws both arrows around a 184 px track, and its track press and its thumb drag each move the scroller, while
167
+ a coarse one draws none, its 200 px track holding a 40 px thumb, and neither its track press nor its thumb drag moves
168
+ the scroller (each press on a scroller of its own, so the fine bar's moves show the presses reach the bar); the bars'
169
+ controls are one frozen object per pointer (all three under a fine one, none under a coarse one), and the tree's bar
170
+ takes the same.
171
+ `tests/components/explorerPane.test.tsx`: under a coarse pointer the tree's bar keeps its track and thumb and draws
172
+ no arrows.
173
+ - `tests/components/tableScrollBarWiring.test.tsx` (was `tableCircleWiring.test.tsx`): besides the tables' circle, a
174
+ document's tables (the viewer's `spreadsheetScrollBarControls`) and a CSV or workbook file's grid (its block's
175
+ `scrollBarControls`) get the pointer's bar controls, the frozen object (`scrollBarControlsFor`) the explorer's own bars
176
+ take; the tree's bar spreads the same values into its options.
177
+ - `tests/components/documentScrollAreas.test.tsx`, `tests/components/nativeScrollBar.test.tsx`: every content scroller's
178
+ bar slot, the viewer's in the tree and single views included, is as wide as the pointer's slot token, and the
179
+ viewer's toolbar keeps that length clear at its inline end. `tests/components/documentStreaming.test.tsx`: the
180
+ server's HTML of a delivered document already carries the slot's width, the toolbar's clearance and the full-width
181
+ column's mark. `tests/components/documentStyles.test.tsx`: the viewer that is its region's first child opts in to the
182
+ band before the measure, in a page and in a panel, and still while the next document loads behind the progress line;
183
+ a text file's viewer under its header does not. `tests/components/editPreview.test.tsx`: the editor's preview, handed
184
+ the page viewer's bar, circle gutter and slot width, keeps none of them.
185
+ - `tests/components/documentMarkup.test.tsx`: Copy the text logs a refused write with its reason and no missing
186
+ clipboard, turns a clipboard that throws into an announced failure, and lets a late answer to an earlier press,
187
+ success or failure, show and announce nothing while a late failure is still logged.
188
+ - `tests/unit/location.test.ts`: the tree view's `maximized` is written in its place and read back, other values and
189
+ a tree without a document or a folder are ignored without a redirect, `explorerHref` refuses the latter, the source
190
+ redirect keeps it while the redirects that lose the document do not, and the single view ignores it.
191
+ - `tests/unit/settings.test.ts`: a closed explorer is written only as `true` in the fixed key order and read back,
192
+ `false` is not written, and any other value is dropped.
193
+ - `tests/unit/geometryTokens.test.ts`, `tests/unit/tokens.test.ts`: `EXPLORER_BAR_PIXELS` is 55 px and the sheet's
194
+ bar, the rail and the merged document bar are spaced by it; every toggle and close button is one control at least;
195
+ the scrollers keep the gutter under a fine pointer and overlay the bar under a coarse one, the bar's slot taking the
196
+ bar's width under a fine pointer and none under a coarse one (the slot and the overlay add up to the bar's width under
197
+ both); the document bar's padding;
198
+ forced colors for the toggles and close buttons; the handle's band is `FINE_TARGET_PIXELS` and, under a coarse
199
+ pointer, `COARSE_TARGET_PIXELS`, and 0 without a handle; before the measure the container query's threshold is
200
+ `explorerSheetBelowPixels` in rem, the floor `EXPLORER_MIN_REM`, the explorer, the handle and the rail are hidden
201
+ below the threshold, and the sheet's shape there copies the rules it stands in for.
202
+ - `tests/unit/labels.test.ts`: both catalogs carry the six labels of the copy buttons of the code blocks and the
203
+ display formulas.
204
+ - `tests/support/mediaQueryStandIn.ts`: one `matchMedia` stand-in for the browser-half setup and
205
+ `installLayoutStandIns`.
206
+ - `tests/e2e/explorer-toggle.spec.ts` (real browser, 1280 × 720): the close button sits 5 px from the explorer's top
207
+ and from the end that keeps half the handle's band clear, with the source switch ending at least 5 px before it
208
+ and centred on it; closing leaves a 55 px rail whose 44 px toggle is 5 px from its edges, the content starting at
209
+ its edge, with the focus on the toggle, the choice in the cookie and in the server's markup, kept by a reload and
210
+ per view; the toggle reopens at the same width and hands the focus back to the close button; a drag held at the
211
+ edge and brought back keeps the split, one released there closes it, and Shift+ArrowLeft closes it to the rail;
212
+ in either view, widening the explorer and then dragging it closed reopens it at the widened width, and a reload
213
+ gives the same width; the handle's arrow keys stop at the minimum and close on the next press, the toggle then
214
+ reopening at the width a reload gives; a tree closed and reopened, or moved to the sheet and back, shows the row it
215
+ showed first at the same height; crossing the sheet threshold hands the focus between the rail's toggle and the
216
+ sheet's.
217
+ - `tests/e2e/document-maximize.spec.ts`: Maximize, the last button of the document's bar, replaces the URL, covers
218
+ the page below the demo's header to the window's edges, keeps the same focused button under the restore name,
219
+ announces the document's name, makes the explorer's panel and handle inert (Tab and Shift+Tab never land there and
220
+ still reach the host's header), and Escape restores all of it, from inside a block's toolbar (a non-modal dialog
221
+ the browser does not close on Escape) too, while Escape in a block's fullscreen (a modal dialog) closes only the
222
+ fullscreen and keeps the document maximized; maximizing and then restoring the long document keep its scroller's
223
+ `scrollTop` within 1 px; a maximized address covers in the server's markup, a link followed while maximized opens
224
+ the next document maximized while its href carries no flag, a maximized folder covers with its README; on a phone
225
+ the one 55 px bar keeps its height and the document's place while the sheet's toggle lies inert under the cover.
226
+ - `tests/e2e/touch-layout.spec.ts`: under a coarse pointer at 320, 360, 390 and 430 px the document keeps 16 px on
227
+ both sides and spans the width, its 8 px bar lying over the scroller's end and nothing overflowing; at 390 px the
228
+ bar draws no arrows, the bar and the hidden circle let presses through, a finger's scroll shows the circle, which
229
+ then takes presses, and it hides again `TAP_SCROLL_CIRCLE_HIDE_DELAY_MS` (2 s) after the last scroll, a flick's
230
+ momentum included, and no sooner (both times read on the page's clock); a multi-view panel keeps no gutter, and the
231
+ stage's bar draws no arrows, passes the presses at a quarter, half and three quarters of its length to the stage's
232
+ scroll root, and a finger's pan that starts on it scrolls the stage; the tree's bar, in the phone's sheet, and a
233
+ document's ```` ```spreadsheets ```` table's grid's bar draw no arrows, their thumbs are disabled, a press on their
234
+ strip lands on the box of their scroll pane (not on the track, nor on a row), and a finger's pan that starts there
235
+ scrolls the tree or the table's rows while the document stays where it was; a table whose rows fit its box while its
236
+ columns are wider gives its rows' pane `touch-action: pan-y` (vertical pans stay with the document, horizontal ones
237
+ go to the table) and a table whose rows scroll gives it `none`; a fine pointer at a phone's width keeps
238
+ the 54 px gutter, the bar beside the scroller with its arrows and the circle always shown, and the table's bar its
239
+ arrows and an idle thumb, a click at the same point of its track scrolling the table.
240
+ - `tests/e2e/appearance.spec.ts`: the bars follow the explorer's theme as the page does, not the system's scheme: under
241
+ a dark system scheme a light page's table, document and tree bars stay light, and choosing Dark turns all three
242
+ dark, the three drawing one track and thumb colour under either theme.
243
+ - `tests/e2e/support.ts`: one `cellOf`, `gridReady`, `TABLES_DOCUMENT` and `twoFrames` for the specs that read the
244
+ tables and wait for frames.
245
+ - `tests/e2e/first-paint.spec.ts`: at 390 px (coarse), 768 px (coarse) and 1280 px (fine), the tree view's document,
246
+ its empty state and the multi-panel view, with the explorer open and closed, draw the explorer panel, the rail, the
247
+ content panel and its first child, the document bar, the document's scroll row, the viewer's bar slot, its toolbar
248
+ and the document's first heading in the server's render (a bot's, without JavaScript) where the hydrated, measured
249
+ page draws them (the measured slot as wide as the pointer's bar, the heading below the toolbar's band): out of the
250
+ split at 390 px, the 13rem floor at
251
+ 768 px, the golden share at 1280 px, the rail one bar wide above the threshold. The tree view's document bar keeps
252
+ its inside as well: its row's start padding, its block-end border and its surface are the same in both paints, and
253
+ every button of the first paint is still there once measured, in the same box, its label visually hidden in both
254
+ paints or in neither (the source toggle and the Edit toggle, which hydration adds, are not compared). Read frame by
255
+ frame while the page loads and hydrates, a coarse-pointer tablet never shows the server's tree bar with its arrows
256
+ or its circle, and a document's eight code blocks keep their header rows and their lines in every frame while the
257
+ document never grows shorter: in the complete document a bot receives, all eight keep the server's highlighting in
258
+ every frame; in the document streamed to people, no highlighted block turns back into plain text and all eight end
259
+ highlighted, while a block the server finished after the browser's first frame shows its plain lines in the same
260
+ box until React reveals it (React batches such reveals, 300 ms after the previous one).
261
+ - `tests/e2e/instant-preview.spec.ts`: typing after a display formula and an inline one in the editing preview leaves
262
+ both formulas' MathML roots in the document. `tests/e2e/document-markup.spec.ts`, `editing.spec.ts`,
263
+ `svg-image-source.spec.ts`: the document bar ends with the icon-only Maximize, named and without text, which stays
264
+ while editing. `tests/e2e/expand-all.spec.ts`: the arrow keys close the explorer to the rail, which aborts the tree's
265
+ request in flight, and the focused rail toggle reopens it, which requests again.
266
+ `tests/e2e/scroll-lock-report.spec.ts`: the window resizes while the reader's drag holds the explorer collapsed, and
267
+ the release closes it to the rail.
268
+
269
+ ### Documentation
270
+
271
+ - README: the rail, the maximized document and the touch layout in the overview and the Layout table, the maximize
272
+ insets as `--aqmx-maximize-*` with `data-aqmx-content-covers-page`, the tree view's `maximized` and its history entry,
273
+ and the coarse-pointer scroll bars. `docs/behavior/layout.md`: "Closing the explorer", "The maximized document", the
274
+ merged sheet bar, the insets, the coarse-pointer rhythm, and which pans move a table's columns under a coarse pointer
275
+ (a horizontal pan over the rows does even when every row fits; one that starts on the header or footer rows or on the
276
+ horizontal bar goes to the document). `docs/behavior/url-contract.md`: `maximized` in the tree
277
+ view, its canonical form, history entry and carry, and the display settings' closed explorer.
278
+ `docs/behavior/dom-hooks.md`: the new hooks, `data-aqmx-measured` among them. `docs/behavior/localization.md`:
279
+ `documentMaximized` and `documentRestored`. `docs/behavior/layout.md` and the README's Layout table: the first
280
+ paint before the measure. `docs/behavior/layout.md` and the README's scroll bars: the bar's slot from the first
281
+ paint, and the band the viewer's toolbar covers before the measure.
282
+
3
283
  ## 0.33.0 (2026-11-04) — The tree's lines and expand glyphs lie above opaque row tints, and its colours follow the explorer's theme, on @aiquants/directory-tree 6.0.0
4
284
 
5
285
  ### Breaking
package/README.md CHANGED
@@ -3,7 +3,8 @@
3
3
  A Markdown document explorer for React Router 8 (framework mode): a source tree beside the document you are reading, a multi-panel view for reading several documents side by side, and a full-page view for reading or embedding one document. Storage, authentication and Markdown parsing are yours — the package talks to them through small server ports, so the same explorer browses a folder on disk, a cloud bucket or a document store.
4
4
 
5
5
  - **Three views, one URL contract** — the tree view, the multi-panel view and the single view are addressed by plain URLs (`/docs/tree/<document>`, `/docs/multi?doc=a&doc=b`, `/docs/single/<document>`). `explorerHref` writes only canonical URLs (it refuses a target that would be redirected or partly ignored), and a non-canonical URL is redirected to its canonical form on the server and in the browser alike.
6
- - **Golden-ratio layout** — the explorer takes 1/φ³ of the width in the tree view (the document gets 2φ times the explorer) and 1/φ⁴ in the multi-panel view, may grow to the golden section 1/φ² and never below 13rem (it follows the reader's root font size); on a frame too narrow for that, such as a phone, the explorer opens as a sheet over the content from a labelled toggle; spacing and durations are Fibonacci numbers; multi-view columns never get narrower than the 40-character multi-column reading measure, so text is never scaled down.
6
+ - **Golden-ratio layout** — the explorer takes 1/φ³ of the width in the tree view (the document gets 2φ times the explorer) and 1/φ⁴ in the multi-panel view, may grow to the golden section 1/φ² and never below 13rem (it follows the reader's root font size), and closes to a 55 px rail that opens it again;
7
+ on a frame too narrow for that, such as a phone, the explorer opens as a sheet over the content from a labelled toggle (in the tree view, in one bar with the document's), and a touch screen gives the content its whole width; the tree view's document maximizes over the page as a multi-view panel does; spacing and durations are Fibonacci numbers; multi-view columns never get narrower than the 40-character multi-column reading measure, so text is never scaled down.
7
8
  - **Streaming first paint** — the page loader streams the tree, the open documents and the notices; after that the browser reads through a JSON data route with a stale-while-revalidate cache (a document opened again within 55 s is used as it is; an older one is shown at once and revalidated in the background), so switching documents never reloads the tree. A tree row or document link that the pointer or the keyboard focus rests on for 89 ms is prefetched, one request at a time (a target the reader has left by then is skipped).
8
9
  The explorer's **Refresh tree** button (a visible label, also its accessible name) has the server reload the tree
9
10
  and answers it, then reads the documents again past the host's caches: shown ones in the background
@@ -49,22 +50,24 @@ A single-view (embedding) page never downloads the tree and multi-panel views, w
49
50
 
50
51
  - React 19.2.7 or later and React Router 8 in framework mode (route modules with `loader` / `headers`).
51
52
  - 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)`.
52
- - The peer packages, at these versions or later within the caret ranges the package declares: `@aiquants/markdown` ^12.1.0 (document rendering;
53
- the gutter its scroll container keeps beside the explorer's bar for the tap-scroll circle (`scrollBarGutter`); the Source toggle of a storage SVG image that stands alone in a paragraph, read through `imageSource`, and a Copy that copies the image as a PNG image or its source, the source readable in every display style, a notice in place of a block that cannot render and plain text for a fence in a language it does not know;
53
+ - The peer packages, at these versions or later within the caret ranges the package declares: `@aiquants/markdown` ^12.3.0 (document rendering;
54
+ the gutter its scroll container keeps beside the explorer's bar for the tap-scroll circle (`scrollBarGutter`, given as a custom property that a media query sets), code blocks whose Copy button sits in a header row above the code, and documents whose front matter does not render; the Source toggle of a storage SVG image that stands alone in a paragraph, read through `imageSource`, and a Copy that copies the image as a PNG image or its source, the source readable in every display style, a notice in place of a block that cannot render and plain text for a fence in a language it does not know;
54
55
  the full screen of its tables, Mermaid diagrams and SVG images, which every block marks with the same DOM hook (`data-aqmd-fullscreen`), and `DEFAULT_MARKDOWN_STYLE`, the style a document starts in by default; its components' stylesheet without utilities,
55
- its controls' 44 px targets under every pointer, ```spreadsheets tables — inside list items and quotes too, and in a pane of their own (`layout="fill"`) never fewer than three rows, with the display options `toolbar=`, `zoom=`, `headings=`, `autofit=`, `frame=` and `tapscroll=` (the circle in the look the explorer passes as `spreadsheetTapScrollCircle`, or `tapScrollCircle` on a table file's block),
56
+ its controls' 44 px targets under every pointer, ```spreadsheets tables — inside list items and quotes too, and in a pane of their own (`layout="fill"`) never fewer than three rows, with the display options `toolbar=`, `zoom=`, `headings=`, `autofit=`, `frame=` and `tapscroll=` (the circle in the look the explorer passes as `spreadsheetTapScrollCircle`, or `tapScrollCircle` on a table file's block), the tables' bar controls the explorer passes for the reader's pointer (`spreadsheetScrollBarControls`, or `scrollBarControls` on a table file's block),
56
57
  every row shown when `height` reaches the table's, and boxes no wider than the table — and their write-back through an editor that answers what came of each write (written, changed, a line that would close the fence, unwritable), reads a block's body back and tells them of its other changes,
57
58
  the React-free `@aiquants/markdown/code-blocks` that names the `data-code-meta` the sanitizer keeps on `code`, holds the converter's reading of a fenced block's lines and the table labels with their placeholders,
58
59
  its Mermaid labels and drawings that finish inside the document when a diagram's text changes or it unmounts mid-drawing, 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),
59
- `@aiquants/directory-tree` ^6.0.0 (rows that take paint and text styles only and have no vertical padding, a `removeRootIndent` shift that keeps the root's icon whole, reveals of rows under the scroll bar's buttons, the connector lines and expand glyphs drawn above the rows, its built-in colours from a `light-dark()` palette that follows the explorer's `color-scheme`, and a pending expansion that marks the tree busy without dimming it),
60
- `@aiquants/drag-drop-panels` ^0.13.0 (the panel headers' move menu, named by the explorer's `panelMove`, their overflow menu, named by `panelMoreActions`, which takes the leading buttons a narrow header's row has no room for, their 44 px buttons under every pointer and the header arrangement 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),
61
- `@aiquants/spreadsheet` ^0.19.0 (the grid of those tables — one `role="grid"` with header rows, the content size a box is fitted to, a keyboard move the document follows, a frame around a range that ends where the range does, under a frozen row and in a right-to-left page too, and command chords that type nothing kept from the browser while a cell is being edited,
62
- read-only where it cannot write and named by its block — which markdown loads only for a document that holds one, and the grid of a table file's preview, whose TSV grammar (`@aiquants/spreadsheet/tsv`) reads a TSV file — `iterateTsvPrefixRows` the rows of a file read partway — and whose operation budget (`SPREADSHEET_MAX_OPERATION_CELLS` of `@aiquants/spreadsheet/view`) bounds its table) and `@aiquants/virtualscroll` ^3.22.1 (44 px scroll-to-edge pills and tap-scroll circles, the pills' text at the body step).
60
+ `@aiquants/directory-tree` ^6.1.1 (rows that take paint and text styles only and have no vertical padding, a `removeRootIndent` shift that keeps the root's icon whole, reveals of rows under the scroll bar's buttons, the connector lines and expand glyphs drawn above the rows, its built-in colours from a `light-dark()` palette that follows the explorer's `color-scheme`, a pending expansion that marks the tree busy without dimming it,
61
+ and the expansion applied from the first render of a client mount, by which a tree that mounts again — the explorer reopened, the sheet opened — starts with the row that was at its top),
62
+ `@aiquants/drag-drop-panels` ^0.14.0 (`isMaximizeEscape`, by which Escape restores the tree view's maximized document as it does a maximized panel, the panel headers' move menu, named by the explorer's `panelMove`, their overflow menu, named by `panelMoreActions`, which takes the leading buttons a narrow header's row has no room for, their 44 px buttons under every pointer and the header arrangement 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),
63
+ `@aiquants/spreadsheet` ^0.20.0 (the grid of those tables — one `role="grid"` with header rows, the content size a box is fitted to, a keyboard move the document follows, a frame around a range that ends where the range does, under a frozen row and in a right-to-left page too, command chords that type nothing kept from the browser while a cell is being edited, and bars whose arrow buttons, thumb drag and track click a host can leave out (`scrollBarControls`),
64
+ read-only where it cannot write and named by its block — which markdown loads only for a document that holds one, and the grid of a table file's preview, whose TSV grammar (`@aiquants/spreadsheet/tsv`) reads a TSV file — `iterateTsvPrefixRows` the rows of a file read partway — and whose operation budget (`SPREADSHEET_MAX_OPERATION_CELLS` of `@aiquants/spreadsheet/view`) bounds its table) and `@aiquants/virtualscroll` ^3.24.0 (44 px scroll-to-edge pills and tap-scroll circles, the pills' text at the body step, and under a coarse pointer bars without
65
+ arrows (`showArrowButtons`) whose circles show only while the reader scrolls (`tapScrollCircleOptions.visibility`)).
63
66
  The client depends on these floors, while a package manager may only warn about an older peer.
64
67
  - A Markdown parser of your choice on the server that produces HTML and its headings (the explorer sanitizes the HTML before it is sent).
65
68
  - Browsers: the multi view's panel-limit notice and the panel headers' move menu use 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), and the move menu does not open: Alt + Shift + an arrow moves a panel there.
66
69
  That notice wraps around the sheet's close button with a logical float (`float: inline-end`, Chrome and Edge 118 and later); in browsers without logical floats (before Chrome and Edge 118, the Chromium versions without the Popover API included) a long notice runs partly under the close button.
67
- The tree's type icons take their colours from `@aiquants/directory-tree`'s `light-dark()` palette (Chrome and Edge 123, Firefox 120, Safari 17.5 and later); a browser without `light-dark()` ignores those declarations, and the icons take their row's text colour.
70
+ The tree's type icons take their colours from `@aiquants/directory-tree`'s `light-dark()` palette (Chrome and Edge 123, Firefox 120, Safari 17.5 and later); a browser without `light-dark()` ignores those declarations, and the icons take their row's text colour. The bars of the tree, the document and the tables take their colours from `@aiquants/virtualscroll`'s `light-dark()` palette as well (3.23.0 and later, so every version the explorer accepts): such a browser draws their tracks, arrows and thumbs transparent, and a thumb does not show.
68
71
 
69
72
  ## Installation
70
73
 
@@ -287,8 +290,8 @@ to; load it when your documents contain math.
287
290
  - 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`,
288
291
  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`.
289
292
  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).
290
- - 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.
291
- 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`.
293
+ - A maximized multi-view panel and the tree view's maximized document cover the viewport inside the explorer's maximize insets, `--aqmx-maximize-top`, `--aqmx-maximize-right`, `--aqmx-maximize-bottom` and `--aqmx-maximize-left` (all `0px` by default; the stage hands them to drag-drop-panels' `--aqdd-maximize-*`), so one binding in your layout keeps your own header or menu visible in both views. Everything of the explorer they cover (the explorer and its handle, the rail of a closed explorer or the sheet's bar, and the other panels) is inert until the panel or the document is restored.
294
+ Your own chrome is not: whatever of it they cover stays in the Tab order and in the accessibility tree, so either bind the insets so they leave it uncovered, or make it inert (or `visibility: hidden`) while something is maximized — the maximized panel's frame and the tree view's maximized document column carry `data-aqmx-maximized="true"`, the split's frame carries `data-aqmx-content-covers-page="true"` in both cases (`:has([data-aqmx-content-covers-page="true"])`), and the URL carries `maximized`.
292
295
  - 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.
293
296
 
294
297
  ## Views and URLs
@@ -302,11 +305,13 @@ to; load it when your documents contain math.
302
305
  - `?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.
303
306
  - 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`).
304
307
  `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.
305
- `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.
308
+ `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 maximized or shown as written — so every link it writes resolves back to the location given.
306
309
  - 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.
307
310
  - 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.
308
311
  - `markup` names the Markdown documents, SVG images and table files 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.
309
- - 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).
312
+ - `maximized` says what fills the page: `maximized=true` for the tree view's document or folder README (the Maximize button at the end of the document's bar; see [The maximized document](docs/behavior/layout.md#the-maximized-document)), and `maximized=<document>` for the open document whose panel is maximized in the multi view. In `ExplorerLocation` it is a boolean in the tree view and a document or `null` in the multi view; the single view, whose frame is the page already, has none.
313
+ The tree view's maximize stays through a source switch and the document links and table-of-contents entries it follows (their hrefs never carry it); a pick in the tree and a switch between the views drop it.
314
+ - 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, the Source toggle and the tree view's Maximize replace (hiding and showing a panel leave the URL unchanged).
310
315
  - 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)).
311
316
 
312
317
  The full contract, including canonicalization, is in [URL contract](docs/behavior/url-contract.md).
@@ -515,7 +520,7 @@ The single view has no tree.
515
520
  - **When the tree may move**: only for a change of the open document (load, a link in a document, Back and Forward, opening or maximizing a panel), once per change.
516
521
  - It never moves for a document the reader opened from the tree (by click, Enter or Space), for the document that was open while the reader picked a source by hand, or again for a document it already moved for. The explorer remembers that document across remounts of the tree and the pane, until another document is settled.
517
522
  - Such a document is asked of the shown source alone, through the `ancestors` operation (`GET <dataPath>/ancestors?source=<shown source>&path=<document>`), so a source the reader picked is never left by itself and costs no search of the others.
518
- It stops at the reader's next input in the tree (a press, a wheel, a touch, a key or a focus), at the next document or source, at Collapse all, when the explorer is hidden during the reveal (closing the sheet, collapsing the explorer panel), when a folder's listing fails, or when every folder of the chain has loaded and the row is not there — so it waits for at most one listing per folder. A chain deeper than `revealDocument.maxDepth` (16 by default) opens nothing: the server answers `null` for it.
523
+ It stops at the reader's next input in the tree (a press, a wheel, a touch, a key or a focus), at the next document or source, at Collapse all, when the explorer is hidden during the reveal (closing the sheet or the explorer, a drag holding the explorer panel collapsed), when a folder's listing fails, or when every folder of the chain has loaded and the row is not there — so it waits for at most one listing per folder. A chain deeper than `revealDocument.maxDepth` (16 by default) opens nothing: the server answers `null` for it.
519
524
  - **Stored state**: the folders a reveal opens are part of the reader's remembered expansion for that source, exactly as if the reader had opened them, so a reload shows them open and the reader closes them as any other folder.
520
525
  - **The port**: `ExplorerSource.ancestors?(context, path, readPath, options): Promise<readonly string[] | null>` answers the folder row paths from the source's top level down to the document's direct parent, exactly as that source's `tree` and `children` name them (`[]` for a document at the top level), or `null` when the document is not in this source or cannot be revealed there (for example a document reached only through a shortcut, whose row has the shortcut's path).
521
526
  It is called only for a document path inside the source's boundary that passed the deny rules, with the confirmed `readPath` (see [Source boundaries](#source-boundaries)). Without it, the source's documents are not revealed in it: the `ancestors` operation answers `not-found` for the source, and the `reveal` operation passes it over without calling any of its ports (a source that only lists, such as an entry point onto what others shared, reveals its documents through a source that answers them).
@@ -759,6 +764,7 @@ Spread it into the configuration when your application has no sign-in: it provid
759
764
 
760
765
  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.
761
766
  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.
767
+ The explorer takes its inline size from its container too, never from its content: the split's frame is a size container in the inline axis (it lays itself out from its own width, from the first paint), so a container that shrinks to fit its content — an absolutely positioned or fixed box without a width, `width: fit-content` or `max-content`, a float, an `auto` grid track with `justify-content: start` — sizes the explorer to 0 px. Give such a container a width; a block container and a stretched flex or grid item already have one.
762
768
  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.
763
769
  Hidden parts — a closed sheet, a collapsed explorer panel, an explorer the host hides — are not checked.
764
770
 
@@ -892,8 +898,10 @@ The labels the layout, a table or an SVG image fills with a value are templates
892
898
  | Explorer default, tree view | 1/φ³ ≈ 23.607 % of the split (the document is 2φ times the explorer) |
893
899
  | Explorer default, multi-panel view | 1/φ⁴ ≈ 14.590 % |
894
900
  | Explorer maximum | the golden section 1/φ² ≈ 38.197 % |
895
- | Explorer minimum | 13rem (208 px at a 16 px root font size; 16 px is assumed until the browser measures it) |
896
- | Narrow frames | below 13rem × φ² the explorer leaves the split and opens as a sheet over the content, from a labelled 44 px toggle |
901
+ | Explorer minimum | 13rem (208 px at a 16 px root font size), which the stylesheet keeps from the first paint |
902
+ | Closed explorer | a rail 55 px wide (a 44 px toggle between 5 px of padding, and a 1 px border); the close button, a drag released at the split's edge or the arrow keys past the minimum close it, and the choice is remembered per view |
903
+ | Narrow frames | below 13rem × φ² the explorer leaves the split (from the first paint, before the page hydrates) and opens as a sheet over the content, from a labelled 44 px toggle in a bar 55 px high, which is one bar with the document's while the tree view shows a document |
904
+ | Maximized document | the tree view's document column covers the page inside the maximize insets, as a maximized multi-view panel does |
897
905
  | 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 |
898
906
  | 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 |
899
907
  | Dialogs | centered over the visible part of the content pane, at least 21 px (`--aqmx-space-7`) from every edge of the viewport |
@@ -919,10 +927,15 @@ Every scroller of the explorer that the reader browses gets one pointer scroll b
919
927
  - A circle is one control wide (44 px) and sits 49 px before its bar, at the middle of the scroller's height. It scrolls the same with a Mermaid diagram or an embedded frame at its height, and a drag that starts on it selects no text.
920
928
  - The tables' grids take the same look and speeds (`TABLE_TAP_SCROLL_CIRCLE`): a table file's preview shows the grid's circle one control wide where the grid places it (toward the bottom-right quarter of its box), once the table scrolls on either axis, and a document's ```` ```spreadsheets ```` table shows one, 24 px across from markdown 11.8.2 (WCAG 2.5.8's minimum target), only where its options say `tapscroll=1` (`@aiquants/markdown`'s `spreadsheetTapScrollCircle`).
921
929
  The look loads with the bars' circle module on first use, as the bars do, so a single-view page's static part stays without `@aiquants/virtualscroll`; a circle drawn before it arrives shows it once it has.
922
- - Every document scroller with a circle (the viewer's scroller, the image, medium, file and failure views, and each multi-view panel's scroll area) keeps a 54 px gutter at its inline end, outside its own padding: the circle with 5 px on each side.
930
+ - Under a fine pointer every document scroller with a circle (the viewer's scroller, the image, medium, file and failure views, and each multi-view panel's scroll area) keeps a 54 px gutter at its inline end, outside its own padding: the circle with 5 px on each side.
923
931
  So no content (a diagram's or a table's toolbar, a code block's copy button, a focused link) lies under the circle at any scroll position; only an image zoomed wider than its canvas passes beneath it while it pans sideways. The wheel and touch scroll over the gutter as over the rest of the document.
924
932
  The gutter is kept while the content fits as well, so the text never re-wraps when the bar appears. For the viewer the explorer passes it as `@aiquants/markdown`'s `scrollBarGutter`. The tree's rows reach under the tree's circle, which has no gutter.
925
- - The stage's bar has no circle: 49 px before the stage's bar a circle would cover the right-most panel's own bar and circle, and a gutter that holds it (54 px more of the stage's inline-end padding) would cost the stage a column (4 to 3 at a 1920 px window, 3 to 2 at 1440 px). The stage keeps its thumb, track and arrows, the plain wheel (which the panels hand to the stage), touch and the keyboard.
933
+ - The stage's bar has no circle: 49 px before the stage's bar a circle would cover the right-most panel's own bar and circle, and a gutter that holds it (54 px more of the stage's inline-end padding) would cost the stage a column (4 to 3 at a 1920 px window, 3 to 2 at 1440 px). The stage keeps its thumb, track and arrows (under a fine pointer), the plain wheel (which the panels hand to the stage), touch and the keyboard.
934
+ - Under a coarse pointer (a touch screen, `(pointer: coarse)`) the content takes the scroller's whole width: a document scroller's bar lies over its inline end and lets every press but its circle's through to the content, the scrollers keep no gutter, and every bar, the tree's, the stage's and the tables' grids' (a document's ```spreadsheets tables and a table file's grid)
935
+ included, leaves out its thumb drag and track click and draws no arrows (its track runs the bar's whole length), none of them a target for a finger: one setting for every bar, so a table's bars behave as the page's. The other bars let every press through as well, so a finger's pan that starts on a bar's strip scrolls what the bar scrolls: the stage's bar passes it to the stage, and the tree's bar and the tables' vertical bars to the box of their scroll pane, which takes it as a press on its rows; a table's horizontal bar lies below its rows, outside their pane, and passes it to the browser.
936
+ The circles, the tables' included, show only while the reader scrolls — from a scroll that follows the reader's own press, touch, wheel turn or key within 2 s, until 2 s after the scroll's last change — and take no presses while hidden; the tree's bar keeps its Top and Bottom buttons. The stylesheet follows the media query itself, so the first paint already lays the content out this way. The server cannot know the pointer and draws the tree's bar for a fine one, with its arrows and an always-shown circle; under a coarse pointer the stylesheet keeps
937
+ that bar hidden, in its place, until hydration draws it without them, so no arrow or circle appears and vanishes.
938
+ - Each content scroller's bar has its slot's width from the first paint — 8 px under a fine pointer, none under a coarse one (`--aqmx-scroll-bar-slot-size`, set by the same media query) — although the bars' module loads after the page, so the text never narrows when a bar appears. The explorer passes it to the viewer as `@aiquants/markdown`'s `scrollBarInlineSize` and to its own scrollers and a multi-view panel's area as `HostedScrollArea`'s `barInlineSize`.
926
939
  - Each bar drives its scroller's native scrolling, of which only the vertical scrollbar is hidden: a zoomed image keeps its native horizontal scrollbar, and the wheel, the keyboard, touch, find in page, fragments and the table of contents, the reading position a panel keeps, Ctrl/⌘ + wheel over a panel, and the browser's scroll anchoring work as without it, with the bar following each of them. The viewer's toolbar keeps clear of the document's bar.
927
940
  - In a multi-view panel the document follows its content's height and the panel's scroll area scrolls, so the panel's viewer, image, medium, file and failure views have no bar of their own; the panel's bar is exempt from panel drags (`data-aqdd-no-panel-drag`). The stage's bar is not shown while a panel is maximized.
928
941
  - Menus and popovers (the tree settings, the table of contents, the toolbars), the scrollers nested in a document (code blocks, tables, inline math) and embedded frames, a PDF's included, keep their native scrollbars and get no circle.