@aiquants/markdown-explorer 0.23.0 → 0.24.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.
Files changed (58) hide show
  1. package/CHANGELOG.md +127 -0
  2. package/README.md +66 -21
  3. package/dist/{EditSurface-Dhvw9IDD.js → EditSurface-CFXG8Qok.js} +333 -336
  4. package/dist/{EditSurface-Bk4tdJ99.cjs → EditSurface-CiKQiYSD.cjs} +5 -5
  5. package/dist/{ExplorerSplit-BAFiXU-V.cjs → ExplorerSplit-BWMVatnB.cjs} +1 -1
  6. package/dist/{ExplorerSplit-Q5VqUBDE.js → ExplorerSplit-DIkC3R7O.js} +81 -81
  7. package/dist/{MultiLayout-DlATT7km.js → MultiLayout-DXnuRzb4.js} +22 -22
  8. package/dist/{MultiLayout-Bq_TS3ez.cjs → MultiLayout-q_Pvwykp.cjs} +1 -1
  9. package/dist/{NativeScrollBar-A6-qEpz7.cjs → NativeScrollBar-UYBG64v1.cjs} +1 -1
  10. package/dist/{NativeScrollBar-TsIcS3JZ.js → NativeScrollBar-s_uSPPEd.js} +1 -1
  11. package/dist/{TreeLayout-zrSo4MNZ.js → TreeLayout-BQ1lWVf3.js} +3 -3
  12. package/dist/{TreeLayout-l-r2pPao.cjs → TreeLayout-Di0yv1E-.cjs} +1 -1
  13. package/dist/core/config.d.cts +13 -0
  14. package/dist/core/config.d.ts +13 -0
  15. package/dist/core/contracts.d.cts +22 -4
  16. package/dist/core/contracts.d.ts +22 -4
  17. package/dist/core/labels.d.cts +12 -0
  18. package/dist/core/labels.d.ts +12 -0
  19. package/dist/core/textEncoding.d.cts +4 -0
  20. package/dist/core/textEncoding.d.ts +4 -0
  21. package/dist/{dataRoute-Diu_7gle.js → dataRoute-BEvesOvN.js} +105 -97
  22. package/dist/dataRoute-Cv7fgCW7.cjs +1 -0
  23. package/dist/index-BhxsL0Sm.js +4097 -0
  24. package/dist/index-ZdsIXJap.cjs +13 -0
  25. package/dist/index.cjs +1 -1
  26. package/dist/index.d.cts +2 -2
  27. package/dist/index.d.ts +2 -2
  28. package/dist/index.js +24 -23
  29. package/dist/location-CasigkBk.cjs +1 -0
  30. package/dist/location-gXXmC7CQ.js +643 -0
  31. package/dist/{merge-BzMpSaxx.js → merge-CQAXBfvi.js} +1 -1
  32. package/dist/{merge-DlPkU2Jc.cjs → merge-DkmrVEIc.cjs} +1 -1
  33. package/dist/{sanitizePolicy-Du3lFZd-.cjs → sanitizePolicy-CZwOaJ92.cjs} +1 -1
  34. package/dist/{sanitizePolicy-BvhYIqVO.js → sanitizePolicy-gVKBhabq.js} +1 -1
  35. package/dist/sanitizeWorker.cjs +1 -1
  36. package/dist/sanitizeWorker.js +1 -1
  37. package/dist/server/fileSystemSource.d.cts +1 -0
  38. package/dist/server/fileSystemSource.d.ts +1 -0
  39. package/dist/server/ports.d.cts +8 -1
  40. package/dist/server/ports.d.ts +8 -1
  41. package/dist/server.cjs +1 -1
  42. package/dist/server.d.cts +1 -0
  43. package/dist/server.d.ts +1 -0
  44. package/dist/server.js +783 -768
  45. package/dist/styles/markdown-explorer.css +1 -1
  46. package/dist/{useSplitPersistence-HfAb8Kzh.js → useSplitPersistence-BPNjvuJi.js} +1 -1
  47. package/dist/{useSplitPersistence-CR4Oxtaa.cjs → useSplitPersistence-Bmpb2prR.cjs} +1 -1
  48. package/docs/behavior/dom-hooks.md +13 -6
  49. package/docs/behavior/layout.md +22 -10
  50. package/docs/behavior/localization.md +10 -4
  51. package/docs/behavior/security.md +7 -4
  52. package/docs/behavior/url-contract.md +2 -2
  53. package/package.json +5 -5
  54. package/dist/dataRoute-vXGZMVB-.cjs +0 -1
  55. package/dist/index-BNFl3BsO.cjs +0 -13
  56. package/dist/index-Jz6zeO4O.js +0 -3703
  57. package/dist/location-8Ho8ZNv_.js +0 -499
  58. package/dist/location-DN0AI4ir.cjs +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,132 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.24.1 (2026-10-27) — An SVG image inside a document copies as an image, labelled in both languages
