@aiquants/markdown-explorer 0.11.0 → 0.12.1
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.
- package/CHANGELOG.md +27 -1
- package/README.md +65 -6
- package/dist/EditSurface-By6NPcD7.js +633 -0
- package/dist/EditSurface-BztcpQPW.cjs +2 -0
- package/dist/{ExplorerSplit-DwlWWfRv.js → ExplorerSplit-BjjqNRtj.js} +52 -52
- package/dist/{ExplorerSplit-51frK8xf.cjs → ExplorerSplit-CqmbUSZ7.cjs} +1 -1
- package/dist/{MultiLayout-CeR_l6Rb.js → MultiLayout-BYXoD1aS.js} +4 -4
- package/dist/{MultiLayout-B4PtS45V.cjs → MultiLayout-BZbEl73E.cjs} +1 -1
- package/dist/{NativeScrollBar-Dp4YWBp7.cjs → NativeScrollBar-B7jTbQmn.cjs} +1 -1
- package/dist/{NativeScrollBar-CVWeTlHC.js → NativeScrollBar-RP37nwmY.js} +1 -1
- package/dist/{TreeLayout-D-NyhuVM.cjs → TreeLayout-CEp5oKly.cjs} +1 -1
- package/dist/{TreeLayout-min5AOhr.js → TreeLayout-Uo6RG7lq.js} +3 -3
- package/dist/client/MarkdownExplorer.d.cts +3 -2
- package/dist/client/MarkdownExplorer.d.ts +3 -2
- package/dist/core/contracts.d.cts +16 -0
- package/dist/core/contracts.d.ts +16 -0
- package/dist/dataRoute-CH3yOKR0.cjs +1 -0
- package/dist/{dataRoute-CU9CKP44.js → dataRoute-Pm_0ue_4.js} +93 -92
- package/dist/{index-DJ_FUtYM.cjs → index-CGBl3fYT.cjs} +8 -8
- package/dist/{index-BPj19kIo.js → index-CjCr8czx.js} +962 -908
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +9 -9
- package/dist/{location-LNl0QOXI.cjs → location-BUNWJ4eB.cjs} +1 -1
- package/dist/{location-BT23fKeh.js → location-DWd6SQhN.js} +1 -1
- package/dist/{merge-AnqxGn__.cjs → merge-DRGBbLuR.cjs} +1 -1
- package/dist/{merge-hyUGPGbJ.js → merge-q-5i8qsn.js} +1 -1
- package/dist/sanitizePolicy-BfUlXI5E.cjs +1 -0
- package/dist/sanitizePolicy-djLC3fRN.js +96 -0
- package/dist/sanitizeWorker.cjs +1 -1
- package/dist/sanitizeWorker.js +143 -226
- package/dist/server.cjs +1 -1
- package/dist/server.js +3 -3
- package/dist/styles/markdown-explorer.css +1 -1
- package/docs/behavior/dom-hooks.md +1 -1
- package/docs/behavior/layout.md +4 -1
- package/docs/behavior/security.md +2 -0
- package/package.json +3 -3
- package/dist/EditSurface-BK_Pz_LF.js +0 -371
- package/dist/EditSurface-CfbYYXrc.cjs +0 -2
- package/dist/dataRoute-CIFFX5bd.cjs +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,32 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## 0.12.1 (2026-10-15)
|
|
4
|
+
|
|
5
|
+
### Fixed
|
|
6
|
+
|
|
7
|
+
- **The editor and its preview scroll together** (patch): scrolling the editor no longer makes the preview move back and forth at every line, and the ends meet. The preview used to keep the editor's top line at the same pixel offset, so it moved one to one with the editor inside a line and jumped by the difference of the two line heights at each new line (back while scrolling down: 12 steps back over 1,600 px of the demo's long notes, up to 64 px; 35 over a draft with images), and it was not tied to either end.
|
|
8
|
+
The two panes now scroll together, both ways, through a map of the converter's blocks: the top of each block's first source line goes with the top of its box and the bottom of its last line with the bottom of its box, positions in between are linear, both tops and both bottoms are pinned together, and blocks whose place differs between the source and the rendering (footnotes) are left out. Either pane moves continuously and on whenever the other does, crossing a block taller on its side (an image, a heading) faster; the same measurements now find no step back, and both ends meet.
|
|
9
|
+
The pane the reader works in (the wheel, a pointer press, a key, the focus moving in, typing) leads at once, so a single jump such as Ctrl+End is never lost, and for 610 ms after that input the other pane's scrolls (the sync's own moves, the editor's corrections while it draws new lines, the browser clamping a preview that shrank, the tail of an earlier scroll animation) never take the lead; a scroll without input, such as a find in page, takes it once the input ended.
|
|
10
|
+
The map is measured again when the preview renders anew or changes size (an image or a diagram finishing) and when the editor's text or line heights change, and the preview's scroller no longer anchors its scroll to its content (`overflow-anchor: none`).
|
|
11
|
+
|
|
12
|
+
## 0.12.0 (2026-10-15)
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- **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)).
|
|
17
|
+
`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`.
|
|
18
|
+
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.
|
|
19
|
+
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`).
|
|
20
|
+
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`).
|
|
21
|
+
New exports: `ExplorerDraft`, `ExplorerDraftAnswer` and `ExplorerDraftConverter`.
|
|
22
|
+
|
|
23
|
+
### Changed
|
|
24
|
+
|
|
25
|
+
- Until its first rendering lands, the preview shows the document's own rendering (marked busy) when the document is loaded, instead of the skeleton.
|
|
26
|
+
- 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.
|
|
27
|
+
- 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.
|
|
28
|
+
|
|
29
|
+
## 0.11.0 (2026-10-14)
|
|
4
30
|
|
|
5
31
|
### Added
|
|
6
32
|
|
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
|
|
30
|
-
is
|
|
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.
|
|
@@ -410,7 +411,7 @@ editMaxBytes: 2 * 1024 * 1024, // the largest source and draft, the default
|
|
|
410
411
|
- **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.
|
|
411
412
|
- **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.
|
|
412
413
|
- **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.
|
|
413
|
-
- **Source lines.** The editor opens at the place the reader was reading, or at the word they double-clicked, and the
|
|
414
|
+
- **Source lines.** The editor opens at the place the reader was reading, or at the word they double-clicked, and the editor and the preview scroll together block by block, 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 and the two panes scroll together by the ratio of their lengths alone; the sanitizer keeps the attribute only in that form.
|
|
414
415
|
|
|
415
416
|
### Revealing the open document
|
|
416
417
|
|
|
@@ -615,6 +616,7 @@ Spread it into the configuration when your application has no sign-in: it provid
|
|
|
615
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). |
|
|
616
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. |
|
|
617
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. |
|
|
618
620
|
|
|
619
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.
|
|
620
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.
|
|
@@ -653,9 +655,65 @@ While a document is edited, the bar shows the draft's status on one line and the
|
|
|
653
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.
|
|
654
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.
|
|
655
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.
|
|
656
|
-
The preview renders the draft as the document would be, beside the editor (below it on a narrow pane)
|
|
658
|
+
The preview renders the draft as the document would be, beside the editor (below it on a narrow pane): on every keystroke with a `draftConverter`, else once the reader pauses typing (SERVER_PREVIEW_DELAY_MS, 610 ms). The two scroll together, both ways: the pane the reader works in (the wheel, a press, a key, typing) leads, and the other keeps the same blocks at the top of its view, moving on continuously — a block taller on one side, such as an image or a heading, is crossed faster there, never with a jump or a step back — and both reach their tops and their bottoms together. 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.
|
|
657
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.
|
|
658
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
|
+
|
|
659
717
|
### Localization
|
|
660
718
|
|
|
661
719
|
`locale` selects a built-in catalog (`MARKDOWN_EXPLORER_LABEL_CATALOGS.en` / `.ja`); `labels` overrides single keys.
|
|
@@ -708,7 +766,7 @@ Every scroller of the explorer that the reader browses gets one pointer scroll b
|
|
|
708
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)).
|
|
709
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.
|
|
710
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`).
|
|
711
|
-
- 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.
|
|
712
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).
|
|
713
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.
|
|
714
772
|
|
|
@@ -722,6 +780,7 @@ Tests and host styling may rely on the `data-testid` and `data-aqmx-*` attribute
|
|
|
722
780
|
|
|
723
781
|
- One explorer per page: the drag-and-drop layout looks up its panels document-wide.
|
|
724
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.
|
|
725
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.
|
|
726
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.
|
|
727
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).
|
|
@@ -738,7 +797,7 @@ Tests and host styling may rely on the `data-testid` and `data-aqmx-*` attribute
|
|
|
738
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),
|
|
739
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,
|
|
740
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),
|
|
741
|
-
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.
|
|
742
801
|
Run it with `pnpm run demo:dev` from the package folder.
|
|
743
802
|
|
|
744
803
|
## License
|