@aiquants/markdown-explorer 0.5.0 → 0.7.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 (66) hide show
  1. package/CHANGELOG.md +49 -0
  2. package/README.md +65 -8
  3. package/dist/EditSurface-BCB-0vUK.js +371 -0
  4. package/dist/EditSurface-BZ98L7hy.cjs +2 -0
  5. package/dist/ExplorerSplit-BTRTah7R.cjs +1 -0
  6. package/dist/{ExplorerSplit-CWcK1E4I.js → ExplorerSplit-DpoMtzq3.js} +391 -417
  7. package/dist/MultiLayout-B7OiXgWH.cjs +1 -0
  8. package/dist/MultiLayout-BD2LiwOe.js +947 -0
  9. package/dist/{NativeScrollBar-DbzyQ85y.cjs → NativeScrollBar-B4j3Vigb.cjs} +1 -1
  10. package/dist/{NativeScrollBar-apXjIKRW.js → NativeScrollBar-EXOKhHP4.js} +1 -1
  11. package/dist/TreeLayout-B9dF2A3h.cjs +1 -0
  12. package/dist/TreeLayout-hn2bfU22.js +29 -0
  13. package/dist/client/MarkdownExplorer.d.cts +2 -1
  14. package/dist/client/MarkdownExplorer.d.ts +2 -1
  15. package/dist/client/storage.d.cts +1 -0
  16. package/dist/client/storage.d.ts +1 -0
  17. package/dist/core/contracts.d.cts +67 -6
  18. package/dist/core/contracts.d.ts +67 -6
  19. package/dist/core/labels.d.cts +53 -0
  20. package/dist/core/labels.d.ts +53 -0
  21. package/dist/core/location.d.cts +7 -0
  22. package/dist/core/location.d.ts +7 -0
  23. package/dist/dataRoute-CcZ8PK00.cjs +1 -0
  24. package/dist/dataRoute-D1vE1wFW.js +270 -0
  25. package/dist/index-C0gh_dRY.js +3188 -0
  26. package/dist/index-CCc6qUbM.cjs +5 -0
  27. package/dist/index.cjs +1 -1
  28. package/dist/index.d.cts +1 -1
  29. package/dist/index.d.ts +1 -1
  30. package/dist/index.js +32 -31
  31. package/dist/location-DmzVAFvo.cjs +1 -0
  32. package/dist/{location-c1zdeySY.js → location-Q4sgRrUm.js} +202 -193
  33. package/dist/merge-0W6xtIxj.cjs +5 -0
  34. package/dist/merge-Bi41vtSe.js +20 -0
  35. package/dist/sanitizeWorker.cjs +1 -1
  36. package/dist/sanitizeWorker.js +173 -172
  37. package/dist/server/errors.d.cts +1 -1
  38. package/dist/server/errors.d.ts +1 -1
  39. package/dist/server/ports.d.cts +34 -1
  40. package/dist/server/ports.d.ts +34 -1
  41. package/dist/server.cjs +1 -1
  42. package/dist/server.d.cts +1 -1
  43. package/dist/server.d.ts +1 -1
  44. package/dist/server.js +889 -729
  45. package/dist/{storage-DA4ItHzl.js → storage-BSthKLSG.js} +14 -13
  46. package/dist/storage-Dgi4JXaB.cjs +1 -0
  47. package/dist/storage.cjs +1 -1
  48. package/dist/storage.js +1 -1
  49. package/dist/styles/markdown-explorer.css +1 -1
  50. package/docs/behavior/dom-hooks.md +20 -3
  51. package/docs/behavior/layout.md +11 -0
  52. package/docs/behavior/localization.md +4 -1
  53. package/docs/behavior/security.md +21 -4
  54. package/docs/behavior/url-contract.md +13 -4
  55. package/package.json +14 -5
  56. package/dist/ExplorerSplit-ajN3GSdA.cjs +0 -1
  57. package/dist/MultiLayout-BtWtCzJV.js +0 -922
  58. package/dist/MultiLayout-DvkcdO9c.cjs +0 -1
  59. package/dist/TreeLayout-BcHsv9G8.js +0 -23
  60. package/dist/TreeLayout-rwhJfLmU.cjs +0 -1
  61. package/dist/dataRoute-Btg4w3vO.js +0 -205
  62. package/dist/dataRoute-DHpu0fg2.cjs +0 -1
  63. package/dist/index-CIZw73j9.js +0 -2154
  64. package/dist/index-Cie6WPiM.cjs +0 -3
  65. package/dist/location-CSIhx-L4.cjs +0 -1
  66. package/dist/storage-Bkb2Axdi.cjs +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,54 @@
1
1
  # Changelog
2
2
 
