@aiquants/markdown-explorer 0.10.0 → 0.12.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 (49) hide show
  1. package/CHANGELOG.md +26 -1
  2. package/README.md +66 -6
  3. package/dist/EditSurface-BTAhzvHi.js +509 -0
  4. package/dist/EditSurface-Dfj6Sxxb.cjs +2 -0
  5. package/dist/ExplorerSplit-DekOjAUZ.cjs +1 -0
  6. package/dist/{ExplorerSplit-D0zf7Cr_.js → ExplorerSplit-MPHjw3nW.js} +251 -248
  7. package/dist/{MultiLayout-Jy9BKofx.js → MultiLayout-DtSW4rEQ.js} +4 -4
  8. package/dist/{MultiLayout-Bq10p3a3.cjs → MultiLayout-HMzVDYWq.cjs} +1 -1
  9. package/dist/{NativeScrollBar-Dt6xH5Mb.cjs → NativeScrollBar-B0AkVF3E.cjs} +1 -1
  10. package/dist/{NativeScrollBar-CyiyL47o.js → NativeScrollBar-CNQr7JY1.js} +1 -1
  11. package/dist/{TreeLayout-8pRo1ANN.js → TreeLayout-CJO9tOPq.js} +3 -3
  12. package/dist/{TreeLayout-kVWFEKJD.cjs → TreeLayout-_XQR-9tV.cjs} +1 -1
  13. package/dist/client/MarkdownExplorer.d.cts +3 -2
  14. package/dist/client/MarkdownExplorer.d.ts +3 -2
  15. package/dist/core/contracts.d.cts +17 -0
  16. package/dist/core/contracts.d.ts +17 -0
  17. package/dist/core/labels.d.cts +2 -0
  18. package/dist/core/labels.d.ts +2 -0
  19. package/dist/core/treeSettings.d.cts +2 -1
  20. package/dist/core/treeSettings.d.ts +2 -1
  21. package/dist/dataRoute-CH3yOKR0.cjs +1 -0
  22. package/dist/dataRoute-Pm_0ue_4.js +279 -0
  23. package/dist/index-DpIVKG8Y.cjs +13 -0
  24. package/dist/{index-CfcJEnrC.js → index-o6OpR4ND.js} +967 -907
  25. package/dist/index.cjs +1 -1
  26. package/dist/index.d.cts +1 -1
  27. package/dist/index.d.ts +1 -1
  28. package/dist/index.js +9 -9
  29. package/dist/location-BUNWJ4eB.cjs +1 -0
  30. package/dist/{location-Dc1qNEGm.js → location-DWd6SQhN.js} +123 -112
  31. package/dist/{merge-D0aGvFKC.cjs → merge-Bs7o3GyP.cjs} +1 -1
  32. package/dist/{merge-SRCxtHk2.js → merge-DDJaJmMU.js} +1 -1
  33. package/dist/sanitizePolicy-BfUlXI5E.cjs +1 -0
  34. package/dist/sanitizePolicy-djLC3fRN.js +96 -0
  35. package/dist/sanitizeWorker.cjs +1 -1
  36. package/dist/sanitizeWorker.js +143 -226
  37. package/dist/server.cjs +1 -1
  38. package/dist/server.js +548 -540
  39. package/docs/behavior/dom-hooks.md +2 -2
  40. package/docs/behavior/localization.md +1 -0
  41. package/docs/behavior/security.md +2 -0
  42. package/package.json +3 -3
  43. package/dist/EditSurface-1Jf0CG-f.js +0 -371
  44. package/dist/EditSurface-B-l3Do_C.cjs +0 -2
  45. package/dist/ExplorerSplit-WX8afxrQ.cjs +0 -1
  46. package/dist/dataRoute-8pyILcjL.cjs +0 -1
  47. package/dist/dataRoute-Csl1WBDz.js +0 -278
  48. package/dist/index-sNJrKoGN.cjs +0 -13
  49. package/dist/location-CRYkEWiC.cjs +0 -1
