@iyulab/canopy-page 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ Notable changes to canopy-page. The format follows
 The `settings.json` contract is what consuming projects plan their upgrades around, so changes
 to it — its fields, its validation, and what the checks reject — are what this file is about.
 
+## [0.13.0] — 2026-08-22
+
+### Added
+
+- **Upgraded to canopy 0.12.0** — an external-link icon on `home` when it points outside the
+  site, a scroll-edge shadow on code blocks wider than the viewport, and the on-page outline now
+  shows its own label instead of only an `aria-label`. See
+  [canopy's own changelog](https://github.com/iyulab/canopy/blob/main/CHANGELOG.md#0120--2026-08-22)
+  for details.
+- **A `Ctrl K`/`⌘K` badge on the search box**, so the keyboard shortcut that already worked has
+  something telling a reader it exists. Hidden once the box has focus, and on narrow viewports
+  where the box collapses to an icon and a shortcut is unlikely to matter anyway.
+- **`check` warns about a filename that needs percent-encoding in its own URL** — a stray space
+  or other ASCII character outside a URL's unreserved set, most often. The page still publishes
+  correctly (a static host serves the encoded URL fine), so this is a warning, not an error;
+  ignore it if the encoding is intended. Blind to non-ASCII on purpose: a Korean, Japanese, or
+  any other non-English filename needs encoding too, but that's the language, not a mistake.
+
 ## [0.12.0] — 2026-08-22
 
 ### Added

package/README.md

@@ -33,7 +33,8 @@ page never depends on any of the scripted ones: block scripts, or print the page
 go away.
 
 - **Search**, matching a query against every page's title, headings, and body — `Ctrl+K` /
-  `Cmd+K` jumps to it from anywhere
+  `Cmd+K` jumps to it from anywhere, badged on the search box itself so the shortcut is
+  discoverable without reading the docs
 - **The current page and section, marked** in the sidebar and the on-page outline, updating as
   you scroll
 - **A dark/light toggle** that remembers a reader's choice; without one, pages follow the
@@ -45,9 +46,13 @@ go away.
 - **Sidebar groups collapse**, open exactly along the path to the page you're on and closed
   everywhere else
 - **A breadcrumb trail** in the topbar, when there's a title, a logo, `home`, or search for it to
-  sit beside
+  sit beside — and an icon on `home` specifically when it points off the site, so a link sitting
+  right next to that trail doesn't look like it stays on it
 - **A full-screen menu on narrow screens** that starts closed instead of opening on every page,
   remembering a reader's own choice to leave it open for the rest of that visit
+- **A code block wider than the screen shows a shadow at whichever edge still has more to
+  scroll to**, and nothing once you've scrolled there — a cue for a scrollbar that some
+  OS/browser combinations hide until hovered
 - **Sitemap and `robots.txt`**, once `siteUrl` is set
 
 See it live at <https://iyulab.github.io/canopy-page>, or read
@@ -236,6 +241,11 @@ Warnings — reported, and the build continues:
 - A section with no `label` and no index page, whose sidebar heading falls back to its own
   directory name — a filesystem detail, not a name anyone chose. Add a `label`, or an index page
   for the section to name itself
+- A filename whose published URL needs percent-encoding — a stray space or other ASCII
+  character outside a URL's unreserved set, most often. The page still publishes and works; this
+  is a nudge to check whether the encoding was intended, not a defect. Blind to non-ASCII on
+  purpose, so a Korean, Japanese, or any other non-English filename is never flagged for being
+  itself
 
 Checking reads the settings and each page. It never renders, so it is fast enough to sit at the
 front of a pipeline, at the scale a product manual reaches. References inside fenced

package/dist/assets/search.css

@@ -8,6 +8,44 @@
   position: relative;
 }
 