3
+ ## Unreleased
4
+
5
+ ### Added
6
+
7
+ - **Editing a Markdown document** (minor): a host that gives the server the new `edit` ports lets readers edit Markdown documents in place, and the explorer brings everything around the edit — opening where the reader is, saving over the version the draft started from, merging what was saved meanwhile, a preview, the revisions and a guard for unsaved drafts.
8
+ - The document bar offers an **Edit** toggle (`aria-pressed`) between Source and Refresh document for a document whose `edit` is `{ kind: "inline" }` — labelled beside a page view's pane (`editDocumentLabel`, tooltip `editDocument`), icon-only and named after the document in a multi-view panel (`editDocumentNamed`) — or a link to the document's own editor in a new tab for `{ kind: "external", href }` (`editExternallyLabel`, `editExternally`, `editExternallyNamed`).
9
+ Pressing it opens the editor with the block at the top of the reader's view at the same place on screen; pressed again it closes the editor, asking first when the draft is unsaved (`unsavedTitle`, `unsavedBody`, `unsavedDiscard`, `unsavedStay`), and puts the editor's top line back at the same place in the rendered document (again on the fresh copy a save made the pane read, unless the reader moved meanwhile). The toggle is the same element in both states, so the focus stays on it.
10
+ - A double-click on a word of the rendered document opens the editor with the cursor on that word, which stays where it was on screen, in the tree and single views and in a maximized panel; a panel that is not maximized maximizes on a double-click as before. Links, controls, embedded media and drawings keep their own double-click. Places on screen are matched through the converter's source lines (`data-source-lines`, `@aiquants/markdown` 6.3's `includeSourceLines`), text to text.
11
+ - While a document is edited, the bar shows the session's status on one line (`editLoading`, `draftUnsaved`, `draftSaving`, `draftSaved`, `draftSavedMerged`, `draftConflicts`, `draftSaveFailed`) and the editor's actions: Next conflict while conflicts wait, the **Preview** toggle where the pane has room (a page view, a maximized panel), **History** when the host keeps revisions, **Save** (`aria-disabled` until the draft changes; Ctrl/⌘+S in the editor) and the Edit toggle; the source toggle and Refresh document step aside.
12
+ The announcer speaks each save's outcome (`documentSaved`, `documentSavedMerged`, …).
13
+ - The editor is CodeMirror 6 in a chunk loaded on demand (pointing at or focusing Edit starts the download; a chunk that fails to load shows a failure with Try again inside the pane): Markdown with GitHub's extensions, syntax colours from the explorer's tokens at 7:1, line numbers, wrapping, search, undo. Escape inside the editing surface is consumed, so a maximized panel stays maximized; Tab leaves the editor; a held Enter repeats inside it.
14
+ It fills the pane in a page view and a maximized panel and grows with its text in a panel that is not maximized. Every scroll it asks for moves the pane's own scroller only.
15
+ - Saving names the version the draft started from. When the document changed meanwhile, the draft is merged line by line (node-diff3, loaded only then) into the document as it is now: changes on different lines are saved at once (at most three writes per save), lines both sides changed differently become conflicts between git-style markers (`conflictOurs`, `conflictTheirs`) with buttons above each that keep the reader's lines, the saved lines or both (`conflictUseOurs`, `conflictUseTheirs`, `conflictKeepBoth`);
16
+ Next conflict (`conflictNext`) moves the cursor there and the focus to its first button. A draft that still holds markers is not saved.
17
+ - The preview renders the draft as the document would be (the data route's `preview` operation, sanitized like a document) beside the editor, or below it on a narrow pane, once the reader paused typing, and follows the editor's top line. Whether it shows is a setting of the reader kept in browser storage (default off).
18
+ - The revisions dialog lists the revisions the host keeps (`historyTitle`, `historyCurrent`, `historyKept`, `historyEntry`), shows the one picked and puts it into the draft (`historyRestore`, `historyRestored`), saved like any draft.
19
+ - A navigation that would take a document with an unsaved draft off the page asks first (one blocker per router); leaving the page asks through `beforeunload` only while a document is edited. Drafts survive remounts and view switches for the reader's lifetime of the explorer.
20
+ - A save or an edit the server answers with a grant shows a notice (`editGrantTitle`, `editGrantBody`, `editGrantAction`, `editGrantRetry`): with the new `<MarkdownExplorer onEditGrant>` the host opens the grant (a consent popup, for example) and the explorer asks again once it resolves `true`; without it, a link opens the grant in a new tab beside Try again.
21
+ - The server's new `edit` ports (`ExplorerEditPorts`: `source`, `save`, `preview`, `revisions`, `revision`) back the data route's new operations `edit` (GET), `save` and `preview` (POST, the draft as `text/markdown; charset=utf-8` with `X-Markdown-Explorer: edit` and the shared cross-origin check), `revisions` and `revision` (GET), behind the same authentication, deny rules (reported) and admission as a document. The draft is limited to `editMaxBytes` (default 2 MiB), must be UTF-8 without NUL, and is read before the host is called;
22
+ versions and revision ids are tokens of 1 to `EXPLORER_EDIT_TOKEN_MAX_LENGTH` (1024) characters. Without `edit`, the operations answer like unknown ones.
23
+ - New exports: `ExplorerEditPorts`, `ExplorerHostEditSource`, `ExplorerDraft`, `ExplorerHostSaveResult`, `ExplorerHostPreview` (server entry), `ExplorerDocumentEdit`, `ExplorerGrantRequired`, `ExplorerRevision` and `EXPLORER_EDIT_TOKEN_MAX_LENGTH` (root entry). New DOM hooks for the editor, its status, actions, preview, grant notices, the confirmation and the revisions dialog (see [DOM hooks](docs/behavior/dom-hooks.md)); the region's `data-aqmx-document-view` gains `edit`.
24
+ - The server's sanitizer keeps the converter's source lines (`data-source-lines` in the form `<first>-<last>`) on any element.
25
+
26
+ ### Changed
27
+
28
+ - **Source in the URL** (minor): whether a Markdown document shows as written is part of the URL (`markup`), so a reload, a shared link and Back and Forward show it the same way. The tree and single views write `markup=true` for their document, the multi view one `markup=<document>` per open document shown as written, in the order of `doc`; the Source toggle replaces the entry (in a page view without the fragment, so the swapped content is not taken back to its target).
29
+ - The choice belongs to the document in the URL, no longer to the reader: another document, a panel navigated to another document and a reopened panel show rendered, while a source switch, the reveal's move of the tree and the switches between the tree and multi views (the view switch, opening a selection that holds the tree view's document) carry it. The document still shown while the next one loads keeps the way it showed.
30
+ - `ExplorerLocation` gains `markup` (a boolean in the tree and single views, a list in the multi view) and `ExplorerHrefTarget` an optional `markup`; `explorerHref` refuses a multi-view document shown as written that is not open or repeats, and a tree view without a document shown as written. The resolver redirects a multi-view `markup` that is not canonical (not open, repeated, out of order) and ignores a tree or single value other than `true`.
31
+ - **Breaking for hosts:** a Markdown document a host's `document` port answers must carry `edit` — `null`, `{ kind: "inline" }` (only with the `edit` ports) or `{ kind: "external", href }` with an absolute `https:` URL. A Markdown document without it is a contract violation (logged, and the reader sees `failed`); `createFileSystemSource` answers `edit: null`.
32
+
33
+ ## 0.6.0 (2026-10-13)
34
+
35
+ ### Added
36
+
37
+ - **Source of a Markdown document** (minor): the document bar offers a **Source** toggle before Refresh document while its document is a loaded Markdown document — labelled beside a page view's pane (`showMarkupLabel` «Source» / 「ソース」, tooltip `showMarkup`), icon-only and named after the document in a multi-view panel (`showMarkupNamed`) — a toggle button (`aria-pressed`) that shows the document as written instead of rendered, in place, keeping the focus on the toggle.
38
+ - The pane reads the document's file through the data route's new `text` operation and shows it like a text file (the file header with Open and Download, `textTruncated` when the file was cut, the text never interpreted): the skeleton until the first answer (`markupLoading` for screen readers), a failure announced once (`documentFailed`) with Try again for a `failed` read, and the text read again on every new answer for the document (Refresh document, Refresh tree, a revalidation) while the previous text stays.
39
+ - The choice belongs to the reader and the document (one choice per reader): every view showing the document follows it, a document the reader comes back to keeps it, and nothing is saved. The document region carries `data-aqmx-document-view` (`rendered` / `markup`) for a Markdown document; new DOM hooks `markdown-explorer-document-markup`, `markdown-explorer-markup-skeleton` and `markdown-explorer-markup-failure`.
40
+ - The data route's `text` operation (`GET <dataPath>/text?path=<document>`, GET and HEAD) answers a text document (`name`, `text`, `truncated`, the asset `url`) or a failure document, behind the same authentication, deny rules (a refusal logged with the operation `text`) and admission as `asset`,
41
+ reading the file through the host's `asset` port: at most `textMaxBytes` bytes (a range when the reported size is larger, one byte past the limit when the size is unknown), decoded as UTF-8 (a leading byte order mark dropped, a multi-byte character the limit cuts left out), `unsupported` for bytes holding NUL, `failed` (logged) for a stream short of its reported size.
42
+ No host change is needed.
43
+ - The server option `textMaxBytes` (a positive integer up to 256 MiB; default 2 MiB) bounds it; `ExplorerOperation` gains `"text"`.
44
+ - New labels `showMarkupLabel`, `showMarkup`, `showMarkupNamed` and `markupLoading` (English and Japanese).
45
+
46
+ ### Changed
47
+
48
+ - **The refresh's proof of origin is the shared cross-origin check of server routes** (`crossOriginRefusal` of `@aiquants/request-isolation`, a new dependency, serving no navigation from another origin): the tree refresh and a document request marked as a refresh still need the custom header `X-Markdown-Explorer: refresh`, and now pass that one check instead of the explorer's own reading of `Sec-Fetch-Site`.
49
+ - A refresh `POST` without Fetch Metadata is now refused (403) when its `Origin` names another host or port, is `null` or is not a URL; before, any request without `Sec-Fetch-Site` passed. A request without `Origin` still passes, and so does a marked document `GET` without Fetch Metadata, whatever its `Origin`.
50
+ - `Sec-Fetch-Site: none` (a load the user started, which a fetch never sends) now passes, as `same-origin` does. `same-site` and `cross-site` are refused as before.
51
+
3
52
  ## 0.5.0 (2026-10-09)
