nnw-theme 1.0.2 → 1.1.0

package/README.md

@@ -18,7 +18,7 @@ Run it with `npx`, from anywhere inside the theme repository. It needs Node 24 o
 ```sh
 npx nnw-theme@1 init       # once: name the theme and choose its permanent identifier
 npx nnw-theme@1 setup      # once per machine: install the WebKit build checks use
-npx nnw-theme@1 preview    # live gallery that rebuilds on save
+npx nnw-theme@1 preview    # live gallery that reloads on save
 npx nnw-theme@1 check      # the release gate: package, render, and test every case
 ```
 
@@ -30,7 +30,7 @@ version, name it: `npx nnw-theme@1.4.2 check`.
 | --- | --- |
 | `init` | Personalize a fresh copy of the template (run once) |
 | `setup` | Install the WebKit browser that `check` and `screenshot` use (`--with-deps` on Linux CI) |
-| `preview` | Serve the gallery on localhost, open it, and rebuild on save |
+| `preview` | Serve the gallery on localhost, open it, and rebuild and reload it on save |
 | `render [fixtures…]` | Write the gallery to `build/preview/` once |
 | `check` | Validate and package, then render and test every case in WebKit |
 | `screenshot` | Check one case and save its image; `--promote` makes it the marketplace card |

package/assets/live-reload.js

@@ -0,0 +1,62 @@
+// Live reload for `nnw-theme preview`. The preview server injects this into the
+// gallery and the full-size views only; rendered theme pages stay exactly as NNW
+// would show them. Each build event carries the build number and, when the latest
+// rebuild failed, its error.
+(() => {
+	const events = new EventSource("/__live");
+	const style = document.createElement("style");
+	// Scroll anchoring keeps the case in view steady while the error banner comes and
+	// goes. The banner itself can't be the anchor, and neither can the scaled thumbnail
+	// frames: WebKit anchors on them but then doesn't adjust.
+	style.textContent = `#nnw-live-error, .thumb iframe { overflow-anchor: none; }
+#nnw-live-error { background: #cf222e; color: #fff; font: .9rem/1.4 system-ui;
+  margin: 0 0 1rem; padding: .6rem .9rem; position: sticky; top: 0;
+  white-space: pre-wrap; z-index: 1; }
+body:not(:has(.case)) #nnw-live-error { left: 0; margin: 0; position: fixed; right: 0; }`;
+	document.head.append(style);
+
+	let build;
+	events.addEventListener("build", (event) => {
+		const state = JSON.parse(event.data);
+		showError(state.error);
+		if (build !== undefined && state.build !== build) refresh();
+		build = state.build;
+	});
+
+	function showError(message) {
+		let banner = document.getElementById("nnw-live-error");
+		if (!message) return banner?.remove();
+		if (!banner) {
+			banner = document.createElement("div");
+			banner.id = "nnw-live-error";
+			banner.setAttribute("role", "alert");
+			document.body.prepend(banner);
+		}
+		banner.textContent = `Rebuild failed; showing the last good build.\n${message}`;
+	}
+
+	// Setting src, even to its current value, navigates the frame again.
+	const reload = (frames) => {
+		for (const frame of frames) frame.setAttribute("src", frame.getAttribute("src"));
+	};
+
+	async function refresh() {
+		const cases = (root) => [...root.querySelectorAll(".case")].map((c) => c.id).join();
+		if (!document.querySelector(".case")) {
+			// A full-size view: reload its page in place.
+			reload(document.querySelectorAll("iframe"));
+			return;
+		}
+		// Refresh the thumbnails in place when the cases are unchanged, so nothing
+		// moves; a fixture added or removed changes the gallery, so reload it.
+		try {
+			const response = await fetch(location.pathname, { cache: "no-store" });
+			const next = new DOMParser().parseFromString(await response.text(), "text/html");
+			if (response.ok && cases(next) === cases(document)) {
+				reload(document.querySelectorAll(".case iframe"));
+				return;
+			}
+		} catch {}
+		location.reload();
+	}
+})();

package/dist/browser.js

@@ -10,6 +10,7 @@ import { extname, join, normalize, sep } from "node:path";
 import { packagePath, ThemeError } from "./project.js";
 import { pyReprList } from "./pyformat.js";
 const FOOTNOTE_CHECK = readFileSync(packagePath("assets", "footnotes.js"), "utf8");