package/CHANGELOG.md CHANGED
@@ -1,6 +1,31 @@
1
1
  # Changelog
2
2
 
3
- ## Unreleased
3
+ ## 0.12.0 (2026-10-15)
4
+
5
+ ### Added
6
+
7
+ - **Instant preview** (minor): `<MarkdownExplorer draftConverter>` takes the host's converter of drafts in the browser (`ExplorerDraftConverter`), so the editor's preview renders every keystroke without a round trip; with `@aiquants/markdown` 6.4.0 it is the Go service's converter compiled to WebAssembly (`@aiquants/markdown/converter`, see the README's [Rendering drafts in the browser](README.md#rendering-drafts-in-the-browser)).
8
+ `convert(draft, signal)` answers an `ExplorerDraftAnswer`: the unsanitized rendering (`preview`), a failure, or `unavailable`. The explorer converts one draft at a time (only the latest waiting draft goes next), sanitizes each rendering in the browser with the server's allow-list rules and shows it through a React transition, never `aria-busy`.
9
+ Whether an image or a linked document exists still comes from the server: a table of the marks it answered (`data-asset-exists`, `data-doc-exists`, or none), seeded from the document's own rendering, marks every rendering, and a target the table does not hold is asked about through the `preview` operation once the reader pauses for VERIFY_DELAY_MS (987 ms), one request at a time, with unmarked answers remembered, so typing sends no request.
10
+ Without a converter, and for a draft it answers `unavailable`, the server renders the preview once the reader pauses (SERVER_PREVIEW_DELAY_MS, 610 ms), as before; the preview names the tier of what it shows in `data-aqmx-preview-tier` (`instant` or `server`).
11
+ The optional `prepare()` lets a converter load ahead: the explorer calls it when the reader points at or focuses Edit while the preview is on and fits the pane, or the preview toggle while the preview is hidden. A converter that rejects other than with its signal's reason, answers outside the contract or throws in `prepare` is reported once on the console (the first two are treated as `unavailable`).
12
+ New exports: `ExplorerDraft`, `ExplorerDraftAnswer` and `ExplorerDraftConverter`.
13
+
14
+ ### Changed
15
+
16
+ - Until its first rendering lands, the preview shows the document's own rendering (marked busy) when the document is loaded, instead of the skeleton.
17
+ - The editor hands the preview its text on every change, directly, with no React render per keystroke; it still writes the draft into the session at most every 144 ms.
18
+ - The HTML sanitizer's rules moved to `core/sanitizePolicy` and take the DOMPurify instance to run (the server's workers pass `isomorphic-dompurify`, the editing chunk a DOMPurify of its own from its browser build) and an optional existence lookup (internal; no entry exports it). The server's sanitizing is unchanged.
19
+
20
+ ## 0.11.0 (2026-10-14)
21
+
22
+ ### Added
23
+
24
+ - **Sort by modification time** (minor): the tree's sort order adds `oldest` (Modified old→new, 「更新日時の昇順 (古い順)」) and `newest` (Modified new→old, 「更新日時の降順 (新しい順)」) after the name orders, in the settings menu and in `defaultTreeSettings`.
25
+ They compare the new optional `ExplorerEntry.modifiedAt` (epoch milliseconds, a safe integer, validated like every entry field and carried through the tree and children answers), put the entries a source gives no time last in both directions, and order equal or unknown times by name; the folder placement still applies.
26
+ Rows carry the time as `data-aqmx-modified-at`. `createFileSystemSource` gives every entry its own modification time (`lstat`, links not followed; none for an entry that vanished during the walk). New labels `sortOldest` and `sortNewest`.
27
+
28
+ ## 0.10.0 (2026-10-14)
4
29
 
5
30
  ### Changed
6
31
 
package/README.md CHANGED
@@ -26,8 +26,9 @@ the tree and multi views carry it; another document opens rendered.
26
26
  With the server's `edit` ports, a Markdown document also offers **Edit**: the reader edits its Markdown in place