+/* Reserve room so the shortcut badge below doesn't sit on top of typed
+   text — canopy's own input padding only accounts for its search icon on
+   the left. */
+.canopy-search input[type="search"] {
+  padding-right: 3rem;
+}
+
+/* Advertises Ctrl+K/Cmd+K (search.js). An inert glyph, not a button — same
+   masked-icon-adjacent technique canopy's own shell uses for its search and
+   theme-toggle icons: pointer-events: none lets a click straight through to
+   the input underneath it. Hidden once the input has focus, so it doesn't
+   crowd a query being typed, and on narrow viewports, where canopy's own
+   shell (styles.ts, the `max-width: 40rem` breakpoint) collapses the input
+   to an icon-sized 2.25rem with no room for a badge — and where a physical
+   keyboard, the whole reason the shortcut exists, is unlikely anyway. */
+.canopy-search-shortcut {
+  position: absolute;
+  top: 50%;
+  right: var(--sp-2);
+  transform: translateY(-50%);
+  padding: 0.05em 0.4em;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-m);
+  font-size: 0.75em;
+  line-height: 1.4;
+  color: var(--text-muted);
+  background: var(--bg-secondary);
+  pointer-events: none;
+}
+.canopy-search input[type="search"]:focus ~ .canopy-search-shortcut {
+  display: none;
+}
+@media (max-width: 40rem) {
+  .canopy-search-shortcut {
+    display: none;
+  }
+}
+
 .canopy-search-results {
   position: absolute;
   top: 100%;

package/dist/assets/search.js

@@ -208,6 +208,19 @@ var CanopySearch = (function () {
       }
     });
 
+    // The shortcut above only works if a reader knows it exists — the badge
+    // is what tells them. Built here rather than in canopy's own shell markup
+    // because only this script knows the shortcut actually ended up wired
+    // (a build with no --script attached never reaches this line at all, so
+    // it never advertises a key that would do nothing). CSS hides it once
+    // the input has focus (search.css) so it doesn't crowd a query being
+    // typed.
+    var shortcut = document.createElement("kbd");
+    shortcut.className = "canopy-search-shortcut";
+    shortcut.setAttribute("aria-hidden", "true");
+    shortcut.textContent = /Mac|iPhone|iPad/.test(navigator.platform || "") ? "⌘K" : "Ctrl K";
+    form.appendChild(shortcut);
+
     // A script that ran this far is a script that can wire the form up —
     // reveal it now, and not before, so a build with no script attached
     // (or one that throws before this point) never shows a dead control.

package/dist/check.d.ts

@@ -1,4 +1,16 @@
 import { type Finding, type LoadedSite } from "./site.js";