4
53
 
5
54
  ### Added
package/README.md CHANGED
@@ -18,6 +18,15 @@ document. The document stays on screen while it reloads and is replaced in place
18
18
  reloaded document is announced, and a failed reload keeps the document under a notice naming the failure, which is
19
19
  announced too and stays until a newer copy of the document replaces or confirms it, the reader moves to another
20
20
  document, or the next refresh starts.
21
+ Beside it, a Markdown document offers **Source**: a toggle that shows the document as written instead of rendered
22
+ (its file read through the data route's `text` operation, shown like a text file). The choice is part of the URL
23
+ (`markup`), so a reload, a shared link and Back and Forward show the document the same way, and the switches between
24
+ the tree and multi views carry it; another document opens rendered.
25
+ With the server's `edit` ports, a Markdown document also offers **Edit**: the reader edits its Markdown in place
26
+ (CodeMirror, loaded on demand), from where they were reading or from the word they double-clicked, saves over the
27
+ version the draft started from (changes saved elsewhere are merged line by line, and conflicts are resolved in the
28
+ editor), previews the draft beside the editor, brings back an older revision, and is asked before an unsaved draft
29
+ is lost (see [Editing](#editing)).
21
30
  A single-view (embedding) page never downloads the tree and multi-panel views, which load on demand.
22
31
  - **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.
23
32
  - **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.
@@ -28,7 +37,7 @@ A single-view (embedding) page never downloads the tree and multi-panel views, w
28
37
 
29
38
  - React 19.2.7 or later and React Router 8 in framework mode (route modules with `loader` / `headers`).
30
39
  - Node.js 22.22 or later (the floor React Router 8 declares). The package ships ES modules and CommonJS; the CommonJS entries load the ESM-only `react-router` through `require(esm)`.
31
- - The peer packages, at these versions or later within the caret ranges the package declares: `@aiquants/markdown` ^6.2.0 (document rendering; its math diagnostics, gantt sizing, embeds, link cards and their sizes, the React-free `@aiquants/markdown/embeds` the sanitizer worker loads, and the Node-only link-card handler of `@aiquants/markdown/server`, which needs Node.js 22.13 or later — below the explorer's own floor),
40
+ - The peer packages, at these versions or later within the caret ranges the package declares: `@aiquants/markdown` ^6.3.0 (document rendering; its math diagnostics, gantt sizing, embeds, link cards and their sizes, the React-free `@aiquants/markdown/embeds` the sanitizer worker loads and `@aiquants/markdown/source-lines` the editor and the sanitizer read, and the Node-only link-card handler of `@aiquants/markdown/server`, which needs Node.js 22.13 or later — below the explorer's own floor),
32
41
  `@aiquants/directory-tree` ^4.1.1 (reveals of rows under the scroll bar's buttons), `@aiquants/drag-drop-panels` ^0.10.0, `@aiquants/resize-panels` ^2.1.0 (the source of each layout change, by which the tree pane's width is saved) and `@aiquants/virtualscroll` ^3.11.4.
33
42
  The client depends on these floors, while a package manager may only warn about an older peer.
34
43
  - A Markdown parser of your choice on the server that produces HTML and its headings (the explorer sanitizes the HTML before it is sent).
@@ -243,15 +252,16 @@ to; load it when your documents contain math.
243
252
  | View | URL | What it shows |
244
253
  | --- | --- | --- |
245
254
  | Tree | `{basePath}/{tree}` or `{basePath}/{tree}/{document}` | The source tree beside the selected document |
246
- | Multi-panel | `{basePath}/{multi}?doc=…&doc=…&maximized=…` | Several documents as panels in columns |
255
+ | Multi-panel | `{basePath}/{multi}?doc=…&doc=…&maximized=…&markup=…` | Several documents as panels in columns |
247
256
  | Single | `{basePath}/{single}/{document}` | One document over the whole frame (for reading and embedding) |
248
257
 
249
258
  - `?source=<id>` selects the tree's source among the server's sources; the first source is the default and is written by omission. Switching the source never closes open documents — a document path names one document whichever trees list it.
250
259
  - A document path occupies one URL segment. Build links with `explorerHref(config, target)`, the only function that writes explorer URLs; read them back with `resolveExplorerLocation(config, splat, search)`. Both need the server's source ids for the `source` parameter: pass a configuration joined with them, `withExplorerSources(config, sourceIds)` (`ExplorerLocationConfig`; `isExplorerSourceId` is the id rule, and an empty, invalid or repeated id throws a `RangeError`).
251
260
  `explorerHref` also accepts a plain `ExplorerConfig` with a target without `source` (`ExplorerSourcelessHrefTarget`, the default source), such as a host menu's link; a target with a `source` and a configuration without ids throws a `TypeError` naming `withExplorerSources`, as does `resolveExplorerLocation` with such a configuration.
252
- `explorerHref` throws a `RangeError` for a target the resolver would redirect or partly ignore — repeated or more than `multiView.maxPanels` documents, a maximized document that is not open, an unknown source or document style, an unsupported alignment or embedding value — so every link it writes resolves back to the location given.
261
+ `explorerHref` throws a `RangeError` for a target the resolver would redirect or partly ignore — repeated or more than `multiView.maxPanels` documents, a maximized document or a document shown as written that is not open, an unknown source or document style, an unsupported alignment or embedding value, a tree view without a document shown as written — so every link it writes resolves back to the location given.
253
262
  - The single view accepts embedding parameters: `showToc=false`, `showStyle=false`, `showAlign=false`, `padding` (0–256 px, written in decimal digits), `width` and `maxWidth` (a CSS length in px, rem, em, ch, vw or %; the column never grows wider than the pane, whatever the value). The tree and single views accept `style` and `align` as display overrides.
254
- - History: a click in the tree replaces the URL's document; links inside a document, entries of its table of contents (in the tree and single views, to the heading's hash), source switches and view switches push; every multi-view action replaces (hiding and showing a panel leave the URL unchanged).
263
+ - `markup` names the Markdown documents shown as written (the Source toggle): `markup=true` for the tree or single view's document, and one `markup=<document>` per open document shown that way in the multi view, in the order of `doc`. In `ExplorerLocation` it is a boolean in the tree and single views and a list in the multi view; a target without it shows every document rendered.
264
+ - History: a click in the tree replaces the URL's document; links inside a document, entries of its table of contents (in the tree and single views, to the heading's hash), source switches and view switches push; every multi-view action and the Source toggle replace (hiding and showing a panel leave the URL unchanged).
255
265
  - An entry of a document's table of contents links to its heading's own address: the page's URL with the heading's fragment, or, in a multi-view panel, the panel's document in the tree view with that fragment, so a modified or middle click, a new tab or a copied address opens the heading (see [URL contract](docs/behavior/url-contract.md#table-of-contents)).
256
266
 
257
267
  The full contract, including canonicalization, is in [URL contract](docs/behavior/url-contract.md).
@@ -268,7 +278,7 @@ The full contract, including canonicalization, is in [URL contract](docs/behavio
268
278
  | `scopeSecret` | `string` | The deployment's secret for the readers' scopes: at least 32 characters (a shorter one throws a `RangeError`) and the same on every server instance. |
269
279
  | `sources` | `ExplorerSource<P>[]` | The sources in switcher order (at least one; the first is the default): `id` (lowercase letters, digits and `-`, starting with a letter or digit, unique; the URL's `source` value), `label` (a string, or a function of the principal), `boundary` (where the source's documents may lie, see [Source boundaries](#source-boundaries)), `tree(context)` (lists the source's roots), `children?(context, path, readPath)` for lazy folders (asked only while the tree shows the folder open — the reader opened it, Expand all opened it (a press keeps opening folders as their listings land, within `expandAll`), or a remembered expansion opened it — and only for a path inside the source's boundary; a listing no tree wants any more is aborted through `context.signal`, which the source should honour), `ancestors?(context, path, readPath, options)` (the folders down to a document, for the reader's reveal; see [Revealing the open document](#revealing-the-open-document)), `cacheScope?` (`"principal"`, the default, or `"shared"`). The `context` is described under [Entries and notices](#entries-and-notices). |
270
280
  | `document` | `(context, path, readPath) => Promise<ExplorerHostDocument>` | Resolves a document path. Called only for a path inside at least one source's boundary; `readPath` is what the admitting source's `confirm` answered (`path` when that source has no `confirm`), so read `readPath` and show the document as `path`. An image, media, text or file document reports its file's `version`; the explorer writes its URL (see [Documents](#documents)). |
271
- | `asset` | `(context, path, readPath) => Promise<ExplorerAssetFile>` | Finds the file behind the data route's `asset` operation: any regular file the document admission admits, whatever its kind. Called only after the path passed the deny rules and the same union admission as a document, with the same `readPath`; see [Serving files](#serving-files). |
281
+ | `asset` | `(context, path, readPath) => Promise<ExplorerAssetFile>` | Finds the file behind the data route's `asset` operation (and its `text` operation, which reads a Markdown document's source through it): any regular file the document admission admits, whatever its kind. Called only after the path passed the deny rules and the same union admission as a document, with the same `readPath`; see [Serving files](#serving-files). |
272
282
  | `signedOutPage` | `(request, headers) => Response` | The page response for a signed-out reader, usually a redirect to sign-in. Data requests answer 401 instead. |
273
283
  | `forbiddenPage?` | `(request, headers) => Response` | The page response for a reader without access (default: a 403 for the route's error boundary). |
274
284
  | `notices?` | `(context) => Promise<ExplorerNotice[]>` | Callouts above the tree (a missing permission with a link that grants it, for example). |
@@ -276,6 +286,7 @@ The full contract, including canonicalization, is in [URL contract](docs/behavio
276
286
  | `treeCache?` | `{ ttlMs?, maxEntries?, maxBytes? } \| false` | The server's tree cache, each limit defaulting on its own (5 minutes, 64 entries, 64 MiB of the trees' JSON, counted at two bytes per character). The time to live counts from the moment the tree's walk began, and an expired tree is never answered: a page load or tree request after it waits for one new walk, which every concurrent request shares. Each cached tree is also kept parsed beside its JSON, which `maxBytes` does not count; its share falls as names get longer and is higher for non-ASCII names (measured on trees of 20,000 entries: about 1.0 to 1.9 times the counted bytes for ASCII names of 40 down to 4 characters, 1.4 to 2.2 times for non-ASCII names), and a tree with any non-ASCII name keeps a two-byte JSON as large as its count, so plan for up to about 2.4 times `maxBytes` of memory per process with ASCII names and up to about 3.2 times with short non-ASCII names. `false` turns the cache off. |
277
287
  | `sanitizer?` | `{ workers?, deadlineMs?, maxHtmlBytes?, cacheBytes?, workerHeapMb?, jobsPerScope?, maxQueuedJobs? }` | The HTML sanitizer, each field defaulting on its own: 2 worker threads, a 30 s deadline per document, HTML up to 4 MiB, a 64 MiB cache of outcomes, 512 MiB of heap per worker (`workerHeapMb`), at most `multiView.maxPanels` + max(1, `workers` − 1) + 3 documents per reader running or waiting (`maxPanels` + 4 with the default two workers, 16 with the default 12 panels) and four times `jobsPerScope` waiting in all, also when `jobsPerScope` is set. Neither `jobsPerScope` nor `maxQueuedJobs` may be set below `multiView.maxPanels`, because a page sends the document of every panel at once and a reader who finds every worker busy waits with all of them; a smaller value throws a `RangeError` naming both options at startup, as does a `workerHeapMb` that leaves room for fewer than 4,096 parsed nodes beside HTML of `maxHtmlBytes`. A document over the size, nesting, node, comment or attribute limits, whose sanitized HTML is longer than four characters per byte of `maxHtmlBytes` (16,777,216 by default), past the deadline, or one that runs a worker out of heap is `too-large`; one beyond either admission limit, or one whose worker could not start, is `failed` (logged without the principal) and a later request tries again. A reader runs at most `workers` − 1 documents at once (one when there is a single worker): with the default two workers, one reader — or all anonymous readers, who share one scope and so one admission budget — uses one. |
278
288
  | `deferredTimeoutMs?` | `number` | How long the page loader waits for a streamed value (default 4000 ms; keep it below your server entry's `streamTimeout`). A late value renders the loading state on the server (never a failure) and is fetched by the browser once a pane shows it. The work behind a late tree or document keeps running for another `deferredTimeoutMs`, so the browser's data request for it can join that work instead of starting over (a host that joins requests for the same work keeps it for that request), and its `signal` aborts then; the work behind late notices, which the browser never fetches again, is aborted as soon as they are given up. |
289
+ | `textMaxBytes?` | `number` | The most bytes of a file the data route's `text` operation reads and answers (a positive integer up to 256 MiB; default 2 MiB): a longer file answers its beginning, marked truncated. The explorer shows a Markdown document's source with it, so a host that renders larger Markdown sets it to its own source limit. |
279
290
  | `logger?` | `{ error(message, detail) }` | Where adapter failures and malformed source output are reported (default `console.error`). A tree or children entry with an empty name, or with a path the browser cannot address (empty, too long, a lone surrogate, a control character or a backslash — for example macOS's `Icon\r`), or outside its source's boundary, is left out together with its subtree and reported with the message `[markdown-explorer] <operation> left out an entry` and the detail `{ operation, sourceId, path, error }`, whose `error` names the reason; any other malformed listing becomes `failed`. A boundary that throws or answers malformed values is reported with the operation `boundary`, and so is the rejection of a promise a `contains` answers (it is not awaited and counts as outside). A failed authentication of a data request is reported with the operation `authenticate` and never quotes a header: `headers` that `Headers` cannot read are reported by a fixed message, and a `Response` that `authenticate` throws (React Router's `throw redirect(...)`) by its status alone; any other exception of your adapters is logged as thrown, so keep secrets out of it. |
280
291
  | `onTreeRefreshed?` | `(key: string) => void` | Called once per tree refresh, after its reload settled (whatever its result) unless the request went away, with the refreshed tree's cache key (opaque). A multi-process host relays the key to its other processes, which call `forgetTree(key)` (see [Hosting notes](#hosting-notes)). Its return value is ignored, but a promise it returns (an asynchronous relay) is observed, never awaited: a throw, or the rejection of that promise, is logged with the operation `refresh` and does not change the response. |
281
292
 
@@ -339,7 +350,7 @@ Notices are shown in your own words, as given; a malformed notice list is logged
339
350
 
340
351
  ```ts
341
352
  type ExplorerDocument =
342
- | { kind: "markdown"; name: string; htmlContent: string; headings: { text: string; depth: number; id: string }[] }
353
+ | { kind: "markdown"; name: string; htmlContent: string; headings: { text: string; depth: number; id: string }[]; edit: ExplorerDocumentEdit | null }
343
354
  | { kind: "text"; name: string; text: string; truncated: boolean; url: string }
344
355
  | { kind: "image"; name: string; url: string }
345
356
  | { kind: "media"; name: string; url: string; mediaType: "video" | "audio" | "pdf" }
@@ -352,6 +363,7 @@ This is the document the browser receives. Your `document` port answers `Explore
352
363
  `version` is an opaque validator of 1 to 256 visible ASCII characters other than `"`, the same one your `asset` port reports for the file; the explorer writes the document's `url` as its own asset URL with that version (`<dataPath>/asset?path=…&v=<version>`, see [URL contract](docs/behavior/url-contract.md#asset-urls)).
353
364
  An answer of those kinds that carries a `url` key, or lacks a valid `version`, breaks the contract: it is logged and the reader sees `failed`.
354
365
  `failureDocument(reason, code?)` returns an `ExplorerFailureDocument`, which both unions accept.
366
+ A markdown document says how the reader may edit it in `edit` (`ExplorerDocumentEdit`), which every markdown answer must carry: `null` (no editing), `{ kind: "inline" }` (in the explorer, through the server's `edit` ports; without them the answer breaks the contract) or `{ kind: "external", href }` (the document's own editor, an absolute `https:` URL the bar opens in a new tab). Decide it per document and per reader (see [Editing](#editing)); `createFileSystemSource` answers `null`.
355
367
  A `text` document shows the beginning of a file under the file header (its name, Open in a new tab and Download, so a truncated preview can still be fetched whole); a `file` document is a file the explorer cannot show, which every view (single, tree, the multi view's panels) shows as a download view: the file header over a note (the label `fileNotShown`) with a download link.
356
368
 
357
369
  A markdown document lists at most `EXPLORER_MAX_HEADINGS` (10,000) headings; one that lists more is answered `too-large`, because every listed heading travels with the document (in the data response, the browser's document cache and the viewer's table of contents, one entry each) and a parser can list headings its HTML never renders (`#` lines inside a math block), so none of the HTML's limits bounds the list. A cache of your parser's results can rely on the same bound.
@@ -371,6 +383,32 @@ Your parser resolves each link and each image; the rules are in [Document links]
371
383
  a missing target gets `data-asset-exists="false"`, which the viewer shows as a labelled placeholder; a relative `src` left as written would resolve against the page URL and load an explorer page instead), and the demo's parser (`demo/app/markdown.server.ts` in the source repository) is a complete example.
372
384
  The deny rules are checked on the document's path only: a parser that expands include directives (such as `<!-- @import "…" -->`) must apply them to every file it reads, or leave such directives unexpanded (`@aiquants/markdown`'s `parseMarkdown` leaves them unexpanded unless `resolveImports` is set, and applies the `deniedPathSegments` you give it, the explorer's rules, to every import, image and link target). The explorer serves the files of documents and embedded images itself (see [Serving files](#serving-files)).
373
385
 
386
+ ### Editing
387
+
388
+ Give `createMarkdownExplorer` the editor's ports as `edit` (`ExplorerEditPorts`) and answer `edit: { kind: "inline" }` for the markdown documents a reader may edit. Each port receives the context, the document path and the admitting source's `readPath`, after the deny rules (a refusal is logged) and the same admission as a document; refuse with `ExplorerError` as anywhere else, and check in every port that this reader may edit this document, since a request can name any path.
389
+
390
+ ```ts
391
+ edit: {
392
+ // The whole source and its version (an opaque token naming this content), or a grant to ask for first
393
+ source: async (context, path, readPath) => ({ kind: "edit", text, version, history: true }), // or { kind: "grant", href: "/auth/consent?grant=edit" }
394
+ // Write only if the document still has draft.baseVersion; otherwise write nothing and answer the current content
395
+ save: async (context, path, readPath, draft) => ({ kind: "saved", version: newVersion }), // or { kind: "conflict", version, text } / a grant
396
+ // Render the draft exactly as the document would be (the explorer sanitizes it like a document)
397
+ preview: async (context, path, readPath, text) => ({ htmlContent, headings }),
398
+ // The revisions you keep, newest first, and one revision's text
399
+ revisions: async (context, path, readPath) => [{ id, modifiedAt, size, author, kept, current }],
400
+ revision: async (context, path, readPath, revisionId) => text,
401
+ },
402
+ editMaxBytes: 2 * 1024 * 1024, // the largest source and draft, the default
403
+ ```
404
+
405
+ - **Versions.** A version and a revision id are tokens of 1 to `EXPLORER_EDIT_TOKEN_MAX_LENGTH` (1024) characters: whatever makes a conditional write possible on your storage (an object generation, a revision id, a modification time with the size).
406
+ `save` must write only when the document still has the version the draft started from; when it changed, answer `conflict` with the current version and text and write nothing. The browser then merges the draft into that text line by line and saves again over the new version (up to three writes per save), or leaves the conflicts in the draft for the reader.
407
+ - **Limits.** A draft (`save`, `preview`) is read before any port is called: `text/markdown` with no charset or `utf-8`, at most `editMaxBytes` bytes (`too-large`, 413), valid UTF-8 without NUL (`invalid`, 400). A source, a conflict's text or a revision longer than `editMaxBytes` breaks the contract (logged, `failed`); refuse such a document in `source` with `ExplorerError("too-large")` instead.
408
+ - **Grants.** Answer `{ kind: "grant", href }` from `source` or `save` when the reader must first allow writing (an OAuth consent for a wider scope, for example); `href` is a root-relative address of your own. The explorer shows a notice whose action calls `<MarkdownExplorer onEditGrant>` with it, or, without that prop, links to it in a new tab beside Try again.
409
+ - **Operations.** The data route answers `GET <dataPath>/edit?path=`, `POST <dataPath>/save?path=&base=<version>`, `POST <dataPath>/preview?path=`, `GET <dataPath>/revisions?path=` and `GET <dataPath>/revision?path=&revision=<id>`. `save` and `preview` carry `X-Markdown-Explorer: edit` and must pass the shared cross-origin check, like a refresh. Without `edit`, these operations answer as unknown ones (404), and `editMaxBytes` alone throws.
410
+ - **Source lines.** The editor opens at the place the reader was reading, or at the word they double-clicked, and the preview follows the editor, through the source lines your converter writes on every block: `data-source-lines="<first>-<last>"` (1-based, both inclusive), `@aiquants/markdown`'s `includeSourceLines`. Without them the editor opens at the start of the document; the sanitizer keeps the attribute only in that form.
411
+
374
412
  ### Revealing the open document
375
413
 
376
414
  The reader's tree setting "Reveal the open document" (`revealDocument`, off in `DEFAULT_TREE_SETTINGS`; turn it on for every reader with `defaultTreeSettings: { revealDocument: true }`) opens the folders down to the open document and brings its row into the tree's window. The open document is the URL's document in the tree view (whatever the selection mode, "Off" included), and in the multi view the maximized panel's document, else the one opened last (a panel's link replaces its document; on load, where no order of opening is known, the last open document in layout order).
@@ -491,6 +529,9 @@ and `Cache-Control: private, max-age=60, stale-while-revalidate=600, no-transfor
491
529
  The body of a 200 or 206 with a `Content-Length` carries exactly that many bytes: the explorer drops the bytes past it and cancels the stream `open` returned, and fails the response when that stream ends short, so a file that changes while it is served never gets a body that disagrees with its length and ETag.
492
530
  The URL carries the path in its query, so no name needs an extra escape and the request's own path never ends in `.data`; a document's URL carries `v=<version>` as a cache-buster, which the server never reads (the ETag is always the current version).
493
531
 
532
+ The data route's `text` operation reads a file through the same port for the Source toggle: `<dataPath>/text?path=<document path>` (GET and HEAD) takes the same authentication, deny rules (a refusal logged once with the operation `text`) and admission as `asset`, then answers JSON like a document request — status 200 with a text document (`name`, `text`, `truncated`, and the file's asset `url` with its version) or a failure document, and the reader's scope header.
533
+ It reads at most `textMaxBytes` bytes (the first ones as a range when `size` is larger, the whole file otherwise, an empty file never, a file of unknown `size` one byte past the limit to learn whether more follows), cancels the stream once enough was read, decodes them as UTF-8 (a leading byte order mark dropped, a multi-byte character the limit cuts left out), and answers `unsupported` for bytes holding NUL and `failed` (logged) for a stream that ends before the `size` the port reported. It sends no refresh mark: the port receives `refresh: false`.
534
+
494
535
  ### Link cards
495
536
 
496
537
  With `embeds: { linkCards: true }`, the data route has a `link-card` operation: `GET` or `HEAD` `<dataPath>/link-card?url=<href>`, which `@aiquants/markdown`'s link card asks (same-origin, in the background, once the card nears the viewport). It is the only route of the cards: the explorer creates `@aiquants/markdown`'s `createLinkCardHandler` once, in `createMarkdownExplorer`, behind the read-only authentication, and passes every answer of it through unchanged — status, headers and cache headers. In order:
@@ -568,6 +609,7 @@ Spread it into the configuration when your application has no sign-in: it provid
568
609
  | `renderTreeFailure?` | `(failure) => ReactNode \| undefined` | Renders a tree failure you understand better (by its `code`); `undefined` keeps the explorer's own message. Your node replaces the explorer's callout inside the tree-failure element, which keeps its hooks (`data-testid="markdown-explorer-tree-failure"` and `data-aqmx-failure`); the callout is the failure's only announcement (`role="alert"`), so your node must announce itself (for example with `role="alert"`). |
569
610
  | `lockDocumentScroll?` | `boolean` | Stops the page itself from scrolling while the explorer fills the viewport; the explorer must then fit in the viewport (see below). |
570
611
  | `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. |
612
+ | `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. |
571
613
 
572
614
  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.
573
615
  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.
@@ -597,6 +639,17 @@ Nothing is listed while the explorer is hidden (a closed sheet, a collapsed expl
597
639
  While listings are queued or in flight, a progress line floats at the bottom of the tree area without moving the tree ("Loading 12 folders…", or "Opening all folders (40 opened, 12 loading)…" during a press). A press stopped at a limit leaves its stop sentence in a notice above the tree, in the pane's flow (the tree moves down by the notice's height, so the notice covers no row), until the next press, Collapse all, the pane having no rows to show (a failed, empty or cleared tree), or unmount (a source or view switch). Neither is a live region: the stop is announced once.
598
640
  A folder met again among its own ancestors (a shortcut inside its own target, or two folders holding shortcuts to each other) is shown as a loop row, "Name (already open above)", that never expands: activating it scrolls to that folder, above it, and moves the focus there.
599
641
 
642
+ #### The editor
643
+
644
+ A markdown document whose `edit` is `inline` gets an **Edit** toggle (`aria-pressed`) in the document bar, between Source and Refresh document: labelled beside a page view's pane, icon-only and named after the document in a multi-view panel. One whose `edit` is `external` gets a link to its own editor in a new tab instead.
645
+ Pressing Edit opens the editor with the block at the top of the reader's view at the same place on screen; a double-click on a word of the rendered document opens it with the cursor on that word, which stays where it was, in the tree and single views and in a maximized panel (a panel that is not maximized maximizes on its first double-click, as before; links, controls, media and drawings keep their own double-click). Pressed again, Edit closes the editor — asking first when the draft is unsaved — and the rendered document shows the editor's top line at the same place.
646
+ The toggle is one element in both states, so the focus stays on it.
647
+ While a document is edited, the bar shows the draft's status on one line and the editor's actions instead of Source and Refresh document: Next conflict while conflicts wait, Preview where the pane has room (a page view or a maximized panel), History when the host keeps revisions, and Save (Ctrl/⌘+S in the editor), which is `aria-disabled` until the draft changes; the announcer speaks each save's outcome.
648
+ 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.
649
+ 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.
650
+ 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.
651
+ 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.
652
+
600
653
  ### Localization
601
654
 
602
655
  `locale` selects a built-in catalog (`MARKDOWN_EXPLORER_LABEL_CATALOGS.en` / `.ja`); `labels` overrides single keys.
@@ -647,7 +700,9 @@ Every scroller of the explorer that the reader browses gets one pointer scroll b
647
700
  - Document paths from URLs are limited to 4096 characters without lone surrogates, control characters or backslashes; deny rules are matched through up to three lenient percent-decoding levels, against each level whole and split on `/` or `\` (a storage may read either as part of a name or as a separator), and after full Unicode case folding.
648
701
  - Every source is confined to its boundary: its tree and children list only paths inside it, a children request reaches the host only for a path the named source's boundary admits, and a document or a file's bytes reach the host only when the boundary of at least one source admits its path (see [Source boundaries](#source-boundaries)). A source whose boundary admits everything a reader can read in a store confines nothing in that store.
649
702
  - 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)).
650
- - 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 a same-origin fetch.
703
+ - 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.
704
+ - 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`).
705
+ - 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.
651
706
  - 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).
652
707
  - 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.
653
708
 
@@ -660,6 +715,7 @@ Tests and host styling may rely on the `data-testid` and `data-aqmx-*` attribute
660
715
  ## Known limitations
661
716
 
662
717
  - One explorer per page: the drag-and-drop layout looks up its panels document-wide.
718
+ - 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.
663
719
  - 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.
664
720
  - 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.
665
721
  - 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).
@@ -675,7 +731,8 @@ Tests and host styling may rely on the `data-testid` and `data-aqmx-*` attribute
675
731
 
676
732
  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),
677
733
  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,
678
- 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), and the end-to-end tests' fixtures.
734
+ 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),
735
+ 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.
679
736
  Run it with `pnpm run demo:dev` from the package folder.
680
737
 
681
738
  ## License