+const LIVE_RELOAD = readFileSync(packagePath("assets", "live-reload.js"), "utf8");
 const NOT_INSTALLED = "WebKit is not installed; run `npx nnw-theme@1 setup`";
 const CONTENT_TYPES = {
     ".html": "text/html; charset=utf-8",
@@ -20,9 +21,11 @@ const CONTENT_TYPES = {
     ".json": "application/json",
     ".txt": "text/plain; charset=utf-8",
 };
-/** Serve a directory on 127.0.0.1 at a free port. */
-export async function serve(directory, port = 0) {
+export async function serve(directory, { live = false } = {}) {
     const root = normalize(directory);
+    const listeners = new Set();
+    let state = { build: 0 };
+    const send = (response) => response.write(`event: build\ndata: ${JSON.stringify(state)}\n\n`);
     const server = createServer((request, response) => {
         let path;
         try {
@@ -32,6 +35,16 @@ export async function serve(directory, port = 0) {
             response.writeHead(400).end();
             return;
         }
+        if (live && path === "/__live" && request.method === "GET") {
+            response.writeHead(200, {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-store",
+            });
+            listeners.add(response);
+            response.once("close", () => listeners.delete(response));
+            send(response);
+            return;
+        }
         if (path.endsWith("/"))
             path += "index.html";
         const file = normalize(join(root, path));
@@ -48,6 +61,12 @@ export async function serve(directory, port = 0) {
             response.writeHead(404).end();
             return;
         }
+        if (live && extname(file) === ".html" && !file.startsWith(join(root, "pages") + sep)) {
+            const html = content.toString("utf8");
+            const at = html.lastIndexOf("</body>");
+            const script = `<script>${LIVE_RELOAD}</script>`;
+            content = Buffer.from(at === -1 ? html + script : html.slice(0, at) + script + html.slice(at), "utf8");
+        }
         response.writeHead(200, {
             "Content-Type": CONTENT_TYPES[extname(file).toLowerCase()] ?? "application/octet-stream",
             "Content-Length": content.length,
@@ -57,7 +76,7 @@ export async function serve(directory, port = 0) {
     });
     await new Promise((resolve, reject) => {
         server.once("error", reject);
-        server.listen(port, "127.0.0.1", resolve);
+        server.listen(0, "127.0.0.1", resolve);
     });
     const address = server.address();
     if (!address || typeof address === "string")
@@ -68,6 +87,11 @@ export async function serve(directory, port = 0) {
             server.closeAllConnections();
             server.close(() => resolve());
         }),
+        publish(error) {
+            state = error === undefined ? { build: state.build + 1 } : { ...state, error };
+            for (const listener of listeners)
+                send(listener);
+        },
     };
 }
 async function playwright() {

package/dist/commands/init.js

@@ -1,6 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 import { setupWebkit } from "../browser.js";
 import { interactive, promptConfirm, promptText } from "../interactive.js";
 import { findRoot, findTheme, IDENTITY_END, IDENTITY_START, PLACEHOLDER_MARKER, readPlist, ThemeError, writePlist, } from "../project.js";
@@ -168,5 +168,5 @@ export default async function init({ values }) {
                 "Finish preview setup later with `npx nnw-theme@1 setup`.");
         }
     }
-    console.log("Next: describe the design you want, then run `npx nnw-theme@1 preview`.");
+    console.log(`Next: work on your design in ${relative(process.cwd(), theme) || "."}, then run \`npx nnw-theme@1 preview\`.`);
 }

package/dist/commands/preview.js

@@ -17,11 +17,11 @@ export default async function preview({ values }) {
     const theme = findTheme(root);
     const build = () => renderSite(root, theme, normalTargets(extraFixtures(root)));
     const site = build();
-    const server = await serve(site);
+    const server = await serve(site, { live: true });
     console.log(`Preview: ${server.url}`);
     if (!values["no-open"])
         openInBrowser(server.url);
-    console.log("Watching theme and fixtures. Press Ctrl-C to stop.");
+    console.log("Watching theme and fixtures; open pages reload on changes. Press Ctrl-C to stop.");
     let timer;
     const watcher = watch(root, { recursive: true }, (_event, name) => {
         if (!name || !watched(root, `${root}${sep}${name}`))
@@ -30,10 +30,13 @@ export default async function preview({ values }) {
         timer = setTimeout(() => {
             try {
                 build();
+                server.publish();
                 console.log("Rebuilt preview.");
             }
             catch (error) {
-                console.error(`error: ${error.message}`);
+                const { message } = error;
+                server.publish(message);
+                console.error(`error: ${message}`);
             }
         }, 200);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nnw-theme",
-	"version": "1.0.2",
+	"version": "1.1.0",
 	"description": "Create, preview, check, and publish a NetNewsWire theme.",
 	"license": "Apache-2.0",
 	"author": "Dave Marquard",