+/**
+ * A published path's segments, exactly where percent-encoding canopy applies
+ * to the *link* (never the file, which keeps its raw name) turns out to
+ * matter: `relativeHref` (canopy's site-path.ts) encodes each segment with
+ * `encodeURIComponent`, so a name with a space or other URL-unsafe character
+ * still resolves — a static host serves "error%20messages.html" correctly —
+ * but nothing tells the author whether that was intended. Pages become
+ * `.html`; every other published file's segments are checked exactly as
+ * written, mirroring `toSitePath`'s own "everything but markdown passes
+ * through unchanged".
+ */
+export declare function filenameEncodingFindings(site: LoadedSite): Finding[];
 /** Check every page's references, returning one finding per broken reference. */
 export declare function referenceFindings(site: LoadedSite): Promise<Finding[]>;
 /**

package/dist/check.js

@@ -85,6 +85,57 @@ function wikilinkExists(site, target) {
         return site.index.resolve(target) !== undefined;
     return site.index.pages.some((page) => toPageKey(page).split("/").pop() === key);
 }
+/**
+ * `encodeURIComponent`'s unreserved set — the ASCII characters it leaves
+ * alone. Everything else ASCII (a space, `#`, `&`, `?`, …) is the kind of
+ * character that lands in a filename by accident — a stray space, a
+ * character copied from somewhere that meant it as punctuation, not a path.
+ */
+const ASCII_URI_SAFE = /^[A-Za-z0-9\-_.!~*'()]$/;
+/**
+ * True if `segment` contains an ASCII character `encodeURIComponent` would
+ * escape. Deliberately blind to non-ASCII: canopy percent-encodes every
+ * character outside the unreserved set, which means *any* non-English
+ * filename — a Korean directory name, an emoji — would otherwise trip this,
+ * and canopy-page's own demo site intentionally ships one (see
+ * `examples/site/guide/한국어-예시/`) as a *supported* pattern, not a mistake
+ * to flag. An ASCII character in the escaped set, on the other hand, is
+ * consistently a slip — nobody names a file "error#messages.md" on purpose.
+ */
+function hasAsciiEncodingIssue(segment) {
+    for (const char of segment) {
+        const code = char.codePointAt(0);
+        if (code !== undefined && code <= 0x7f && !ASCII_URI_SAFE.test(char))
+            return true;
+    }
+    return false;
+}
+/**
+ * A published path's segments, exactly where percent-encoding canopy applies
+ * to the *link* (never the file, which keeps its raw name) turns out to
+ * matter: `relativeHref` (canopy's site-path.ts) encodes each segment with
+ * `encodeURIComponent`, so a name with a space or other URL-unsafe character
+ * still resolves — a static host serves "error%20messages.html" correctly —
+ * but nothing tells the author whether that was intended. Pages become
+ * `.html`; every other published file's segments are checked exactly as
+ * written, mirroring `toSitePath`'s own "everything but markdown passes
+ * through unchanged".
+ */
+export function filenameEncodingFindings(site) {
+    const findings = [];
+    for (const file of [...site.index.pages, ...site.index.assets]) {
+        const published = file.replace(/\.md$/i, ".html");
+        const segments = published.split("/");
+        if (!segments.some(hasAsciiEncodingIssue))
+            continue;
+        const href = segments.map((segment) => encodeURIComponent(segment)).join("/");
+        findings.push({
+            level: "warning",
+            message: `${file}: published URL is "${href}" (rename to avoid the encoding, or ignore if intentional)`,
+        });
+    }
+    return findings;
+}
 /** Check every page's references, returning one finding per broken reference. */
 export async function referenceFindings(site) {
     const findings = [];
@@ -169,6 +220,7 @@ export async function siteFindings(site) {
     return [
         ...settingsFindings(site),
         ...navFindings(site.nav),
+        ...filenameEncodingFindings(site),
         ...(await referenceFindings(site)),
     ];
 }

package/dist/vault.d.ts

@@ -1,3 +1,21 @@
+/**
+ * Reading the source tree a settings file describes.
+ *
+ * canopy-page has to see the same files canopy will publish, because everything
+ * it does is about them: expanding `guide/*` into pages, reporting a link to a
+ * page that does not exist, deciding what a section contains. The checks are
+ * only worth anything if the file list they run against is the one that ships.
+ *
+ * That means the exclusion rules here have to agree with canopy's, and they are
+ * stated in canopy's README as the interface they are: dot-prefixed directories
+ * and `node_modules` are never published, and caller patterns come in three
+ * shapes. Agreeing by restating is a seam — if canopy ever widens its dialect,
+ * a check here would quietly disagree with the build. See
+ * TODO(upstream: claudedocs/issues/ISSUE-canopy-20260806-published-file-listing.md)
+ * for the proposal that would let a consumer ask canopy instead of restating it.
+ */
+/** Directories whose contents are never published, whatever the settings say. */
+export declare function isSkippedDir(name: string): boolean;
 /**
  * Match a site-relative POSIX path against one exclusion pattern.
  *

package/dist/vault.js

@@ -17,7 +17,7 @@ import path from "node:path";
  * for the proposal that would let a consumer ask canopy instead of restating it.
  */
 /** Directories whose contents are never published, whatever the settings say. */
-function isSkippedDir(name) {
+export function isSkippedDir(name) {
     return name.startsWith(".") || name === "node_modules";
 }
 /**

package/dist/watch.js

@@ -3,6 +3,7 @@ import http from "node:http";
 import { basename, extname, resolve, sep } from "node:path";
 import { watch as watchFiles } from "chokidar";
 import { buildSite } from "./build.js";
+import { isSkippedDir } from "./vault.js";
 /**
  * Serving a build's output locally during authoring.
  *
@@ -240,8 +241,7 @@ export async function watchSite(options) {
                 return false;
             if (resolved === resolvedOut || resolved.startsWith(outWithSep))
                 return true;
-            const name = basename(resolved);
-            return name === "node_modules" || name.startsWith(".");
+            return isSkippedDir(basename(resolved));
         },
     });
     // chokidar.watch() returns before its initial directory scan finishes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/canopy-page",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Authoring pipeline for documentation sites: one settings file, integrity checks, and a build.",
   "type": "module",
   "license": "MIT",
@@ -53,7 +53,7 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
-    "@iyulab/canopy": "^0.11.2",
+    "@iyulab/canopy": "^0.12.0",
     "chokidar": "^5.0.0"
   }
 }