4
+
5
+ ### Changed
6
+
7
+ - **The peer floor is `@aiquants/markdown` ^11.3.0**, whose SVG image toolbar copies the image as a PNG that pastes as
8
+ an image while the image shows (the source's Copy still copies the text) and puts the source in a `<code>`, so the
9
+ Zenn style's light colour scheme no longer paints it dark on dark.
10
+
11
+ ### Added
12
+
13
+ - Labels for the image's Copy: `viewerSvgImageCopyImage` («Copy the image» / 「画像をコピー」),
14
+ `viewerSvgImageCopiedImage` («Copied the image.» / 「画像をコピーしました。」) and `viewerSvgImageCopyImageFailed`
15
+ («Could not copy the image.» / 「画像をコピーできませんでした。」), handed to the viewer's `svgImageCopyImage`,
16
+ `svgImageCopiedImage` and `svgImageCopyImageFailed`.
17
+
18
+ ## 0.24.0 (2026-10-27) — Table files shown as tables: CSV, TSV and a workbook's first sheet
19
+
20
+ ### Breaking
21
+
22
+ - **A new document kind, `spreadsheet`: a table file shown as a table.** The browser's documents gain
23
+ `{ kind: "spreadsheet", name, url, format, firstSheetOnly, edit }` and the host's `document` port may answer
24
+ `{ kind: "spreadsheet", name, format, firstSheetOnly, edit, version }`: `format` is `"csv"` or `"tsv"` (the bytes
25
+ the `asset` port delivers), `firstSheetOnly` says the file is only the first sheet of a workbook the storage exports,
26
+ and `edit` is `null` or an external editor (`{ kind: "external", href }`, the explorer editing no table file itself).
27
+ A spreadsheet answer without a known `format`, a boolean `firstSheetOnly` and such an `edit` breaks the contract (it
28
+ is logged and the reader sees `failed`). `ExplorerSpreadsheetDocument`, `ExplorerSpreadsheetFormat` and
29
+ `ExplorerExternalEdit` are exported. `createFileSystemSource` answers `.csv` files as `csv` and `.tsv` and `.tab`
30
+ files as `tsv` spreadsheet documents: a `.csv` or `.tsv` file was a text document, and a `.tab` file a `file`
31
+ document offered for download. Excel and OpenDocument workbooks stay `file` documents.
32
+ - **The resolved configuration carries `legacyTextEncoding` (`string | null`) and `spreadsheets` (`{ maxBytes }`), and
33
+ `revalidateExplorerConfig` checks every key.** `defineExplorerConfig` fills both. Revalidation now asks a
34
+ configuration to equal, key by key, what `defineExplorerConfig` resolves from it, so one built or edited by hand
35
+ with a key left out, a group left partial (`spreadsheets: {}`, `multiView` without `columns`) or a value it would
36
+ resolve otherwise fails with a `RangeError` naming the place that differs and both values there
37
+ (`config.spreadsheets.maxBytes`, `config.iframeHosts.length`), or the key the resolved configuration does not have
38
+ (`config.embeds.linkCardSize` given as `undefined`) — unless a check of `defineExplorerConfig` refuses the value
39
+ first with its own error (a missing `legacyTextEncoding` or `embeds`, or a `multiView` that is not a plain object,
40
+ throws a `TypeError`) —, where a missing group used to be completed with its defaults while the browser read the
41
+ host's object as it was.
42
+ - **`defineExplorerConfig` refuses an option it does not know**: a key outside `ExplorerConfigInput` (a misspelled
43
+ `legacyEncoding`, a singular `spreadsheet`, a `sourceIds` left in) fails with a `RangeError` naming it, where it was
44
+ ignored and the option it meant silently took its default.
45
+ - **Text is read by the explorer's one rule**: the encoding a byte order mark names (the mark dropped), else UTF-8,
46
+ else the configuration's legacy encoding, each strictly, and bytes none of them reads in the first encoding tried,
47
+ with U+FFFD for each sequence it cannot read; a beginning of a file that ends within a byte order mark reads nothing
48
+ yet. The `text` operation reads that way, and so does `createFileSystemSource` for its text and Markdown files, NUL
49
+ being looked for in the decoded text: a UTF-16 file with a byte order mark now answers its text (the `text` operation
50
+ answered `unsupported`, and the file-system source a `file` document).
51
+
52
+ ### Added
53
+
54
+ - **Table files show as tables.** A spreadsheet document shows its file under the file header (Open in a new tab as
55
+ plain text, Download) as a read-only `@aiquants/markdown` table block named after the file, in the UI language and
56
+ the explorer's colour scheme, filling a page pane (never fewer than three rows) and taking its rows' height in a
57
+ multi-view panel. The file's notes and table share one scroller under the header, the document's scroller, so at a
58
+ 400 % zoom both are reached by scrolling it. The browser reads the file itself through the asset's plain-text
59
+ delivery (never redirected to the storage), as a stream, and stops reading once the table holds the 100,000 cells a
60
+ grid operates on at once or the bytes reach `spreadsheets.maxBytes` (default 2 MiB); columns past the 1,000th are
61
+ left out, and a cell keeps at most the 32,767 characters a cell of Excel holds. A file read partway yields only the
62
+ rows the rest of it cannot change — every row a line break ends, up to a quoted cell the bytes read do not close —,
63
+ so the rows shown are always the file's first rows; its encoding is decided on the bytes read. CSV is read by
64
+ RFC 4180 (quoted cells with commas, line breaks and doubled quotes; the text after a closing quote joining the cell,
65
+ as Excel reads it), TSV by `@aiquants/spreadsheet`'s grammar. Notes say when the file is only a workbook's first
66
+ sheet, when the table is only part of the file and when the file has no data (its cells, taken whole within that
67
+ budget, are all empty, or it has none); bytes in no encoding of the explorer's rule show a note naming the encodings tried (by their written names:
68
+ `UTF-8`, `Shift_JIS`, or the one a byte order mark names), text holding NUL a note that the file is not text, and a
69
+ file in whose bytes read no row ends a note that it cannot be shown as a table, each with the download. The skeleton
70
+ shows until the first reading, and a page view announces the document once its table shows; a failure before
71
+ anything was read shows the failure view with its retry and is announced alone (in a multi-view panel through the
72
+ panel's announcer), and a retry that succeeds moves the focus into the table's body and, in a page view, announces
73
+ the document. A refresh reads the file again with the previous table on screen and the region busy, and is reported
74
+ once the file is read (see Changed); a background answer whose reading fails keeps the table without a word, as a
75
+ background failure keeps a loaded document.
76
+ - **A table file offers Source**: the document bar's toggle (its tooltip `showSpreadsheetMarkup` naming the CSV or the
77
+ TSV) shows the file as written through the `text` operation, read by the same rule as the table, and keeps the choice
78
+ in the URL's `markup`. A spreadsheet's external editor (a Google Sheets spreadsheet's, for example) is linked from the
79
+ bar like a Markdown document's.
80
+ - **Configuration**: `legacyTextEncoding`, the legacy encoding of the files the explorer reads as text (a WHATWG label
81
+ `TextDecoder` knows, such as `Shift_JIS`, `sjis` or `windows-1252`, resolved to the encoding's written name), in
82
+ which it reads bytes that carry no byte order mark and are not UTF-8 — a table file's and a document shown as written
83
+ alike; UTF-8, UTF-16, ISO-2022-JP (seven-bit, so UTF-8 always reads it first) and x-user-defined (no text encoding)
84
+ are refused with a `RangeError` naming why. `spreadsheets.maxBytes`: a positive integer up to 256 MiB, default 2 MiB
85
+ (`SPREADSHEET_BYTE_LIMITS`), the most a Source view reads by default, since the browser parses what it reads on its
86
+ main thread at a cost that grows with the bytes.
87
+ - **`createFileSystemSource` takes `legacyTextEncoding`** for its text and Markdown files — a label, or `null` for none,
88
+ so the resolved configuration's value passes as it is —, and `@aiquants/markdown-explorer/server` exports the rule
89
+ for a host's own sources: `legacyTextEncodingOf`, and `decodeText` and `decodeTextLeniently`, which resolve a legacy
90
+ label as `legacyTextEncodingOf` does and refuse the same names.
91
+ - Labels: `showSpreadsheetMarkup`, `spreadsheetLoading`, `spreadsheetFirstSheetOnly`, `spreadsheetTruncated`,
92
+ `spreadsheetUnreadableEncoding` (given the encodings tried), `spreadsheetNotText`, `spreadsheetLongRow`,
93
+ `spreadsheetEmpty` and `spreadsheetFullscreen`. DOM hooks: `markdown-explorer-spreadsheet-view` (with
94
+ `data-aqmx-spreadsheet`: `loading`, `table`, `empty`, `unreadable` or `failure`), its body, the document's scroller
95
+ (`data-aqmx-document-scroller`), `-spreadsheet-first-sheet`, `-spreadsheet-truncated`, `-spreadsheet-empty`,
96
+ `-spreadsheet-skeleton`, `-spreadsheet-failure` and `-spreadsheet-unreadable` (with `data-aqmx-unreadable`:
97
+ `encoding`, `binary` or `long-row`) and its download, and the document kind `spreadsheet`.
98
+ - The demo's `notes/tables` holds a UTF-8 CSV with quoted cells, a Shift_JIS CSV (the demo gives
99
+ `legacyTextEncoding: "Shift_JIS"` to its configuration and to its file-system sources), a TSV and a CSV wider than
100
+ the preview's 1,000 columns.
101
+
102
+ ### Changed
103
+
104
+ - **A document's refresh is reported once what it brought is on screen.** Where the document's content reads a part
105
+ of it itself — a table file's table, a document shown as written —, the document bar stays busy until that part is
106
+ read from the new answer and only then announces `documentRefreshed`; a failure of that reading is the refresh's
107
+ failure, shown in the bar's one notice with what was read before kept and announced once, so a refresh is never
108
+ announced as both reloaded and failed, and no second notice repeats it. A refresh that replaces the content's own
109
+ failure view is reported as the pane shows it, as for a shown failure: in a page view the pane alone announces the
110
+ document (or the new failure), in a multi-view panel the bar announces it as reloaded and leaves a failure to the
111
+ pane. The bar's notice of a failed reload also comes down when the reader switches between the document rendered and
112
+ as written, whose content then reads the document again. A page view announces a document whose content reads such a
113
+ part as shown once the part shows, or when the reader switches to a view that reads none before it does, and says
114
+ nothing for a document it shows as stale while another one the reader asked for loads.
115
+ - **A document shown as written keeps its text when reading it again fails**, as the table does (both read their own
116
+ part the same way): the region is busy while it reads again, a refresh reports the failure in the bar, a background
117
+ answer's reading that fails keeps the text without a word, and a retry that replaces its failure view moves the
118
+ focus into the text and, in a page view, announces the document, as a document that replaces a failure is.
119
+ - **The focus ring of a document's scroller is drawn inside its edge.** The pane carries the focus to the scroller of
120
+ the shown document (a viewer's, a file view's, a table file's body) when nothing inside takes it, and the region
121
+ clips what lies outside that scroller, so its outer ring was hidden all around; one rule now insets the ring of every
122
+ such scroller, the edit preview's included.
123
+ - Peers: `@aiquants/markdown` ^11.2.0 (the table that fills its pane keeps three rows; an SVG image's toolbar sits at
124
+ the row's end with Copy before the Source toggle, and Copy copies the image's source from the image too) and
125
+ `@aiquants/spreadsheet` ^0.16.1 (`iterateTsvPrefixRows`, the rows of a TSV file read partway).
126
+ - While the editing chunk loads, its skeleton carries the screen-reader text `editLoading`, as the editor's skeleton
127
+ does while it reads the source; the two are one skeleton, shared with the document pane's other loading and failure
128
+ states.
129
+
3
130
  ## 0.23.0 (2026-10-27) — An SVG image shows its SVG a press away, as a document and inside one
4
131
 
5
132
  ### Breaking
package/README.md CHANGED
@@ -18,14 +18,20 @@ 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 and an SVG image offer **Source**: a toggle that shows the document as written instead
22
- of rendered (its file — an SVG image's own SVG — read through the data route's `text` operation, shown like a text
23
- file, whose header copies the text exactly as written); a raster image offers none. The choice is part of the URL
21
+ Beside it, a Markdown document, an SVG image and a table file offer **Source**: a toggle that shows the document as
22
+ written instead of rendered (its file — an SVG image's own SVG, a table file's CSV or TSV — read through the data
23
+ route's `text` operation, shown like a text file, whose header copies the text exactly as written); a raster image
24
+ offers none. The choice is part of the URL
24
25
  (`markup`), so a reload, a shared link and Back and Forward show the document the same way, and the switches between
25
26
  the tree and multi views carry it; another document opens rendered.
26
- Inside a rendered document, a storage SVG image that stands alone in a paragraph gets its own Source toggle in a
27
- toolbar above it, which shows the image's SVG in its place through the same operation, and the image again on a second
28
- press.
27
+ Inside a rendered document, a storage SVG image that stands alone in a paragraph gets its own Copy and Source toggle in
28
+ a toolbar above it, at the row's end: the toggle shows the image's SVG in its place through the same operation, and the
29
+ image again on a second press, and Copy copies the image as a PNG that pastes as an image while the image shows, and the
30
+ SVG as written while the source shows.
31
+ A table file — a CSV or TSV file, or a workbook the host exports as one, such as a Google Sheets spreadsheet's first
32
+ sheet — shows as a read-only grid under its file header, named after the file: the browser reads the file itself in its
33
+ encoding (a byte order mark's, UTF-8 or the configured legacy encoding) and stops once the table holds as much as a
34
+ grid shows, saying so (see [Table files](#table-files)).
29
35
  With the server's `edit` ports, a Markdown document also offers **Edit**: the reader edits its Markdown in place
30
36
  (CodeMirror, loaded on demand), from where they were reading or from the word they double-clicked, saves over the
31
37
  version the draft started from (changes saved elsewhere are merged line by line, and conflicts are resolved in the
@@ -42,13 +48,13 @@ A single-view (embedding) page never downloads the tree and multi-panel views, w
42
48
 
43
49
  - React 19.2.7 or later and React Router 8 in framework mode (route modules with `loader` / `headers`).
44
50
  - 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)`.
45
- - The peer packages, at these versions or later within the caret ranges the package declares: `@aiquants/markdown` ^11.1.0 (document rendering; the Source toggle of a storage SVG image that stands alone in a paragraph, read through `imageSource`, a notice in place of a block that cannot render and plain text for a fence in a language it does not know; its components' stylesheet without utilities,
46
- its controls' 44 px targets under every pointer, ```spreadsheets tables — inside list items and quotes too — and their write-back through an editor that answers what came of each write (written, changed, a line that would close the fence, unwritable), reads a block's body back and tells them of its other changes,
51
+ - The peer packages, at these versions or later within the caret ranges the package declares: `@aiquants/markdown` ^11.3.0 (document rendering; the Source toggle of a storage SVG image that stands alone in a paragraph, read through `imageSource`, and a Copy that copies the image as a PNG image or its source, the source readable in every display style, a notice in place of a block that cannot render and plain text for a fence in a language it does not know; its components' stylesheet without utilities,
52
+ its controls' 44 px targets under every pointer, ```spreadsheets tables — inside list items and quotes too, and in a pane of their own (`layout="fill"`) never fewer than three rows — and their write-back through an editor that answers what came of each write (written, changed, a line that would close the fence, unwritable), reads a block's body back and tells them of its other changes,
47
53
  the React-free `@aiquants/markdown/code-blocks` that names the `data-code-meta` the sanitizer keeps on `code`, holds the converter's reading of a fenced block's lines and the table labels with their placeholders,
48
54
  its Mermaid labels and drawings that finish inside the document when a diagram's text changes or it unmounts mid-drawing, its math diagnostics, gantt sizing, embeds, link cards and their sizes, the React-free `@aiquants/markdown/embeds` the sanitizer worker loads and `@aiquants/markdown/source-lines` the editor and the sanitizer read, and the Node-only link-card handler of `@aiquants/markdown/server`, which needs Node.js 22.13 or later — below the explorer's own floor),
49
55
  `@aiquants/directory-tree` ^5.0.1 (rows that take paint and text styles only and have no vertical padding, a `removeRootIndent` shift that keeps the root's icon whole, and reveals of rows under the scroll bar's buttons),
50
- `@aiquants/drag-drop-panels` ^0.12.0 (the panel headers' move menu, named by the explorer's `panelMove`, their 44 px buttons under every pointer and the header arrangement the behavior docs follow), `@aiquants/resize-panels` ^2.2.0 (the source of each layout change, by which the tree pane's width is saved), `@aiquants/spreadsheet` ^0.16.0 (the grid of those tables — one `role="grid"` with header rows,
51
- read-only where it cannot write and named by its block — which markdown loads only for a document that holds one) and `@aiquants/virtualscroll` ^3.22.1 (44 px scroll-to-edge pills and tap-scroll circles, the pills' text at the body step).
56
+ `@aiquants/drag-drop-panels` ^0.12.0 (the panel headers' move menu, named by the explorer's `panelMove`, their 44 px buttons under every pointer and the header arrangement the behavior docs follow), `@aiquants/resize-panels` ^2.2.0 (the source of each layout change, by which the tree pane's width is saved), `@aiquants/spreadsheet` ^0.16.1 (the grid of those tables — one `role="grid"` with header rows,
57
+ read-only where it cannot write and named by its block — which markdown loads only for a document that holds one, and the grid of a table file's preview, whose TSV grammar (`@aiquants/spreadsheet/tsv`) reads a TSV file — `iterateTsvPrefixRows` the rows of a file read partway — and whose operation budget (`SPREADSHEET_MAX_OPERATION_CELLS` of `@aiquants/spreadsheet/view`) bounds its table) and `@aiquants/virtualscroll` ^3.22.1 (44 px scroll-to-edge pills and tap-scroll circles, the pills' text at the body step).
52
58
  The client depends on these floors, while a package manager may only warn about an older peer.
53
59
  - A Markdown parser of your choice on the server that produces HTML and its headings (the explorer sanitizes the HTML before it is sent).
54
60
  - Browsers: the multi view's panel-limit notice and the panel headers' move menu use the Popover API (Chrome and Edge 114, Firefox 125, Safari 17 and later). In browsers without it (for example iOS 16), the notice is drawn in place at the stage's corner instead of in the top layer (while the sheet is open it spans the sheet's header, as in every browser), and the move menu does not open: Alt + Shift + an arrow moves a panel there.
@@ -79,7 +85,8 @@ export const explorerConfig = defineExplorerConfig({
79
85
  })
80
86
  ```
81
87
 
82
- `defineExplorerConfig` validates everything once and returns a frozen value: mount paths, view slugs (`tree`, `multi`, `single` by default), the multi-view limits (`maxPanels` 12, `columns` 4), Expand all's budget per press (`maxFolders` 500, `maxDepth` 16), the deepest document the reader's reveal opens folders for (`maxDepth` 16), the document styles, the iframe host allow-list, the embeds and link cards and the reader's default tree settings. A mistake throws at startup instead of producing links that point nowhere.
88
+ `defineExplorerConfig` validates everything once and returns a frozen value: mount paths, view slugs (`tree`, `multi`, `single` by default), the multi-view limits (`maxPanels` 12, `columns` 4), Expand all's budget per press (`maxFolders` 500, `maxDepth` 16), the deepest document the reader's reveal opens folders for (`maxDepth` 16), the document styles, the iframe host allow-list, the embeds and link cards, the reader's default tree settings, the legacy text encoding and a table file's byte budget.
89
+ A mistake throws at startup instead of producing links that point nowhere, a key that is not an option (a misspelled `legacyEncoding`, a singular `spreadsheet`) included: it throws a `RangeError` naming it instead of leaving the option it meant at its default.
83
90
  The source ids are not part of it: they are the ids of the server's `sources` (a runtime setting of the server), and the browser learns them from the page data. `withExplorerSources(config, sourceIds)` joins them to the configuration where the URL codec needs them (see [Views and URLs](#views-and-urls)).
84
91
 
85
92
  | Option | Type | Purpose |
@@ -95,6 +102,8 @@ The source ids are not part of it: they are the ids of the server's `sources` (a
95
102
  | `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. |
96
103
  | `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. |
97
104
  | `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 and READMEs 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"`; `readmePlacement` `"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)). |
105
+ | `legacyTextEncoding?` | `string` | The legacy encoding of the files the explorer reads as text: a WHATWG label `TextDecoder` knows (for example `Shift_JIS`, `sjis` or `windows-1252`), resolved to the encoding's written name (`Shift_JIS`; `legacyTextEncodingOf`). UTF-8 and UTF-16 (read before it, and only by a byte order mark), ISO-2022-JP (seven-bit, so UTF-8 always reads it first) and x-user-defined (no text encoding) are refused with a `RangeError` naming why. The explorer reads a file's bytes in it when they carry no byte order mark and are not UTF-8 — a table file it shows as a table and a document it shows as written alike (see [Table files](#table-files)); give `createFileSystemSource` the same encoding for its text and Markdown files. None when omitted: a table file of such bytes is then not shown as a table, and a document shown as written shows them as UTF-8, with U+FFFD for each sequence UTF-8 cannot read. |
106
+ | `spreadsheets?` | `{ maxBytes? }` | A table file's preview: the most bytes the browser reads of the file (a positive integer up to 256 MiB; default 2 MiB, the most a Source view reads by default; `SPREADSHEET_BYTE_LIMITS`), which stops sooner once the table holds as many cells as a preview shows (see [Table files](#table-files)). The browser parses what it reads on its main thread, at a cost that grows with the bytes rather than with the cells it shows, so a larger value costs a pathological file (one long row, one long cell) more time. The field defaults on its own, also when given as `undefined`. |
98
107
 
99
108
  For example, `defaultTreeSettings: { sortMode: "desc" }` lists every folder's entries by name, Z to A, until the reader picks another order.
100
109
 
@@ -289,7 +298,7 @@ to; load it when your documents contain math.
289
298
  `explorerHref` throws a `RangeError` for a target the resolver would redirect, read as another location or partly ignore — repeated or more than `multiView.maxPanels` documents, a maximized document or a document shown as written that is not open, an unknown source or document style, an unsupported alignment or embedding value, a tree view with both a document and a folder, a document path that ends in a slash, a tree view with neither a document nor a folder shown as written — so every link it writes resolves back to the location given.
290
299
  - A folder of the tree view takes the same segment with a slash after its path: `explorerHref(config, { view: "tree", folder: "guide/concepts" })` writes `/docs/tree/guide%2Fconcepts%2F`, and `ExplorerLocation`'s tree view carries `doc` and `folder`, at most one of them not `null` (see [Folders and their READMEs](#folders-and-their-readmes)). The single view shows documents only and redirects a folder to the tree view.
291
300
  - 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.
292
- - `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.
301
+ - `markup` names the Markdown documents, SVG images and table files shown as written (the Source toggle): `markup=true` for the tree or single view's document, and one `markup=<document>` per open document shown that way in the multi view, in the order of `doc`. In `ExplorerLocation` it is a boolean in the tree and single views and a list in the multi view; a target without it shows every document rendered.
293
302
  - History: a click in the tree replaces the URL's document or folder; links inside a document, entries of its table of contents (in the tree and single views, to the heading's hash), source switches and view switches push; every multi-view action and the Source toggle replace (hiding and showing a panel leave the URL unchanged).
294
303
  - 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)).
295
304
 
@@ -395,15 +404,18 @@ type ExplorerDocument =
395
404
  | { kind: "text"; name: string; text: string; truncated: boolean; url: string }
396
405
  | { kind: "image"; name: string; url: string; imageType: "raster" | "svg" }
397
406
  | { kind: "media"; name: string; url: string; mediaType: "video" | "audio" | "pdf" }
407
+ | { kind: "spreadsheet"; name: string; url: string; format: "csv" | "tsv"; firstSheetOnly: boolean; edit: ExplorerExternalEdit | null }
398
408
  | { kind: "file"; name: string; url: string }
399
409
  | ExplorerFailureDocument // { kind: "failure"; failure: { reason: ExplorerFailureReason; code?: string } }
400
410
  ```
401
411
 
402
- This is the document the browser receives. Your `document` port answers `ExplorerHostDocument` (exported from the server entry), which is the same except that an image, media, text or file document carries its file's `version` instead of a `url`:
403
- `{ kind: "image"; name; imageType; version }`, `{ kind: "media"; name; mediaType; version }`, `{ kind: "text"; name; text; truncated; version }` and `{ kind: "file"; name; version }`.
412
+ This is the document the browser receives. Your `document` port answers `ExplorerHostDocument` (exported from the server entry), which is the same except that an image, media, text, spreadsheet or file document carries its file's `version` instead of a `url`:
413
+ `{ kind: "image"; name; imageType; version }`, `{ kind: "media"; name; mediaType; version }`, `{ kind: "text"; name; text; truncated; version }`, `{ kind: "spreadsheet"; name; format; firstSheetOnly; edit; version }` and `{ kind: "file"; name; version }`.
404
414
  `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)).
405
415
  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`.
406
416
  An image document names its type in `imageType` (`ExplorerImageType`): `"svg"` for an SVG file, whose SVG the Source toggle shows as written, and `"raster"` for every other image format. Answer it from what your storage knows of the file's type, the type your `asset` port serves it with; the explorer never guesses it from the name, and an image answer without one of the two breaks the contract the same way.
417
+ A spreadsheet document is a table file the explorer shows as a table (see [Table files](#table-files)); it names the format of the bytes your `asset` port delivers for it in `format` (`ExplorerSpreadsheetFormat`: `"csv"` or `"tsv"`), whether those bytes are only the first sheet of a workbook your storage exports (`firstSheetOnly`, which adds a note above the table; a Google Sheets spreadsheet exported as CSV is), and the file's own editor in `edit` (`ExplorerExternalEdit`:
418
+ `null`, or `{ kind: "external", href }` with an absolute `https:` URL the bar opens in a new tab, as for a markdown document; the explorer edits no table file itself). Answer them from what your storage knows of the file, as for an image; a spreadsheet answer without a known `format`, a boolean `firstSheetOnly` and such an `edit` breaks the contract the same way.
407
419
  `failureDocument(reason, code?)` returns an `ExplorerFailureDocument`, which both unions accept.
408
420
  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), `{ kind: "draft" }` (in the explorer without saving, to try changes in the preview: the ports' `source` and `preview` only, and the same contract) or `{ kind: "external", href }` (the document's own editor, an absolute `https:` URL the bar opens in a new tab).
409
421
  Decide it per document and per reader (see [Editing](#editing)); `createFileSystemSource` answers `null`.
@@ -429,6 +441,25 @@ Your parser resolves each link and each image; the rules are in [Document links]
429
441
  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.
430
442
  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)).
431
443
 
444
+ ### Table files
445
+
446
+ A spreadsheet document shows its file under the file header (its name; Open in a new tab, which shows the file as plain text; Download) as a read-only table: `@aiquants/markdown`'s table block — the grid of `@aiquants/spreadsheet`, with its zoom, copy, save as TSV and full screen —, named after the file, in the UI language and the explorer's colour scheme, filling a page pane (the block's `fill` layout, never fewer than three rows at the grid's zoom) and taking the height of its rows in a multi-view panel.
447
+ The file's notes and its table share one scroller under the file header, the document's scroller: in a page pane the table fills what the notes leave, and the body scrolls only when the pane is shorter than the file header, the notes, the stage's padding and the table block at its fewest — its toolbar and notice line and those three rows (at a 400 % zoom, for example).
448
+
449
+ - **Reading**: the browser reads the file itself, through the asset's plain-text delivery (`&as=text`: one request on the page's origin, never redirected to the storage), as a stream. At looks that each wait for twice the bytes the one before saw (the first after 64 KiB) it makes the table of what it has, so the looks together parse less than twice the bytes read, and it stops reading — cancelling the rest of the request — once the cell budget refuses a row (the 100,000 cells a grid operates on at once, `SPREADSHEET_MAX_OPERATION_CELLS`)
450
+ or the bytes reach `spreadsheets.maxBytes` (default 2 MiB);
451
+ columns past the 1,000th are left out, so the widest table still shows 100 rows, and a cell keeps at most the 32,767 characters a cell of Excel holds, so one long cell cannot stall the grid's layout. A file read partway yields only the rows the rest of it cannot change — every row a line break ends, up to a quoted cell the bytes read do not close —, so the rows shown are always the file's first rows, wherever the reading stopped.
452
+ A table that is not the whole file says so above it (the label `spreadsheetTruncated`), and a file in whose first `spreadsheets.maxBytes` no row ends — its first row runs past them, or, in a TSV, a quote that opens in it closes nowhere within them — shows a note that it cannot be shown as a table (`spreadsheetLongRow`), with the download.
453
+ - **Text**: the bytes are read by the explorer's one rule: the encoding a byte order mark names (UTF-8, UTF-16LE or UTF-16BE), else UTF-8, else the configuration's `legacyTextEncoding` (for example `Shift_JIS`, in which a Japanese spreadsheet application writes CSV), each strictly and never guessed, and decided on the bytes read when the reading stops: a file that is UTF-8 up to there shows as UTF-8 even if a later byte is not. Bytes none of them reads show a note naming the encodings tried by their written names (`spreadsheetUnreadableEncoding`:
454
+ the one a byte order mark names, or UTF-8 and the legacy encoding), text holding NUL a note that the file is not text (`spreadsheetNotText`), each with the download, and a file without data — read whole, its cells, taken whole within the budget, all empty, or none at all — a note that it has no data (`spreadsheetEmpty`; a file whose empty cells run past the budget shows them as a table that is only part of the file).
455
+ - **Rows**: CSV by RFC 4180 — rows end at CRLF, LF or CR; a cell that starts with `"` is quoted and holds commas and line breaks, `""` standing for one `"`; the text after its closing quote joins the cell up to the next comma or line break, as Excel reads it; a quote that never closes holds the rest of the file — and TSV by `@aiquants/spreadsheet`'s grammar, the one a ```spreadsheets block reads. Rows of different widths are padded with empty cells.
456
+ - **States**: the skeleton until the first reading, after which a page view announces the document; a failure before anything was read (the asset answering one, or the connection breaking) shows the failure view with its retry and is announced as a document's failure, alone (in a multi-view panel through the panel's announcer), and a retry that succeeds moves the focus into the table's body and, in a page view, announces the document, as the pane does for a document that replaces a failure;
457
+ every new answer for the document reads the file again with the previous table on screen and the region busy (its progress line and `aria-busy`). Refresh document waits for that reading and reports it once: as reloaded, or, when the reading fails, in the bar's notice (`documentRefreshFailed`) with the table kept; a background answer whose reading fails keeps the table without a word, as a background failure keeps a loaded document. Leaving the view aborts the reading. A document shown as written (its Source) behaves the same way.
458
+ - **As written**: the document bar's Source toggle shows the file's CSV or TSV as written (its tooltip names which), read through the `text` operation by the same rule.
459
+ - **Workbooks**: a `firstSheetOnly` document shows the note `spreadsheetFirstSheetOnly` above the table, and an `external` edit puts the link to the workbook's own editor in the bar.
460
+
461
+ `createFileSystemSource` answers `.csv` files as `csv` and `.tsv` and `.tab` files as `tsv`, never `firstSheetOnly` and without an editor. Excel and OpenDocument workbooks stay `file` documents (downloads): the explorer reads no workbook format.
462
+
432
463
  ### Editing
433
464
 
434
465
  Give `createMarkdownExplorer` the editor's ports as `edit` (`ExplorerEditPorts`) and answer `edit: { kind: "inline" }` for the markdown documents a reader may edit, or `edit: { kind: "draft" }` for those they may edit but not save: `source` answers those with `{ kind: "draft", text }`, the text alone, and such a session never calls `save`, `revisions` or `revision` (refuse them there all the same).
@@ -504,13 +535,17 @@ Names the tree cannot carry — not in NFC, with a colon, ending in a dot or a s
504
535
  | `maxEntries?` | `number` | The most entries a tree may list before it is `too-large` (default 20000). |
505
536
  | `maxDocumentBytes?` | `number` | The largest Markdown file read (default 2 MiB); a larger one is `too-large`. |
506
537
  | `textPreviewBytes?` | `number` | How many leading bytes of a text file are shown (default 8 KiB). |
538
+ | `legacyTextEncoding?` | `string \| null` | The legacy encoding of the source's text and Markdown files, read by the explorer's rule like every file the explorer reads as text: a byte order mark's encoding, else UTF-8, else this; bytes none of them reads show in the first encoding tried, with U+FFFD for each sequence it cannot read, and a text file whose decoded text holds NUL is a `file` document. A label `legacyTextEncodingOf` accepts, or `null` for none, so the resolved configuration's `legacyTextEncoding` passes as it is. None when omitted. |
507
539
  | `walkConcurrency?` | `number` | The most directories the walk reads at once (default 8). |
508
540
  | `cacheScope?` | `"principal" \| "shared"` | Who shares the cached tree: `"principal"` (default), or `"shared"` when the tree does not depend on the reader. Keep `"principal"` when you wrap the source to filter its tree per reader. |
509
541
  | `reportSkipped?` | `(skipped: FileSystemSkippedEntry) => void` | Receives each name the walk leaves out (`sourceId`, `path` and a `FileSystemSkipReason`), once per path (default: a `console.warn`). |
510
542
 
511
543
  Any other option key (a misspelt limit, an option this source does not have) throws a `TypeError` naming it when the source is created, instead of being ignored.
512
544
 
513
- The source's `document(context, path, readPath)` reads the file `readPath` names and shows it as `path` (its parser receives `path`); every other kind (image, media, text, file) reports the file's version, `<size>-<mtimeNs>`, and an image its `imageType`: `"svg"` for the `.svg` extension, the one its `asset` serves as `image/svg+xml`, and `"raster"` for the other image extensions. A file of an unknown extension, and a text file whose preview holds a NUL byte, is a `file` document.
545
+ A host's own sources read text by the same rule through the exports of `@aiquants/markdown-explorer/server`: `legacyTextEncodingOf(label)` (a label's written name, or a `RangeError` for a label that cannot name the legacy encoding), `decodeText(bytes, complete, legacyEncoding)` (strict: the text, or `null` when no encoding of the rule reads the bytes) and `decodeTextLeniently(bytes, complete, legacyEncoding)` (the first encoding tried, with U+FFFD, when none reads them).
546
+ `legacyEncoding` is a label `legacyTextEncodingOf` accepts, or `null` for none — the resolved configuration's `legacyTextEncoding` as it is —, and the decoders refuse the labels it refuses with the same `RangeError`. `complete` says the bytes are the whole file; otherwise a character their end cut is left out, and bytes that end within a byte order mark read nothing yet.
547
+
548
+ The source's `document(context, path, readPath)` reads the file `readPath` names and shows it as `path` (its parser receives `path`); every other kind (image, media, text, file) reports the file's version, `<size>-<mtimeNs>`, and an image its `imageType`: `"svg"` for the `.svg` extension, the one its `asset` serves as `image/svg+xml`, and `"raster"` for the other image extensions. A file of an unknown extension, and a text file whose decoded preview holds NUL, is a `file` document.
514
549
  The source's `ancestors(context, path, readPath)` answers the folders down to the file `readPath` names from its path prefixes (`<prefix>a` and `<prefix>a/b` for `<prefix>a/b/c.md`, `[]` for a file at the top level), which are exactly its tree's row paths, and `null` for any path its walk would not list (outside the prefix, missing, not a regular file, denied, or reached through a symbolic link). A wrapper that turns a folder lazy (as the demo's `withLazyFolder` does) keeps it, because the row paths do not change.
515
550
  The source's `asset(context, path, readPath)` serves every regular file the same checks admit: images and media with their type, everything else (Markdown, text and the files of unknown extensions) without one (`""`), so the explorer delivers it as an `application/octet-stream` download.
516
551
  It opens the file again without following links, requires the device, inode, size and modification time the checks saw (`not-found` when the path now names another file or the file has changed since) and streams the requested range from that handle (the whole file only as long as the checks saw it), which closes when the stream ends, fails or is cancelled, or the request aborts.
@@ -542,7 +577,7 @@ export const explorer = createMarkdownExplorer({
542
577
  ### Serving files
543
578
 
544
579
  The explorer serves every file it shows or offers for download itself, through the `asset` operation of its data route: `<dataPath>/asset?path=<document path>[&v=<version>][&as=text]` (GET and HEAD; see [URL contract](docs/behavior/url-contract.md#asset-urls)).
545
- Images, audio, video and PDF are shown in place; every other file (Markdown, text, spreadsheets, anything else) is delivered as a download, except that `&as=text` asks for any file as UTF-8 plain text shown in place (`text/plain; charset=utf-8`, under the same `nosniff` and sandboxing policy), which is where a text viewer's Open in a new tab goes, since a browser downloads Markdown or cannot show it.
580
+ Images, audio, video and PDF are shown in place; every other file (Markdown, text, table files, workbooks, anything else) is delivered as a download, except that `&as=text` asks for any file as UTF-8 plain text shown in place (`text/plain; charset=utf-8`, under the same `nosniff` and sandboxing policy), which is where a text viewer's Open in a new tab goes, since a browser downloads Markdown or cannot show it, and what a table file's preview reads (one request on the page's origin, since the operation reads the bytes itself and never redirects).
546
581
  The host supplies only the bytes, through the `asset` port:
547
582
 
548
583
  | `ExplorerAssetFile` field | Type | Meaning |
@@ -579,8 +614,11 @@ and `Cache-Control: private, max-age=60, stale-while-revalidate=600, no-transfor
579
614
  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.
580
615
  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).
581
616
 
582
- The data route's `text` operation reads a file through the same port for the Source toggles (the document bar's, and that of an SVG image inside a rendered document): `<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.
583
- 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`.
617
+ The data route's `text` operation reads a file through the same port for the Source toggles (the document bar's — a Markdown document, an SVG image, a table file — and that of an SVG image inside a rendered document) and that image's Copy:
618
+ `<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.
619
+ 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),
620
+ cancels the stream once enough was read, decodes them by the explorer's one rule — the encoding a byte order mark names (the mark dropped), else UTF-8, else the configuration's `legacyTextEncoding`, each strictly, and bytes none of them reads in the first encoding tried with U+FFFD for each sequence it cannot read (a character the limit cuts left out; `decodeTextLeniently`) —, and answers `unsupported` for text holding NUL and `failed` (logged) for a stream that ends before the `size` the port reported.
621
+ It sends no refresh mark: the port receives `refresh: false`.
584
622
 
585
623
  ### Redirecting to the storage
586
624
 
@@ -864,7 +902,8 @@ Every scroller of the explorer that the reader browses gets one pointer scroll b
864
902
  - 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.
865
903
  - 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.
866
904
  - 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)).
867
- - The source of a Markdown document or an SVG image (the Source toggles: the document bar's, and that of an SVG image inside a rendered document) 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.
905
+ - The source of a Markdown document, an SVG image or a table file (the Source toggles: the document bar's, and that of an SVG image inside a rendered document, and that image's Copy) 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 by the explorer's rule into JSON, which the browser shows as text and never interprets.
906
+ - A table file's preview reads the file's bytes through the asset's plain-text delivery, the download the reader already has, and puts its cells into the grid as text (a cell is never markup or a link). What the grid copies and saves is each cell's text as read, so a cell a spreadsheet application reads as a formula stays one there, exactly as in the downloaded file.
868
907
  - 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`).
869
908
  - 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.
870
909
  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.
@@ -886,7 +925,12 @@ Tests and host styling may rely on the `data-testid` and `data-aqmx-*` attribute
886
925
  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.
887
926
  - 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.
888
927
  - A ```spreadsheets table stays read-only in the preview, and says so, when its block holds a line the converter reads with a tab split at a container's edge or a tab right after `>`, or an info string whose first word holds a backslash or an ampersand: readings the editor does not reproduce, so it never writes such a block in a way the converter would read differently. Inside a list item, a line of spaces and tabs only reads as an empty line (CommonMark), so a row whose cells are all white space is written as an empty line and keeps no cells; the table then shows the row as the editor reads it.
889
- - 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).
928
+ - Document kinds are the six above; `createFileSystemSource` previews only files with a known text extension or name as text, shows `.csv`, `.tsv` and `.tab` files as tables, and offers any other file as a `file` document (a download). The explorer reads no workbook format (Excel, OpenDocument): a workbook shows as a table only when the host exports it as CSV or TSV, and then as one sheet.
929
+ - A table file's preview shows at most the 100,000 cells a grid operates on at once, 1,000 columns and 32,767 characters of a cell, and reads at most `spreadsheets.maxBytes` of the file, which it parses on the browser's main thread (a row of more cells than a preview shows is still read whole: a single 2 MiB row of commas or tabs takes a few tenths of a second, where 2 MiB of ordinary rows stops at the cell budget in about a hundredth). It reads no encoding the file does not mark or the configuration does not name:
930
+ a UTF-8 file with a few stray bytes shows the encoding note instead of a table (or, with a legacy encoding configured, is read in that encoding). The encoding is decided on the bytes each view reads, so the table and the Source view of a file whose encoding changes past where one of them stopped reading may read it differently.
931
+ - A TSV file read partway shows only the rows before the first cell that opens a quote the bytes read do not close (a lone `"` used as a ditto mark, for example), since the rest of the file could still close it: a TSV larger than `spreadsheets.maxBytes` with such a cell near its start shows only the rows above it — or, with no row above it, the note that no row ends within the part read (`spreadsheetLongRow`) —, where read whole it shows every row (an unclosed quote is literal in a whole TSV). A CSV is not affected (an unclosed quote holds the rest of a whole CSV too).
932
+ - Text is decoded by the runtime's `TextDecoder`, and runtimes answer a few bytes differently from the Encoding Standard: Node refuses the byte 0x80 in Shift_JIS (the standard reads it as U+0080) and reads it as U+0080 in Big5 and EUC-KR (the standard refuses it). A file holding such a byte can therefore show as a table in the browser while its Source, read on the server, falls back to the first encoding tried with U+FFFD, or the other way round.
933
+ - Open in a new tab shows a text or table file as UTF-8 plain text (`as=text`) whatever `legacyTextEncoding` names: the server would have to read the whole file to name its encoding, which a HEAD or ranged request never does, so a file in the legacy encoding shows garbled there, while the explorer's own views read it in that encoding (a table, a Source view, and the text preview of a file-system source given the same encoding).
890
934
  - HTML larger than `sanitizer.maxHtmlBytes` (4 MiB), placed deeper than 512 levels while it is parsed, making the parser create more elements than it has characters, more nodes than the worker's heap holds (81,920 elements, attributes and comments by default) or more than 4,096 comments, holding a tag with more than 1,024 attributes (counted before parsing for every `<` or `</` followed by a letter, so text in a script, a comment or an attribute value that looks like such a tag counts too), giving `html` or `body` more than 1,024 attributes through repeated tags,
891
935
  carrying attributes whose characters, counting every copy of a reopened formatting element, exceed `maxHtmlBytes`, sanitizing to HTML longer than four characters per byte of `maxHtmlBytes`, or not sanitized within `sanitizer.deadlineMs` (30 s) shows as `too-large`.
892
936
  - All anonymous readers share one scope, so they share the admission budget as well as the running share: with `anonymousAccess`, the `jobsPerScope` documents running or waiting are counted for all visitors together, and panels beyond that budget come back `failed` until a reload or "Try again". For a public deployment, set `jobsPerScope` to the number of visitors expected to open a multi view at the same moment times `multiView.maxPanels`; `maxQueuedJobs` then defaults to four times that.
@@ -901,7 +945,8 @@ Tests and host styling may rely on the `data-testid` and `data-aqmx-*` attribute
901
945
  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),
902
946
  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,
903
947
  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),
904
- 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.
948
+ 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), table files (`notes/tables`: a UTF-8 CSV with quoted cells, a Shift_JIS CSV read through `legacyTextEncoding:
949
+ "Shift_JIS"`, which the demo gives its file-system sources too, a TSV, and a CSV wider than the preview's 1,000 columns), the instant preview with `@aiquants/markdown`'s browser converter as `draftConverter` (`demo/app/draft-converter.client.ts`), and the end-to-end tests' fixtures.
905
950
  Run it with `pnpm run demo:dev` from the package folder.
906
951
 
907
952
  ## License