@aiquants/markdown-explorer 0.34.0 → 0.36.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 (146) hide show
  1. package/CHANGELOG.md +608 -0
  2. package/README.md +121 -41
  3. package/dist/EditSurface-B70iRFkG.cjs +6 -0
  4. package/dist/EditSurface-BCFJRyIM.js +990 -0
  5. package/dist/ExplorerSplit-BNrHrIus.cjs +2 -0
  6. package/dist/ExplorerSplit-Bgccz2nm.js +1589 -0
  7. package/dist/MultiLayout-Bo9LAXiY.cjs +1 -0
  8. package/dist/{MultiLayout-kcZyVnvK.js → MultiLayout-Dy5TIC2t.js} +249 -248
  9. package/dist/{NativeScrollBar-pUbA4Zq3.cjs → NativeScrollBar-Bj-LKej0.cjs} +1 -1
  10. package/dist/{NativeScrollBar-UNed10Na.js → NativeScrollBar-DpZMYhmf.js} +2 -2
  11. package/dist/TreeLayout-DsSKW_Qj.js +103 -0
  12. package/dist/TreeLayout-T8sc_wg7.cjs +1 -0
  13. package/dist/client/MarkdownExplorer.d.cts +14 -1
  14. package/dist/client/MarkdownExplorer.d.ts +14 -1
  15. package/dist/client/edit/lineEndings.d.cts +4 -0
  16. package/dist/client/edit/lineEndings.d.ts +4 -0
  17. package/dist/client/hostContract.d.cts +67 -0
  18. package/dist/client/hostContract.d.ts +67 -0
  19. package/dist/core/config.d.cts +13 -0
  20. package/dist/core/config.d.ts +13 -0
  21. package/dist/core/contracts.d.cts +31 -4
  22. package/dist/core/contracts.d.ts +31 -4
  23. package/dist/core/dataRoute.d.cts +5 -1
  24. package/dist/core/dataRoute.d.ts +5 -1
  25. package/dist/core/documentId.d.cts +6 -0
  26. package/dist/core/documentId.d.ts +6 -0
  27. package/dist/core/draftAnswer.d.cts +23 -0
  28. package/dist/core/draftAnswer.d.ts +23 -0
  29. package/dist/core/labels.d.cts +78 -0
  30. package/dist/core/labels.d.ts +78 -0
  31. package/dist/core/location.d.cts +22 -2
  32. package/dist/core/location.d.ts +22 -2
  33. package/dist/core/ownUrls.d.cts +15 -0
  34. package/dist/core/ownUrls.d.ts +15 -0
  35. package/dist/core/treeSettings.d.cts +3 -2
  36. package/dist/core/treeSettings.d.ts +3 -2
  37. package/dist/core/viewSettings.d.cts +3 -1
  38. package/dist/core/viewSettings.d.ts +3 -1
  39. package/dist/describeValue-CLlVRO8d.js +17 -0
  40. package/dist/describeValue-Ccvhbt36.cjs +1 -0
  41. package/dist/explorerCore-B3RGmMG6.js +1083 -0
  42. package/dist/explorerCore-CUkyKtm8.cjs +1 -0
  43. package/dist/index-D0l_BJqb.js +5980 -0
  44. package/dist/index-lpL7GltU.cjs +18 -0
  45. package/dist/index.cjs +1 -1
  46. package/dist/index.d.cts +8 -4
  47. package/dist/index.d.ts +8 -4
  48. package/dist/index.js +53 -43
  49. package/dist/licenses/@heroicons/react/LICENSE +21 -0
  50. package/dist/licenses/entities/LICENSE +11 -0
  51. package/dist/licenses/parse5/LICENSE +19 -0
  52. package/dist/location-Dh6K-y7w.js +761 -0
  53. package/dist/location-DrOP6t1F.cjs +1 -0
  54. package/dist/lru-DC8GBmkX.js +39 -0
  55. package/dist/lru-SGmUyBQU.cjs +1 -0
  56. package/dist/{merge-C1MWvhCS.js → merge-BwcqBd4c.js} +1 -1
  57. package/dist/{merge-BziXxZkE.cjs → merge-Dckw7r9T.cjs} +1 -1
  58. package/dist/nestingGuardWorker.js +5511 -0
  59. package/dist/ownUrls-BTPGNhBt.cjs +1 -0
  60. package/dist/ownUrls-DD0cSCsF.js +409 -0
  61. package/dist/sanitizeJob-BYqzjFJC.js +21 -0
  62. package/dist/sanitizeJob-CudE1RUP.cjs +1 -0
  63. package/dist/sanitizePolicy-C-ehd0J_.cjs +2 -0
  64. package/dist/sanitizePolicy-DAPnUUVm.js +139 -0
  65. package/dist/sanitizeWorker.cjs +1 -1
  66. package/dist/sanitizeWorker.js +134 -139
  67. package/dist/sanitizerService-B8v4ap9t.js +240 -0
  68. package/dist/sanitizerService-DomN7lwC.cjs +1 -0
  69. package/dist/server/assetResponse.d.cts +60 -0
  70. package/dist/server/assetResponse.d.ts +60 -0
  71. package/dist/server/browser/browserPlatform.d.cts +12 -0
  72. package/dist/server/browser/browserPlatform.d.ts +12 -0
  73. package/dist/server/createMarkdownExplorer.d.cts +0 -10
  74. package/dist/server/createMarkdownExplorer.d.ts +0 -10
  75. package/dist/server/errors.d.cts +1 -1
  76. package/dist/server/errors.d.ts +1 -1
  77. package/dist/server/explorerCore.d.cts +12 -0
  78. package/dist/server/explorerCore.d.ts +12 -0
  79. package/dist/server/fileSystemSource.d.cts +1 -0
  80. package/dist/server/fileSystemSource.d.ts +1 -0
  81. package/dist/server/inProcessFetch.d.cts +5 -0
  82. package/dist/server/inProcessFetch.d.ts +5 -0
  83. package/dist/server/platform.d.cts +18 -0
  84. package/dist/server/platform.d.ts +18 -0
  85. package/dist/server/ports.d.cts +55 -5
  86. package/dist/server/ports.d.ts +55 -5
  87. package/dist/server/sanitizeProtocol.d.cts +3 -0
  88. package/dist/server/sanitizeProtocol.d.ts +3 -0
  89. package/dist/server/sanitizer.d.cts +5 -40
  90. package/dist/server/sanitizer.d.ts +5 -40
  91. package/dist/server/sanitizerOptions.d.cts +24 -0
  92. package/dist/server/sanitizerOptions.d.ts +24 -0
  93. package/dist/server/sanitizerService.d.cts +41 -0
  94. package/dist/server/sanitizerService.d.ts +41 -0
  95. package/dist/server/{workerPool.d.cts → workerJobs.d.cts} +0 -16
  96. package/dist/server/{workerPool.d.ts → workerJobs.d.ts} +0 -16
  97. package/dist/server.cjs +1 -1
  98. package/dist/server.d.cts +3 -1
  99. package/dist/server.d.ts +3 -1
  100. package/dist/server.js +270 -1343
  101. package/dist/serverBrowser.cjs +1 -0
  102. package/dist/serverBrowser.d.cts +1 -0
  103. package/dist/serverBrowser.d.ts +1 -0
  104. package/dist/serverBrowser.js +120 -0
  105. package/dist/serverCore.cjs +1 -0
  106. package/dist/serverCore.d.cts +14 -0
  107. package/dist/serverCore.d.ts +14 -0
  108. package/dist/serverCore.js +46 -0
  109. package/dist/storage-BpYsprog.cjs +1 -0
  110. package/dist/{storage-CmGHg7OA.js → storage-D1uSw-xj.js} +19 -18
  111. package/dist/storage.cjs +1 -1
  112. package/dist/storage.js +1 -1
  113. package/dist/styles/markdown-explorer.css +1 -1
  114. package/dist/{tapScrollCircle-DigcJCsu.cjs → tapScrollCircle-DyLInGck.cjs} +1 -1
  115. package/dist/{tapScrollCircle-D_BpaLwY.js → tapScrollCircle-smKLgRa2.js} +1 -1
  116. package/dist/testing.cjs +1 -0
  117. package/dist/testing.d.cts +11 -0
  118. package/dist/testing.d.ts +11 -0
  119. package/dist/testing.js +82 -0
  120. package/dist/useSplitPersistence-BUa_KMsV.cjs +1 -0
  121. package/dist/useSplitPersistence-pnb21dsr.js +44 -0
  122. package/docs/behavior/dom-hooks.md +5 -1
  123. package/docs/behavior/hosting.md +123 -0
  124. package/docs/behavior/layout.md +5 -3
  125. package/docs/behavior/localization.md +25 -8
  126. package/docs/behavior/security.md +55 -15
  127. package/docs/behavior/url-contract.md +30 -3
  128. package/package.json +48 -10
  129. package/dist/EditSurface-CF82jZQg.cjs +0 -6
  130. package/dist/EditSurface-CqHk2R3k.js +0 -982
  131. package/dist/ExplorerSplit-D325YGEf.cjs +0 -1
  132. package/dist/ExplorerSplit-DGH9bckm.js +0 -1500
  133. package/dist/MultiLayout-CzR7yJ0m.cjs +0 -1
  134. package/dist/TreeLayout-BnIU87HX.js +0 -96
  135. package/dist/TreeLayout-DtvIpuOe.cjs +0 -1
  136. package/dist/dataRoute-D6KiSHIc.js +0 -298
  137. package/dist/dataRoute-DwYtgyt6.cjs +0 -1
  138. package/dist/index-BDCbvHDs.cjs +0 -15
  139. package/dist/index-DR31S_-4.js +0 -5012
  140. package/dist/location-C44b9H1S.js +0 -676
  141. package/dist/location-hGLhCCg4.cjs +0 -1
  142. package/dist/sanitizePolicy-CwvyPpp5.js +0 -98
  143. package/dist/sanitizePolicy-T5T-3vV5.cjs +0 -1
  144. package/dist/storage-DM0EvkVf.cjs +0 -1
  145. package/dist/useSplitPersistence-DCeYbJMx.js +0 -38
  146. package/dist/useSplitPersistence-QGcvyMAa.cjs +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,613 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.36.0 (2026-11-12) — Document IDs: a permalink that keeps opening its document when the document's path changes
