@iyulab/canopy-page 0.11.2 → 0.13.0

package/CHANGELOG.md

@@ -7,6 +7,34 @@ 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
+
+- **Content images open full-size in a lightbox on click**, closing on a background click,
+  <kbd>Esc</kbd>, or its close button. An image already wrapped in a link to its own file — a
+  common workaround for the lack of a zoom before this — still opens the lightbox first; a
+  middle click or a modifier-held click on it still follows the link, for a reader who wants the
+  file itself.
+
 ## [0.11.2] — 2026-08-18
 
 ### Changed

package/README.md

@@ -33,19 +33,26 @@ 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
   system setting
+- **Content images open full-size in a lightbox** when clicked, closing on a background click,
+  <kbd>Esc</kbd>, or its close button
 - **Prev/next cards** linking to a page's neighbors in the sidebar's own order, and **backlinks**
   listing every page that points to it
 - **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
@@ -234,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/image-lightbox.css

@@ -0,0 +1,61 @@
+/* Image lightbox — pairs with assets/image-lightbox.js. Reuses canopy's own
+   tokens (--bg-primary, --text-normal, --radius-m, --sp-*) rather than
+   introducing new ones. z-index 30 sits above search's 10 and the mobile
+   nav overlay's 20, since the lightbox can open while either is present. */
+
+.canopy-content img {
+  cursor: zoom-in;
+}
+
+body.canopy-lightbox-open {
+  overflow: hidden;
+}
+
+.canopy-lightbox-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 30;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--sp-8);
+  background: rgba(0, 0, 0, 0.85);
+}
+
+.canopy-lightbox-overlay[hidden] {
+  display: none;
+}
+
+.canopy-lightbox-overlay img {
+  max-width: 90vw;
+  max-height: 90vh;
+  object-fit: contain;
+  cursor: default;
+  border-radius: var(--radius-m);
+}
+
+.canopy-lightbox-close {
+  position: fixed;
+  top: var(--sp-4);
+  right: var(--sp-4);
+  width: 2.5rem;
+  height: 2.5rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-m);
+  background: var(--bg-primary);
+  color: var(--text-normal);
+  font-size: 1.25rem;
+  line-height: 1;
+  cursor: pointer;
+}
+
+.canopy-lightbox-close::before {
+  content: "\00d7";
+}
+
+.canopy-lightbox-close:hover {
+  background: var(--bg-secondary);
+}

package/dist/assets/image-lightbox.js

@@ -0,0 +1,87 @@
+/**
+ * canopy-page's image lightbox — vanilla JS, no dependencies. Wires every
+ * `<img>` inside `.canopy-content` so a click opens it full-size in a
+ * dismissible overlay, rather than leaving a reader stuck at whatever width
+ * the article column happens to render it at.
+ *
+ * An image an author already wrapped in `<a href="...">` (a common way to
+ * work around the lack of a zoom before this script existed) still opens the
+ * lightbox first: the overlay shows the same source either way, so the link
+ * added nothing a reader couldn't already get from the image itself. The one
+ * case left alone is a click that already carries browser intent to open a
+ * new tab/window — middle click, or a modifier-held click — which this
+ * script never intercepts, so that intent still reaches the ancestor link.
+ *
+ * `shouldIntercept` is exposed for tests: it is the one piece of this file
+ * with real logic, and it needs no DOM to run.
+ */
+var CanopyImageLightbox = (function () {
+  "use strict";
+
+  /** Whether a click should open the lightbox instead of its default action. */
+  function shouldIntercept(event) {
+    return event.button === 0 && !event.ctrlKey && !event.metaKey && !event.shiftKey && !event.altKey;
+  }
+
+  function main() {
+    var images = document.querySelectorAll(".canopy-content img");
+    if (images.length === 0) return;
+
+    var overlay = document.createElement("div");
+    overlay.className = "canopy-lightbox-overlay";
+    overlay.hidden = true;
+
+    var overlayImg = document.createElement("img");
+    overlay.appendChild(overlayImg);
+
+    var closeButton = document.createElement("button");
+    closeButton.type = "button";
+    closeButton.className = "canopy-lightbox-close";
+    closeButton.setAttribute("aria-label", "Close");
+    overlay.appendChild(closeButton);
+
+    var opener = null;
+
+    function close() {
+      overlay.hidden = true;
+      document.body.classList.remove("canopy-lightbox-open");
+      if (opener) {
+        opener.focus();
+        opener = null;
+      }
+    }
+
+    function open(img) {
+      overlayImg.src = img.currentSrc || img.src;
+      overlayImg.alt = img.alt;
+      overlay.hidden = false;
+      document.body.classList.add("canopy-lightbox-open");
+      opener = img;
+      closeButton.focus();
+    }
+
+    overlay.addEventListener("click", function (event) {
+      if (event.target === overlayImg) return;
+      close();
+    });
+    closeButton.addEventListener("click", close);
+    document.addEventListener("keydown", function (event) {
+      if (!overlay.hidden && event.key === "Escape") close();
+    });
+
+    images.forEach(function (img) {
+      img.addEventListener("click", function (event) {
+        if (!shouldIntercept(event)) return;
+        event.preventDefault();
+        event.stopPropagation();
+        open(img);
+      });
+    });
+
+    document.body.appendChild(overlay);
+  }
+
+  if (typeof document !== "undefined") main();
+
+  return { shouldIntercept: shouldIntercept };
+})();

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/assets-bundle.js

@@ -34,11 +34,12 @@ const SEARCH_FAILED_DEFAULT = "Search failed to load.";
  * asset stays valid, readable JavaScript on its own.
  */
 export async function assembleScript(searchFailed) {
-    const [search, scrollspy, themeToggle, mobileNav] = await Promise.all([
+    const [search, scrollspy, themeToggle, mobileNav, imageLightbox] = await Promise.all([
         readAsset("search.js"),
         readAsset("scrollspy.js"),
         readAsset("theme-toggle.js"),
         readAsset("mobile-nav.js"),
+        readAsset("image-lightbox.js"),
     ]);
     // A function replacer, not a replacement string: String.replace treats
     // "$&"/"$'"/"$$" etc. in a replacement string as patterns, and a site
@@ -46,7 +47,7 @@ export async function assembleScript(searchFailed) {
     const searchWithStrings = searchFailed === undefined
         ? search
         : search.replace(JSON.stringify(SEARCH_FAILED_DEFAULT), () => JSON.stringify(searchFailed));
-    return `${searchWithStrings}\n${scrollspy}\n${themeToggle}\n${mobileNav}`;
+    return `${searchWithStrings}\n${scrollspy}\n${themeToggle}\n${mobileNav}\n${imageLightbox}`;
 }
 /**
  * CSS canopy-page contributes on top of a site's own tokens, carried via
@@ -54,7 +55,11 @@ export async function assembleScript(searchFailed) {
  * already uses, so no new canopy surface is needed for this either.
  */
 export async function assembleTokensCss(userTokensCss) {
-    const [search, scrollspy] = await Promise.all([readAsset("search.css"), readAsset("scrollspy.css")]);
-    const own = `${search}\n${scrollspy}`;
+    const [search, scrollspy, imageLightbox] = await Promise.all([
+        readAsset("search.css"),
+        readAsset("scrollspy.css"),
+        readAsset("image-lightbox.css"),
+    ]);
+    const own = `${search}\n${scrollspy}\n${imageLightbox}`;
     return userTokensCss === undefined ? own : `${userTokensCss}\n${own}`;
 }

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.11.2",
+  "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"
   }
 }