27
27
  (CodeMirror, loaded on demand), from where they were reading or from the word they double-clicked, saves over the
28
28
  version the draft started from (changes saved elsewhere are merged line by line, and conflicts are resolved in the
29
- editor), previews the draft beside the editor, brings back an older revision, and is asked before an unsaved draft
30
- is lost (see [Editing](#editing)).
29
+ editor), previews the draft beside the editor (on every keystroke with a browser converter, such as
30
+ `@aiquants/markdown`'s Go converter compiled to WebAssembly), brings back an older revision, and is asked before an
31
+ unsaved draft is lost (see [Editing](#editing)).
31
32
  A single-view (embedding) page never downloads the tree and multi-panel views, which load on demand.
32
33
  - **Embeds and link cards** — with `embeds` in the configuration, a link alone in a paragraph shows its post or video from up to ten providers (YouTube, X, Instagram, Threads, TikTok, Bluesky, LinkedIn, Reddit, note and niconico) in a cross-origin frame, with no provider script in the page, or a link card the explorer's own data route reads (`{dataPath}/link-card`, through `@aiquants/markdown`'s link-card handler: internal addresses never become cards); the link itself always stays, under the frame, as the card or as the paragraph.
33
34
  - **Secure by default** — Markdown HTML is sanitized on the server with an allow-list (scripts, event handlers, `srcdoc` and foreign iframes never reach the browser), and the document viewer applies its own on every render (a document keeps only the converter's class tokens, and ids only on headings, footnotes and `user-content-…` targets); document paths are validated, and deny rules hide environment files, keys and version-control metadata through up to three percent-decoding levels; tokens, principals, server paths and raw error messages never leave the server.
@@ -85,7 +86,7 @@ The source ids are not part of it: they are the ids of the server's `sources` (a
85
86
  | `documentStyles?` | `readonly { name, className }[]` | Document styles, the first being the default; `@aiquants/markdown`'s `DEFAULT_MARKDOWN_STYLES` (None, GitHub, Zenn; also exported without React from `@aiquants/markdown/viewer-settings`) when omitted. |
86
87
  | `iframeHosts?` | `readonly string[]` | Host names whose `https:` iframes written in documents may load (exact match); none when omitted. They gate only iframes written in documents; provider frames come from `embeds`, and no iframe of the page's own origin ever renders, whatever is listed. |
87
88
  | `embeds?` | `{ providers?, linkCards?, linkCardSize? }` | What `@aiquants/markdown` makes of a link alone in a paragraph. `providers` lists the ids (`EMBED_PROVIDER_IDS` of `@aiquants/markdown/embeds`: `youtube`, `x`, `instagram`, `threads`, `tiktok`, `bluesky`, `linkedin`, `reddit`, `note`, `niconico`) whose posts and videos documents embed as cross-origin frames, whatever the link's text. `linkCards: true` turns a link written as its own URL into a card, which the data route's own `link-card` operation serves (see [Link cards](#link-cards)): no route of yours is needed. `linkCardSize` picks the size of every card, `compact`, `banner` or `full` (`LINK_CARD_SIZES` of `@aiquants/markdown/embeds`; `@aiquants/markdown`'s `banner` when omitted), and needs `linkCards: true`. Each field defaults to none (`[]`, `false`, omitted), also when given as `undefined`, so without the option such a link stays its paragraph. Repeated ids are removed. An unknown id, a `linkCards` that is not a boolean, an unknown size, a size without `linkCards: true` or an unknown key (`linkCardEndpoint` included) throws a `RangeError` (`[markdown-explorer] embeds…`), and anything but a plain object a `TypeError`. The resolved `config.embeds` is the `MarkdownEmbeds` the viewer takes: `linkCardEndpoint` is `<dataPath>/link-card` when link cards are on and `null` otherwise, and `linkCardSize` is present only when given. See `@aiquants/markdown`'s README (Embeds) for the URLs each provider recognizes, the frames' sizes and the cards' sizes. |
88
- | `defaultTreeSettings?` | `Partial<TreeSettings>` | The reader's tree settings before they change any, merged over the package's `DEFAULT_TREE_SETTINGS` (the source's own order, folders mixed among the files, Single selection, a recursive double click, 8 px expand icons, nothing kept expanded, the open document not revealed, the root indent kept, lines, expand icons and folder and file icons on). Each value is one the settings menu offers: `sortMode` `"native"`, `"asc"` or `"desc"`; `folderPlacement` `"mixed"`, `"first"` or `"last"`; `selectionMode` `"single"`, `"multiple"` or `"none"`; `doubleClickAction` `"recursive"` or `"toggle"`; `expandIconSize` `8`, `13` or `5`; the other settings (`alwaysExpanded`, `revealDocument`, `removeRootIndent`, `lines`, `expandIcons`, `directoryIcons`, `fileIcons`) `true` or `false`. An unknown key or any other value throws a `RangeError`, and anything but a plain object (a `Map`, a class instance, an object inheriting its settings) throws a `TypeError`; a setting given as `undefined` keeps the package default. The server render and the hydration draw these defaults (see [Tree settings](#tree-settings)). |
89
+ | `defaultTreeSettings?` | `Partial<TreeSettings>` | The reader's tree settings before they change any, merged over the package's `DEFAULT_TREE_SETTINGS` (the source's own order, folders mixed among the files, Single selection, a recursive double click, 8 px expand icons, nothing kept expanded, the open document not revealed, the root indent kept, lines, expand icons and folder and file icons on). Each value is one the settings menu offers: `sortMode` `"native"`, `"asc"`, `"desc"`, `"oldest"` or `"newest"` (by the entries' `modifiedAt`); `folderPlacement` `"mixed"`, `"first"` or `"last"`; `selectionMode` `"single"`, `"multiple"` or `"none"`; `doubleClickAction` `"recursive"` or `"toggle"`; `expandIconSize` `8`, `13` or `5`; the other settings (`alwaysExpanded`, `revealDocument`, `removeRootIndent`, `lines`, `expandIcons`, `directoryIcons`, `fileIcons`) `true` or `false`. An unknown key or any other value throws a `RangeError`, and anything but a plain object (a `Map`, a class instance, an object inheriting its settings) throws a `TypeError`; a setting given as `undefined` keeps the package default. The server render and the hydration draw these defaults (see [Tree settings](#tree-settings)). |
89
90
 
90
91
  For example, `defaultTreeSettings: { sortMode: "desc" }` lists every folder's entries by name, Z to A, until the reader picks another order.
91
92
 
@@ -333,6 +334,7 @@ The published type declarations carry no doc comments, so the shapes a source re
333
334
  | `path` | `string` | The document path that `document()` resolves and URLs carry. A path names one document; it may appear in several sources' trees (sources may overlap). It must lie inside the listing source's boundary. |
334
335
  | `type` | `"file" \| "directory"` | A file opens as a document; a directory holds entries. |
335
336
  | `mimeType?` | `string` | Handed on to the tree's row. |
337
+ | `modifiedAt?` | `number` | When the source last saw the entry change, in epoch milliseconds (a safe integer; any other value fails the listing). The tree's Modified old→new and new→old orders read it, putting the entries without it last; leave it out when the source does not know (a GCS folder is only a prefix). `createFileSystemSource` gives every entry its own modification time. |
336
338
  | `children?` | `ExplorerEntry[]` | A directory's entries; never on a file. |
337
339
  | `lazy?` | `boolean` | `true` marks a directory whose entries come from the source's `children()` when the reader opens it: the source needs `children()`, and the entry lists no children (an empty array at most). |
338
340
 
@@ -614,6 +616,7 @@ Spread it into the configuration when your application has no sign-in: it provid
614
616
  | `lockDocumentScroll?` | `boolean` | Stops the page itself from scrolling while the explorer fills the viewport; the explorer must then fit in the viewport (see below). |
615
617
  | `onMathDiagnostics?` | `(path, diagnostics: readonly MarkdownMathDiagnostic[]) => void` | Receives the KaTeX diagnostics of a markdown document once it rendered (never during render), with the document's path; the reader's console never sees them. `MarkdownMathDiagnostic` (`{ code, message, formula, displayMode }`) comes from `@aiquants/markdown`. The explorer reaches your function through one stable function, so passing a new function on every render neither parses the document again nor delivers its diagnostics twice; text documents report none. |
616
618
  | `onEditGrant?` | `(href: string) => Promise<boolean>` | Lets the reader grant what an edit or a save asked for (`{ kind: "grant", href }`, see [Editing](#editing)): open your root-relative `href` as you see fit (a consent popup, for example) and resolve whether the reader came back from it; the editor then asks again. Without it, the editor links to `href` in a new tab beside Try again. |
619
+ | `draftConverter?` | `ExplorerDraftConverter` | Renders drafts in the browser, so the editor's preview follows every keystroke (see [Rendering drafts in the browser](#rendering-drafts-in-the-browser)). Without it the server renders the preview once the reader pauses. The explorer reaches your converter through one stable object, so passing a new one on every render does not restart the preview. |
617
620
 
618
621
  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.
619
622
  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.
@@ -652,9 +655,65 @@ While a document is edited, the bar shows the draft's status on one line and the
652
655
  The editor (CodeMirror 6, loaded when the reader first points at or focuses Edit) fills the pane where it can and grows with its text in a panel that is not maximized; Escape inside it is consumed, so a maximized panel stays maximized, and Tab leaves it.
653
656
  A save writes the draft back with the line endings of the file it opened (`\r\n` when the file held one, `\n` otherwise), so editing never rewrites the lines the reader left alone; a file that already mixed endings is saved with `\r\n` throughout.
654
657
  A save that meets changes saved elsewhere merges them line by line: changes on different lines are saved at once; lines both sides changed differently are written between git-style markers with buttons above each conflict (keep my lines, the saved lines, or both), and Next conflict moves the focus to those buttons. A draft with markers left is not saved.
655
- The preview renders the draft as the document would be, beside the editor (below it on a narrow pane), once the reader pauses typing, and keeps the block of the editor's top line level with it; whether it shows is the reader's choice, kept in browser storage under `storageNamespace` (default off). History lists the revisions, shows the one picked and puts it into the draft, to be saved like any draft.
658
+ The preview renders the draft as the document would be, beside the editor (below it on a narrow pane), and keeps the block of the editor's top line level with it: on every keystroke with a `draftConverter`, else once the reader pauses typing (SERVER_PREVIEW_DELAY_MS, 610 ms). Until its first rendering lands it shows the document's own rendering (the skeleton when the document is not loaded), and afterwards the last rendering stays until the next one lands, so it never flashes empty. Whether it shows is the reader's choice, kept in browser storage under `storageNamespace` (default off). History lists the revisions, shows the one picked and puts it into the draft, to be saved like any draft.
656
659
  Drafts last while the explorer is mounted, across view switches and remounted panels. A navigation that would take a document with an unsaved draft off the page asks first (the explorer holds the router's one blocker, so render one explorer per router), and leaving the page asks through `beforeunload` while a document is edited.
657
660
 
661
+ #### Rendering drafts in the browser
662
+
663
+ `draftConverter` lets the preview render every draft in the browser, with the conversion your server makes, so the preview follows the reader's typing instead of waiting for a pause and a round trip. With `@aiquants/markdown` the converter is its browser converter, the Go service's converter compiled to WebAssembly (`@aiquants/markdown/converter`); give it the options your server's conversion uses, and the HTML limit of the explorer's sanitizer (`sanitizer.maxHtmlBytes`, 4 MiB by default), so a draft too large for the server is too large in the browser too:
664
+
665
+ ```ts
666
+ import { type BrowserConversion, createMarkdownConverter, MarkdownConversionError, MarkdownConversionTimeoutError, type MarkdownConverter, MarkdownResourceExhaustedError } from "@aiquants/markdown/converter"
667
+ import converterWasmUrl from "@aiquants/markdown/converter.wasm?url"
668
+ import converterWorkerUrl from "@aiquants/markdown/converter/worker?worker&url"
669
+ import { DEFAULT_DENIED_PATH_SEGMENTS, type ExplorerDraftAnswer, type ExplorerDraftConverter, failureDocument } from "@aiquants/markdown-explorer"
670
+
671
+ // In a browser-only module (React Router: `draftConverter.client.ts`)
672
+ let converter: MarkdownConverter | null = null
673
+ let started = false
674
+ const converterOf = (): MarkdownConverter => (converter ??= createMarkdownConverter({ workerUrl: converterWorkerUrl, wasmUrl: converterWasmUrl, timeoutMs: 10_000 }))
675
+ const conversionOf = (markdownText: string, filePath: string): BrowserConversion => ({
676
+ markdownText,
677
+ filePath, // a workspace document's path under the root below, or its gcs:// / gdrive:// URI
678
+ workspaceRoot: "/workspace",
679
+ options: { deniedPathSegments: [...DEFAULT_DENIED_PATH_SEGMENTS], maxHtmlBytes: 4 * 1024 * 1024, includeSourceLines: true },
680
+ })
681
+
682
+ const answerOf = (error: unknown): ExplorerDraftAnswer => {
683
+ if (error instanceof MarkdownResourceExhaustedError || error instanceof MarkdownConversionTimeoutError) return failureDocument("too-large")
684
+ if (!(error instanceof MarkdownConversionError)) throw error
685
+ if (error.code === "unavailable") return { kind: "unavailable" }
686
+ return failureDocument(error.code === "invalid_argument" ? "invalid" : "failed")
687
+ }
688
+
689
+ export const draftConverter: ExplorerDraftConverter = {
690
+ convert: async ({ path, text }, signal) => {
691
+ started = true
692
+ try {
693
+ const { htmlContent, headings } = await converterOf().convert(conversionOf(text, path), signal)
694
+ return { kind: "preview", htmlContent, headings }
695
+ } catch (error) {
696
+ if (signal.aborted) throw signal.reason
697
+ return answerOf(error)
698
+ }
699
+ },
700
+ // Starts the worker and its WebAssembly ahead of the first draft; a short document warms the first conversion up
701
+ prepare: () => {
702
+ if (started) return
703
+ started = true
704
+ converterOf().convert(conversionOf("# Heading\n\n- [A link](other.md) and `code`\n", "warm-up.md")).catch(() => undefined)
705
+ },
706
+ }
707
+ ```
708
+
709
+ - **The contract.** `convert(draft, signal)` receives the document's path as the explorer names it and the draft's text, and resolves to `{ kind: "preview", htmlContent, headings }` (unsanitized, without existence marks), a failure document (shown over the last rendering, as a failed preview is; more than `EXPLORER_MAX_HEADINGS` headings is `too-large`, as on the server), or `{ kind: "unavailable" }` when the converter cannot run, for which the server renders that draft. It rejects only with the signal's reason once the signal aborted. Any other rejection, or an answer outside the contract, is a bug: the explorer reports it once on the console and treats it as `unavailable`.
710
+ - **Loading ahead.** `prepare()`, when given, is called when the reader is about to see the preview — they point at or focus Edit while the preview is on and fits the pane, or point at or focus the preview toggle — so the worker and its WebAssembly (about 0.4 s to start in Chromium) load before the first draft. The explorer may call it many times: return at once and do the work once.
711
+ - **One draft at a time.** The explorer converts the first draft at once; a draft that arrives while another converts waits, and only the latest waiting draft is converted next (a WebAssembly call cannot be interrupted, so the running one is never aborted). It aborts the signal only when the preview goes away. A rendering is shown without `aria-busy`, through a React transition, so typing goes ahead of it.
712
+ - **The server's rules.** Each rendering is sanitized in the browser with the allow-list rules the server applies to every document (the same module, on a DOMPurify instance of the preview's own from `isomorphic-dompurify`'s browser build, part of the editing chunk), so the instant preview shows what the saved document will.
713
+ - **Which targets exist.** Only the server can tell whether an image or a linked document exists. The preview keeps a table of the marks the server answered (`data-asset-exists`, `data-doc-exists`, or none), seeded from the document's own rendering, and writes the known ones onto every rendering. When a rendering names a target the table does not hold, the preview asks the data route's `preview` operation about the newest draft once the reader has paused for VERIFY_DELAY_MS (987 ms), one request at a time, learns the marks of the answer, remembers every asked target the answer left unmarked (or a failed answer did not reach) as having none, and renders the newest draft again. So the server is asked about a target once, and a draft that adds no new image or link causes no request at all; a missing image the reader just added shows as a broken image until the answer lands, then as the viewer's missing-image placeholder.
714
+ - **The server tier.** Without a converter, and for a draft the converter answers `unavailable` (its WebAssembly could not load, for example), the server renders the draft once the reader has paused for SERVER_PREVIEW_DELAY_MS (610 ms); the last rendering stays on screen marked `aria-busy` meanwhile, and a newer draft aborts the request. The preview names the tier of what it shows in `data-aqmx-preview-tier` (`instant` or `server`).
715
+ - **Content Security Policy.** A page that sets `script-src` needs `'wasm-unsafe-eval'` in it for the WebAssembly, and `worker-src 'self'` (or a `script-src` covering the worker) for the same-origin worker.
716
+
658
717
  ### Localization
659
718
 
660
719
  `locale` selects a built-in catalog (`MARKDOWN_EXPLORER_LABEL_CATALOGS.en` / `.ja`); `labels` overrides single keys.
@@ -707,7 +766,7 @@ Every scroller of the explorer that the reader browses gets one pointer scroll b
707
766
  - File bytes are served only by the explorer's `asset` operation, after the deny rules and the document admission, inline only for raster images, audio, video and PDF, always with `nosniff` and a `same-origin` resource policy, and with a sandboxing policy except for PDF, under which inline audio and video keep the URL's origin (`allow-same-origin`, no `allow-scripts`) (see [Serving files](#serving-files)).
708
767
  - A Markdown document's source (the Source toggle) is read only by the explorer's `text` operation, through the same `asset` port after the same deny rules and admission, so it serves nothing the reader could not already download: at most `textMaxBytes` of the file's beginning, decoded as UTF-8 into JSON, which the browser shows as text and never interprets.
709
768
  - Data responses are `private, no-store` JSON with `nosniff`, a sandboxing content security policy and `same-origin` resource policy, and the data route refuses React Router's single-fetch requests (`.data`), whose answers would carry none of those headers; the tree refresh, and a document request marked as triggered by a refresh (`X-Markdown-Explorer: refresh`, which makes the host skip its caches), require the custom request header and pass the shared cross-origin check of server routes (`@aiquants/request-isolation`).
710
- - Editing writes only through the host's `edit` ports, after the deny rules and the same admission as a document. A save and a preview need the custom header `X-Markdown-Explorer: edit` and pass the shared cross-origin check, and their draft is read and checked (media type, `editMaxBytes`, UTF-8 without NUL) before any port is called; a grant's `href` must be root-relative and an external editor's `https:`; the preview is sanitized exactly as a document. The host checks in every port that the reader may edit the document, and writes only over the version the draft started from.
769
+ - Editing writes only through the host's `edit` ports, after the deny rules and the same admission as a document. A save and a preview need the custom header `X-Markdown-Explorer: edit` and pass the shared cross-origin check, and their draft is read and checked (media type, `editMaxBytes`, UTF-8 without NUL) before any port is called; a grant's `href` must be root-relative and an external editor's `https:`; the preview is sanitized exactly as a document. A draft the host's browser converter renders (`draftConverter`) is sanitized in the browser with the same allow-list rules before it is shown, and never leaves the browser; only the existence marks come from the server's answers. The host checks in every port that the reader may edit the document, and writes only over the version the draft started from.
711
770
  - Link cards are read by `@aiquants/markdown`'s handler behind a read-only authentication (no token refresh, no `Set-Cookie`; an authentication that carries headers is refused and logged), and its guards keep every internal address from becoming a card; see [Link cards](#link-cards).
712
771
  - Each data response carries an opaque, pseudonymous scope (an HMAC of the principal key under `scopeSecret`); when it changes, the browser drops every cache and remembered path. Browser storage is also checked against the page's scope on every page load, before anything reads it.
713
772
 
@@ -721,6 +780,7 @@ Tests and host styling may rely on the `data-testid` and `data-aqmx-*` attribute
721
780
 
722
781
  - One explorer per page: the drag-and-drop layout looks up its panels document-wide.
723
782
  - Merges are line-based (node-diff3): changes on adjacent lines, or on the same line, conflict even when they would combine. A panel that is not maximized shows no preview; maximize it to see one.
783
+ - The browser applies the server sanitizer's allow-list rules and nesting limit (512 levels, which Chromium's own parser never exceeds), but not its other resource limits (parsed nodes, attributes, worker heap, time): the host's converter bounds a draft's HTML with `maxHtmlBytes` instead. The existence marks of a target the reader just added arrive about a second after they pause, so until then a new image that does not exist shows as a broken image, and a new link to a missing document as an ordinary link.
724
784
  - A held Enter acts once on every control inside the explorer, those of other packages included (the tree's rows, the panel headers' buttons, the document viewer's toolbar and the controls inside a document), except Zoom in and Zoom out, which keep stepping while a press that began on them is held (see [Held keys](docs/behavior/layout.md#held-keys)): a press that hands the focus to them, such as following a link to an image, does not step them. The repeated keydowns end at the explorer's root, so a keydown listener the host attaches outside the explorer for the bubbling phase does not receive them either.
725
785
  - A loop row (a folder met again among its own ancestors) shows an expand glyph and `aria-expanded="false"` like any closed folder, because `@aiquants/directory-tree` has no row that cannot expand; it never opens. The 4 listings in flight are counted per explorer, not across browser tabs.
726
786
  - Document kinds are the five above; `createFileSystemSource` previews only files with a known text extension or name as text and offers any other file as a `file` document (a download).
@@ -737,7 +797,7 @@ Tests and host styling may rely on the `data-testid` and `data-aqmx-*` attribute
737
797
  The source repository holds a runnable demo next to the package (`packages/markdown-explorer/demo`): three file-system sources with anonymous access (`guide` and `notes`, kept apart by their path prefix, with one folder of the guide, `guide/a`, served lazily through `children`; and `reference`, rooted at the folder `guide/reference` inside `guide`, so a document under it appears in two trees under the same path),
738
798
  the page and data routes, the error boundary, document and asset ports that route each path to the first source whose boundary contains it (no asset route of its own), a Markdown parser that produces document links and image targets, GitHub alerts, Zenn's message and details containers, embed placeholders, and footnotes, task lists and formulas in the Go converter's markup,
739
799
  every embed provider and link cards served by the data route (`embeds: { providers, linkCards: true }`; `guide/reference/embeds.md` and `guide/reference/link-cards.md` show them; the end-to-end tests answer the browser's card requests from their own fixtures, so they stay offline),
740
- editing (the parser writes source lines; the Markdown of `notes` is edited in place and saved to memory, never to the files, per draft space named by a cookie so tests never share saves; `guide/reference/embeds.md` links to an external editor), and the end-to-end tests' fixtures.
800
+ editing (the parser writes source lines; the Markdown of `notes` is edited in place and saved to memory, never to the files, per draft space named by a cookie so tests never share saves; `guide/reference/embeds.md` links to an external editor), the instant preview with `@aiquants/markdown`'s browser converter as `draftConverter` (`demo/app/draft-converter.client.ts`), and the end-to-end tests' fixtures.
741
801
  Run it with `pnpm run demo:dev` from the package folder.
742
802
 
743
803
  ## License