4
+
5
+ ### Breaking
6
+
7
+ - **Two exported types gain what document IDs add (hosts, types only).** `ExplorerLocationResult` (what
8
+ `resolveExplorerLocation` answers) has a third kind, `{ kind: "document-id", id, opens, location }`, which the
9
+ resolver answers only with `documentIds` in the configuration: a host that switches over `kind` exhaustively needs a
10
+ case for it (its `location` is the one to draw meanwhile). `ExplorerPageData` carries a required `documentId`, `null`
11
+ on every page but an ID URL's that does not open (the explorer's loader writes it): a host that builds page data
12
+ itself, for its own tests for example, adds `documentId: null`. Without `documentIds` nothing changes at run time.
13
+
14
+ ### Added
15
+
16
+ - **Document IDs and their URLs (hosts, readers).** With `documentIds: { slug }` in `defineExplorerConfig`,
17
+ `{basePath}/{slug}/{ID}` opens the document an ID names in the tree view and `{basePath}/{slug}/{ID}/{views.single}`
18
+ in the single view, with the URL's `style` and `align` and, in the single view, its embedding parameters. The slug
19
+ follows the view slugs' rule and differs from every view slug and from `dataPath`'s first segment under `basePath`;
20
+ without the option it stays an unknown view slug.
21
+ The page loader answers an ID the reader can open with a `302` to the document's path URL, under the source that
22
+ admits it, with `Cache-Control: private, no-store` (never `301` or `308`, which a browser keeps while the path an ID
23
+ names changes when its document moves), and any other ID with the page of the default source's tree,
24
+ `documentId: { id, failure }` in the page data and the failure's status (`invalid` 400 for an ID written wrong,
25
+ `not-found` 404, `forbidden` 403, `failed` 500), never naming the path. A navigation inside the explorer to an ID URL
26
+ shows the document's skeleton, resolves the ID through the data route's new `resolve-id` operation and replaces the
27
+ URL with the path URL, keeping its fragment; a failure shows in the document's place
28
+ (`markdown-explorer-document-id-failure`, with `data-aqmx-failure`), with Try again for `failed` only.
29
+ - **The ID (hosts).** 12 symbols of Crockford's Base32: 11 random symbols the server draws from Web Crypto and a mod-37
30
+ check symbol, kept inside the alphabet by drawing again a body whose remainder is 32 or more. `DOCUMENT_ID_ALPHABET`,
31
+ `DOCUMENT_ID_LENGTH`, `isCanonicalDocumentId` (the canonical form), `parseDocumentId` (a reader's writing: hyphens,
32
+ lowercase, `I`, `L` and `O`; a character outside ASCII is refused before any case is raised) and `groupDocumentId`
33
+ (`7K3M-9QX2-AB4W`) are exported from `.`; `explorerHref` writes an ID URL from
34
+ `{ view: "document-id", id, opens?, overrides?, embed? }`, and `ExplorerDocumentIdOpening` names how the document
35
+ opens. `documentIdVectors()` and `DocumentIdVector` of `./testing` list the answers `parseDocumentId` owes, for a
36
+ host's registry and for an implementation of the rule in another language.
37
+ - **Copy permalink (readers).** With `documentIds`, the bar of a document that is not edited offers Copy permalink after
38
+ Refresh document, from the server's render on and unavailable (`aria-disabled`) while the document loads or failed,
39
+ so the bar's buttons keep their places: a press asks the new `issue-id` operation for the document's ID
40
+ (issued on the first press, the same ID ever after) and copies its ID URL, absolute and with the router's basename,
41
+ in the form of the current view (the single view's with its overrides and embedding parameters, the tree view's with
42
+ its overrides, a multi-view panel's as the tree view's). The write starts inside the press, as Safari requires, with
43
+ a `ClipboardItem` whose text the ID URL fulfils, and the outcome is announced and shown as the other copies' are,
44
+ with the ID grouped or with why nothing was copied (`markdown-explorer-document-permalink`,
45
+ `data-aqmx-copy-outcome`). New labels, in English and Japanese: `copyPermalink`, `copyPermalinkLabel`,
46
+ `copyPermalinkNamed`, `permalinkCopied`, `permalinkCopyFailed`, `permalinkClipboardRefused`,
47
+ `documentIdFailedTitle`, `documentIdInvalid`, `documentIdNotFound` and `documentIdForbidden`.
48
+ - **The registry of document IDs (hosts).** `createMarkdownExplorer` takes `documentIds`
49
+ (`ExplorerDocumentIdPorts`) exactly when the configuration has `documentIds` (either alone throws a `TypeError`):
50
+ `issue(context, path, candidate)` answers an `ExplorerDocumentIdIssue` (`issued`, `existing` with the path's ID, or
51
+ `taken`) and `resolve(context, id)` an `ExplorerDocumentIdBinding` (`bound` with a path, or `unbound`). The explorer
52
+ draws every candidate (up to 4 per issue), checks the reader before it calls a port — the deny rules, the sources'
53
+ boundaries and the document's existence through `asset`, without opening its bytes —, hands the registry the
54
+ document path (never a source's `readPath`), and checks every answer: a broken one is logged and answered `failed`.
55
+ `issue-id` (`POST`) needs `X-Markdown-Explorer: document-id` and the cross-origin check of a refresh, before the
56
+ reader is authenticated; `resolve-id` (`GET`, `HEAD`) takes the canonical form only. Unlike a document request, both
57
+ answer a failure with its own status, and without the ports both answer as unknown operations (404).
58
+
59
+ ### Tests
60
+
61
+ - `tests/unit/documentId.test.ts`: the ID's alphabet, the drawing (the redraw of a body whose check value is 32 or
62
+ more included), the canonical check, the lenient reading and the grouping, against the table of
63
+ `tests/fixtures/document-id-vectors.json` that `./testing` ships.
64
+ - `tests/server/documentIdOperations.test.ts` (a runtime-independent suite): the ports' assembly, `issue-id` (the
65
+ method, the proof and the cross-origin check before authentication, the path checks before the registry, the
66
+ `readPath` the registry never sees, the redraw of `taken` candidates and its limit, broken answers, `ExplorerError`
67
+ and other exceptions), `resolve-id` (the method, canonical IDs only, the disclosure table, broken bindings) and the
68
+ page loader's redirects and failure pages.
69
+ - `tests/components/documentIdUrl.test.tsx` (an ID URL inside the explorer: the skeleton, the replacing navigation
70
+ that keeps the fragment, the failures and their Try again, the cancellation on a change of URL, the failures the
71
+ loader answered), `tests/components/documentPermalink.test.tsx` (Copy permalink: when the bar holds it and when it
72
+ is unavailable, its names, the write inside the press, the forms of the three views and the basename, the issue's
73
+ failure and the browser's refusal, the latest press deciding) and
74
+ `tests/components/documentPermalinkHydration.test.tsx` (the unavailable button the server draws while the document
75
+ streams, the hydration without a mismatch or a request, and the same button acting once the document opens, with the
76
+ served buttons keeping their order at the row's end).
77
+ - `location`, `settings`, `labels`, `dataClient` and `entryPurity` cover the ID URLs, the `documentIds` option, the new
78
+ labels, the client's `issueId` and `resolveId`, and the `./testing` entry's second table.
79
+ - `tests/e2e/document-ids.spec.ts` (Chromium), on the demo's registry of document IDs (`demo/app/document-ids.server.ts`,
80
+ which the demo's `/docs` explorer now has under `/docs/d/<ID>`): Copy permalink through the real clipboard, the
81
+ loader's `302` with `private, no-store` in the tree and single views with the fragment kept, and the pages of an ID
82
+ written wrong, one no document has and one bound to a path no source admits (the status, the failure in the
83
+ document's place, no second request, no Copy permalink, no path).
84
+
85
+ ### Documentation
86
+
87
+ - README: `documentIds` in the configuration, the ID URLs in Views and URLs, the `documentIds` ports in the Server API
88
+ table, a Document IDs section (issue, resolve, the answers' checks, erasing and moving), the security model and the
89
+ demo's registry.
90
+ - `docs/behavior/url-contract.md`: the ID URLs in the shape and canonical-form tables and a Document IDs section (the
91
+ ID, writing and reading, the page loader, the browser, Copy permalink). `docs/behavior/security.md`: a Document IDs
92
+ section (an ID is not a permission, the disclosure table, `resolve-id`, `issue-id`, the answers' checks), the ID
93
+ operations' statuses, and what the host's registry must keep. `docs/behavior/dom-hooks.md`:
94
+ `markdown-explorer-document-permalink` and `markdown-explorer-document-id-failure`.
95
+
96
+ ## 0.35.0 (2026-11-10) — The server half runs in the page on a browser runtime, a host drives the explorer through props and a handle, and each document carries its language
97
+
98
+ ### Breaking
99
+
100
+ - **The peers `@aiquants/markdown` and `@aiquants/resize-panels` are `^13.0.0` and `^2.3.0` (hosts).** The explorer
101
+ offers the reader's column width and colour pair in markdown 13.0.0's display popover (`CONTENT_MEASURES` and
102
+ `CONTENT_COLORS` of `@aiquants/markdown/viewer-settings`) and names the popover's sections and a diagram's notices,
103
+ marks a document's content with its language (`contentLang`) and the labels it passes with the UI language
104
+ (`labelsLang`), hands a document's tables the size of its bars' tap-scroll circle (`spreadsheetTapScrollCircle`'s
105
+ `size`), and builds the browser runtime's link-card handler from `@aiquants/markdown/link-cards`; resize-panels
106
+ 2.3.0 draws the placeholder of a split that cannot fit its panels in the explorer's labels (`PanelGroup`'s
107
+ `labels`, `PanelGroupLabelKey`). On Node.js the `link-card` operation serves markdown 13.0.0's handler, which opens
108
+ pages only through the markdown service and without it answers its own `500` (`no-store`), so a host that serves
109
+ link cards without converting through the service now needs it. markdown 13.0.0's other breaking changes concern a
110
+ host's own conversions and the markdown service (see its changelog).
111
+ - **The two types named `ExplorerDraft` are renamed by role, and the unsaved draft the handle restores gets a name of
112
+ its own (hosts).** `ExplorerDraft` from `.` (`{ path, text }`, what `ExplorerDraftConverter.convert` receives) is
113
+ now `ExplorerPreviewDraft`; `ExplorerDraft` from `./server` (`{ text, baseVersion }`, what the `edit.save` port
114
+ receives) is now `ExplorerHostSaveDraft`. Their shapes are unchanged: rename the imports. `ExplorerUnsavedDraft` is
115
+ the new unsaved draft that `restoreDrafts()` takes and `onDraftChange` reports.
116
+ - **Each Markdown and text document carries its language as a canonical BCP 47 tag its source declares (hosts).** The
117
+ `markdown` and `text` documents of `ExplorerHostDocument` (`./server`) and of `ExplorerDocument` (`.`) carry a
118
+ required `lang`, the language their content is written in, apart from the explorer's `locale`: a non-empty string
119
+ that `Intl.getCanonicalLocales()` writes back unchanged (`"ja"`, `"en-US"` and `"zh-Hant-TW"` pass; `"EN"`,
120
+ `"en-us"`, `"en_US"` and `"iw"` do not). A host's `document` port answers it from its source's settings; an answer
121
+ without it, or with a tag off the rule, breaks the contract (a `TypeError`) and the document's load is `failed`.
122
+ `createFileSystemSource()` takes a required `lang`, which its Markdown and text documents carry: a value that is not
123
+ a string, an omitted one included, throws a `TypeError`, and a string off the rule a `RangeError` naming it. The
124
+ data route's `text` operation names no language, since it shows any file as written.
125
+ - **The HTML of a document and of the editing preview keeps a URL of the app itself only under the path its use allows
126
+ (hosts, readers).** The sanitizers, on the server and in the preview, know the app's own URLs from the
127
+ configuration: its origins (`appOrigins`), the data path for images and other resources, `basePath` and the data
128
+ path for links, and for the `src` of a `video`, an `audio` or a `source` also the media path (`mediaDataPath`). A
129
+ path-only URL, and an absolute one whose origin `appOrigins` lists (its scheme, host and port) or whose scheme is
130
+ that of a listed origin with a scheme that is not special (such as `wails:`, whatever its host), stays only when its
131
+ normalised path is the one its use allows or continues it after a `/`; a URL on the media path's origin alone stays
132
+ only as a media `src` under the media path. A protocol-relative URL (`//host/…`) stays only when it does under every
133
+ scheme the page may have, and an absolute URL that does not parse is dropped. A relative URL stays in a document
134
+ link (an HTML `a` with `data-link-kind="doc"`) and, without a `.` or `..` segment (`%2e` included), in any other
135
+ link; an SVG reference keeps a fragment only, and an image's or a media file's relative URL is dropped. A URL is
136
+ read as WHATWG reads it (leading and trailing C0 controls and spaces trimmed, tabs and newlines removed), one with a
137
+ backslash is dropped from any use, a `srcset` stays only when every candidate does, and the presentation attributes
138
+ (`clip-path`, `color-profile`, `cursor`, `fill`, `filter`, `marker-start`, `marker-mid`, `marker-end`, `mask`,
139
+ `stroke`) drop a value with a backslash, an image function or a `url(` whose argument does not start with `#`.
140
+ Absolute URLs of other origins stay as before. `video` and `audio` always carry `preload`: `none` where the document
141
+ wrote `none`, `metadata` otherwise. A host names its origins in `appOrigins` and its media path in `mediaDataPath`;
142
+ a document whose HTML reaches the app elsewhere (an image or a media file outside the data path, a relative link
143
+ with `..` that is not a document link) loses those URLs until they point under the allowed paths.
144
+ - **HTML nested deeper than 256 levels is refused as too large, in every runtime (readers, hosts).** The sanitizer's
145
+ nesting limit is 256 levels (it was 512), one value on the server, in the browser runtime and in the editing
146
+ preview: a document with an element placed deeper is `too-large`. The limit keeps a margin for the parsers to agree.
147
+ - **A path segment still percent-encoded after three decodes is denied (hosts, readers).** Deny rules that have at
148
+ least one pattern also deny a path segment or an entry name that one more lenient decode would still change after
149
+ the three they look through, whichever patterns they have, as the Go path rules that run the same table
150
+ (`./testing`) do; rules without a pattern (`deny: []`) deny nothing.
151
+ - **The `sanitizer` setting must be a plain object (hosts).** `createMarkdownExplorer`'s `sanitizer` and the browser
152
+ runtime's accept only a plain object: an array, a class instance or a `Map` throws a `TypeError`
153
+ (`[markdown-explorer] sanitizer must be a plain object of { … }`, naming the fields: `workers`, `deadlineMs`,
154
+ `maxHtmlBytes`, `cacheBytes`, `workerHeapMb`, `jobsPerScope` and `maxQueuedJobs` on Node, the same without `workers`
155
+ and `workerHeapMb` in the browser). Both refuse the five fields they share in the same order with the same messages;
156
+ a valid setting behaves as before.
157
+ - **A brace outside a placeholder is refused in every template label (hosts).** A template label
158
+ (`MARKDOWN_EXPLORER_LABEL_TEMPLATES`) holds braces only as its `{name}` placeholders, in both catalogs and in a
159
+ host's overrides: those the explorer passes to `@aiquants/drag-drop-panels` (the panels'), to
160
+ `@aiquants/resize-panels` (the split placeholder's details) and to `@aiquants/markdown` (a table block's, derived
161
+ from its catalog, and an SVG image's). An unclosed or unopened brace, a doubled one, an empty `{}` or a name with a
162
+ space throws a `RangeError` naming its position when the labels are resolved; the catalogs' own templates have none.
163
+
164
+ ### Added
165
+
166
+ - **The host contract (hosts).** `MarkdownExplorer` takes as props what a host that embeds it exchanges with it, each
167
+ defaulting to what a web page does (the default in parentheses): `fetch` for the data requests and the link cards
168
+ (the global `fetch`), `persistSettings(serialized)`, which stores the serialized view settings where the server's
169
+ `readSettings` finds them (the settings cookie), `subscribeHostChanges` with `hostChangePolicy` (`"reload"`, or
170
+ `"notify"`), `guardUnload` (`true`: leaving the page with an unsaved draft asks through `beforeunload`; a host that
171
+ asks on close itself passes `false`), `onReload` (the page's reload), `onSessionEnded` (none), `onDraftChange`
172
+ (none), `accountState` (`"signed-in"`, or `"signed-out"`), `confirmUnversionedSaves` (`false`), `paletteKey` (none),
173
+ an opaque name of the palette a host binds the explorer's colour roles to, whose change makes the explorer read
174
+ again the colours it paints itself (the tree's canvas lines), and `ref`. It checks them on every render (a function
175
+ or a flag of the wrong type, or a `paletteKey` that is not a string, throws a `TypeError`; a value outside its set
176
+ or an empty `paletteKey` a `RangeError`) and always calls the latest function given, without rebuilding its
177
+ transport or redrawing its context. `EXPLORER_HOST_CHANGE_POLICIES` and `EXPLORER_ACCOUNT_STATES` list the two sets
178
+ (`ExplorerHostChangePolicy`, `ExplorerAccountState`), and `.` exports the contract's types: `ExplorerHostChange`,
179
+ `ExplorerMediaFailure`, `ExplorerUnsavedDraft`, `ExplorerDraftChange`, `ExplorerDraftRestore`,
180
+ `MarkdownExplorerHandle` and `LineEnding`.
181
+ - **The handle (hosts).** `ref` receives a `MarkdownExplorerHandle`, the same value while the explorer renders, which
182
+ acts on the current reader's explorer when it is called: `flushUnsaved()` writes out the pending edits and returns
183
+ the paths left unsaved; `confirmDiscard(paths)` asks once about the unsaved ones among them and resolves `true`
184
+ without asking when there are none; `restoreDrafts(drafts)` brings a host's `ExplorerUnsavedDraft`s back as unsaved
185
+ drafts, as they were where their base version is still the document's and through a save's three-way merge where it
186
+ is not, and resolves the paths it restored and those it could not with the reason (a read's failure, `forbidden`
187
+ where the reader must grant a permission first, `failed` where the reader already edits the document, whose draft
188
+ stays); `announce(text)` speaks through the explorer's live region; `owns(element)` tells whether the element is
189
+ inside the explorer's root; and `reportMediaFailure(failure)` reports a media URL that failed
190
+ (`ExplorerMediaFailure`). Each checks its arguments and throws, or rejects where it returns a promise.
191
+ - **Changes the host saw elsewhere (hosts, readers).** `subscribeHostChanges(listener)` hands the explorer each
192
+ `ExplorerHostChange`, `{ sourceIds, paths }`. A listed source's tree is read again while a view shows it, that
193
+ source alone (one no view shows is only marked stale). A listed document that a pane shows, has loaded and the
194
+ reader is not editing follows `hostChangePolicy`: `"reload"` reads it again and announces
195
+ `documentReloadedAfterChange(name)`, or shows the notice when it cannot read it, and `"notify"` shows a notice above
196
+ the document, `documentChangedElsewhere(name)` with Reload. The explorer subscribes again when the function or the
197
+ reader changes and applies nothing that arrives after the unsubscribe; a subscribe that returns no unsubscribe
198
+ function throws.
199
+ - **Drafts kept outside the page (hosts).** `onDraftChange` receives, at the end of the task that changed them, the
200
+ drafts as the explorer writes them, those changed since the last call (`kept`), and the paths whose drafts ended:
201
+ saved, discarded, closed, or back to the text they started from (`ended`); its first call holds every draft unsaved
202
+ by then. The explorer listens only while a function is given, and not again when only the function changes; the
203
+ handle's `restoreDrafts` brings a kept copy back.
204
+ - **A save to a source that keeps no previous versions can ask first (hosts, readers).** With
205
+ `confirmUnversionedSaves`, a save that would write a change to a document whose source keeps no previous versions
206
+ (`history: false`), from the bar's Save or the editor's Mod-S, writes out the editor's pending keystrokes and asks:
207
+ `unversionedSaveTitle` («Save without keeping the previous version?» / 「前の版を残さずに保存しますか?」) and
208
+ `unversionedSaveBody`, with `unversionedSaveConfirm` («Save» / 「保存する」) and the existing `unsavedStay` to keep
209
+ editing. The confirmation sits outside the editing surface, so Ctrl+E inside it does not switch the view.
210
+ - **Sign-in and reload on a failure (hosts, readers).** A failure's Reload calls `onReload` and, when `guardUnload` is
211
+ `false`, first asks about the unsaved drafts. With `onSessionEnded`, an `unauthorized` failure (an ended session)
212
+ offers the host's sign-in without leaving the page: the function resolves `true` once the reader is signed in again,
213
+ and the failed view tries again (calls made while a sign-in is open share its answer; a failed or cancelled sign-in
214
+ resolves `false`). `accountState` picks the words, which name no service (a host names its own through `labels`):
215
+ `failureUnauthorizedSignInBody` («Sign in again to continue.» / 「もう一度サインインすると続けられます。」) with
216
+ `signInAgain` («Sign in again» / 「もう一度サインイン」) while signed in, and `failureUnauthorizedSignedOutBody`
217
+ («Sign in to open it.» / 「サインインすると開けます。」) with `signIn` («Sign in» / 「サインイン」) while signed
218
+ out. Without `onSessionEnded` the failure offers the reload.
219
+ - **Media failures (readers, hosts).** The explorer hears the media events inside its root, following the root a host
220
+ frame that differs per view recreates, and with the reports of the handle's `reportMediaFailure` tells, in the order
221
+ they come, a file it could not load from one it cannot play. The notice names one file (`mediaLoadFailed(name)`,
222
+ `mediaUnplayable(name)`) or counts several (`mediaLoadFailedCount(count)`, `mediaUnplayableCount(count)`); the one
223
+ of files that could not be loaded has Reload, which loads them again, and the one of files that cannot be played has
224
+ none. A report's `final` tells whether the host's cut is final: a final cut shows the notice at once, any other once
225
+ the element stalls or fails, since it reads again on its own; a reported PDF frame shows it at once.
226
+ - **Notices above the document (readers).** The changes made elsewhere and the media failures show in a
227
+ `role="status"` container between the document's refresh bar and the document region
228
+ (`markdown-explorer-document-notices`, each notice `markdown-explorer-document-notice` with `data-aqmx-notice`:
229
+ `changed`, `media-load` or `media-unplayable`); the first two offer `reload` («Reload» / 「読み込み直す」).
230
+ - **Announcements wait while a block is full screen (readers).** While a block of the document is full screen (its
231
+ dialog open as `:modal`), the explorer's announcements, the host's `announce` included, wait; when the block leaves
232
+ full screen they are spoken together in the order they came, a sentence that repeats the one before it dropped.
233
+ - **The reader's column width and colours (readers, hosts).** A page view's display popover offers the column width
234
+ and the colour pair (markdown 13.0.0's width and colours sections), as a panel's does while it is maximized; an
235
+ embed's `?showStyle=false` hides them with the style, and the editing preview shows neither. The choice is kept with
236
+ the display settings: `ExplorerViewSettings` has `measure` and `documentColors`, which the cookie writes after
237
+ `align`, each only as one of `@aiquants/markdown`'s `CONTENT_MEASURES` and `CONTENT_COLORS`. Any other value is
238
+ dropped with its key (the document then shows the viewer's own default), no other key name is read for them, and a
239
+ cookie without them reads and is written back as before.
240
+ - **A document's language (readers).** A Markdown or text document's `lang` marks its content for the viewer
241
+ (`contentLang`, markdown 13.0.0), rendered, shown as written or previewed while editing, so the content is read in
242
+ its own language.
243
+ - **The explorer's labels keep the UI language inside a document (readers).** The labels the explorer passes
244
+ `MarkdownViewer` carry the UI language (`labelsLang`), so every element they name declares it itself: the controls
245
+ the viewer draws inside the content (a code block's copy button, a diagram's controls, an embed frame's title) and
246
+ those of its bar. The explorer's own controls declare no language and read in the page's; a table file's grid is not
247
+ marked, as a table file names no language. An inert link's reason (`inertLink`: its `title` and its announced text)
248
+ reads in the UI language while the link's text keeps its own language and direction, moved to an inner span; where
249
+ the content names no language, the link declares none.
250
+ - **Fragment-only links under any router (readers, hosts).** In a page view a plain click on a fragment-only link
251
+ moves to its target once whatever the router, a memory router (as a desktop webview has) included: the explorer
252
+ follows the location the router made of the browser's own fragment navigation, or the click where it made none. `#`
253
+ keeps going to the top.
254
+ - **The split's placeholder reads in the explorer's language (readers, hosts).** When a split's panels cannot fit it,
255
+ `@aiquants/resize-panels` draws a placeholder over them, whose texts are now the explorer's labels
256
+ `panelGroupMinimumExceededSummary` and `panelGroupMinimumExceededDetail` (`{required}`, `{available}`), and
257
+ `panelGroupMaximumInsufficientSummary` and `panelGroupMaximumInsufficientDetail` (`{total}`, `{needed}`), the
258
+ English word for word resize-panels' own. The explorer passes all four to `PanelGroup`'s `labels` whichever a host
259
+ overrides; they carry no `lang`, so the placeholder, outside any document's language, reads in the page's.
260
+ - **Labels for markdown 13.0.0's display popover and diagram notices (hosts, readers).** `viewerStyleSectionTitle`
261
+ («Style» / 「スタイル」) heads the popover's style section; `viewerMeasureTitle` («Width» / 「幅」) with
262
+ `viewerMeasureFill` and `viewerMeasureReading`, and `viewerColorsTitle` («Colors» / 「配色」) with
263
+ `viewerColorsDefault`, `viewerColorsSepia`, `viewerColorsDarkLowGlare` and `viewerColorsHighContrast`, name the
264
+ width and colours sections and their choices; `viewerMermaidLoading`, `viewerMermaidInitializationFailed`,
265
+ `viewerMermaidRenderFailed` and `viewerMermaidEmptyDrawing` are a diagram's notices while it is drawn and when it
266
+ cannot be. The English catalog repeats the viewer's built-in texts, and the viewer receives all of them in the UI
267
+ language.
268
+ - **Labels for a diagram's source view and the names of the diagram types (hosts, readers).** `viewerMermaidSource`
269
+ («Source» / 「ソース」) names the toggle that shows a diagram's source in place of the drawing,
270
+ `viewerMermaidSourceRegion` («Diagram source» / 「図のソース」) the region that holds the source, and
271
+ `viewerMermaidCopySource`, `viewerMermaidCopiedSource` and `viewerMermaidCopySourceFailed` that region's Copy button
272
+ and its outcomes; the 31 `viewerMermaidType…` keys (`viewerMermaidTypeFlowchart` «Flowchart» / 「流れ図」,
273
+ `viewerMermaidTypeSequence` «Sequence diagram» / 「シーケンス図」 and the others) name the diagram types, which the
274
+ drawing carries as its role description in place of the type code Mermaid writes. The English catalog repeats the
275
+ viewer's built-in texts, and the viewer receives all of them in the UI language. The viewer reads them from the
276
+ `@aiquants/markdown` release that adds the source view and the type names; an earlier one reads only its own keys.
277
+ - **The server core (hosts).** `./server/core` is the server half without a runtime:
278
+ `createExplorerServer(config, platform)` runs on an `ExplorerServerPlatform` (`prepareScope`, `createSanitizer`,
279
+ `createLinkCardHandler`, with `SanitizerSetup`) and takes an `ExplorerServerCoreConfig`: the configuration
280
+ `createMarkdownExplorer` takes (`ExplorerServerSharedConfig`) without `scopeSecret`, with the `sanitizer` limits
281
+ every runtime accepts, and with a required `readSettings(request)`, which returns the request's serialized view
282
+ settings or `undefined` (any other answer throws a `TypeError`), and a required `assetMaxRangeBytes`. A platform's
283
+ scope must be 22 base64url characters for every principal key, or the core throws a `TypeError`. The entry also
284
+ exports `createInProcessDataFetch`, `ASSET_CONTENT_SECURITY_POLICIES`, the rules a host shares with the explorer
285
+ (the deny rules, the document-path and source-id rules, `EXPLORER_MAX_HEADINGS`, the text decoding),
286
+ `ExplorerError`, and the port and platform types. `createMarkdownExplorer` (`./server`) is `createExplorerServer` on
287
+ Node's runtime, which reads the settings cookie and caps no range.
288
+ - **The browser runtime (hosts).** `./server/browser` exports
289
+ `createBrowserExplorerPlatform({ principalKey, scope, window, nestingGuardWorkerUrl, pageFetch })`
290
+ (`BrowserExplorerPlatformOptions`), a platform that runs the core in the page, as a desktop webview does. It checks
291
+ its options when created and throws a `TypeError` naming the wrong one (a window without `crypto.subtle`, outside a
292
+ secure context, among them); answers the scope of its one principal key and refuses any other without naming it;
293
+ sanitizes with the page's DOMPurify behind a Web Worker that guards the nesting, the self-contained module
294
+ `./server/browser/nesting-guard-worker` (`dist/nestingGuardWorker.js`) whose URL the host passes as
295
+ `nestingGuardWorkerUrl`; measures the HTML with the window's Web Crypto, giving Node's values; and builds the
296
+ link-card handler from markdown 13.0.0's `@aiquants/markdown/link-cards` on `pageFetch` (with `null`, a
297
+ configuration that has link cards throws a `TypeError`). Its `sanitizer` limits default to one worker's, with the
298
+ parsed-node budget of a Node worker on the default heap (81,920 at the default 4 MiB, so `maxHtmlBytes` may be at
299
+ most 14,155,776, which leaves it 4,096 nodes; a `RangeError` above it), and `workers` and `workerHeapMb`, which only
300
+ Node reads, throw a `TypeError`. A job's deadline covers the guard and DOMPurify together: a result that ends after
301
+ it is dropped and the job times out. The demo's `/browser-docs` page runs the core this way.
302
+ - **The in-process fetch (hosts).** `createInProcessDataFetch(server, { dataPath, pageAddress })` returns, for the
303
+ explorer's `fetch`, a function that answers the data route inside the page: a request for `<dataPath>/<operation>`
304
+ on the page's scheme and host goes to the server's `dataLoader` (GET, HEAD) or `dataAction` (any other method), HEAD
305
+ keeping the status and headers without the body, and any other URL fails with a `TypeError`, reaching neither the
306
+ core nor the network. It compares scheme and host rather than origins, so a `wails://` page (origin `"null"`) is
307
+ answered. A request aborted before the call never reaches the core, and one aborted while the core works rejects
308
+ with its reason at once. `dataPath` follows the configuration's mount-path rule, and `pageAddress` must be an
309
+ absolute URL the data path resolves against (not relative, `about:blank`, `data:` or `mailto:`).
310
+ - **Files a host streams itself (hosts).** `MarkdownExplorerServer.planData(args)`, given the loader's arguments,
311
+ plans a data request (`ExplorerDataPlan`) for a host that streams files itself. An `asset` GET answered with bytes
312
+ (200 or 206) is a `file`: its status, all its headers, the file's bridge (`uri`, `storageVersion`), its range and
313
+ length, and `fail(error)` for a read that fails before the first byte (the error passes the host's `readFailure`,
314
+ then the route's failure mapping, log and headers), planned without reading the bytes (a plain-text view reads only
315
+ the head that names its encoding). Every other answer is a whole `response`, as `dataLoader` gives it. A file
316
+ without a bridge whose bytes would be planned is logged as a host contract violation and answered `failed` (500),
317
+ and a table preview's workbook (`as=workbook`), which the explorer reads only through its own fetch, is refused as
318
+ `invalid` (400) without a log.
319
+ - **A file's bridge (hosts).** `ExplorerAssetFile` takes an optional `bridge`, `{ uri, storageVersion, readFailure }`,
320
+ for a host that streams the bytes itself rather than through `open`: the storage URI, its version (`null` for a
321
+ storage without versions), and `readFailure`, which maps a failed read the way `open`'s failures are mapped, so a
322
+ bridged failure answers the status a failed `open` would. The explorer copies it field by field and freezes it.
323
+ `undefined` is no bridge; `null`, a value that is not an object, an empty `uri` or `storageVersion`, and a
324
+ `readFailure` that is not a function break the contract (logged, 500). The file's version is not compared with the
325
+ storage's.
326
+ - **A range answer can be capped, and the asset answers' policies are exported (hosts).** `assetMaxRangeBytes` (a
327
+ positive safe integer or `null`) caps the range answers of `asset`, stored as is or shown as plain text: a single
328
+ satisfiable range longer than it is answered with a 206 of that many bytes from its start. A request without
329
+ `Range`, a mismatching `If-Range` and a 416 are answered as before, and `null` answers the range asked, as the Node
330
+ entry does. `ASSET_CONTENT_SECURITY_POLICIES` holds the two `Content-Security-Policy` values the asset answers
331
+ carry, `sandboxed` and `mediaDocument`.
332
+ - **The app's own origins and media path (hosts).** The configuration takes `appOrigins`, the origins the app's own
333
+ pages are served from (a frozen `[]` by default), each exactly a URL's `protocol//host` (an origin whose scheme is
334
+ not special, such as `wails://localhost`, makes every URL of that scheme the app's): an empty host, an explicit
335
+ default port or a path throws a `RangeError`, a value that is not an array or an element that is not a string a
336
+ `TypeError` naming the element's index, and repeats collapse in the order written. `mediaDataPath` (`null` by
337
+ default) is the media data path: an absolute `http:` or `https:` URL, as the browser writes it, of an origin and a
338
+ mount path only (a trailing `/`, a query, a fragment, user information, an explicit default port or a `.` or `..`
339
+ segment throws). For either, `undefined` is the same as leaving it out, and `null`, `""` or a number is an error.
340
+ - **The rule of a document's language (hosts).** `.` and `./server/core` export `isExplorerDocumentLang(value)`, the
341
+ rule a Markdown or text document's `lang` is checked with (a non-empty string that `Intl.getCanonicalLocales()`
342
+ writes back unchanged), so a host refuses a wrong tag in its own settings when its server reads them, not on each
343
+ document's load.
344
+ - **Draft conversion helpers (hosts).** `.` exports `draftAnswerOf(error)` and `draftConversionOf(setup)` for a host's
345
+ browser draft converter. `draftAnswerOf` maps a conversion's failure to the explorer's draft answer: a conversion
346
+ stopped by its size limit or its deadline is a `too-large` failure document, `invalid_argument` is `invalid`,
347
+ `internal` is `failed`, and `unavailable` leaves the draft to the data route's `preview`; any other error, a value
348
+ that only looks like a converter error and a converter error with a reason it does not know are thrown again.
349
+ `draftConversionOf` builds from the deny rules and the conversion limits (`DraftConversionSetup`,
350
+ `MarkdownConversionLimits`) the deadline (`timeoutMs`) and each draft's options (`ExplorerDraftConversionOptions`: a
351
+ copy of the deny rules, the HTML limits, the source lines). The error classes are `@aiquants/markdown/converter`'s,
352
+ which markdown 13.0.0's `@aiquants/markdown/service-client` exports as well.
353
+ - **The deny table (hosts).** `./testing` exports `denyVectors()`, the explorer's deny-rule table as 207 frozen rows
354
+ of `{ pattern, path, expect }` (`DenyVector`), for a host to check its own deny implementation against. The entry
355
+ reaches no package, and no other entry reaches it.
356
+
357
+ - **The tree setting "Show folder READMEs" (readers, hosts).** A switch right after "Reveal the open document",
358
+ offered in the tree view only (`showFolderReadme`, on in `DEFAULT_TREE_SETTINGS`; `settingShowFolderReadme`: «Show
359
+ folder READMEs», 「フォルダーの README を表示」), ties the README the tree view shows to the folders' opening and
360
+ closing. Turned off, a press on a folder only opens or closes it, and a folder URL still shows the folder's README;
361
+ a host turns it off for every reader with `defaultTreeSettings: { showFolderReadme: false }`.
362
+
363
+ ### Changed
364
+
365
+ - **The viewer's style button is its display button (readers).** `viewerStyleTitle`, `viewerSelectStyle`,
366
+ `viewerPinStyle` and `viewerUnpinStyle` read «Display», «Display options», «Pin display options» and «Unpin display
367
+ options» (「表示」「表示の設定」「表示の設定をピン留め」「表示の設定のピン留めを解除」), the built-in texts of
368
+ markdown 13.0.0's display popover, whose style section `viewerStyleSectionTitle` heads.
369
+ - **A document table's tap-scroll circle is the bars' 44 px (readers).** The explorer hands a document's tables the
370
+ size of its bars' circle, 44 px, which markdown 13.0.0 draws.
371
+ - **A notice's action into the explorer moves through the router (readers).** An `ExplorerNotice`'s `action` whose
372
+ `href` is a page of the explorer, a path-only address under `basePath` outside the data route, moves through the
373
+ router; any other stays a plain link.
374
+ - **The history dialog retries a version's text alone (readers).** A version whose text failed to load is retried by
375
+ reading that text again.
376
+ - **The bundles carry the notices of the third-party code they inline (hosts).** A legal comment at the head of each
377
+ chunk that keeps such code names the package, its version and licence, and the copy of its licence file in
378
+ `dist/licenses/<name>/`: `parse5` (MIT) and `entities` (BSD-2-Clause) in the nesting-guard worker, and
379
+ `@heroicons/react` (MIT), which the library build bundles.
380
+
381
+ - **Closing the shown folder moves the tree view up (readers).** With "Show folder READMEs" on, a press (a click,
382
+ Enter or Space) on the shown folder while it is open moves the view up once the folder closes — at the end of the
383
+ delay that tells a single press from a double click, or at the end of a double click —: to the folder above the
384
+ pressed row (its README, or the line saying it has none), or for a top-level folder to the source's README as a
385
+ document, or to the empty pane when the source has none, so repeated presses walk up one level at a time. The move
386
+ replaces the URL's document and leaves an explorer sheet open, since it picks no destination; a document the reader
387
+ shows before the folder closes stays. A double click that leaves the folder open keeps its README, a press on an
388
+ open folder that is not shown now only closes it (it showed the folder and kept it open), and the arrow keys and
389
+ Collapse all never change what the view shows. Under "Always expanded" a press on a folder whose contents are known
390
+ shows it, or on the shown folder moves up at once, and no longer flips the folder's hidden expansion.
391
+ - **The explorer's navigations carry their kind as router state (hosts).** Every navigation the explorer starts
392
+ carries `{ aqmxNavigation }` (`browse`, `close-folder`, `switch-source`, `switch-view` or `follow-link`) as its
393
+ `location.state` (it was `null`), so what watches the location reads why it changed from the navigation itself.
394
+
395
+ ### Fixed
396
+
397
+ - **Every type a public entry's declarations show is exported (hosts).** `.` exports the seven types its declarations
398
+ showed but no entry exported: `ExplorerEntryType`, `ExplorerNoticeTone`, `ExplorerTextDocument` and its
399
+ `ExplorerFileText`, `MarkdownExplorerSpreadsheetLabels`, `ExplorerHrefWriter` and `TreeReadmePlacement`. `./server`
400
+ exports `ExplorerAssetDisplay`, which its declarations showed and no entry exported either, and, as types, the new
401
+ `ExplorerDataPlan`, `SanitizerLimitsInput` and `ExplorerServerSharedConfig` its declarations show. The build checks
402
+ every public entry for such types.
403
+ - **Under `lockDocumentScroll`, the placement check follows the explorer's current root (hosts).** A host frame that
404
+ differs per view and recreates the root stays watched: the check runs once per root element, a recreated root is
405
+ checked afresh, and the removed one is no longer watched.
406
+ - **Messages name values through one describer (hosts).** A value an error, violation or warning message names (a
407
+ rejected or out-of-range value, a quoted name or candidate) is written one way: a string quoted and cut after 80
408
+ code points, ending in `…`, never inside a surrogate pair; a number, a boolean, a symbol, `null` and `undefined` as
409
+ they are (`-0` included); a bigint with its `n`; an object by its kind, never by its content or its own `toString`.
410
+ The counts, limits, lengths and positions the package itself asks for stay plain numbers. A rejected value no longer
411
+ looks valid (the string `"5"` is not written `5`, nor `null` as `object`), a bigint no longer throws a `TypeError`
412
+ that hides the package's own error, and a document of an unknown kind no longer puts its content into the message. A
413
+ message about `scopeSecret` names the value's type alone; `iframeHosts` names an element out of place with its index
414
+ (as `appOrigins` does), overlapping view sections are named by value, a source id given twice to
415
+ `withExplorerSources` is named with its indices (as the server's `sources` are), and a malformed mount path's
416
+ message says that `.` and `..` segments are refused.
417
+ - **A URL whose scheme has a digit is judged by its scheme (readers).** The sanitizer's URL check counts digits among
418
+ a scheme's characters, so a URL such as `h323:…` is no longer taken for a relative one.
419
+ - **A document invalidated during a background re-read is no longer taken as checked (readers).** When the explorer
420
+ invalidates a document no pane holds, it also forgets the background re-read already running, whose answer, the
421
+ document from before the change, counted as checking it again.
422
+
423
+ - **A tree press navigates with the URL's current overrides (readers).** After the URL's overrides changed while the
424
+ same document or folder stayed shown (an override dropped, another style chosen), a press on the tree's Tab stop —
425
+ the row that last took the tree's focus, or else the shown row — navigated with the overrides of that row's last
426
+ render (Enter, Space, or a click, also one that brings the focus back into the tree), so a dropped override came
427
+ back: the tree's rows keep the press handler they last rendered with, and only a press that moves the Tab stop
428
+ renders the pressed row again. The tree's press handler now keeps its identity and reads the pane's current
429
+ handlers.
430
+
431
+ ### Tests
432
+
433
+ - `vitest.config.ts`: the runtime-independent server suites run in four projects, `server` (Node), `server-plan`
434
+ (Node, the data route's GET and HEAD planned by `planData` and answered from the file's bridge, as a host that
435
+ streams files itself), and `server-browser-chromium` and `server-browser-webkit` (Vitest's browser mode, headless
436
+ through Playwright), while the suites that test Node's runtime itself run in `server` alone
437
+ (`tests/server/README.md` says which run where and how to write one that runs anywhere); `tests/browser/**` runs in
438
+ the two browser projects, which pre-bundle every dependency their suites load. `test` and `test:coverage` run the
439
+ `browser`, `wiring`, `server`, `server-plan` and `server-browser-chromium` projects (V8 coverage is measured in
440
+ Chromium only), `test:browser:webkit` runs WebKit, and `test:run` and `test:watch` every project. `@vitest/browser`
441
+ and `@vitest/browser-playwright` are 4.1.10 exactly, and `playwright` is the catalog's.
442
+ - `tests/server/runtimes/` (`node.ts`, `browser.ts`, chosen per project through `projectRuntime`) and
443
+ `tests/server/fixtures/memorySource.ts` (an in-memory storage with the asset port, a default bridge and reads
444
+ through it): the suites build the core on either runtime. A browser runtime answers the page's one principal, so a
445
+ test of a second one runs on Node; cookies travel in headers every runtime keeps (`SESSION_COOKIE_HEADER`,
446
+ `SETTINGS_COOKIE_HEADER`), the assertions that need a forbidden header run only where it reaches the core, and
447
+ `testRequest` refuses a header the runtime dropped.
448
+ - `tests/server/explorerCore.test.ts`, `tests/server/nodePlatform.test.ts`, `tests/server/serverCoreTypes.test.ts`:
449
+ where and how often the core calls its platform, the order of its errors, the scope contract, the settings reader
450
+ and the range cap (stored as is, plain text, `null`); Node's runtime checks nothing when created, checks the secret
451
+ when the scope is prepared and derives the scope by HMAC; the two configurations share their fields, each keeps its
452
+ own, and the core's `sanitizer` takes Node's setting as it is. `tests/server/planData.test.ts`: a table of plans (a
453
+ capped range, 416, HEAD, 304, an empty file, a file of unknown length, `as=text`, a redirect, `not-found`, no cap,
454
+ `fail`, a file without a bridge), `fail`'s four answers through the host's mapping, `as=workbook`, other operations
455
+ and methods, `.data` and an unexpected error, and a `file` plan streamed from the bridge answering what `dataLoader`
456
+ answers.
457
+ - `tests/server/inProcessFetch.test.ts`: the in-process fetch answers the data route and never calls the global fetch.
458
+ `tests/server/sanitizerOptions.test.ts`, `tests/server/sanitizer.test.ts`: the browser's and Node's resolvers accept
459
+ only a plain object and refuse with the same first error. `tests/server/sanitizeJob.test.ts`: the sanitizing step
460
+ after the nesting guard, which every runtime shares. `tests/server/documentLang.test.ts`: the `lang` rule, the
461
+ contract and the host document's copy, answering alike in Node, Chromium and WebKit. `tests/server/ownUrls.test.ts`:
462
+ the table `tests/server/fixtures/own-urls.json` (80 rows over a web, a desktop and a desktop-media configuration)
463
+ and its shape, in Node, Chromium and WebKit. `tests/server/linkCardOperation.test.ts`: without
464
+ `MARKDOWN_SOCKET_PATH` the handler's own 500 reaches GET and HEAD with its status, headers and body, while the
465
+ explorer logs nothing and fetches no local page.
466
+ - `tests/unit/denyVectors.test.ts`: the deny rules answer the 207 rows of `tests/fixtures/deny-vectors.json`, the
467
+ table `./testing` exports. `tests/server/htmlNestingParity.test.ts` (Node), with
468
+ `tests/fixtures/nesting-parity.json` and `tests/fixtures/over-limit-nesting.html`: the 23 rows within the limit
469
+ agree between the guard, jsdom's parse and the table and sanitize idempotently, while the 12 over it and the
470
+ over-limit document are refused. `tests/server/fixtures/digest-vectors.json`: Node's measure and the browser's run
471
+ the same table.
472
+ - `tests/browser/` (Chromium and WebKit, real Web Workers): `nestingGuardWorker.test.ts` (the worker and the guard in
473
+ the page answer as the nesting table, and the three rows at the limit, a `div`, a `ul`/`li` and a `table`, keep
474
+ depth 256 in a document, a fragment and a document embedded 64 levels deep), `domSanitizerPool.test.ts` (the pool's
475
+ output matches the Node step's and is idempotent, rows over the limit are `too-large`, and its failures, deadline,
476
+ yield and admission, the guard's refusals and errors coming from stand-in workers, `guardWorkers.ts`),
477
+ `browserPlatform.test.ts` (the options' checks, the scope, the limits, the budget sent to the guard, real
478
+ sanitizing, the measure, and the link cards on a stand-in port) and `fullscreenBlock.test.ts`.
479
+ - `tests/browser/fragmentLinks.test.tsx`: under a browser router and a memory router, a fragment-only link pressed by
480
+ a pointer click or by Enter (a footnote's reference and back link in remark-gfm's and goldmark's markups, a heading
481
+ the URL does not hold yet, the top, and the fragment the URL already holds) scrolls the pane once, leaves the focus
482
+ where it went and keeps the document. `tests/browser/treeLinePalettes.test.tsx`: five palettes bound as a host binds
483
+ its own and named by a new `paletteKey` are read back from the tree canvas's pixels, and one bound without a new
484
+ name stays undrawn until the name changes. `tests/browser/fullscreenAnnouncements.test.tsx`: through the real
485
+ explorer and table block, announcements wait while the block is full screen and, once it leaves by its control or by
486
+ Escape, are spoken in order with a repeat dropped. `tests/browser/unversionedSaveConfirm.test.tsx`: Mod-S right
487
+ after typing writes the pending keystrokes and asks; Enter or Escape stays and hands the focus back to the editor,
488
+ and saving sends the text over its base version.
489
+ - `tests/unit/hostContract.test.ts`, `tests/unit/hostChanges.test.ts`, `tests/components/explorerHost.test.tsx`,
490
+ `tests/components/explorerDrafts.test.tsx`: the host's options and the handle's arguments are checked; a change
491
+ reloads or notifies by the policy and skips an edited, unshown or unloaded document; the paths `onDraftChange` folds
492
+ match `flushUnsaved()` after each write (the first render, typing, back to the original text, saving, discarding, a
493
+ restored draft), with a later listener, a replaced function, `confirmDiscard` and malformed arguments; under the
494
+ lock, a frame that recreates the root moves the watch to the current root, which reports a collapse once.
495
+ `tests/unit/stores.test.ts`: `noteChanged`, `reloadSource` and `invalidate`.
496
+ `tests/components/markdownExplorer.test.tsx`: the context's defaults and relays.
497
+ - `tests/components/documentNotices.test.tsx`, `tests/components/explorerNotices.test.tsx`,
498
+ `tests/components/historyConfirm.test.tsx`, `tests/components/historyDialog.test.tsx`,
499
+ `tests/components/liveRegion.test.tsx`, `tests/components/unsavedChangesGuard.test.tsx`,
500
+ `tests/unit/documentChanges.test.ts`, `tests/unit/mediaFailure.test.ts`: the screens' side of the host contract (the
501
+ notices above the document and their Reload, a notice's link into the explorer, the history dialog's retry, the
502
+ announcements held while a block is full screen, the unload and unversioned-save checks, and the order of media
503
+ reports and events). `tests/components/singleView.test.tsx`, `tests/components/treeLayout.test.tsx`: the notices'
504
+ container between the refresh bar and the document region.
505
+ - `tests/components/modalDialog.test.tsx`, `tests/components/documentEdit.test.tsx`: closing a modal dialog hands the
506
+ focus back to the control that opened it, under the stand-in dialog of `tests/support/dialogStandIn.ts`, which,
507
+ unlike a browser closing a modal dialog, hands none back itself; each press first moves the focus as a real press
508
+ does.
509
+ - `tests/unit/labels.test.ts`: both catalogs carry the 13 viewer keys of markdown 13.0.0 (82 viewer keys in all), the
510
+ 14 keys of the host contract's screens (their texts word for word, a host's override that names a service, a wrong
511
+ type, a blank text, and the spaces around alphanumerics in Japanese) and the split placeholder's four (the English
512
+ resize-panels' defaults word for word, the Japanese spaced, the placeholders per key); a brace outside a placeholder
513
+ is refused at its position, and neither catalog's templates has one. `tests/components/panelGroupLabels.test.tsx`,
514
+ `tests/components/explorerSplit.test.tsx`, `tests/components/editSplit.test.tsx`: the split takes both catalogs and
515
+ the overrides the resolution lets through, refuses the same templates at the same position, and names its
516
+ placeholder by the UI language's summary without a `lang`, with the same labels on every render.
517
+ - `tests/components/document.test.tsx`, `tests/wiring/editTables.test.tsx`: the elements the viewer's labels name
518
+ carry the UI language's `lang` themselves, inside content of the other language and outside it, while the explorer's
519
+ own controls carry none. `tests/components/documentLinks.test.tsx`: an inert link's reason reads in the UI language
520
+ while its text keeps the document's language, or its own `lang="ar"` and `dir="rtl"`, and outside the content it
521
+ names no language; fragment-only links scroll once under a browser and a memory router.
522
+ - `tests/unit/settings.test.ts`: `measure` and `documentColors` are written in the fixed order and read back, a value
523
+ outside the viewer's lists and a key under another name are dropped, a cookie without them is unchanged, and every
524
+ value of the lists round-trips; the reshaped messages. `tests/unit/describeValue.test.ts`: the describer (the cut,
525
+ numbers, bigint, kinds, no call of an object's own `toString`), and each layer's entry cutting a long rejected
526
+ string and refusing a bigint with its own error.
527
+ - `tests/unit/draftAnswer.test.ts`: the six answers, the service client's classes being the same classes, five errors
528
+ thrown again, and the options. `tests/wiring/documentTableCircle.test.tsx`: the circle's diameter reaching a
529
+ document table's grid. `tests/components/explorerPane.test.tsx`: the tree's line colours are the computed colours
530
+ the probe resolves. `tests/components/lockDocumentScroll.test.tsx`: the watch is one function while the flag holds
531
+ and watches nothing unlocked.
532
+ - `scripts/verify-dist.mjs`, `tests/unit/entryPurity.test.ts`, `tests/server/configuration.test.ts`: `./server/core`,
533
+ `./server/browser` and the nesting-guard worker reach no Node built-in, `@aiquants/markdown/server`, `undici` or
534
+ `jsdom`; `./server/core` loads in both formats; the worker is one module that imports nothing, and its notice names
535
+ `entities` and `parse5`; every chunk's notice has its licence file; no public entry's declarations show a type that
536
+ no public entry exports; `./testing` reaches no package and no other entry reaches it; the root entry and
537
+ `./server/core` export `isExplorerDocumentLang`; the server side may import
538
+ `@aiquants/markdown/link-cards`; the built server keeps a document's `lang`; and the link-card handler answers its
539
+ own 500 without the markdown service, its dependencies read from the installed `@aiquants/markdown/server` entry.
540
+ - `tests/support/`: `dialogStandIn.ts`, `documents.ts`, `routerProbes.tsx`, `viewsFromUrl.tsx`, `linkPresses.ts`,
541
+ `linkPages.tsx`, `frames.ts`, `explorerRoot.tsx`, `thrown.ts` and `panelGroupLabels.ts` replace the copies the
542
+ component tests each carried, or support the new ones.
543
+ - `playwright.config.ts`: two projects, `chromium` (every spec) and `webkit` (Desktop Safari, `browser-core.spec.ts`
544
+ only), and the servers it starts get an empty `MARKDOWN_SOCKET_PATH`. `tests/e2e/browser-core.spec.ts` (four tests
545
+ in both engines), on the demo's `/browser-docs` page, where the core runs on the browser runtime over three bundled
546
+ Markdown files: it renders with its tree, follows a document link and starts the nesting-guard worker, reveals a
547
+ document in its folder, round-trips the display settings and keeps the scope without a cookie, and goes from the
548
+ base path to the canonical tree URL, with no request to the data route or another origin and no exception.
549
+ - `tests/e2e/link-cards.spec.ts`: the demo's data route answers with the handler's own 500 and sets no cookie.
550
+ `tests/e2e/document-viewer.spec.ts`, `tests/e2e/embeds.spec.ts`: the elements with names carry the UI language's
551
+ `lang` themselves, a diagram's controls sit inside content of the guide source's language, and an embed frame's
552
+ title comes from the UI language's catalog. `tests/e2e/spreadsheets.spec.ts`: a document table's tap-scroll circle
553
+ is `TAP_SCROLL_CIRCLE_SIZE`. `tests/e2e/single-view.spec.ts`: the style control opens the width and colours
554
+ sections, which `?showStyle=false` hides with it. `tests/e2e/focus-handoff.spec.ts`: each page view's fragment test
555
+ runs with Enter and with a pointer click. `tests/e2e/multi-view.spec.ts`: the display popover's test titles.
556
+
557
+ - `tests/components/folderReadme.test.tsx`: closing the shown folder moves up to the pressed row's parent, to the
558
+ source's README (which the reveal does not move to another source), or to the empty pane at the root, with a
559
+ `close-folder` navigation; double clicks in both modes, the arrow keys (on a row and outside the rows), Collapse
560
+ all, a document shown before the folder closes, "Always expanded" (its hidden expansion kept, a lazy folder opened
561
+ in the reader's expansion), "Show folder READMEs" off, a folder listed in two places, and, after the overrides
562
+ changed, a press on the focused row and a pointer press from outside the tree on the shown folder.
563
+ `tests/components/explorerEntries.test.tsx`: `closeTargetOf` (the folder of the row above, told apart by identity;
564
+ the source's README; nothing; a row not drawn). `tests/components/explorerSheet.test.tsx`: the sheet stays open on a
565
+ move up and closes on a press that opens a folder and on going back to the move's entry.
566
+ `tests/components/navigation.test.tsx`: each kind's router state and `explorerNavigationOf`.
567
+ `tests/components/treeLayout.test.tsx`: after the URL's overrides changed, Enter and a click on the focused row, and
568
+ a pointer press from outside the tree on the Tab stop (the shown row, and the row focused last).
569
+ `tests/components/explorerPane.test.tsx` and `tests/unit/settings.test.ts`: the new switch's row, ring, storage and
570
+ host default, and the settings the multi view hides. `tests/support/routerProbes.tsx`: `LocationProbe` shows the
571
+ router state (`data-router-state`).
572
+
573
+ ### Documentation
574
+
575
+ - README: the package's entries, with a link to the new hosting page; `appOrigins` and `mediaDataPath` in the
576
+ configuration; `planData` and an asset file's `bridge`; the host contract's props and a section on the handle (its
577
+ methods, `ExplorerUnsavedDraft` and the checks of what a host gives); the shared halves of a browser draft converter
578
+ (`draftConversionOf`, `draftAnswerOf`); the split's labels, a template's braces and the language of the viewer's
579
+ labels; the demo's `/browser-docs` page and the two E2E projects; Link cards (the handler opens pages only through
580
+ the markdown service, and without it answers its own `500`, `no-store`), `documentStyles` in the style section of
581
+ the viewer's display popover, the documents' `lang` (with `isExplorerDocumentLang` for a host's own settings) and
582
+ `createFileSystemSource`'s `lang`, the 256-level nesting limit and the deny rules' three decoding levels,
583
+ `lockDocumentScroll`'s check per root element, `./storage` importing no package, the peers' floors with what the
584
+ explorer takes from markdown 13.0.0 and resize-panels 2.3.0, and a document table's circle one control wide.
585
+ - `docs/behavior/hosting.md` (new): what each entry holds and never loads; the steps for running the server half
586
+ inside the page (the core's configuration, the browser runtime's options, the in-process fetch and the route), with
587
+ what a page host must know; the browser runtime's sanitizer; the app's own URLs (`appOrigins`, `mediaDataPath`); and
588
+ streaming files from a bridge with `planData`.
589
+ - `docs/behavior/security.md`: the sanitizing on each runtime, with the browser runtime's guard worker, its refused
590
+ worker fields, node budget, `maxHtmlBytes` cap, admission defaults, deadline across both steps and guard failures;
591
+ the app's own URLs, the presentation attributes and `preload`; the scope on each runtime; the host's duties on each,
592
+ with the `media-src`, `frame-src` and `worker-src` directives; a file of no known kind as a `file` document offered
593
+ for download (it read `unsupported`); the link cards through the markdown service, the `text` operation's answer
594
+ without `lang`, the 256-level depth limit, and the denial of a segment still encoded after three decodes, with
595
+ `deny: []` denying nothing. `docs/behavior/layout.md`: the tree's type icons reach 3:1 against `--aqmx-surface` and
596
+ each tint in both schemes, the display popover and the alignment menu among the parts that stop a held Enter,
597
+ `lockDocumentScroll` per root element, and a document table's circle one control wide.
598
+ `docs/behavior/localization.md`: the viewer's labels of the display popover,
599
+ its width and colours sections and a diagram's notices; the notices above a document, the sign-in texts of an
600
+ `unauthorized` failure, the unversioned save's confirmation and the split placeholder's texts and templates; a brace
601
+ outside a placeholder; and the viewer's labels in the UI language (`labelsLang`). `docs/behavior/dom-hooks.md`: the
602
+ notices' container and each notice with its `data-aqmx-notice`. `docs/behavior/url-contract.md`: `measure` and
603
+ `documentColors` in the display settings.
604
+ - Docstrings: `ExplorerAssetFile.open` (the plain-text view opens the file's head on a HEAD to name its encoding, and
605
+ before the range of a range request), `ExplorerTextDocument` (its text is read by the reading order, the byte-order
606
+ mark, UTF-8 and the legacy encodings, rather than always as UTF-8), and the document table's circle (44 px).
607
+ - README: "Folders and their READMEs" (opening a folder, closing the shown one, double clicks, "Always expanded", the
608
+ keys and Collapse all, and "Show folder READMEs"), `showFolderReadme` among `defaultTreeSettings`, and the tree
609
+ settings the multi view does not offer. `docs/behavior/localization.md`: `settingShowFolderReadme`.
610
+
3
611
  ## 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
612
 
5
613
  ### Breaking