steerdown 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/split.js ADDED
@@ -0,0 +1,399 @@
1
+ /**
2
+ * Splits a built HTML page into sections and blocks. It walks nodes only through a `NodeAdapter`,
3
+ * so the build passes parse5 nodes and a browser can pass DOM nodes to the same code. Keep it free
4
+ * of DOM globals and parser imports.
5
+ */
6
+ const droppedElements = new Set(("nav footer script style template svg noscript form button input select textarea option " +
7
+ "optgroup datalist output meter progress").split(" "));
8
+ /** Elements that end the running line of text before them and after them. */
9
+ const blockElements = new Set(("address article aside blockquote caption dd details dialog div dl dt fieldset figcaption " +
10
+ "figure header hgroup hr legend li main menu ol p pre search section summary table tbody " +
11
+ "td tfoot th thead tr ul").split(" "));
12
+ const headingLevels = { h1: 1, h2: 2, h3: 3, h4: 4, h5: 5, h6: 6 };
13
+ const htmlWhitespace = /[ \t\n\r\f]+/g;
14
+ const linkListShareForHub = 0.6;
15
+ const firstMarkedHeadingLevel = 3;
16
+ function collapse(text) {
17
+ return text.replace(htmlWhitespace, " ").trim();
18
+ }
19
+ /** True for content the reader never reads as text: page chrome, controls and hidden decoration. */
20
+ export function isDropped(node, adapter) {
21
+ return (droppedElements.has(adapter.name(node)) ||
22
+ adapter.attribute(node, "data-pagefind-ignore") !== undefined ||
23
+ adapter.attribute(node, "aria-hidden") === "true");
24
+ }
25
+ /** True when a link points at the heading it belongs to, such as a `#` anchor link. */
26
+ function isSelfLink(href, selfId) {
27
+ return href !== undefined && selfId !== undefined && href === `#${selfId}`;
28
+ }
29
+ /** The kept child elements of a node, with their names. */
30
+ function* elementsOf(node, adapter) {
31
+ for (const child of adapter.children(node)) {
32
+ const name = adapter.name(child);
33
+ if (name !== undefined && !isDropped(child, adapter)) {
34
+ yield { child, name };
35
+ }
36
+ }
37
+ }
38
+ /** Every element under a node that matches, not looking inside a match. */
39
+ function findAll(node, adapter, matches) {
40
+ const found = [];
41
+ for (const child of adapter.children(node)) {
42
+ if (adapter.name(child) === undefined) {
43
+ continue;
44
+ }
45
+ if (matches(child)) {
46
+ found.push(child);
47
+ }
48
+ else {
49
+ found.push(...findAll(child, adapter, matches));
50
+ }
51
+ }
52
+ return found;
53
+ }
54
+ /** The elements marked `data-pagefind-body`, outermost only. */
55
+ export function pagefindBodies(document, adapter) {
56
+ return findAll(document, adapter, (node) => adapter.attribute(node, "data-pagefind-body") !== undefined);
57
+ }
58
+ /** The first element with the given name, in document order. */
59
+ export function firstElement(document, adapter, name) {
60
+ return findAll(document, adapter, (node) => adapter.name(node) === name)[0];
61
+ }
62
+ /** The text of `head > title`, empty when the page has none. */
63
+ export function documentTitle(document, adapter) {
64
+ let node = document;
65
+ for (const name of ["html", "head", "title"]) {
66
+ const parent = node;
67
+ node = [...adapter.children(parent)].find((child) => adapter.name(child) === name);
68
+ if (node === undefined) {
69
+ return "";
70
+ }
71
+ }
72
+ return collapse([...adapter.children(node)].map((child) => adapter.text(child) ?? "").join(""));
73
+ }
74
+ /** The text under a node on one line, leaving out dropped content and links to `selfId`. */
75
+ function inlineText(node, adapter, selfId) {
76
+ const parts = [];
77
+ const collect = (parent) => {
78
+ for (const child of adapter.children(parent)) {
79
+ const text = adapter.text(child);
80
+ const name = adapter.name(child);
81
+ if (text !== undefined) {
82
+ parts.push(text);
83
+ }
84
+ else if (name === "br") {
85
+ parts.push(" ");
86
+ }
87
+ else if (name !== undefined && !isDropped(child, adapter)) {
88
+ const isSkipped = name === "a" && isSelfLink(adapter.attribute(child, "href"), selfId);
89
+ if (!isSkipped) {
90
+ collect(child);
91
+ }
92
+ }
93
+ }
94
+ };
95
+ collect(node);
96
+ return collapse(parts.join(""));
97
+ }
98
+ /** The shared leading whitespace of the lines. */
99
+ function commonIndent(lines) {
100
+ return lines
101
+ .map((line) => line.match(/^[ \t]*/)[0])
102
+ .reduce((shared, indent) => {
103
+ let length = 0;
104
+ while (length < shared.length && shared[length] === indent[length]) {
105
+ length++;
106
+ }
107
+ return shared.slice(0, length);
108
+ });
109
+ }
110
+ /** True for whitespace that only indents markup: a text node of whitespace with a line break. */
111
+ function isMarkupIndentation(text, isBeforeCode) {
112
+ const isBlank = text.trim() === "";
113
+ return isBlank && (isBeforeCode || text.includes("\n"));
114
+ }
115
+ /**
116
+ * The text of a code block, a line per source line and per block element inside it, without
117
+ * blank lines or the indentation every line shares. Whitespace that only indents the markup,
118
+ * or comes before any code, counts as a line break.
119
+ */
120
+ function codeText(pre, adapter) {
121
+ const parts = [];
122
+ let isBeforeCode = true;
123
+ const collect = (parent) => {
124
+ for (const child of adapter.children(parent)) {
125
+ const text = adapter.text(child);
126
+ const name = adapter.name(child);
127
+ if (text !== undefined) {
128
+ parts.push(isMarkupIndentation(text, isBeforeCode) ? "\n" : text);
129
+ isBeforeCode &&= text.trim() === "";
130
+ }
131
+ else if (name === "br") {
132
+ parts.push("\n");
133
+ }
134
+ else if (name !== undefined && !isDropped(child, adapter)) {
135
+ const breaks = blockElements.has(name) ? "\n" : "";
136
+ parts.push(breaks);
137
+ collect(child);
138
+ parts.push(breaks);
139
+ }
140
+ }
141
+ };
142
+ collect(pre);
143
+ const lines = parts
144
+ .join("")
145
+ .split(/\r?\n/)
146
+ .map((line) => line.trimEnd())
147
+ .filter((line) => line !== "");
148
+ if (lines.length === 0) {
149
+ return "";
150
+ }
151
+ const indent = commonIndent(lines);
152
+ return lines.map((line) => line.slice(indent.length)).join("\n");
153
+ }
154
+ /** A table's caption and rows, a line each, with a row's cells joined by ` | `. */
155
+ function tableText(table, adapter) {
156
+ const lines = [];
157
+ const isRowPart = (name) => name === "caption" || name === "tr";
158
+ for (const part of findAll(table, adapter, (node) => isRowPart(adapter.name(node)))) {
159
+ if (isDropped(part, adapter)) {
160
+ continue;
161
+ }
162
+ const isCaption = adapter.name(part) === "caption";
163
+ const cells = isCaption
164
+ ? [inlineText(part, adapter, undefined)]
165
+ : [...elementsOf(part, adapter)].map(({ child }) => inlineText(child, adapter, undefined));
166
+ const line = cells.join(" | ").trim();
167
+ if (line.replace(/[ |]/g, "") !== "") {
168
+ lines.push(line);
169
+ }
170
+ }
171
+ return lines.join("\n");
172
+ }
173
+ /** The number of kept `h2` elements under a node. */
174
+ function countH2(node, adapter) {
175
+ let count = 0;
176
+ for (const { child, name } of elementsOf(node, adapter)) {
177
+ count += name === "h2" ? 1 : countH2(child, adapter);
178
+ }
179
+ return count;
180
+ }
181
+ /** Walks a page's content in document order and collects its sections and blocks. */
182
+ class PageSplitter {
183
+ adapter;
184
+ keepSources;
185
+ title;
186
+ sections = [{ anchor: "", heading: "", blocks: [] }];
187
+ idlessHeadings = [];
188
+ /** The running line of text and whether each part of it is inside a link. */
189
+ run = [];
190
+ linkDepth = 0;
191
+ itemPending = false;
192
+ /** The id of the latest heading, whose own anchor links are left out of the text. */
193
+ headingId;
194
+ idHolders = [];
195
+ constructor(adapter, keepSources) {
196
+ this.adapter = adapter;
197
+ this.keepSources = keepSources;
198
+ }
199
+ split(roots) {
200
+ for (const root of roots) {
201
+ this.walkChildren(root);
202
+ }
203
+ this.flush();
204
+ const [intro, ...rest] = this.sections;
205
+ const sections = intro.blocks.length > 0 ? this.sections : rest;
206
+ return { title: this.title ?? "", sections, idlessHeadings: this.idlessHeadings };
207
+ }
208
+ walkChildren(node) {
209
+ for (const child of this.adapter.children(node)) {
210
+ this.walk(child);
211
+ }
212
+ }
213
+ walk(node) {
214
+ const text = this.adapter.text(node);
215
+ if (text !== undefined) {
216
+ this.addText(text, node);
217
+ return;
218
+ }
219
+ const name = this.adapter.name(node);
220
+ if (name === undefined || isDropped(node, this.adapter)) {
221
+ return;
222
+ }
223
+ const id = this.adapter.attribute(node, "id") || undefined;
224
+ if (id !== undefined) {
225
+ this.idHolders.push({ id, node, textSeen: false });
226
+ }
227
+ this.visit(node, name);
228
+ if (id !== undefined) {
229
+ this.idHolders.pop();
230
+ }
231
+ }
232
+ visit(node, name) {
233
+ const level = headingLevels[name];
234
+ if (level !== undefined) {
235
+ this.addHeading(node, level);
236
+ }
237
+ else if (name === "pre") {
238
+ this.addBlock({ kind: "code", text: codeText(node, this.adapter) });
239
+ }
240
+ else if (name === "table") {
241
+ this.addBlock({ kind: "table", text: tableText(node, this.adapter) });
242
+ }
243
+ else if (name === "br") {
244
+ this.addText(" ");
245
+ }
246
+ else if (name === "a") {
247
+ this.visitLink(node);
248
+ }
249
+ else if (blockElements.has(name)) {
250
+ this.visitBlock(node, name);
251
+ }
252
+ else {
253
+ this.walkChildren(node);
254
+ }
255
+ }
256
+ /** Walks a block element. A list item's first line of text becomes the item. */
257
+ visitBlock(node, name) {
258
+ const isItem = name === "li";
259
+ this.flush();
260
+ this.itemPending ||= isItem;
261
+ this.walkChildren(node);
262
+ this.flush();
263
+ this.itemPending &&= !isItem;
264
+ }
265
+ visitLink(node) {
266
+ const href = this.adapter.attribute(node, "href");
267
+ if (isSelfLink(href, this.headingId)) {
268
+ return;
269
+ }
270
+ const isLink = href !== undefined;
271
+ this.linkDepth += isLink ? 1 : 0;
272
+ this.walkChildren(node);
273
+ this.linkDepth -= isLink ? 1 : 0;
274
+ }
275
+ markTextSeen() {
276
+ for (const holder of this.idHolders) {
277
+ holder.textSeen = true;
278
+ }
279
+ }
280
+ addText(text, source) {
281
+ this.run.push({ text, linked: this.linkDepth > 0, source });
282
+ if (text.trim() !== "") {
283
+ this.markTextSeen();
284
+ }
285
+ }
286
+ /** Ends the running line as a paragraph, or as a list item when it opens one. */
287
+ flush() {
288
+ const parts = this.run.filter((part) => part.text.trim() !== "");
289
+ const text = collapse(this.run.map((part) => part.text).join(""));
290
+ this.run = [];
291
+ if (text === "") {
292
+ return;
293
+ }
294
+ const kind = this.itemPending ? "item" : "paragraph";
295
+ this.itemPending = false;
296
+ const allLinked = parts.every((part) => part.linked);
297
+ const startsWithLink = kind === "item" && parts[0].linked;
298
+ const block = { kind, text, linkLed: allLinked || startsWithLink };
299
+ if (this.keepSources) {
300
+ block.sources = parts.flatMap((part) => (part.source === undefined ? [] : [part.source]));
301
+ }
302
+ this.sections.at(-1).blocks.push(block);
303
+ }
304
+ addBlock(block) {
305
+ this.flush();
306
+ if (block.text !== "") {
307
+ this.sections.at(-1).blocks.push(block);
308
+ this.markTextSeen();
309
+ }
310
+ }
311
+ /** The id of the closest element with an id, when it holds this `h2` alone and no text before it. */
312
+ wrapperId() {
313
+ const holder = this.idHolders.at(-1);
314
+ if (holder === undefined || holder.textSeen || countH2(holder.node, this.adapter) !== 1) {
315
+ return undefined;
316
+ }
317
+ return holder.id;
318
+ }
319
+ addHeading(node, level) {
320
+ this.flush();
321
+ const ownId = this.adapter.attribute(node, "id") || undefined;
322
+ if (level === 1 && this.title === undefined) {
323
+ this.title = inlineText(node, this.adapter, ownId);
324
+ this.markTextSeen();
325
+ return;
326
+ }
327
+ const anchor = level === 2 ? (ownId ?? this.wrapperId()) : undefined;
328
+ if (anchor !== undefined) {
329
+ const heading = inlineText(node, this.adapter, anchor);
330
+ this.sections.push({ anchor, heading, blocks: [] });
331
+ this.headingId = anchor;
332
+ this.markTextSeen();
333
+ return;
334
+ }
335
+ const text = inlineText(node, this.adapter, ownId);
336
+ if (level === 2) {
337
+ this.idlessHeadings.push(text);
338
+ }
339
+ this.headingId = ownId;
340
+ this.addBlock({ kind: "heading", text, level });
341
+ }
342
+ }
343
+ /**
344
+ * Splits page content into sections. A section starts at an `h2` with an id, or at an `h2` whose
345
+ * closest element with an id holds no other `h2` and no text before it. Text before the first
346
+ * section is the page intro, left out when empty. With `keepSources`, each paragraph and list item
347
+ * lists the text nodes it was read from.
348
+ */
349
+ export function splitContent(roots, adapter, options = {}) {
350
+ return new PageSplitter(adapter, options.keepSources ?? false).split(roots);
351
+ }
352
+ /**
353
+ * The text Jev reads: a line per block, `- ` before list items, `### ` before `h3` to `h6`, and
354
+ * code fenced with three backticks.
355
+ */
356
+ export function judgedText(blocks) {
357
+ const line = (block) => {
358
+ if (block.kind === "item") {
359
+ return `- ${block.text}`;
360
+ }
361
+ if (block.kind === "code") {
362
+ return `\`\`\`\n${block.text}\n\`\`\``;
363
+ }
364
+ const isMarkedHeading = block.kind === "heading" && block.level >= firstMarkedHeadingLevel;
365
+ return isMarkedHeading ? `### ${block.text}` : block.text;
366
+ };
367
+ return blocks.map(line).join("\n");
368
+ }
369
+ const sentenceSegmenter = new Intl.Segmenter("en", { granularity: "sentence" });
370
+ const isProse = (block) => block.kind === "paragraph" || block.kind === "item";
371
+ /** The sentences of a section's paragraphs and list items, in reading order. */
372
+ export function splitSentences(blocks) {
373
+ const sentences = [];
374
+ for (const block of blocks.filter(isProse)) {
375
+ for (const { segment } of sentenceSegmenter.segment(block.text)) {
376
+ const sentence = segment.trim();
377
+ if (sentence !== "") {
378
+ sentences.push(sentence);
379
+ }
380
+ }
381
+ }
382
+ return sentences;
383
+ }
384
+ /** What a sentence's hash covers: its letters and digits, NFKC-normalized and lowercased. */
385
+ export function sentenceKey(sentence) {
386
+ return sentence
387
+ .normalize("NFKC")
388
+ .toLowerCase()
389
+ .replace(/[^\p{L}\p{N}]/gu, "");
390
+ }
391
+ /** True when most of a section's paragraphs and list items are links, as in a table of contents. */
392
+ export function isLinkHub(blocks) {
393
+ const prose = blocks.filter(isProse);
394
+ if (prose.length === 0) {
395
+ return false;
396
+ }
397
+ const linkLed = prose.filter((block) => block.linkLed).length;
398
+ return linkLed / prose.length >= linkListShareForHub;
399
+ }
@@ -0,0 +1,7 @@
1
+ function E(e,t){let n=t.includes(e),i=e.relation==="prerequisite"&&t.some((s)=>s.relation==="prerequisite"),r=t.some((s)=>s.page===e.page);return!n&&!i&&!r}function w(e){let t=[],n=e.find((i)=>i.relation==="next_step");if(n!==void 0)t.push(n);for(let i of e)if(t.length<3&&E(i,t))t.push(i);return e.filter((i)=>t.includes(i))}var O=new Set("nav footer script style template svg noscript form button input select textarea option optgroup datalist output meter progress".split(" ")),P=new Set("address article aside blockquote caption dd details dialog div dl dt fieldset figcaption figure header hgroup hr legend li main menu ol p pre search section summary table tbody td tfoot th thead tr ul".split(" ")),W={h1:1,h2:2,h3:3,h4:4,h5:5,h6:6},q=/[ \t\n\r\f]+/g;function L(e){return e.replace(q," ").trim()}function g(e,t){return O.has(t.name(e))||t.attribute(e,"data-pagefind-ignore")!==void 0||t.attribute(e,"aria-hidden")==="true"}function H(e,t){return e!==void 0&&t!==void 0&&e===`#${t}`}function*D(e,t){for(let n of t.children(e)){let i=t.name(n);if(i!==void 0&&!g(n,t))yield{child:n,name:i}}}function m(e,t,n){let i=[];for(let r of t.children(e)){if(t.name(r)===void 0)continue;if(n(r))i.push(r);else i.push(...m(r,t,n))}return i}function B(e,t){return m(e,t,(n)=>t.attribute(n,"data-pagefind-body")!==void 0)}function b(e,t,n){return m(e,t,(i)=>t.name(i)===n)[0]}function h(e,t,n){let i=[],r=(s)=>{for(let o of t.children(s)){let a=t.text(o),c=t.name(o);if(a!==void 0)i.push(a);else if(c==="br")i.push(" ");else if(c!==void 0&&!g(o,t)){if(!(c==="a"&&H(t.attribute(o,"href"),n)))r(o)}}};return r(e),L(i.join(""))}function K(e){return e.map((t)=>t.match(/^[ \t]*/)[0]).reduce((t,n)=>{let i=0;while(i<t.length&&t[i]===n[i])i++;return t.slice(0,i)})}function J(e,t){return e.trim()===""&&(t||e.includes(`
2
+ `))}function G(e,t){let n=[],i=!0,r=(a)=>{for(let c of t.children(a)){let l=t.text(c),p=t.name(c);if(l!==void 0)n.push(J(l,i)?`
3
+ `:l),i&&=l.trim()==="";else if(p==="br")n.push(`
4
+ `);else if(p!==void 0&&!g(c,t)){let d=P.has(p)?`
5
+ `:"";n.push(d),r(c),n.push(d)}}};r(e);let s=n.join("").split(/\r?\n/).map((a)=>a.trimEnd()).filter((a)=>a!=="");if(s.length===0)return"";let o=K(s);return s.map((a)=>a.slice(o.length)).join(`
6
+ `)}function U(e,t){let n=[],i=(r)=>r==="caption"||r==="tr";for(let r of m(e,t,(s)=>i(t.name(s)))){if(g(r,t))continue;let a=(t.name(r)==="caption"?[h(r,t,void 0)]:[...D(r,t)].map(({child:c})=>h(c,t,void 0))).join(" | ").trim();if(a.replace(/[ |]/g,"")!=="")n.push(a)}return n.join(`
7
+ `)}function C(e,t){let n=0;for(let{child:i,name:r}of D(e,t))n+=r==="h2"?1:C(i,t);return n}class T{adapter;keepSources;title;sections=[{anchor:"",heading:"",blocks:[]}];idlessHeadings=[];run=[];linkDepth=0;itemPending=!1;headingId;idHolders=[];constructor(e,t){this.adapter=e;this.keepSources=t}split(e){for(let r of e)this.walkChildren(r);this.flush();let[t,...n]=this.sections,i=t.blocks.length>0?this.sections:n;return{title:this.title??"",sections:i,idlessHeadings:this.idlessHeadings}}walkChildren(e){for(let t of this.adapter.children(e))this.walk(t)}walk(e){let t=this.adapter.text(e);if(t!==void 0){this.addText(t,e);return}let n=this.adapter.name(e);if(n===void 0||g(e,this.adapter))return;let i=this.adapter.attribute(e,"id")||void 0;if(i!==void 0)this.idHolders.push({id:i,node:e,textSeen:!1});if(this.visit(e,n),i!==void 0)this.idHolders.pop()}visit(e,t){let n=W[t];if(n!==void 0)this.addHeading(e,n);else if(t==="pre")this.addBlock({kind:"code",text:G(e,this.adapter)});else if(t==="table")this.addBlock({kind:"table",text:U(e,this.adapter)});else if(t==="br")this.addText(" ");else if(t==="a")this.visitLink(e);else if(P.has(t))this.visitBlock(e,t);else this.walkChildren(e)}visitBlock(e,t){let n=t==="li";this.flush(),this.itemPending||=n,this.walkChildren(e),this.flush(),this.itemPending&&=!n}visitLink(e){let t=this.adapter.attribute(e,"href");if(H(t,this.headingId))return;let n=t!==void 0;this.linkDepth+=n?1:0,this.walkChildren(e),this.linkDepth-=n?1:0}markTextSeen(){for(let e of this.idHolders)e.textSeen=!0}addText(e,t){if(this.run.push({text:e,linked:this.linkDepth>0,source:t}),e.trim()!=="")this.markTextSeen()}flush(){let e=this.run.filter((o)=>o.text.trim()!==""),t=L(this.run.map((o)=>o.text).join(""));if(this.run=[],t==="")return;let n=this.itemPending?"item":"paragraph";this.itemPending=!1;let i=e.every((o)=>o.linked),r=n==="item"&&e[0].linked,s={kind:n,text:t,linkLed:i||r};if(this.keepSources)s.sources=e.flatMap((o)=>o.source===void 0?[]:[o.source]);this.sections.at(-1).blocks.push(s)}addBlock(e){if(this.flush(),e.text!=="")this.sections.at(-1).blocks.push(e),this.markTextSeen()}wrapperId(){let e=this.idHolders.at(-1);if(e===void 0||e.textSeen||C(e.node,this.adapter)!==1)return;return e.id}addHeading(e,t){this.flush();let n=this.adapter.attribute(e,"id")||void 0;if(t===1&&this.title===void 0){this.title=h(e,this.adapter,n),this.markTextSeen();return}let i=t===2?n??this.wrapperId():void 0;if(i!==void 0){let s=h(e,this.adapter,i);this.sections.push({anchor:i,heading:s,blocks:[]}),this.headingId=i,this.markTextSeen();return}let r=h(e,this.adapter,n);if(t===2)this.idlessHeadings.push(r);this.headingId=n,this.addBlock({kind:"heading",text:r,level:t})}}function I(e,t,n={}){return new T(t,n.keepSources??!1).split(e)}var z=new Intl.Segmenter("en",{granularity:"sentence"}),_=(e)=>e.kind==="paragraph"||e.kind==="item";function F(e){let t=[];for(let n of e.filter(_))for(let{segment:i}of z.segment(n.text)){let r=i.trim();if(r!=="")t.push(r)}return t}function S(e){return e.normalize("NFKC").toLowerCase().replace(/[^\p{L}\p{N}]/gu,"")}function R(e){let t=e.replace(/^\/+/,"");return t===""||t.endsWith("/")?`${t}index.html`:t}function j(e){return`steerdown/${e.replace(/\.html$/,".json")}`}var Q=1,V=3,X=16,M="steerdown:pins",k={name:(e)=>e.nodeType===Q?e.localName:void 0,attribute:(e,t)=>e.getAttribute?.(t)??void 0,children:(e)=>e.childNodes,text:(e)=>e.nodeType===V?e.data:void 0};function N(){return globalThis}function Y(e){let t=e.indexOf("#");return t===-1?"":e.slice(t+1)}function Z(e){let t=new Map(e.sections.map((s)=>[Y(s.id),s])),n=(e.concepts??[]).map(([s,o])=>({id:s,label:o})),i=([s,o,a,c,l])=>{let[p,d,u]=e.targets[s],f={url:p,pageTitle:d,heading:u,relation:o,probability:a};if(c!==void 0&&l!==void 0)f.origin={position:c,hash:l};return f};return{concepts:n,links:(s,o=[])=>{let a=t.get(s);if(a===void 0)return[];let c=new Set(n.flatMap((d,u)=>o.includes(d.id)?[u]:[])),l=([d])=>(e.targets[d][3]??[]).some(([u])=>c.has(u));if(!a.links.some(l))return a.defaults.map((d)=>i(a.links[d]));let p=a.links.map((d,u)=>({row:d,index:u,relation:d[1],page:e.targets[d[0]][0].split("#")[0],covers:l(d)}));return p.sort((d,u)=>Number(u.covers)-Number(d.covers)||d.index-u.index),w(p).map((d)=>i(d.row))}}}async function le(e){let t=e??`/${j(R(N().location.pathname))}`,n=await fetch(t);if(!n.ok)throw Error(`steerdown: no page data at ${t} (status ${n.status})`);return Z(await n.json())}function ue(){try{let e=JSON.parse(N().localStorage.getItem(M)??"[]");return Array.isArray(e)?e.filter((t)=>typeof t==="string"):[]}catch{return[]}}function pe(e){try{N().localStorage.setItem(M,JSON.stringify(e))}catch{}}async function ee(e){let t=new TextEncoder().encode(JSON.stringify(e));return[...new Uint8Array(await crypto.subtle.digest("SHA-256",t))].map((r)=>r.toString(16).padStart(2,"0")).join("").slice(0,X)}function te(e){let t=B(e,k);if(t.length>0)return t;let n=b(e,k,"main")??b(e,k,"body");return n===void 0?[]:[n]}function ne(e,t,n){let i=-1;return e.forEach((r,s)=>{let o=i===-1||Math.abs(s-n)<Math.abs(i-n);if(r===t&&o)i=s}),i}function ie(e){let t=[],n="";for(let i of e){let r=0;for(let s of i.data??""){let o=S(s);for(let a=0;a<o.length;a++)t.push({node:i,start:r,end:r+s.length});n+=o,r+=s.length}}return{key:n,positions:t}}async function fe(e,t){let{document:n}=N(),r=I(te(n),k,{keepSources:!0}).sections.find((x)=>x.anchor===e);if(t.origin===void 0||r===void 0)return;let s=F(r.blocks).map(S),o=await Promise.all(s.map(ee)),a=ne(o,t.origin.hash,t.origin.position),c=s[a];if(c===void 0||c==="")return;let l=r.blocks.flatMap((x)=>x.sources??[]),{key:p,positions:d}=ie(l),u=s.slice(0,a).join("").length,f=p.startsWith(c,u)?u:p.indexOf(c);if(f===-1)return;let A=d[f],v=d[f+c.length-1],y=n.createRange();return y.setStart(A.node,A.start),y.setEnd(v.node,v.end),y}export{le as loadPage,fe as originRange,Z as pageFromData,ue as readPins,pe as savePins};
package/dist/urls.js ADDED
@@ -0,0 +1,16 @@
1
+ /** Where pages and their data files are served. Shared by emit and the browser script. */
2
+ /** The folder under the built site that holds one data file per page. */
3
+ export const emitFolder = "steerdown";
4
+ /** The URL a built HTML file is served at: `x/index.html` is `/x/`, `x.html` stays `/x.html`. */
5
+ export function pageUrl(htmlFile) {
6
+ return `/${htmlFile.replace(/(^|\/)index\.html$/, "$1")}`;
7
+ }
8
+ /** The built HTML file served at a URL path: `/x/` is `x/index.html`, `/x.html` stays `x.html`. */
9
+ export function htmlFileOf(urlPath) {
10
+ const path = urlPath.replace(/^\/+/, "");
11
+ return path === "" || path.endsWith("/") ? `${path}index.html` : path;
12
+ }
13
+ /** Where a page's data file goes: `x/index.html` gets `steerdown/x/index.json`, `x.html` gets `steerdown/x.json`. */
14
+ export function dataFilePath(htmlFile) {
15
+ return `${emitFolder}/${htmlFile.replace(/\.html$/, ".json")}`;
16
+ }
package/package.json CHANGED
@@ -1,6 +1,47 @@
1
1
  {
2
2
  "name": "steerdown",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
4
+ "description": "Typed reading paths for built HTML judged at build time",
5
+ "keywords": [
6
+ "documentation",
7
+ "html",
8
+ "markdown",
9
+ "reading-path",
10
+ "related-content",
11
+ "static-site"
12
+ ],
13
+ "license": "MIT",
14
+ "author": "Alper Halil",
15
+ "bin": {
16
+ "steerdown": "./dist/cli.js"
17
+ },
18
+ "files": [
19
+ "dist",
20
+ "skills"
21
+ ],
22
+ "type": "module",
23
+ "exports": {
24
+ "./browser": "./dist/steerdown.js"
25
+ },
26
+ "dependencies": {
27
+ "parse5": "8.1.1"
28
+ },
29
+ "devDependencies": {
30
+ "@types/bun": "1.3.14",
31
+ "@types/node": "22.20.5",
32
+ "oxfmt": "0.79.0",
33
+ "oxlint": "1.94.0",
34
+ "playwright-core": "1.65.1",
35
+ "typescript": "5.9.3"
36
+ },
37
+ "engines": {
38
+ "node": ">=22.0.0"
39
+ },
40
+ "scripts": {
41
+ "build": "bun scripts/build.ts",
42
+ "format": "oxfmt src tests scripts skills README.md package.json tsconfig.json tsconfig.build.json .oxlintrc.json",
43
+ "format:check": "oxfmt --check src tests scripts skills README.md package.json tsconfig.json tsconfig.build.json .oxlintrc.json",
44
+ "lint": "oxlint --deny-warnings src tests scripts",
45
+ "typecheck": "tsc --noEmit && tsc -p tsconfig.build.json --noEmit"
46
+ }
6
47
  }
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: steerdown-concepts
3
+ description: Propose concepts for a steerdown concept file. Use when the person asks to propose, suggest or improve steerdown concepts, to cover sections no concept covers, or to split over-broad concepts.
4
+ ---
5
+
6
+ # Propose steerdown concepts
7
+
8
+ steerdown scores every section of a site's built HTML against the concepts in `steerdown.concepts.json`, a file the site's authors edit by hand next to the graph file. Your job is to propose concepts. A person reviews them and moves the ones they accept into the concept file. You never edit the concept file yourself.
9
+
10
+ ## Steps
11
+
12
+ 1. Run `npx steerdown concepts input`. If the site's build writes its graph file somewhere other than `steerdown.graph.json`, pass that path with `--graph <file>` to this and the later command. The command prints JSON:
13
+ - `sections`: every section in the graph, with its `page` (the HTML file, relative to the built site the site's `steerdown build` reads), `heading`, and `scores` for the concepts it at least mentions. Scores run from 0 ("not about it at all") to 3 ("is mainly about it").
14
+ - `concepts`: the concept file's concepts. `coveredSections` counts the sections that score 2 or more. It is `null` for a concept that has not been scored with its current definition yet.
15
+ - `proposed`: concepts already proposed and waiting for review. Do not propose them again.
16
+ - `uncovered`: the sections no concept scores 2 or more on.
17
+ - `overBroad`: concepts that score 2 or more on too many sections to tell sections apart.
18
+ 2. Read the pages behind the `uncovered` sections and the sections of each over-broad concept. The input carries no section text.
19
+ 3. Write your proposals to a new JSON file outside the site's content, for example in a temporary folder. It holds an array of objects with exactly these fields:
20
+
21
+ ```json
22
+ [
23
+ {
24
+ "id": "hook-configuration",
25
+ "label": "Configuring hooks",
26
+ "definition": "Setting up the hooks that run commands when tasks change."
27
+ }
28
+ ]
29
+ ```
30
+
31
+ 4. Run `npx steerdown concepts propose <your file>`. It checks every proposal and adds them all to `steerdown.proposals.json`, or adds none and lists each problem. Fix the problems and run it again.
32
+ 5. Tell the person how many concepts you proposed and why, and that they accept one by moving it from `steerdown.proposals.json` into `steerdown.concepts.json`. The next `steerdown build` scores the accepted ones.
33
+
34
+ Do not run `steerdown build` unless the person asks. It sends requests to Jev, which needs their API key and costs money.
35
+
36
+ ## What makes a good concept
37
+
38
+ - It names one topic a reader might want to follow across pages, such as a feature, a task or an idea. Page types ("introduction", "reference") and whole products are not concepts.
39
+ - It covers a few sections, at least two, and not more than about a tenth of them. A concept that covers most of a page's sections, or one section only, does not help a reader find more.
40
+ - The definition is one sentence that says what belongs to the concept, precise enough that a section either is or is not about it.
41
+ - The label is a short noun phrase a reader would recognize.
42
+ - The id is lowercase words joined by hyphens, such as `json-output`. Ids are permanent, because readers' saved choices refer to them. Never reuse the id of a concept in the concept file or the proposals.
43
+ - It does not overlap a concept that exists already. For an over-broad concept, propose two or more narrower concepts that split it, and say which one they would replace. The person decides whether to remove the broad one.
44
+ - Short intros and landing text that are about nothing in particular can stay uncovered.