@gavin-hu/my-pi-agent 0.8.0 → 0.8.1

package/README.md

@@ -11,7 +11,7 @@ context across sessions. `my-pi-agent` is a single [Pi](https://pi.dev) package
 that adds sixteen extensions and two themes — install the pack, turn off what
 you do not want, and keep using Pi unchanged.
 
-<img src="./assets/bytefly-chrome.png" alt="A terminal window running the Pi TUI with the bytefly header, hint row, context and loaded extensions, a turn separator, and the status bar" width="100%">
+![A terminal window running the Pi TUI with the bytefly header, hint row, context and loaded extensions, a turn separator, and the status bar](assets/bytefly-chrome.png)
 
 ## Contents
 

package/README.zh-CN.md

@@ -10,7 +10,7 @@
 `my-pi-agent` 是一个 [Pi](https://pi.dev) 包，新增十六个扩展和两个主题 —— 安装
 整个包，关掉你不需要的部分，其余照常使用 Pi。
 
-<img src="./assets/bytefly-chrome.png" alt="一个运行 Pi TUI 的终端窗口，包含 bytefly 头部、提示行、上下文与已加载扩展、回合分隔线以及状态栏" width="100%">
+![一个运行 Pi TUI 的终端窗口，包含 bytefly 头部、提示行、上下文与已加载扩展、回合分隔线以及状态栏](assets/bytefly-chrome.png)
 
 ## 目录
 

package/extensions/file-browse/README.md

@@ -36,9 +36,11 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   tables, code, inline and reference links, and images, with a one-click
   **raw** view (`?raw=1`). Tables size their columns to the content and scroll
   when wide, and named and numeric character references are decoded. Fenced code
-  blocks are syntax-highlighted when the fence names a supported language. Raw
-  HTML in the source is escaped, never executed, and external images are shown
-  as links rather than fetched.
+  blocks are syntax-highlighted when the fence names a supported language.
+  Headings get stable anchor ids, so in-document `#anchor` links and a table of
+  contents work, and a document with four or more headings gets an **On this
+  page** outline. Raw HTML in the source is escaped, never executed, and
+  external images are shown as links rather than fetched.
 - **Sortable listings.** The Name / Size / Modified headers sort the current
   directory, directories first, and the choice is remembered per browser.
 - **Copy and wrap.** Copy a file's root-relative path or its contents, and
@@ -209,8 +211,12 @@ document and the project document (project wins):
   the full `[text][id]`, collapsed `[text][]`, and shortcut `[text]` forms, and
   numeric and common named character references are resolved. The Rendered/Raw
   switch is a server-side `?raw=1`
-  link, so it works without JavaScript. Set `markdown: false` to fall back to
-  the plain-text view. A fenced code block whose info string names a supported
+  link, so it works without JavaScript. Headings are demoted one level so the
+  card title stays the page's only `h1`, and each gets a slug `id` (unique in
+  the document); `renderMarkdownDocument` returns the heading list and `html.ts`
+  renders an **On this page** disclosure for four or more headings. Set
+  `markdown: false` to fall back to the plain-text view. A fenced code block
+  whose info string names a supported
   language is highlighted through `lib/highlight.ts` (either an extension or a
   long-form alias, `fenceLanguage`); an absent or unknown language stays plain.
 - **Syntax highlighting.** `lib/highlight.ts` is a first-party, escape-first

package/extensions/file-browse/html.ts

@@ -22,7 +22,7 @@ import { formatSize, type DirEntry, type FileView, type Listing, type TreeNode }
 import type { GitStatus } from "./git.ts";
 import { detectLanguage, highlightLines, type HighlightLanguage } from "../../lib/highlight.ts";
 import { FOLDER_ICON, iconHref, languageOf, SPRITE, type IconSpec } from "./icons.ts";
-import { renderMarkdown } from "./markdown.ts";
+import { renderMarkdownDocument, type MarkdownHeading } from "./markdown.ts";
 import { encodePath } from "./paths.ts";
 
 const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
@@ -78,6 +78,13 @@ ${WEB_COMPONENTS_CSS}
 .browse-broken{color:var(--muted);text-decoration:line-through}
 .browse-link-mark{color:var(--muted);font-size:var(--fs-xs)}
 .browse-when{display:none}
+.browse-md-outline{max-width:80ch;margin:0 0 var(--space-3) var(--space-4);border:1px solid var(--border);border-radius:var(--radius-md);font-size:var(--fs-sm)}
+.browse-md-outline>summary{padding:var(--space-2) var(--space-3);cursor:pointer;color:var(--muted);font-family:var(--font-mono);font-size:var(--fs-xs)}
+.browse-md-outline ul{list-style:none;margin:0;padding:0 var(--space-3) var(--space-2)}
+.browse-md-outline a{display:block;padding:2px 0}
+.browse-md-outline a.lvl1{padding-left:var(--space-3)}
+.browse-md-outline a.lvl2{padding-left:var(--space-5)}
+.browse-md-outline a.lvl3{padding-left:var(--space-7)}
 body.palette-open{overflow:hidden}
 @media (max-width:520px){
 .bf-toolbar .bf-theme-toggle{margin-left:auto}
@@ -253,6 +260,20 @@ function renderCodeLines(lines: string[], language?: HighlightLanguage): string
 	return rendered.map((html) => `<span class="bf-code__line">${html.length > 0 ? html : " "}</span>`).join("");
 }
 
+/** An "on this page" outline from the headings the Markdown renderer emitted. */
+function renderOutline(headings: MarkdownHeading[]): string {
+	if (headings.length < 4) return "";
+	const base = Math.min(...headings.map((heading) => heading.level));
+	const items = headings
+		.map((heading) => {
+			const depth = Math.min(heading.level - base, 3);
+			const label = heading.text.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/[`*_~]/g, "");
+			return `<li><a class="lvl${depth}" href="#${heading.id}">${escapeHtml(label)}</a></li>`;
+		})
+		.join("");
+	return `<details class="browse-md-outline"><summary>On this page</summary><ul>${items}</ul></details>`;
+}
+
 /** The card-head controls: Markdown mode, line wrapping, and copy actions. */
 function renderFileActions(page: FilePage): string {
 	const isMarkdown = page.file.kind === "markdown";
@@ -275,7 +296,7 @@ function renderFileActions(page: FilePage): string {
 	}
 	if (page.file.kind === "text" || isMarkdown) {
 		groups.push(
-			`<button type="button" class="bf-btn" data-copy="content" data-href="${escapeHtml(rawHref)}" title="Copy the file contents">copy</button>`,
+			`<button type="button" class="bf-btn" data-copy="content" data-href="${escapeHtml(rawHref)}" title="Copy the file contents">copy contents</button>`,
 		);
 	}
 	groups.push(
@@ -296,10 +317,12 @@ export function renderFilePage(page: FilePage): string {
 	let content: string;
 	let note = "";
 	if (page.file.kind === "text" || page.file.kind === "markdown") {
-		content =
-			page.file.kind === "markdown" && !page.markdownRaw
-				? `<div class="bf-md">${renderMarkdown(page.file.lines.join("\n"), markdownBaseDir(page.rel))}</div>`
-				: `<pre class="bf-code bf-code--numbered"><code>${renderCodeLines(page.file.lines, language)}</code></pre>`;
+		if (page.file.kind === "markdown" && !page.markdownRaw) {
+			const rendered = renderMarkdownDocument(page.file.lines.join("\n"), markdownBaseDir(page.rel));
+			content = `${renderOutline(rendered.headings)}<article class="bf-md">${rendered.html}</article>`;
+		} else {
+			content = `<pre class="bf-code bf-code--numbered"><code>${renderCodeLines(page.file.lines, language)}</code></pre>`;
+		}
 		if (page.file.truncated)
 			note = `<p class="bf-note">Showing the first ${page.file.lines.length} of ${page.file.totalLines} lines.</p>`;
 	} else if (page.file.kind === "image") {

package/extensions/file-browse/markdown.ts

@@ -14,6 +14,10 @@
  * External images are rendered as links (the page CSP is `img-src 'self' data:`)
  * and non-http(s) schemes such as `javascript:` are dropped.
  *
+ * Headings get a stable anchor id and are demoted one level so the embedding
+ * page keeps the only `h1`; `renderMarkdownDocument` returns them for an
+ * outline.
+ *
  * Kept free of the page renderer: it imports only `lib/escape.ts`,
  * `lib/highlight.ts`, and `paths.ts`, so `html.ts` can compose it without a
  * module cycle.
@@ -35,16 +39,69 @@ interface LinkDefinition {
 	title?: string;
 }
 
-/** Per-document render state: the resolution base and the reference definitions. */
+/** A heading the renderer emitted, in document order. */
+export interface MarkdownHeading {
+	/** The rendered tag level, already demoted and capped at `h6`. */
+	level: number;
+	/** The anchor id, unique within the document. */
+	id: string;
+	/** The heading's raw inline Markdown. */
+	text: string;
+}
+
+/**
+ * Per-document render state: the resolution base, the reference definitions,
+ * and the headings emitted so far.
+ */
 interface Context {
 	baseDir: string;
 	defs: Map<string, LinkDefinition>;
+	headings: MarkdownHeading[];
+	slug(text: string): string;
+}
+
+/**
+ * Render a Markdown source string to a safe HTML fragment, plus the headings it
+ * emitted so a caller can build an outline. Headings carry an anchor id and are
+ * demoted one level, so the embedding page keeps the only `h1`.
+ */
+export function renderMarkdownDocument(source: string, baseDir = ""): { html: string; headings: MarkdownHeading[] } {
+	const { defs, body } = collectDefinitions(source.split(/\r\n|\r|\n/));
+	const context = createContext(baseDir, defs);
+	return { html: renderBlocks(body, context), headings: context.headings };
 }
 
 /** Render a Markdown source string to a safe HTML fragment. */
 export function renderMarkdown(source: string, baseDir = ""): string {
-	const { defs, body } = collectDefinitions(source.split(/\r\n|\r|\n/));
-	return renderBlocks(body, { baseDir, defs });
+	return renderMarkdownDocument(source, baseDir).html;
+}
+
+/** Turn heading text into a stable anchor id, dropping Markdown punctuation. */
+function headingSlug(text: string): string {
+	const plain = text
+		.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+		.replace(/[`*_~]/g, "")
+		.toLowerCase()
+		.replace(/[^\p{L}\p{N}\s-]/gu, "")
+		.replace(/[\s-]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return plain || "section";
+}
+
+/** Build the per-document render state, suffixing repeated heading slugs. */
+function createContext(baseDir: string, defs: Map<string, LinkDefinition>): Context {
+	const seen = new Map<string, number>();
+	return {
+		baseDir,
+		defs,
+		headings: [],
+		slug(text: string): string {
+			const base = headingSlug(text);
+			const count = seen.get(base) ?? 0;
+			seen.set(base, count + 1);
+			return count === 0 ? base : `${base}-${count}`;
+		},
+	};
 }
 
 /** Fold a reference label the way CommonMark does: trim, collapse, case-fold. */
@@ -135,7 +192,10 @@ function renderBlocks(lines: string[], ctx: Context): string {
 
 		const heading = matchHeading(line);
 		if (heading) {
-			out.push(`<h${heading.level}>${renderInline(heading.text, ctx)}</h${heading.level}>`);
+			const level = Math.min(heading.level + 1, 6);
+			const id = ctx.slug(heading.text);
+			ctx.headings.push({ level, id, text: heading.text });
+			out.push(`<h${level} id="${id}">${renderInline(heading.text, ctx)}</h${level}>`);
 			i++;
 			continue;
 		}
@@ -403,7 +463,7 @@ function renderListItem(contentLines: string[], ctx: Context): string {
 	const tight = !source.some(isBlank);
 	let body = renderBlocks(source, ctx);
 	if (tight) body = body.replace(/<\/?p>/g, "");
-	const mark = task ? `<span class="md-check" aria-hidden="true">${done ? "☑" : "☐"}</span> ` : "";
+	const mark = task ? `<input class="md-check" type="checkbox" disabled${done ? " checked" : ""}> ` : "";
 	return `<li${task ? (done ? ` class="task done"` : ` class="task"`) : ""}>${mark}${body}</li>`;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, document, memory, wechat, and bytefly.",
   "keywords": [
     "pi-package",
@@ -90,7 +90,7 @@
     "themes": [
       "./themes/*.json"
     ],
-    "image": "./assets/bytefly-chrome.png"
+    "image": "https://raw.githubusercontent.com/gavin-hu/my-pi-agent/main/assets/bytefly-chrome.png"
   },
   "scripts": {
     "test": "bun test --parallel=4 --timeout 30000",