[qiansc]

Summary

0.7.87: each website article now ends with a source map instead of a plain list of source labels (on by default, site.sourceMap: false turns it off). The release also ships the source checklist template from #87.

Compatibility

• Website: articles with recorded references show the source map (with a List view) in their sources area. site.sourceMap: false keeps the previous plain source list. Sites re-render on the next context build.
• SDK: kbPackage.site gains an optional boolean sourceMap. Leaving it unset means on; the parsed configuration gains no field, so existing site configurations and receipts are unaffected.
• Build: the map is computed during the build from recorded references, registered sources and committed snapshots/notes. No agent step is involved and repository snapshot contents are not read.
• New runtime dependency d3-force@3.0.0 (ISC, bundled into the CLI); dev dependency @types/d3-force@3.0.10.

Verification

See "Testing" below.

Checklist

• bun run verify:full passes.
• Lifecycle changes include route and recovery tests. (not affected)
• Published package metadata and local pack behavior were checked when affected.
• English and Simplified Chinese user documentation remain behaviorally equivalent. (the English guide/reference and their workflow copies changed; there are no Chinese counterparts)
• Runtime code remains compatible with Node.js 20+.
• No generated output, secrets, private sources, or local workspaces are included.

Background

The "Sources" area at the end of an article was a list of labels (module/path L1–L5 · commit). Readers could not see which section relied on which document, where the documents came from, or which other articles cite the same material. All of that is already known at build time: the structure file records every section's references and line ranges, the source registry knows repositories, Lark documents and notes, and the link logic already exists.

Changes

• packageSiteSourceMap.ts (new): per-article map data — sections; cited documents grouped by source (repository module and directory, Lark, notes; coarsened to at most six groups); each citation's lines and link; other articles citing the same documents. The layout uses d3-force with a fixed seed, so builds are deterministic, and produces blob circles, tilted group-name positions, label room and a fitted height. Document titles: repository files by path; Lark and notes from their committed titles.
• packageSiteSources.ts: the per-reference link resolution is extracted as siteReferenceSource; the plain source list output is unchanged.
• packageSite.ts: writes contextSourceMap frontmatter when site.sourceMap !== false; section titles per reader language come from translations.
• packageSiteTheme.ts: Map/List switch (remembered; narrow screens show the list). Flat blobs — article sections purple, repository files green, Skills magenta, Lark documents blue, notes orange. Hover highlights links and shows line ranges; clicking a document opens the cited lines and clicking a section scrolls to it. Group names follow the blob edge; labels stay on one line when their row has room and otherwise wrap into balanced lines. The list shows each document on two lines: title, path and line ranges; then the sections using it.
• @c4a/context packageSite.ts: the sourceMap option; docs (package outputs, project API and their workflow copies).
• Version 0.7.87; CHANGELOG also records feat(context): add a source checklist template to the entry and planning skills #87's source checklist template. bun.lock only adds the dependency entries and workspace version lines, with no download URLs.

Risks

• The page does no layout work; articles with many citations get a taller map (up to about 820px).
• Sites that prefer the old list set site.sourceMap: false.

Backward compatibility

No action needed for existing workspaces; the next build shows the map. Configurations without sourceMap parse unchanged, and CLI JSON is unchanged.

Testing

• New packageSiteSourceMap.test.ts (5 pass): only recorded references are used; grouping and titles; lines and links match the source list; articles sharing documents; deterministic, in-bounds layout; group-name tilt limit; coarsening many directories; type colours; section-title extraction.
• packageSite.test.ts: a real site build renders the map by default (section anchors and related-article links), and a new sourceMap: false build keeps the plain list; packageSiteBuild.integration passes.
• bun run verify:full passes.
• Built a 113-article knowledge base and checked pages by screenshot in Chinese and English, light and dark, list view and narrow screens; the whole site builds in about 18 seconds.

🤖 Generated with Claude Code