@dita-viewer/core 0.2.1 → 0.2.2

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 (41) hide show
  1. package/README.md +20 -7
  2. package/dist/editor/renderContext.d.ts +7 -0
  3. package/dist/editor/renderContext.js +24 -0
  4. package/dist/editor/topicRender.d.ts +9 -0
  5. package/dist/editor/topicRender.js +4 -2
  6. package/dist/language/ditaLanguageUtils.js +2 -0
  7. package/dist/profiling.d.ts +7 -1
  8. package/dist/profiling.js +9 -3
  9. package/dist/render/baseTypeMap.js +28 -2
  10. package/dist/render/renderer.d.ts +24 -0
  11. package/dist/render/renderer.js +36 -9
  12. package/dist-esm/bookRender.js +145 -0
  13. package/dist-esm/completion.js +142 -0
  14. package/dist-esm/completionData.js +155 -0
  15. package/dist-esm/diagnostics.js +378 -0
  16. package/dist-esm/editor/conkeyref.js +104 -0
  17. package/dist-esm/editor/keySpace.js +201 -0
  18. package/dist-esm/editor/refResolvers.js +633 -0
  19. package/dist-esm/editor/renderContext.js +138 -0
  20. package/dist-esm/editor/sourceText.js +142 -0
  21. package/dist-esm/editor/topicRender.js +328 -0
  22. package/dist-esm/index.js +66 -0
  23. package/dist-esm/keyMapForDocument.js +23 -0
  24. package/dist-esm/language/ditaLanguageUtils.js +659 -0
  25. package/dist-esm/language/referenceableFiles.js +108 -0
  26. package/dist-esm/mapRender.js +24 -0
  27. package/dist-esm/package.json +1 -0
  28. package/dist-esm/parser/ditaParser.js +409 -0
  29. package/dist-esm/parser/domTypes.js +1 -0
  30. package/dist-esm/parser/mapTagMap.js +77 -0
  31. package/dist-esm/parser/namedEntities.js +321 -0
  32. package/dist-esm/parser/standardTagMap.js +393 -0
  33. package/dist-esm/profiling.js +224 -0
  34. package/dist-esm/render/baseTypeMap.js +1057 -0
  35. package/dist-esm/render/cjkSpacing.js +94 -0
  36. package/dist-esm/render/mapTypeMap.js +568 -0
  37. package/dist-esm/render/renderer.js +519 -0
  38. package/dist-esm/siteRender.js +261 -0
  39. package/package.json +4 -2
  40. package/styles/TOKENS.md +21 -0
  41. package/styles/dita-content.css +31 -17
@@ -0,0 +1,138 @@
1
+ // Shared render-context factory (P2).
2
+ //
3
+ // The three DITA render paths -- renderTopicXml (book / site / map preview),
4
+ // DitaViewerProvider.renderTopicContentUntracked (single-topic custom editor)
5
+ // and ditaDiffProvider.computeDiff (the Git compare panel) -- each used to
6
+ // hand-assemble the same conref / keyref / title / image resolvers into a
7
+ // RenderContext. Duplicating the wiring meant that adding a resolver (the
8
+ // upcoming conkeyref, P3) in one path would silently leave the other two
9
+ // behind. Centralising it here means the key resolvers are wired once.
10
+ //
11
+ // Pure module: no vscode import. `asWebviewUri` and the document directory
12
+ // are passed in by the caller (those are the only genuinely per-path bits),
13
+ // so the whole factory is unit-testable in plain mocha.
14
+ //
15
+ // What legitimately differs per path stays as input flags, so wiring the
16
+ // factory in is behaviour-preserving:
17
+ // - includeIndexLabel: preview and book set indexLabel, the diff view does
18
+ // not (it never surfaces indexterm chips). Kept as a flag to preserve
19
+ // that byte-for-byte.
20
+ // - collectDependencies / bookMembers: only the book/site path uses them.
21
+ // collectDependencies also folds image reads into the dependency set.
22
+ // - suppressIndexterm: only the export path sets it.
23
+ import { resolve, relative, isAbsolute } from 'path';
24
+ import { makeFileCache, makeConrefResolver, makeConrefRangeResolver, makeFileTitleResolver, makeIsInCurrentBook, detectNoteLabels, detectIndexLabel, readImageDimensions, decodeHrefPart, URL_SCHEME_RE, } from './refResolvers';
25
+ import { getKeyDefs } from './keySpace';
26
+ import { resolveConkeyref } from './conkeyref';
27
+ export function buildRenderContext(input) {
28
+ const { docDir, ownRoot, titleMap, keyMap, asWebviewUri, headingLevel, uiLanguage } = input;
29
+ // One cache shared by all three resolvers. They routinely load the same
30
+ // conref/title target; sharing avoids re-parsing it and gives a single
31
+ // place to read back the complete set of files this render touched.
32
+ const fileCache = makeFileCache(docDir);
33
+ const conrefResolver = makeConrefResolver(docDir, ownRoot, fileCache);
34
+ const conrefRangeResolver = makeConrefRangeResolver(docDir, ownRoot, fileCache);
35
+ const fileTitleResolver = makeFileTitleResolver(docDir, fileCache);
36
+ const ctx = {
37
+ headingLevel,
38
+ asWebviewUri,
39
+ documentDir: docDir,
40
+ // Local id match first, then cross-file ("file.dita#topicId" or "file.dita").
41
+ resolveTitle: (id) => titleMap.get(id) || fileTitleResolver(id),
42
+ resolveKey: (key) => keyMap.get(key),
43
+ resolveConref: (conref) => conrefResolver(conref),
44
+ resolveConrefRange: (conref, conrefend) => conrefRangeResolver(conref, conrefend),
45
+ noteLabels: detectNoteLabels(ownRoot, uiLanguage),
46
+ suppressIndexterm: input.suppressIndexterm,
47
+ getImageDimensions: (relPath) => {
48
+ try {
49
+ const absPath = resolve(docDir, decodeHrefPart(relPath));
50
+ // An image's dimensions are emitted as width/height attributes, so
51
+ // the file is a genuine dependency of the rendered HTML and has to be
52
+ // recorded alongside the conref/title targets (only when the caller
53
+ // passes a sink -- the preview and diff paths do not).
54
+ input.collectDependencies?.add(absPath);
55
+ return readImageDimensions(absPath);
56
+ }
57
+ catch {
58
+ return undefined;
59
+ }
60
+ },
61
+ };
62
+ if (input.markConrefs && input.docFile) {
63
+ const docFile = input.docFile;
64
+ // origins only holds elements resolved from another file or through a
65
+ // chain; a same-document target has none, and lives in docFile.
66
+ ctx.conrefSource = (target) => fileCache.originOf(target)?.file ?? docFile;
67
+ }
68
+ if (input.includeIndexLabel)
69
+ ctx.indexLabel = detectIndexLabel(ownRoot, uiLanguage);
70
+ if (input.bookMembers)
71
+ ctx.isInCurrentBook = makeIsInCurrentBook(docDir, input.bookMembers);
72
+ if (input.clickableExternalXrefs)
73
+ ctx.clickableExternalXrefs = true;
74
+ // conkeyref rides on the same file cache: a key's href resolves against the
75
+ // map that defined it (baseDir), not the topic being rendered, so it needs
76
+ // the absolute-path loader rather than the docDir-relative conref resolver.
77
+ // Discovered from keyMap by identity unless the caller passed defs directly.
78
+ let lastLoaded;
79
+ const keyDefs = input.keyDefs ?? getKeyDefs(keyMap);
80
+ if (keyDefs && keyDefs.size > 0) {
81
+ // A keyref on a link-shaped element (topic/xref) resolves to the key's
82
+ // resource target as its effective href. The keydef's href is relative
83
+ // to the map that defined it, but every href the renderer consumes
84
+ // (isInCurrentBook, resolveTitle, the preview's own open-by-href) is
85
+ // relative to the DOCUMENT's folder -- so rebase here, preserving any
86
+ // element-id fragment, and hand through the shapes that are not
87
+ // filesystem paths (URL schemes, absolute paths) untouched.
88
+ ctx.resolveKeyHref = (key) => {
89
+ const def = keyDefs.get(key);
90
+ if (!def?.href)
91
+ return undefined;
92
+ const raw = def.href;
93
+ if (URL_SCHEME_RE.test(raw) || isAbsolute(raw))
94
+ return raw;
95
+ const hashIdx = raw.indexOf('#');
96
+ const pathPart = hashIdx >= 0 ? raw.slice(0, hashIdx) : raw;
97
+ const fragment = hashIdx >= 0 ? raw.slice(hashIdx) : '';
98
+ if (!pathPart)
99
+ return fragment || undefined;
100
+ const abs = resolve(def.baseDir, decodeHrefPart(pathPart));
101
+ return relative(docDir, abs).replace(/\\/g, '/') + fragment;
102
+ };
103
+ const loadTopic = (baseDir, href) => {
104
+ const absPath = resolve(baseDir, decodeHrefPart(href.split('#')[0]));
105
+ // A conkeyref target is a real dependency of the rendered HTML, exactly
106
+ // like a conref target; record it when the caller tracks dependencies.
107
+ input.collectDependencies?.add(absPath);
108
+ return fileCache.loadAbsPath(absPath);
109
+ };
110
+ ctx.resolveConkeyref = (conkeyref) => {
111
+ const el = resolveConkeyref(conkeyref, keyDefs, (baseDir, href) => {
112
+ const absPath = resolve(baseDir, decodeHrefPart(href.split('#')[0]));
113
+ const root = loadTopic(baseDir, href);
114
+ if (root)
115
+ lastLoaded = { file: absPath, root };
116
+ return root;
117
+ });
118
+ if (el && lastLoaded)
119
+ fileCache.noteOrigin(el, lastLoaded);
120
+ return el;
121
+ };
122
+ }
123
+ // One hop further along a reference chain, resolved relative to the file
124
+ // that holds `from`. conkeyref wins over conref when it resolves, the same
125
+ // rule as the first hop (an unresolvable conkeyref falls back to conref).
126
+ ctx.resolveChainHop = (from) => {
127
+ const conkeyref = from.attributes?.conkeyref;
128
+ if (conkeyref && ctx.resolveConkeyref) {
129
+ lastLoaded = undefined;
130
+ const viaKey = ctx.resolveConkeyref(conkeyref);
131
+ if (viaKey)
132
+ return viaKey;
133
+ }
134
+ const conref = from.attributes?.conref;
135
+ return conref ? conrefResolver(conref, from) : undefined;
136
+ };
137
+ return { ctx, touchedFiles: () => fileCache.touchedFiles() };
138
+ }
@@ -0,0 +1,142 @@
1
+ /**
2
+ * How the extension reads and fingerprints DITA source files.
3
+ *
4
+ * Previews are built from more than the document on screen -- conref targets,
5
+ * mapref'd maps, keydef maps, the topics of a book -- and those used to be
6
+ * read from disk, so text that was typed into an editor tab but not saved
7
+ * did not show. The overlay below is the fix: a registry of the unsaved text
8
+ * of open documents. Every read of a DITA source goes through readSourceText
9
+ * (the unsaved text if there is any, otherwise the disk), and every cache
10
+ * fingerprint through sourceStamp (which changes when either does).
11
+ *
12
+ * Pure of the vscode module, so the rules here can be unit-tested; the code
13
+ * that feeds it from editor events is in sourceOverlaySync.ts.
14
+ */
15
+ import { readFileSync, statSync } from 'fs';
16
+ import { normalize } from 'path';
17
+ const overlay = new Map();
18
+ /**
19
+ * One counter for every overlay change to every file, never reset. A stamp
20
+ * built from it cannot collide with an earlier one: document.version, the
21
+ * obvious alternative, restarts at 1 whenever a document is closed and
22
+ * reopened, so "discard changes, reopen, type something else" could land on
23
+ * a version number a cache entry was already built for.
24
+ */
25
+ let revision = 0;
26
+ /**
27
+ * Same file however the path is spelled: `..` segments, case on Windows, and
28
+ * `/` vs `\` -- normalize() only resolves the former two and, on win32,
29
+ * rewrites `/` to `\`, so a caller (or a test) that builds a path with `/`
30
+ * throughout gets a different key than the disk path unless both are folded
31
+ * to one separator here.
32
+ */
33
+ function key(filePath) {
34
+ const n = normalize(filePath).replace(/\\/g, '/');
35
+ return process.platform === 'win32' ? n.toLowerCase() : n;
36
+ }
37
+ /**
38
+ * Records `text` as the current unsaved content of a file. A no-op when it
39
+ * already is: editor events fire for changes that do not alter the text (a
40
+ * re-sync on open, a dirty-flag flip), and each real change here invalidates
41
+ * every cache built from the file.
42
+ */
43
+ export function setSourceOverlay(filePath, text) {
44
+ const k = key(filePath);
45
+ const existing = overlay.get(k);
46
+ if (existing && existing.text === text)
47
+ return;
48
+ overlay.set(k, { text, rev: ++revision });
49
+ }
50
+ /** The file is saved, reverted or closed: the disk is the truth again. */
51
+ export function clearSourceOverlay(filePath) {
52
+ overlay.delete(key(filePath));
53
+ }
54
+ export function clearAllSourceOverlays() {
55
+ overlay.clear();
56
+ }
57
+ /** How many files currently have unsaved text -- test hook. */
58
+ export function sourceOverlaySize() {
59
+ return overlay.size;
60
+ }
61
+ /**
62
+ * The text of a DITA source file as the author currently has it: unsaved
63
+ * editor text when there is some, the file on disk otherwise. Throws exactly
64
+ * as readFileSync does for an unreadable file, so callers keep their existing
65
+ * error handling. The one-value encoding parameter is what expandDitamapRefs'
66
+ * FileReader type asks for.
67
+ */
68
+ export function readSourceText(filePath, encoding = 'utf-8') {
69
+ const k = key(filePath);
70
+ recorder?.add(k);
71
+ const entry = overlay.get(k);
72
+ return entry ? entry.text : readFileSync(filePath, encoding);
73
+ }
74
+ // ── Which sources a render read ──
75
+ //
76
+ // A preview panel has to decide, for an edit made in some other document,
77
+ // whether that edit can change what it shows. The answer is exactly "did my
78
+ // last render read that file", which the readers above can report as they go.
79
+ let recorder;
80
+ /**
81
+ * Runs `fn` and returns its result along with every source file read through
82
+ * readSourceText while it ran (as normalized keys, for dependsOn). Nests: an
83
+ * inner call gets its own files, and they are also added to the outer one.
84
+ * Anything that answers from a cache instead of reading must say what the
85
+ * cached answer was built from -- see noteSourceDependencies.
86
+ */
87
+ export function trackSourceReads(fn) {
88
+ const outer = recorder;
89
+ const mine = new Set();
90
+ recorder = mine;
91
+ try {
92
+ return { result: fn(), files: mine };
93
+ }
94
+ finally {
95
+ recorder = outer;
96
+ if (outer)
97
+ for (const f of mine)
98
+ outer.add(f);
99
+ }
100
+ }
101
+ /**
102
+ * For a cache hit: reading nothing does not mean depending on nothing. The
103
+ * cache entry knows the files it was built from, and reports them here so an
104
+ * enclosing trackSourceReads sees the same set on the second pass as on the
105
+ * first. A no-op outside a tracker.
106
+ */
107
+ export function noteSourceDependencies(filePaths) {
108
+ if (!recorder)
109
+ return;
110
+ for (const p of filePaths)
111
+ recorder.add(key(p));
112
+ }
113
+ /** Whether a set returned by trackSourceReads contains this file, however its path is spelled. */
114
+ export function dependsOn(files, filePath) {
115
+ return files.has(key(filePath));
116
+ }
117
+ /**
118
+ * A fingerprint of one file, comparable by string equality: two calls return
119
+ * the same string exactly when nothing that matters to a cached render
120
+ * derived from the file changed in between.
121
+ *
122
+ * `dirty:<rev>` while the file has unsaved text; `<mtimeMs>:<size>` on disk.
123
+ * mtime alone is not enough -- a restored timestamp (git checkout, a copy
124
+ * tool, a coarse-grained file system) can leave it equal for a file whose
125
+ * content is different, and size catches most of those at the cost of one
126
+ * field of the stat that is already being made. A file that cannot be
127
+ * statted is "?", so deleting a dependency invalidates exactly as modifying
128
+ * it does, and creating one that was missing turns "?" into a real stamp --
129
+ * the other half of the same requirement.
130
+ */
131
+ export function sourceStamp(filePath) {
132
+ const entry = overlay.get(key(filePath));
133
+ if (entry)
134
+ return `dirty:${entry.rev}`;
135
+ try {
136
+ const st = statSync(filePath);
137
+ return `${st.mtimeMs}:${st.size}`;
138
+ }
139
+ catch {
140
+ return '?';
141
+ }
142
+ }
@@ -0,0 +1,328 @@
1
+ // Topic rendering pipeline: text/title extraction, interfaces, parse-and-render
2
+ // functions, and the LRU render cache that book mode uses to skip re-rendering
3
+ // unchanged topics. Moved verbatim from ditaRenderUtils.ts (P5 pure refactor);
4
+ // imports its dependencies from sibling modules so no cycle through the barrel.
5
+ import { existsSync, readdirSync } from 'fs';
6
+ import { dirname, join } from 'path';
7
+ import { parseDita, preprocessEntities } from '../parser/ditaParser';
8
+ import { renderDocument } from '../render/renderer';
9
+ import { buildRenderContext } from './renderContext';
10
+ import { sourceStamp, readSourceText, noteSourceDependencies } from './sourceText';
11
+ // ── Text extraction ──
12
+ export function collectText(node) {
13
+ if (node.type === 'text')
14
+ return node.text || '';
15
+ return (node.children || []).map(collectText).join('');
16
+ }
17
+ // ── Title map (id → title text for xref) ──
18
+ export function buildTitleMap(root) {
19
+ const map = new Map();
20
+ function walk(node) {
21
+ if (node.type === 'element') {
22
+ const id = node.attributes?.id;
23
+ if (id) {
24
+ const titleChild = (node.children || []).find((c) => c.type === 'element' && c.baseType === 'topic/title');
25
+ if (titleChild) {
26
+ map.set(id, collectText(titleChild));
27
+ }
28
+ }
29
+ for (const child of node.children || [])
30
+ walk(child);
31
+ }
32
+ }
33
+ walk(root);
34
+ return map;
35
+ }
36
+ export function renderTopicXml(input) {
37
+ const { xml, docDir, keyMap, asWebviewUri, headingLevel, uiLanguage, suppressIndexterm, collectDependencies, bookMembers, clickableExternalXrefs, docFile, markConrefs } = input;
38
+ try {
39
+ const preprocessedXml = preprocessEntities(xml);
40
+ const ditaDoc = parseDita(preprocessedXml);
41
+ const titleMap = buildTitleMap(ditaDoc.root);
42
+ // Resolvers, note/index labels and image dimensions are assembled by the
43
+ // shared buildRenderContext factory (renderContext.ts) so this path, the
44
+ // single-topic preview and the diff panel wire them identically. The book
45
+ // extras (isInCurrentBook, collectDependencies) and indexLabel are on here.
46
+ const { ctx, touchedFiles } = buildRenderContext({
47
+ docDir,
48
+ ownRoot: ditaDoc.root,
49
+ titleMap,
50
+ keyMap,
51
+ asWebviewUri,
52
+ headingLevel,
53
+ uiLanguage,
54
+ includeIndexLabel: true,
55
+ suppressIndexterm,
56
+ bookMembers,
57
+ clickableExternalXrefs,
58
+ collectDependencies,
59
+ docFile,
60
+ markConrefs,
61
+ });
62
+ const html = renderDocument(ditaDoc.root, ctx);
63
+ if (collectDependencies) {
64
+ for (const touched of touchedFiles())
65
+ collectDependencies.add(touched);
66
+ }
67
+ const titleNode = (ditaDoc.root.children || []).find((c) => c.type === 'element' && c.baseType === 'topic/title');
68
+ const title = titleNode ? collectText(titleNode) : undefined;
69
+ return { doc: ditaDoc, html, title };
70
+ }
71
+ catch (err) {
72
+ const message = err instanceof Error ? err.message : String(err);
73
+ return { html: '', error: `Error rendering topic: ${message}` };
74
+ }
75
+ }
76
+ export function renderTopicToHtml(input) {
77
+ const { filePath, keyMap, asWebviewUri, headingLevel, uiLanguage, suppressIndexterm, collectDependencies, bookMembers, clickableExternalXrefs, markConrefs } = input;
78
+ try {
79
+ if (!existsSync(filePath)) {
80
+ return { html: '', error: `File not found: ${filePath}` };
81
+ }
82
+ // The topic's own file is a dependency of its own render even though it
83
+ // is read here rather than through the shared file cache.
84
+ collectDependencies?.add(filePath);
85
+ const rawXml = readSourceText(filePath, 'utf-8');
86
+ const result = renderTopicXml({
87
+ xml: rawXml,
88
+ docDir: dirname(filePath),
89
+ keyMap,
90
+ asWebviewUri,
91
+ headingLevel,
92
+ uiLanguage,
93
+ suppressIndexterm,
94
+ collectDependencies,
95
+ bookMembers,
96
+ clickableExternalXrefs,
97
+ docFile: filePath,
98
+ markConrefs,
99
+ });
100
+ return { html: result.html, title: result.title, error: result.error };
101
+ }
102
+ catch (err) {
103
+ const message = err instanceof Error ? err.message : String(err);
104
+ return { html: '', error: `Error rendering ${filePath}: ${message}` };
105
+ }
106
+ }
107
+ // ── Topic render cache (book mode) ──
108
+ /**
109
+ * Fingerprint of a set of files, used to decide whether a cached result
110
+ * derived from them is still valid: one sourceStamp per file (sourceText.ts
111
+ * has the rules, including how a missing file and a changed size count),
112
+ * joined in order.
113
+ *
114
+ * Shared by buildKeyMap's cache (keyMap.ts), renderTopicCached below and
115
+ * the book search index. It lived privately in the first until the topic
116
+ * cache needed the identical logic; keeping one copy is the point.
117
+ */
118
+ export function stampFiles(files) {
119
+ return files.map(sourceStamp).join('|');
120
+ }
121
+ /**
122
+ * Pure directory-walking core of findDitamapFiles (keyMap.ts). Lives here
123
+ * rather than there for the same reason stampFiles above does: keyMap.ts
124
+ * imports vscode at module scope for parseDocRoot/vscode.Uri, so nothing
125
+ * defined there can be unit tested without a vscode.Uri/workspace, even
126
+ * logic like this that never touches vscode itself.
127
+ *
128
+ * Walks upward from startDir to root (inclusive); at *each* level it scans
129
+ * that directory's whole subtree, not just its direct children, for
130
+ * .ditamap files -- layouts that keep maps/ and topics/ as siblings (see
131
+ * test-dita-file/manual) put the nearest map one directory below the
132
+ * ancestor level being scanned, so a direct-children-only scan at each
133
+ * ancestor silently misses it and buildKeyMap falls back to whichever
134
+ * unrelated .ditamap happens to sit directly in a further-up ancestor, if
135
+ * any, instead of the real one (kill test: keyMap.test.ts).
136
+ */
137
+ export function collectDitamapFilesUpward(startDir, root, stopAtFirstMatch) {
138
+ const results = [];
139
+ // A directory two ancestor levels up recursively covers everything a
140
+ // closer level already scanned, so without this a .ditamap nested a
141
+ // couple of directories down would be reported once per ancestor level
142
+ // that subsumes it, not once.
143
+ const visited = new Set();
144
+ let dir = startDir;
145
+ while (dir.length >= root.length) {
146
+ collectDitamapFilesRecursive(dir, results, visited);
147
+ if (stopAtFirstMatch && results.length > 0)
148
+ return results;
149
+ const parent = dirname(dir);
150
+ if (parent === dir)
151
+ break;
152
+ dir = parent;
153
+ }
154
+ return results;
155
+ }
156
+ function collectDitamapFilesRecursive(dir, results, visited) {
157
+ if (visited.has(dir))
158
+ return;
159
+ visited.add(dir);
160
+ let entries;
161
+ try {
162
+ entries = readdirSync(dir, { withFileTypes: true });
163
+ }
164
+ catch (e) {
165
+ console.warn(`Failed to read directory ${dir}:`, e instanceof Error ? e.message : e);
166
+ return;
167
+ }
168
+ for (const entry of entries) {
169
+ const full = join(dir, entry.name);
170
+ if (entry.isDirectory()) {
171
+ collectDitamapFilesRecursive(full, results, visited);
172
+ }
173
+ else if (entry.name.toLowerCase().endsWith('.ditamap')) {
174
+ results.push(full);
175
+ }
176
+ }
177
+ }
178
+ /**
179
+ * Budget for the topic render cache below, in bytes of rendered HTML.
180
+ *
181
+ * Bounded and clearable like every other cache in this file, per the rule
182
+ * stated at imageDimensionsCache -- but bounded by bytes rather than by entry
183
+ * count, because count is not a meaningful unit here. The other caches hold
184
+ * fixed-size entries (a dimension pair, a keymap), so capping their count caps
185
+ * their memory; a topic's HTML varies by orders of magnitude between a stub
186
+ * and a full reference topic, so any count cap is either far too generous in
187
+ * bytes or, set low enough to be safe, far too tight in entries.
188
+ *
189
+ * Too tight in entries is the failure that matters, and it is not gradual: a
190
+ * book with more topics than the cap gets NO reuse at all. Each pass renders
191
+ * in map order, so once the cache is full every insertion evicts an entry the
192
+ * same pass has not reached again yet -- a cyclic access pattern, LRU's
193
+ * classic worst case. Budgeting by bytes puts the cliff where it belongs: a
194
+ * book whose entire HTML exceeds the budget is already costing at least that
195
+ * much to hold as one assembled string (plus the webview DOM built from it),
196
+ * so that is the point at which caching more stops being worth it.
197
+ *
198
+ * 32MB holds roughly 4,500 typical topics -- any realistic book, with room
199
+ * for several open at once. Cleared from clearAllCaches() on deactivation.
200
+ */
201
+ export const TOPIC_RENDER_CACHE_MAX_BYTES = 32 * 1024 * 1024;
202
+ const topicRenderCache = new Map();
203
+ let topicRenderCacheBytes = 0;
204
+ let topicRenderCacheBudget = TOPIC_RENDER_CACHE_MAX_BYTES;
205
+ export function clearTopicRenderCache() {
206
+ topicRenderCache.clear();
207
+ topicRenderCacheBytes = 0;
208
+ }
209
+ /** How many topic renders are currently held -- test hook for eviction/clear. */
210
+ export function topicRenderCacheSize() {
211
+ return topicRenderCache.size;
212
+ }
213
+ /** Bytes of HTML currently held -- test hook, paired with the size above. */
214
+ export function topicRenderCacheBytesHeld() {
215
+ return topicRenderCacheBytes;
216
+ }
217
+ /**
218
+ * Test hook: shrinks the budget so eviction can be exercised without first
219
+ * rendering 32MB of real topics. Called with no argument it restores the
220
+ * production budget. Nothing outside the test suite calls this.
221
+ */
222
+ export function setTopicRenderCacheBudgetForTesting(bytes) {
223
+ topicRenderCacheBudget = bytes ?? TOPIC_RENDER_CACHE_MAX_BYTES;
224
+ }
225
+ function dropTopicEntry(key) {
226
+ const entry = topicRenderCache.get(key);
227
+ if (!entry)
228
+ return;
229
+ topicRenderCache.delete(key);
230
+ topicRenderCacheBytes -= entry.bytes;
231
+ }
232
+ function dropOldestTopicEntry() {
233
+ const oldest = topicRenderCache.keys().next().value;
234
+ if (oldest !== undefined)
235
+ dropTopicEntry(oldest);
236
+ }
237
+ /**
238
+ * renderTopicToHtml with reuse across passes -- the difference between "one
239
+ * keystroke in one topic" and "the whole book again" in book mode, which
240
+ * otherwise re-renders every referenced topic on each debounced pass (see
241
+ * scripts/bench-book-render.js for the measured cost, and the budget note
242
+ * above for why reuse is bounded in bytes).
243
+ *
244
+ * Deliberately opt-in and separate rather than built into renderTopicToHtml:
245
+ * "Export as HTML" calls that one with its own asWebviewUri, and sharing a
246
+ * single cache between the two would hand book-mode HTML to an exported
247
+ * standalone file.
248
+ *
249
+ * Two assumptions worth stating, since neither is enforced by the key.
250
+ *
251
+ * asWebviewUri output depends only on the local URI and the window's remote
252
+ * info, never on which webview asked: VS Code builds it as
253
+ * `https://<scheme>+<authority>.vscode-resource.vscode-cdn.net<path>` in a
254
+ * module-level helper with no panel in scope, and cspSource is likewise the
255
+ * constant `'self' https://*.vscode-cdn.net` (both checked against the
256
+ * shipped extension host bundle, not assumed). So HTML built for one map
257
+ * panel is valid in another, and the caller's asWebviewUri closure is not
258
+ * part of the cache key.
259
+ *
260
+ * headingLevel is part of the key rather than a merely validated field
261
+ * because the same topic legitimately sits at different depths across two
262
+ * open books -- validating it instead would make those two entries evict each
263
+ * other on every pass.
264
+ */
265
+ export function renderTopicCached(input) {
266
+ const key = `${input.filePath}\u0000${input.headingLevel}`;
267
+ const cached = topicRenderCache.get(key);
268
+ if (cached &&
269
+ cached.keyMap === input.keyMap &&
270
+ cached.uiLanguage === input.uiLanguage &&
271
+ cached.suppressIndexterm === input.suppressIndexterm &&
272
+ cached.bookMembers === input.bookMembers &&
273
+ stampFiles(cached.files) === cached.stamps) {
274
+ // Re-insert so a hit keeps the entry from being the oldest (and therefore
275
+ // first-evicted) candidate -- same LRU-by-reinsertion as
276
+ // imageDimensionsCache above.
277
+ topicRenderCache.delete(key);
278
+ topicRenderCache.set(key, cached);
279
+ // A hit reads nothing, but the answer still stands for these files.
280
+ noteSourceDependencies(cached.files);
281
+ return { html: cached.html, title: cached.title };
282
+ }
283
+ // Honour a caller-supplied sink as well, so anyone who passed one still
284
+ // sees the dependency set instead of having it silently replaced.
285
+ const dependencies = input.collectDependencies ?? new Set();
286
+ // Previews only (see above), so conref'd content is always marked here.
287
+ const result = renderTopicToHtml({ ...input, markConrefs: true, collectDependencies: dependencies });
288
+ if (result.error) {
289
+ // Never cache a failure. A malformed mid-edit save is exactly the
290
+ // transient case this path sees, and pinning it would keep serving the
291
+ // error page after the file was fixed -- the dependency stamps would
292
+ // still match, because the file that failed to parse is the very file
293
+ // whose stamp gets compared.
294
+ dropTopicEntry(key);
295
+ return result;
296
+ }
297
+ const files = [...dependencies];
298
+ // UTF-8 bytes, not html.length: DITA content is frequently CJK, where the
299
+ // character count understates what is actually retained by up to 3x.
300
+ const bytes = Buffer.byteLength(result.html, 'utf8');
301
+ if (bytes > topicRenderCacheBudget) {
302
+ // A single topic larger than the entire budget. Caching it would evict
303
+ // everything else and then be evicted itself on the next insert, so skip
304
+ // it: that entry alone falls back to uncached rendering.
305
+ dropTopicEntry(key);
306
+ return result;
307
+ }
308
+ // Make room before inserting, and account for any stale entry this key
309
+ // already holds -- overwriting it in place would otherwise leak its bytes
310
+ // out of the running total and shrink the effective budget permanently.
311
+ dropTopicEntry(key);
312
+ while (topicRenderCache.size > 0 && topicRenderCacheBytes + bytes > topicRenderCacheBudget) {
313
+ dropOldestTopicEntry();
314
+ }
315
+ topicRenderCache.set(key, {
316
+ html: result.html,
317
+ title: result.title,
318
+ files,
319
+ stamps: stampFiles(files),
320
+ keyMap: input.keyMap,
321
+ uiLanguage: input.uiLanguage,
322
+ suppressIndexterm: input.suppressIndexterm,
323
+ bookMembers: input.bookMembers,
324
+ bytes,
325
+ });
326
+ topicRenderCacheBytes += bytes;
327
+ return result;
328
+ }
@@ -0,0 +1,66 @@
1
+ // Public surface of @dita-viewer/core.
2
+ //
3
+ // Hosts (the Obsidian plugin, and in time the VS Code extension) render DITA
4
+ // through these exports only. The VS Code DITA Viewer depends on this package
5
+ // and holds no copies of ./parser, ./render and ./editor (see README), so they
6
+ // are edited here and released as a new version.
7
+ export { renderTopicXml, buildTitleMap, collectDitamapFilesUpward } from './editor/topicRender';
8
+ export { buildKeySpace, getKeyDefs } from './editor/keySpace';
9
+ export { readSourceText, setSourceOverlay, clearSourceOverlay } from './editor/sourceText';
10
+ export { decodeHrefPart } from './editor/refResolvers';
11
+ export { buildKeyMapForDocument, buildKeySpaceForDocument } from './keyMapForDocument';
12
+ export { complete } from './completion';
13
+ export { collectDiagnostics } from './diagnostics';
14
+ export { collectReferenceableFiles, toRelativeHref } from './language/referenceableFiles';
15
+ export { IMAGE_EXT } from './completionData';
16
+ export { collectIds, splitRefFragment } from './language/ditaLanguageUtils';
17
+ export { collectRefEntries, offsetToLineCol } from './language/ditaLanguageUtils';
18
+ export { renderMapXml } from './mapRender';
19
+ export { renderBookXml } from './bookRender';
20
+ export { renderSiteXml } from './siteRender';
21
+ export { PROFILE_ATTRS, ditavalAction, isEmptyFilter, isExcluded, isValueExcluded, parseDitaval, profileGroups, profileKey, profileValuesOf, profileValuesOfKeys, pruneExcluded, } from './profiling';
22
+ export { collectMapEntries, getMapTitleText } from './render/mapTypeMap';
23
+ // The parser and renderer entry points a host that renders by itself needs, and
24
+ // what they take and return. Everything the VS Code viewer imports from the
25
+ // copied modules is here, so it can depend on this package instead of copying.
26
+ export { parseDita, parseDitamap, preprocessEntities } from './parser/ditaParser';
27
+ export { STANDARD_TAG_TO_BASETYPE } from './parser/standardTagMap';
28
+ export { MAP_STANDARD_TAG_TO_BASETYPE } from './parser/mapTagMap';
29
+ export { renderDocument, renderElement } from './render/renderer';
30
+ export { collectIndextermChips, findTopLevelIndextermsInSubtree } from './render/baseTypeMap';
31
+ export { createBookRoleLabeler, extractText, getDisplayNameInfo, isDitamapRef, renderMapDocument } from './render/mapTypeMap';
32
+ export { isExternalRef } from './language/ditaLanguageUtils';
33
+ // The rest of what the VS Code viewer imports from the copied modules: the
34
+ // render cache, the file and key resolvers, the source overlay, the editor
35
+ // language helpers, and the helpers its tests call. Their shapes follow the
36
+ // viewer's needs and may change while the version is 0.x.
37
+ export { lookupNamedEntity } from './parser/namedEntities';
38
+ export { BASE_TYPE_RENDERERS } from './render/baseTypeMap';
39
+ export { computeKeyrefSpacing, needsSpace } from './render/cjkSpacing';
40
+ export { mergeProfilingAttrs, profilingChipsHtml, profilingKeysAttr } from './render/renderer';
41
+ export { resolveConkeyref } from './editor/conkeyref';
42
+ export { collectMapKeys, isKeyContextAvailable, keySourceMaps, qualifiedNames, qualifiedNamesMulti } from './editor/keySpace';
43
+ export { DEFAULT_NOTE_LABELS, IMAGE_DIMENSIONS_CACHE_MAX, URL_SCHEME_RE, ZH_NOTE_LABELS, clearImageDimensionsCache, detectIndexLabel, detectNoteLabels, expandDitamapRefs, makeConrefRangeResolver, makeConrefResolver, makeFileCache, makeFileTitleResolver, makeIsInCurrentBook, readImageDimensions } from './editor/refResolvers';
44
+ export { buildRenderContext } from './editor/renderContext';
45
+ export { clearAllSourceOverlays, dependsOn, noteSourceDependencies, sourceOverlaySize, sourceStamp, trackSourceReads } from './editor/sourceText';
46
+ export { TOPIC_RENDER_CACHE_MAX_BYTES, clearTopicRenderCache, collectText, renderTopicCached, renderTopicToHtml, setTopicRenderCacheBudgetForTesting, stampFiles, topicRenderCacheBytesHeld, topicRenderCacheSize } from './editor/topicRender';
47
+ export { collectMapSymbols, collectTopicSymbols, collectUnknownElements, findConrefTargetOffset, findEnclosingKeydefKeys, findIdAttrAt, findKeyDefinitionOffset, findKeysAttrAt, findRefAttrAt, findUnclosedTag, getAttributesForTag, getAutoCloseTag, getCloseTagCompletion, getCompletionContext, getMapRefName, stripSameDocumentFragmentPrefix } from './language/ditaLanguageUtils';
48
+ /**
49
+ * Host tokens the stylesheet reads (styles/dita-content.css). A host defines
50
+ * these on the element that carries the rendered content; styles/TOKENS.md
51
+ * says what each one means.
52
+ */
53
+ export const HOST_TOKENS = [
54
+ '--dita-fg',
55
+ '--dita-fg-muted',
56
+ '--dita-bg',
57
+ '--dita-bg-elevated',
58
+ '--dita-border',
59
+ '--dita-focus',
60
+ '--dita-hover-bg',
61
+ '--dita-selected-fg',
62
+ '--dita-link',
63
+ '--dita-code-bg',
64
+ '--dita-code-inline-bg',
65
+ '--dita-font',
66
+ ];