From f0db82b21bb871fcf42ac3fc9ea6978cbee6867a Mon Sep 17 00:00:00 2001 From: Harvey Date: Tue, 17 Nov 2026 13:11:17 +0330 Subject: [PATCH 1/6] build(desktop): export the desktop renderer without web-only routes bun run build:desktop writes the static export to out/ with NEXT_PUBLIC_APP_TARGET=desktop. Web-only route handlers become route.web.ts(x), which the desktop page extensions skip. The five web metadata files and the /privacy and /offline pages are parked in the checkout for the build and put back: Turbopack ignores pageExtensions for metadata files, and a page.web.tsx loses the root layout's font preload on the web. next.config.ts refuses a web build while anything is parked. The export fails if a web-only route, a web metadata tag or the Windows segment layout reaches out/. icon.tsx is force-static. --- .gitignore | 2 + .../documents/[id]/{route.ts => route.web.ts} | 0 .../closed/{route.ts => route.web.ts} | 0 .../restore/{route.ts => route.web.ts} | 0 app/icon.tsx | 2 + app/llms.txt/{route.ts => route.web.ts} | 0 .../[id]/{route.tsx => route.web.tsx} | 0 next.config.ts | 84 ++++++---- package.json | 1 + scripts/build-desktop.ts | 62 +++++++ scripts/desktop-export.ts | 134 +++++++++++++++ .../unit/api/documents-close-restore.test.ts | 12 +- .../api/documents-delete-rate-limit.test.ts | 4 +- tests/unit/lib/import-boundaries.test.ts | 6 +- tests/unit/scripts/desktop-export.test.ts | 157 ++++++++++++++++++ tsconfig.json | 7 +- 16 files changed, 430 insertions(+), 41 deletions(-) rename app/api/documents/[id]/{route.ts => route.web.ts} (100%) rename app/api/documents/closed/{route.ts => route.web.ts} (100%) rename app/api/documents/restore/{route.ts => route.web.ts} (100%) rename app/llms.txt/{route.ts => route.web.ts} (100%) rename app/pwa-icons/[id]/{route.tsx => route.web.tsx} (100%) create mode 100644 scripts/build-desktop.ts create mode 100644 scripts/desktop-export.ts create mode 100644 tests/unit/scripts/desktop-export.test.ts diff --git a/.gitignore b/.gitignore index e62721d3..946a7a1d 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,8 @@ # next.js /.next/ /out/ +# web metadata files parked during a desktop export (scripts/build-desktop.ts) +/.desktop-export-parked/ # production /build diff --git a/app/api/documents/[id]/route.ts b/app/api/documents/[id]/route.web.ts similarity index 100% rename from app/api/documents/[id]/route.ts rename to app/api/documents/[id]/route.web.ts diff --git a/app/api/documents/closed/route.ts b/app/api/documents/closed/route.web.ts similarity index 100% rename from app/api/documents/closed/route.ts rename to app/api/documents/closed/route.web.ts diff --git a/app/api/documents/restore/route.ts b/app/api/documents/restore/route.web.ts similarity index 100% rename from app/api/documents/restore/route.ts rename to app/api/documents/restore/route.web.ts diff --git a/app/icon.tsx b/app/icon.tsx index 86cbb190..485aa5ac 100644 --- a/app/icon.tsx +++ b/app/icon.tsx @@ -2,6 +2,8 @@ import { ImageResponse } from "next/og"; import { BrandMark } from "@/components/brand"; +// Static in both builds; the desktop export (output: "export") requires it. +export const dynamic = "force-static"; export const size = { width: 512, height: 512 }; export const contentType = "image/png"; diff --git a/app/llms.txt/route.ts b/app/llms.txt/route.web.ts similarity index 100% rename from app/llms.txt/route.ts rename to app/llms.txt/route.web.ts diff --git a/app/pwa-icons/[id]/route.tsx b/app/pwa-icons/[id]/route.web.tsx similarity index 100% rename from app/pwa-icons/[id]/route.tsx rename to app/pwa-icons/[id]/route.web.tsx diff --git a/next.config.ts b/next.config.ts index 566f5910..e4041bd9 100644 --- a/next.config.ts +++ b/next.config.ts @@ -5,6 +5,7 @@ import type { NextConfig } from "next"; import { GA_MEASUREMENT_ID } from "./lib/analytics-config"; import { buildContentSecurityPolicy } from "./lib/security/content-security-policy"; +import { listParked, PARKING_DIR } from "./scripts/desktop-export"; function resolveBuildId(): string { const fromEnv = process.env.NEXT_PUBLIC_BUILD_ID?.trim(); @@ -25,6 +26,19 @@ function resolveBuildId(): string { return pkg.version; } +// The one build-time switch between the two renderers (desktop +// architecture §3.1 step 1). `bun run build:desktop` sets it. +const isDesktop = process.env.NEXT_PUBLIC_APP_TARGET === "desktop"; + +// A desktop export that was killed can leave web-only files parked; a web +// build now would ship without its sitemap, manifest or privacy page. +const parked = isDesktop ? [] : listParked(process.cwd()); +if (parked.length > 0) { + throw new Error( + `${parked.join(", ")} are parked in ${PARKING_DIR}/ by an interrupted desktop export. Run \`bun run build:desktop\` once (it puts them back first), or move them back into app/.`, + ); +} + const nextConfig: NextConfig = { env: { NEXT_PUBLIC_BUILD_ID: resolveBuildId(), @@ -32,39 +46,51 @@ const nextConfig: NextConfig = { // branches; an unset NEXT_PUBLIC_* stays a runtime lookup. NEXT_PUBLIC_APP_TARGET: process.env.NEXT_PUBLIC_APP_TARGET ?? "web", }, + // Desktop is a static export loaded from app://tinydocy. Web-only route + // handlers are `route.web.ts(x)`, which the desktop extensions don't + // match; `*.desktop.tsx` is the desktop-only counterpart. Web-only pages + // and metadata files are parked instead (scripts/desktop-export.ts). + ...(isDesktop ? { output: "export" as const } : {}), + pageExtensions: isDesktop + ? ["desktop.tsx", "tsx", "ts"] + : ["web.tsx", "web.ts", "tsx", "ts"], // Next 16.4+ rewrites AGENTS.md when it detects a coding agent; that file // holds curated repo conventions, so keep it hand-maintained. agentRules: false, poweredByHeader: false, - async headers() { - return [ - { - source: "/:path*", - headers: [ - { key: "X-Content-Type-Options", value: "nosniff" }, - { key: "X-Frame-Options", value: "DENY" }, - { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" }, - // Caps what embedded players can request, whatever `allow` a - // collaborator puts on the iframe. - { - key: "Permissions-Policy", - value: - "camera=(), microphone=(), geolocation=(), display-capture=(), clipboard-read=(), payment=(), usb=(), serial=(), hid=()", - }, - { - key: "Content-Security-Policy", - value: buildContentSecurityPolicy({ - nodeEnv: process.env.NODE_ENV, - hocusUrl: - process.env.NEXT_PUBLIC_HOCUS_URL?.trim() || - "ws://127.0.0.1:1234", - gaMeasurementId: GA_MEASUREMENT_ID, - }), - }, - ], - }, - ]; - }, + // A static export has no server to send headers; the desktop shell sets + // its own CSP (P2.5). + ...(isDesktop ? {} : { headers: webHeaders }), }; +async function webHeaders() { + return [ + { + source: "/:path*", + headers: [ + { key: "X-Content-Type-Options", value: "nosniff" }, + { key: "X-Frame-Options", value: "DENY" }, + { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" }, + // Caps what embedded players can request, whatever `allow` a + // collaborator puts on the iframe. + { + key: "Permissions-Policy", + value: + "camera=(), microphone=(), geolocation=(), display-capture=(), clipboard-read=(), payment=(), usb=(), serial=(), hid=()", + }, + { + key: "Content-Security-Policy", + value: buildContentSecurityPolicy({ + nodeEnv: process.env.NODE_ENV, + hocusUrl: + process.env.NEXT_PUBLIC_HOCUS_URL?.trim() || + "ws://127.0.0.1:1234", + gaMeasurementId: GA_MEASUREMENT_ID, + }), + }, + ], + }, + ]; +} + export default nextConfig; diff --git a/package.json b/package.json index 6b4393af..114a817d 100644 --- a/package.json +++ b/package.json @@ -11,6 +11,7 @@ "dev": "next dev", "hocus": "bun scripts/hocus-server.ts", "build": "next build", + "build:desktop": "bun scripts/build-desktop.ts", "start": "next start", "lint": "eslint .", "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.sw.json", diff --git a/scripts/build-desktop.ts b/scripts/build-desktop.ts new file mode 100644 index 00000000..58830fff --- /dev/null +++ b/scripts/build-desktop.ts @@ -0,0 +1,62 @@ +/** + * Builds the desktop renderer into `out/`: the static export with + * NEXT_PUBLIC_APP_TARGET=desktop (desktop architecture §3.1 step 1). + * Release builds run it on Linux only (#103). How routes leave the export, + * and the parking rules: `scripts/desktop-export.ts`. + * + * bun run build:desktop + */ +import { join } from "node:path"; + +import { + checkDesktopExport, + parkWebOnlyFiles, + restoreParked, +} from "./desktop-export"; + +async function main(): Promise { + const root = process.cwd(); + const leftovers = restoreParked(root); + for (const rel of leftovers) { + console.log(`[desktop-export] put back ${rel}, left by an interrupted run`); + } + + const parked = parkWebOnlyFiles(root); + const putBack = () => { + const restored = restoreParked(root); + if (restored.length !== parked.length) { + console.error( + `[desktop-export] put back ${restored.length} of ${parked.length} files; check app/`, + ); + } + }; + const onSignal = (signal: NodeJS.Signals) => { + putBack(); + process.exit(signal === "SIGINT" ? 130 : 143); + }; + process.once("SIGINT", onSignal); + process.once("SIGTERM", onSignal); + + let code: number; + try { + const build = Bun.spawn(["bun", "next", "build"], { + cwd: root, + stdio: ["ignore", "inherit", "inherit"], + env: { ...process.env, NEXT_PUBLIC_APP_TARGET: "desktop" }, + }); + code = await build.exited; + } finally { + putBack(); + process.off("SIGINT", onSignal); + process.off("SIGTERM", onSignal); + } + if (code !== 0) return code; + + const problems = checkDesktopExport(join(root, "out")); + for (const problem of problems) console.error(`[desktop-export] ${problem}`); + if (problems.length > 0) return 1; + console.log("[desktop-export] out/ is a valid desktop renderer"); + return 0; +} + +if (import.meta.main) process.exit(await main()); diff --git a/scripts/desktop-export.ts b/scripts/desktop-export.ts new file mode 100644 index 00000000..53f181e0 --- /dev/null +++ b/scripts/desktop-export.ts @@ -0,0 +1,134 @@ +/** + * Shared by `scripts/build-desktop.ts` and `next.config.ts`: what leaves the + * desktop static export (NEXT_PUBLIC_APP_TARGET=desktop) and how. No Bun + * APIs and no top-level await: `next.config.ts` imports it. + * + * What leaves the export, and how: + * - Web-only route handlers (`app/api`, `llms.txt`, `/pwa-icons`) are + * `route.web.ts(x)`. `next.config.ts` gives the desktop target page + * extensions that don't match them. No file moves. + * - The files in `WEB_ONLY_FILES` can't use that switch, so + * `bun run build:desktop` parks them for the build and puts them back: + * - Metadata files: Turbopack ignores `pageExtensions` for them (spike + * S1), and with `force-static` they would put the web manifest, + * `og:image` and `apple-touch-icon` tags into every desktop page (#115). + * - Pages: Next 16.4.6 drops the root layout's font preload from a + * `page.web.tsx` (`getPreloadableFonts` strips only `.tsx`, so it looks + * up `app/privacy/page.web` in a manifest keyed `app/privacy/page`). + * Renaming would change the web HTML. + * + * Parking rules (#111, #115): park inside the checkout (a rename across + * drives fails with EXDEV on Windows runners), put back what an interrupted + * run left first, put back in `finally` and on SIGINT/SIGTERM, and refuse to + * run if a file is both in `app/` and parked. `next.config.ts` refuses a web + * build while anything is parked, so a killed run can't ship a web build + * without its sitemap or its privacy page. + */ +import { + existsSync, + mkdirSync, + readdirSync, + readFileSync, + renameSync, + rmdirSync, +} from "node:fs"; +import { join, relative } from "node:path"; + +/** Web-only files parked during a desktop export, relative to the root. */ +export const WEB_ONLY_FILES = [ + "app/sitemap.ts", + "app/robots.ts", + "app/manifest.ts", + "app/opengraph-image.tsx", + "app/apple-icon.tsx", + "app/privacy/page.tsx", + "app/offline/page.tsx", +] as const; + +/** Where those files wait during a desktop export (gitignored). */ +export const PARKING_DIR = ".desktop-export-parked"; + +const parkedName = (rel: string) => rel.replaceAll("/", "__"); + +/** Files currently parked under `root`, as repo-relative paths. */ +export function listParked(root: string): string[] { + const dir = join(root, PARKING_DIR); + if (!existsSync(dir)) return []; + return readdirSync(dir).map((name) => name.replaceAll("__", "/")); +} + +/** Puts back every parked file. Throws if one also exists in `app/`. */ +export function restoreParked(root: string): string[] { + const restored: string[] = []; + for (const rel of listParked(root)) { + if (existsSync(join(root, rel))) { + throw new Error( + `${rel} is both in app/ and in ${PARKING_DIR}/; keep the right copy and delete the other`, + ); + } + renameSync(join(root, PARKING_DIR, parkedName(rel)), join(root, rel)); + restored.push(rel); + } + const dir = join(root, PARKING_DIR); + if (existsSync(dir)) rmdirSync(dir); + return restored; +} + +/** Moves `WEB_ONLY_FILES` out of `app/`. */ +export function parkWebOnlyFiles(root: string): string[] { + const dir = join(root, PARKING_DIR); + mkdirSync(dir, { recursive: true }); + const parked: string[] = []; + for (const rel of WEB_ONLY_FILES) { + if (!existsSync(join(root, rel))) continue; + renameSync(join(root, rel), join(dir, parkedName(rel))); + parked.push(rel); + } + return parked; +} + +/** Top-level names in `out/` that belong to the web build only. */ +const WEB_ONLY_OUTPUT = + /^(api|privacy|offline|pwa-icons|llms\.txt|sitemap|robots|manifest|opengraph-image|twitter-image|apple-icon)(\.|$)/; + +/** Head tags that file-convention metadata adds; none may reach desktop. */ +const WEB_ONLY_TAGS = [ + / void): void { + for (const entry of readdirSync(dir, { withFileTypes: true })) { + const path = join(dir, entry.name); + visit(path); + if (entry.isDirectory()) walk(path, visit); + } +} + +/** + * Problems with an exported `out/`, empty when it is a valid desktop + * renderer: no web-only route, no web metadata tag in any page, and the + * flat segment-prefetch layout (Windows writes `__next./`, #103). + */ +export function checkDesktopExport(outDir: string): string[] { + const problems: string[] = []; + for (const name of readdirSync(outDir)) { + if (WEB_ONLY_OUTPUT.test(name)) problems.push(`web-only output: ${name}`); + } + walk(outDir, (path) => { + const rel = relative(outDir, path); + const name = rel.split(/[\\/]/).at(-1) ?? ""; + if (name.startsWith("__next.") && !name.endsWith(".txt")) { + problems.push(`nested segment directory (Windows layout): ${rel}`); + } + if (!rel.endsWith(".html")) return; + const html = readFileSync(path, "utf8"); + for (const tag of WEB_ONLY_TAGS) { + if (tag.test(html)) problems.push(`${rel} has ${tag.source}`); + } + }); + return problems; +} diff --git a/tests/unit/api/documents-close-restore.test.ts b/tests/unit/api/documents-close-restore.test.ts index e2143b20..21d43c8d 100644 --- a/tests/unit/api/documents-close-restore.test.ts +++ b/tests/unit/api/documents-close-restore.test.ts @@ -8,9 +8,9 @@ import { MAX_TABS_PER_CLIENT } from "@/lib/constants"; import { bootstrapDocumentActivityTable } from "@/lib/security/activity-store"; import { importFresh, resetModules } from "@/tests/helpers/import-fresh"; -type DeleteRoute = typeof import("@/app/api/documents/[id]/route"); -type RestoreRoute = typeof import("@/app/api/documents/restore/route"); -type ClosedRoute = typeof import("@/app/api/documents/closed/route"); +type DeleteRoute = typeof import("@/app/api/documents/[id]/route.web"); +type RestoreRoute = typeof import("@/app/api/documents/restore/route.web"); +type ClosedRoute = typeof import("@/app/api/documents/closed/route.web"); const ID = "11111111-1111-4111-8111-111111111111"; const DAY_MS = 86_400_000; @@ -69,11 +69,11 @@ function tombstone(name: string): void { } const loadDelete = () => - importFresh("@/app/api/documents/[id]/route"); + importFresh("@/app/api/documents/[id]/route.web"); const loadRestore = () => - importFresh("@/app/api/documents/restore/route"); + importFresh("@/app/api/documents/restore/route.web"); const loadClosed = () => - importFresh("@/app/api/documents/closed/route"); + importFresh("@/app/api/documents/closed/route.web"); function params(id: string) { return { params: Promise.resolve({ id }) }; diff --git a/tests/unit/api/documents-delete-rate-limit.test.ts b/tests/unit/api/documents-delete-rate-limit.test.ts index 2ef82446..0cbd327b 100644 --- a/tests/unit/api/documents-delete-rate-limit.test.ts +++ b/tests/unit/api/documents-delete-rate-limit.test.ts @@ -2,14 +2,14 @@ import { afterEach, describe, expect, it, vi } from "bun:test"; import { importFresh, resetModules } from "@/tests/helpers/import-fresh"; -type DeleteRouteModule = typeof import("@/app/api/documents/[id]/route"); +type DeleteRouteModule = typeof import("@/app/api/documents/[id]/route.web"); const INVALID_ID_PARAMS = { params: Promise.resolve({ id: "../bad-document-id" }), }; function loadDeleteRoute(): Promise { - return importFresh("@/app/api/documents/[id]/route"); + return importFresh("@/app/api/documents/[id]/route.web"); } function deleteRequest(headers: Record): Request { diff --git a/tests/unit/lib/import-boundaries.test.ts b/tests/unit/lib/import-boundaries.test.ts index 8f38cf5f..7759507d 100644 --- a/tests/unit/lib/import-boundaries.test.ts +++ b/tests/unit/lib/import-boundaries.test.ts @@ -40,9 +40,9 @@ function staticImports(entry: string): { // Server code: the API routes, the retention cron and the Hocus server must // never load the client tab API or the browser collaboration provider. const SERVER_ENTRIES = [ - "app/api/documents/[id]/route.ts", - "app/api/documents/restore/route.ts", - "app/api/documents/closed/route.ts", + "app/api/documents/[id]/route.web.ts", + "app/api/documents/restore/route.web.ts", + "app/api/documents/closed/route.web.ts", "scripts/purge-retention.ts", "scripts/delete-document.ts", "scripts/hocus-server.ts", diff --git a/tests/unit/scripts/desktop-export.test.ts b/tests/unit/scripts/desktop-export.test.ts new file mode 100644 index 00000000..68a14762 --- /dev/null +++ b/tests/unit/scripts/desktop-export.test.ts @@ -0,0 +1,157 @@ +/** + * The desktop export's move-aside and output check (scripts/desktop-export.ts). + * The export itself is `bun run build:desktop`; these cover the parts that + * would fail silently: a lost file, a web route leaking into desktop. + */ +import { afterEach, beforeEach, describe, expect, it } from "bun:test"; +import { + existsSync, + mkdirSync, + mkdtempSync, + readdirSync, + readFileSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; + +import { + checkDesktopExport, + listParked, + PARKING_DIR, + parkWebOnlyFiles, + restoreParked, + WEB_ONLY_FILES, +} from "@/scripts/desktop-export"; + +const REPO = join(import.meta.dir, "../../.."); + +let root: string; + +function write(rel: string, content = rel): void { + mkdirSync(dirname(join(root, rel)), { recursive: true }); + writeFileSync(join(root, rel), content); +} + +beforeEach(() => { + root = mkdtempSync(join(tmpdir(), "desktop-export-")); +}); + +afterEach(() => { + rmSync(root, { recursive: true, force: true }); +}); + +describe("parking web-only files", () => { + it("lists only files that exist in the repo", () => { + for (const rel of WEB_ONLY_FILES) { + expect(existsSync(join(REPO, rel))).toBe(true); + } + }); + + it("parks every file inside the checkout and puts each back unchanged", () => { + for (const rel of WEB_ONLY_FILES) write(rel); + + expect(parkWebOnlyFiles(root)).toEqual([...WEB_ONLY_FILES]); + for (const rel of WEB_ONLY_FILES) { + expect(existsSync(join(root, rel))).toBe(false); + } + expect(listParked(root).sort()).toEqual([...WEB_ONLY_FILES].sort()); + + expect(restoreParked(root).sort()).toEqual([...WEB_ONLY_FILES].sort()); + for (const rel of WEB_ONLY_FILES) { + expect(readFileSync(join(root, rel), "utf8")).toBe(rel); + } + expect(existsSync(join(root, PARKING_DIR))).toBe(false); + }); + + it("puts back what an interrupted run left before parking again", () => { + write("app/robots.ts"); + parkWebOnlyFiles(root); + // The run was killed here. The next one restores first. + expect(restoreParked(root)).toEqual(["app/robots.ts"]); + expect(parkWebOnlyFiles(root)).toEqual(["app/robots.ts"]); + }); + + it("refuses when a file is both in app/ and parked", () => { + write("app/robots.ts", "parked copy"); + parkWebOnlyFiles(root); + write("app/robots.ts", "new copy"); + + expect(() => restoreParked(root)).toThrow(/both in app\/ and in/); + expect(readFileSync(join(root, "app/robots.ts"), "utf8")).toBe("new copy"); + expect(listParked(root)).toEqual(["app/robots.ts"]); + }); + + it("finds nothing parked in a clean checkout", () => { + expect(listParked(root)).toEqual([]); + expect(restoreParked(root)).toEqual([]); + }); +}); + +describe("route handlers that leave the desktop export", () => { + // `route.web.ts(x)` is what keeps them out (next.config.ts pageExtensions). + // A plain `route.ts` here would join the desktop export, or fail it. + it("are all route.web.ts(x)", () => { + const routes: string[] = []; + for (const dir of ["app/api", "app/llms.txt", "app/pwa-icons"]) { + for (const name of readdirSync(join(REPO, dir), { recursive: true })) { + const file = String(name).split(/[\\/]/).at(-1) ?? ""; + if (file.startsWith("route.")) routes.push(`${dir}/${name}`); + } + } + expect(routes.length).toBeGreaterThan(0); + expect(routes.filter((path) => !/\/route\.web\.tsx?$/.test(path))).toEqual( + [], + ); + }); +}); + +describe("checkDesktopExport", () => { + const PAGE = ''; + + function validExport(): void { + write("out/index.html", PAGE); + write("out/about.html", PAGE); + write("out/about/__next.about.__PAGE__.txt", ""); + write("out/_next/static/chunks/a.js", ""); + } + + it("accepts a desktop renderer", () => { + validExport(); + expect(checkDesktopExport(join(root, "out"))).toEqual([]); + }); + + it("reports web-only routes", () => { + validExport(); + write("out/privacy.html", PAGE); + write("out/sitemap.xml", ""); + write("out/api/documents/x", ""); + expect(checkDesktopExport(join(root, "out")).sort()).toEqual([ + "web-only output: api", + "web-only output: privacy.html", + "web-only output: sitemap.xml", + ]); + }); + + it("reports web metadata tags and in-app /privacy links", () => { + validExport(); + write( + "out/index.html", + 'Privacy', + ); + expect(checkDesktopExport(join(root, "out"))).toEqual([ + 'index.html has { + validExport(); + write("out/about/__next.about/__PAGE__.txt", ""); + expect(checkDesktopExport(join(root, "out"))).toEqual([ + `nested segment directory (Windows layout): ${join("about", "__next.about")}`, + ]); + }); +}); diff --git a/tsconfig.json b/tsconfig.json index 99c6bb37..1a1f62f9 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -31,5 +31,10 @@ ".next/dev/types/**/*.ts", "**/*.mts" ], - "exclude": ["node_modules", "lib/pwa/service-worker.ts", "desktop/smoke"] + "exclude": [ + "node_modules", + "out", + "lib/pwa/service-worker.ts", + "desktop/smoke" + ] } From 0a8843eaa29e1dce85450922e0c6f5eadea14c25 Mon Sep 17 00:00:00 2001 From: Harvey Date: Tue, 17 Nov 2026 13:11:19 +0330 Subject: [PATCH 2/6] feat(desktop): never register the service worker in the desktop build The worker precaches web-only pages (SHELL_PATHS has /privacy) and the desktop renderer loads from disk, so the target flag now turns registration off, as NEXT_PUBLIC_SERVICE_WORKER=0 does. --- .../pwa/service-worker-registration.tsx | 7 ++- .../service-worker-registration.test.ts | 57 +++++++++++++++++++ 2 files changed, 62 insertions(+), 2 deletions(-) create mode 100644 tests/unit/components/service-worker-registration.test.ts diff --git a/components/pwa/service-worker-registration.tsx b/components/pwa/service-worker-registration.tsx index 3f5b104d..7abb9f75 100644 --- a/components/pwa/service-worker-registration.tsx +++ b/components/pwa/service-worker-registration.tsx @@ -7,10 +7,13 @@ import { CACHE_PREFIX } from "@/lib/pwa/sw-config"; /** * Build-time switch, inlined by `bun run build`: NEXT_PUBLIC_SERVICE_WORKER=0 * unregisters the worker and deletes its caches on the next load. Development - * never registers, and removes a production worker left on localhost. + * never registers, and removes a production worker left on localhost. The + * desktop renderer never registers either: it is served from disk, and the + * worker precaches web-only pages (`SHELL_PATHS` has `/privacy`). */ -const SERVICE_WORKER_ENABLED = +export const SERVICE_WORKER_ENABLED = process.env.NODE_ENV === "production" && + process.env.NEXT_PUBLIC_APP_TARGET !== "desktop" && process.env.NEXT_PUBLIC_SERVICE_WORKER !== "0"; const IDLE_TIMEOUT_MS = 10_000; diff --git a/tests/unit/components/service-worker-registration.test.ts b/tests/unit/components/service-worker-registration.test.ts new file mode 100644 index 00000000..671263cd --- /dev/null +++ b/tests/unit/components/service-worker-registration.test.ts @@ -0,0 +1,57 @@ +/** + * The desktop renderer never registers the service worker (#117 follow-up): + * the worker precaches web-only pages (`SHELL_PATHS` has `/privacy`), and + * the desktop export has none of them. + */ +import { afterEach, describe, expect, it } from "bun:test"; + +import { importFresh, resetModules } from "@/tests/helpers/import-fresh"; + +type RegistrationModule = + typeof import("@/components/pwa/service-worker-registration"); + +const NODE_ENV = process.env.NODE_ENV; + +async function enabledWith(env: Record): Promise { + Object.assign(process.env, env); + const { SERVICE_WORKER_ENABLED } = await importFresh( + "@/components/pwa/service-worker-registration", + ); + return SERVICE_WORKER_ENABLED; +} + +afterEach(() => { + Object.assign(process.env, { NODE_ENV }); + delete process.env.NEXT_PUBLIC_APP_TARGET; + delete process.env.NEXT_PUBLIC_SERVICE_WORKER; + resetModules(); +}); + +describe("SERVICE_WORKER_ENABLED", () => { + it("web production build: on (unchanged)", async () => { + expect( + await enabledWith({ + NODE_ENV: "production", + NEXT_PUBLIC_APP_TARGET: "web", + }), + ).toBe(true); + }); + + it("desktop build: off", async () => { + expect( + await enabledWith({ + NODE_ENV: "production", + NEXT_PUBLIC_APP_TARGET: "desktop", + }), + ).toBe(false); + }); + + it("NEXT_PUBLIC_SERVICE_WORKER=0: off (unchanged)", async () => { + expect( + await enabledWith({ + NODE_ENV: "production", + NEXT_PUBLIC_SERVICE_WORKER: "0", + }), + ).toBe(false); + }); +}); From 9cd1cd84d930f9d371da212c858fa02c84cf7658 Mon Sep 17 00:00:00 2001 From: Harvey Date: Tue, 17 Nov 2026 13:11:20 +0330 Subject: [PATCH 3/6] test(desktop): run the desktop project on the static export desktop/shared/export-paths.ts holds the app:// protocol handler's path rules for the shell to reuse: pages to .html, RSC payloads under their exported names, the extension-less icon as image/png, unknown types and traversal refused. scripts/serve-desktop-export.ts serves out/ with them, the desktop project checks that every request the renderer makes is answered, and nightly runs it on Linux. --- .github/workflows/nightly.yml | 67 +++++++++++++++++ desktop/shared/export-paths.ts | 87 ++++++++++++++++++++++ scripts/serve-desktop-export.ts | 43 +++++++++++ tests/e2e/desktop-seams.spec.ts | 55 ++++++++++++-- tests/unit/desktop/export-paths.test.ts | 95 +++++++++++++++++++++++++ 5 files changed, 342 insertions(+), 5 deletions(-) create mode 100644 desktop/shared/export-paths.ts create mode 100644 scripts/serve-desktop-export.ts create mode 100644 tests/unit/desktop/export-paths.test.ts diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 242b8b14..1f590d89 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -11,6 +11,9 @@ name: Nightly # from 3 clients against Hocuspocus (spec §7 abuse soak) # mixed-version N+1, release N and pre-N clients on one document with # the gate env at its default (spec §3.1 N+1 ship gate) +# desktop-renderer the desktop static export (bun run build:desktop) on +# Linux, where releases build it (#103), served with the +# protocol handler's path rules, under the desktop project # desktop-smoke the D-A12 Electron smoke (desktop-smoke.yml) on macOS, # Windows and Linux # @@ -354,6 +357,70 @@ jobs: if-no-files-found: ignore retention-days: 7 + desktop-renderer: + name: Desktop renderer (static export) + runs-on: ubuntu-latest + timeout-minutes: 20 + permissions: + contents: read + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - name: Set up Bun + uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 + with: + bun-version-file: .tool-versions + + - name: Install + run: bun install --frozen-lockfile + + - name: Install Chromium + run: bun playwright install --with-deps chromium + + # Fails if a web-only route or web metadata tag reaches out/, or on the + # Windows segment layout; leaves app/ as it was. + - name: Desktop export + run: NEXT_PUBLIC_HOCUS_URL=ws://127.0.0.1:1234 bun run build:desktop + + - name: Web-only files are back in app/ + run: git diff --exit-code --stat -- app + + # The renderer still syncs through Hocus until the dev bridge (P2.4, + # after P2.1 and P2.2) replaces it. + - name: Start servers + id: servers + run: | + PORT=3849 bun scripts/serve-desktop-export.ts > "$RUNNER_TEMP/serve.log" 2>&1 & + make dev-hocus > "$RUNNER_TEMP/hocus.log" 2>&1 & + for _ in $(seq 1 60); do + if curl -s -o /dev/null http://127.0.0.1:1234 && + curl -sf -o /dev/null http://127.0.0.1:3849/; then + exit 0 + fi + sleep 1 + done + echo "::error::servers did not start" + exit 1 + + - name: Run the desktop project + run: >- + DESKTOP_BASE_URL=http://127.0.0.1:3849 CI= + bun playwright test --project=desktop --trace retain-on-failure + + - name: Upload failure artifacts + if: failure() + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: nightly-desktop-renderer + path: | + test-results/ + ${{ runner.temp }}/*.log + if-no-files-found: ignore + retention-days: 7 + # D-A12: node:sqlite, WAL, a worker thread and a custom app protocol in the # pinned Electron build, on the nightly schedule (no cron of its own). desktop-smoke: diff --git a/desktop/shared/export-paths.ts b/desktop/shared/export-paths.ts new file mode 100644 index 00000000..00abee85 --- /dev/null +++ b/desktop/shared/export-paths.ts @@ -0,0 +1,87 @@ +/** + * Maps a request path on the desktop origin to a file in the static export + * (`out/`), the way the `app://tinydocy` protocol handler serves it + * (desktop architecture §3.1; hardening checklist P2.4). Pure: the caller + * says which files exist, so the Electron handler (P2.5) and the test + * server (`scripts/serve-desktop-export.ts`) share one rule set. + * + * - `/` → `index.html`, `/about` → `about.html` (a page has a `.html` file + * and a same-named directory of segment payloads). + * - RSC payloads are served as they were exported: `about.txt`, + * `about/__next.about.__PAGE__.txt`. Never renamed (#103: no Windows + * layout mapping). + * - Extension-less files get a type from `EXTENSIONLESS_TYPES`; others are + * refused, so nothing is served without a known type (`nosniff`). + * - Paths that decode to `..`, a backslash, a NUL or an empty segment are + * refused before any lookup. + */ + +export type ExportFile = { + /** Path relative to `out/`, with `/` separators. */ + file: string; + contentType: string; +}; + +const TYPES: Record = { + html: "text/html; charset=utf-8", + js: "text/javascript; charset=utf-8", + css: "text/css; charset=utf-8", + txt: "text/plain; charset=utf-8", + json: "application/json", + svg: "image/svg+xml", + png: "image/png", + ico: "image/x-icon", + woff2: "font/woff2", + woff: "font/woff", + wasm: "application/wasm", +}; + +/** Metadata images Next writes without an extension. */ +export const EXTENSIONLESS_TYPES: Record = { + icon: "image/png", +}; + +function extensionOf(file: string): string | null { + const name = file.slice(file.lastIndexOf("/") + 1); + const dot = name.lastIndexOf("."); + return dot > 0 ? name.slice(dot + 1).toLowerCase() : null; +} + +function typeOf(file: string): string | null { + const ext = extensionOf(file); + if (ext !== null) return TYPES[ext] ?? null; + return EXTENSIONLESS_TYPES[file] ?? null; +} + +/** + * The file to serve for `pathname` (the URL's path, still percent-encoded), + * or null for a 404. `isFile(rel)` reports whether `out/` is a file. + */ +export function resolveExportFile( + pathname: string, + isFile: (rel: string) => boolean, +): ExportFile | null { + let path: string; + try { + path = decodeURIComponent(pathname); + } catch { + return null; + } + if (!path.startsWith("/") || /[\\\0]/.test(path)) return null; + + const rel = path.slice(1).replace(/\/$/, ""); + const segments = rel === "" ? [] : rel.split("/"); + if (segments.some((s) => s === "" || s === "." || s === "..")) return null; + + const candidates = + rel === "" + ? ["index.html"] + : extensionOf(rel) === null + ? [`${rel}.html`, rel, `${rel}/index.html`] + : [rel]; + for (const file of candidates) { + const contentType = typeOf(file); + if (contentType && isFile(file)) return { file, contentType }; + } + return null; +} diff --git a/scripts/serve-desktop-export.ts b/scripts/serve-desktop-export.ts new file mode 100644 index 00000000..60f21bf1 --- /dev/null +++ b/scripts/serve-desktop-export.ts @@ -0,0 +1,43 @@ +/** + * Serves the desktop static export (`out/`) over loopback HTTP, with the + * path rules of the `app://tinydocy` protocol handler + * (`desktop/shared/export-paths.ts`). For the `desktop` Playwright project + * until the Electron shell (P2.5) can run it; never a production server. + * + * bun run build:desktop && PORT=3849 bun scripts/serve-desktop-export.ts + */ +import { statSync } from "node:fs"; +import { join, resolve } from "node:path"; + +import { resolveExportFile } from "@/desktop/shared/export-paths"; + +const OUT_DIR = resolve(process.env.DESKTOP_OUT_DIR ?? "out"); +const PORT = Number(process.env.PORT ?? 3849); + +function isFile(rel: string): boolean { + try { + return statSync(join(OUT_DIR, rel)).isFile(); + } catch { + return false; + } +} + +const server = Bun.serve({ + hostname: "127.0.0.1", + port: PORT, + fetch(request) { + if (request.method !== "GET" && request.method !== "HEAD") { + return new Response("Method not allowed", { status: 405 }); + } + const found = resolveExportFile(new URL(request.url).pathname, isFile); + if (!found) return new Response("Not found", { status: 404 }); + return new Response(Bun.file(join(OUT_DIR, found.file)), { + headers: { + "content-type": found.contentType, + "x-content-type-options": "nosniff", + }, + }); + }, +}); + +console.log(`[serve-desktop-export] ${OUT_DIR} on ${server.url}`); diff --git a/tests/e2e/desktop-seams.spec.ts b/tests/e2e/desktop-seams.spec.ts index 0c35417b..389c2db0 100644 --- a/tests/e2e/desktop-seams.spec.ts +++ b/tests/e2e/desktop-seams.spec.ts @@ -3,12 +3,13 @@ import { expect, type Page, test } from "@playwright/test"; import { EditorPage } from "./helpers/editor-page"; /** - * The desktop renderer's web seams (#99, #101), against a production build - * made with the desktop flag (prefetch runs only in production builds): - * NEXT_PUBLIC_APP_TARGET=desktop NEXT_PUBLIC_HOCUS_URL=ws://127.0.0.1:1296 bun run build - * PORT=3849 bun run start + * The desktop renderer (#99, #101, P2.4), against the desktop static export + * served with the protocol handler's path rules (prefetch runs only in + * production builds): + * NEXT_PUBLIC_HOCUS_URL=ws://127.0.0.1:1296 bun run build:desktop + * PORT=3849 bun scripts/serve-desktop-export.ts * HOCUS_PORT=1296 HOCUS_THROTTLE=0 HOCUS_ALLOW_ISOLATED_TABS_DOCS=1 bun run hocus - * DESKTOP_BASE_URL=http://localhost:3849 CI= bun playwright test --project=desktop + * DESKTOP_BASE_URL=http://127.0.0.1:3849 CI= bun playwright test --project=desktop */ test.skip(!process.env.DESKTOP_BASE_URL, "needs a desktop-flag build"); @@ -41,6 +42,50 @@ async function paste(page: Page, text: string): Promise { } test.describe("desktop build", () => { + test("the export answers every request the renderer makes", async ({ + page, + }) => { + const origin = new URL(test.info().project.use.baseURL ?? "").origin; + const failed: string[] = []; + page.on("response", (response) => { + const url = new URL(response.url()); + if (url.origin === origin && response.status() >= 400) { + failed.push(`${response.status()} ${url.pathname}${url.search}`); + } + }); + const urls = recordRequests(page); + + // The header links prefetch both pages' segments; the click is a + // client navigation that fetches the RSC payload (.txt). + await page.goto("/about"); + await page.waitForLoadState("networkidle"); + await page + .getByRole("navigation", { name: "Site" }) + .getByRole("link", { name: "Open the editor" }) + .click(); + await expect(page).toHaveURL(/\/$/); + await new EditorPage(page).waitForSync(); + await page.waitForLoadState("networkidle"); + + expect(failed).toEqual([]); + const paths = urls.map((url) => new URL(url).pathname); + expect(paths.some((path) => path.endsWith(".txt"))).toBe(true); + // The page links it; headless Chromium doesn't fetch icons itself. + const href = await page + .locator('link[rel="icon"][type="image/png"]') + .getAttribute("href"); + const icon = await page.request.get(href ?? ""); + expect(icon.status()).toBe(200); + expect(icon.headers()["content-type"]).toBe("image/png"); + expect( + paths.filter((path) => + /^\/(manifest\.webmanifest|opengraph-image|apple-icon|sitemap|robots|api\/|privacy|offline)/.test( + path, + ), + ), + ).toEqual([]); + }); + test("/about links to the website's privacy page and never fetches /privacy", async ({ page, }) => { diff --git a/tests/unit/desktop/export-paths.test.ts b/tests/unit/desktop/export-paths.test.ts new file mode 100644 index 00000000..6a9bbfe3 --- /dev/null +++ b/tests/unit/desktop/export-paths.test.ts @@ -0,0 +1,95 @@ +import { describe, expect, it } from "bun:test"; + +import { resolveExportFile } from "@/desktop/shared/export-paths"; + +/** The top of a real desktop export (`bun run build:desktop`). */ +const OUT = new Set([ + "index.html", + "index.txt", + "404.html", + "about.html", + "about.txt", + "about/__next.about.__PAGE__.txt", + "__next._tree.txt", + "icon", + "favicon.ico", + "_next/static/chunks/abc.js", + "_next/static/chunks/abc.css", + "_next/static/media/font.woff2", + "_next/static/media/service-worker.123.ts", +]); +const resolve = (path: string) => resolveExportFile(path, (f) => OUT.has(f)); + +describe("resolveExportFile", () => { + it("maps pages to their .html file", () => { + expect(resolve("/")).toEqual({ + file: "index.html", + contentType: "text/html; charset=utf-8", + }); + expect(resolve("/about")?.file).toBe("about.html"); + expect(resolve("/about/")?.file).toBe("about.html"); + }); + + it("serves RSC payloads under their exported names", () => { + expect(resolve("/about.txt")).toEqual({ + file: "about.txt", + contentType: "text/plain; charset=utf-8", + }); + expect(resolve("/about/__next.about.__PAGE__.txt")?.file).toBe( + "about/__next.about.__PAGE__.txt", + ); + expect(resolve("/__next._tree.txt")?.file).toBe("__next._tree.txt"); + }); + + it("gives the extension-less icon its image type", () => { + expect(resolve("/icon")).toEqual({ + file: "icon", + contentType: "image/png", + }); + expect(resolve("/favicon.ico")?.contentType).toBe("image/x-icon"); + }); + + it("types static assets", () => { + expect(resolve("/_next/static/chunks/abc.js")?.contentType).toBe( + "text/javascript; charset=utf-8", + ); + expect(resolve("/_next/static/chunks/abc.css")?.contentType).toBe( + "text/css; charset=utf-8", + ); + expect(resolve("/_next/static/media/font.woff2")?.contentType).toBe( + "font/woff2", + ); + }); + + it("refuses files with no known type", () => { + expect(resolve("/_next/static/media/service-worker.123.ts")).toBeNull(); + }); + + it("returns null for web-only and unknown routes", () => { + for (const path of ["/privacy", "/api/documents/x", "/sitemap.xml", "/x"]) { + expect(resolve(path)).toBeNull(); + } + }); + + it("refuses traversal and malformed paths before any lookup", () => { + const looked: string[] = []; + const spy = (f: string) => { + looked.push(f); + return true; + }; + for (const path of [ + "/../etc/passwd", + "/%2e%2e/etc/passwd", + "/_next/%2e%2e/%2e%2e/secret.txt", + "/a//b.js", + "/./index.html", + "/..%5csecret.txt", + "/%00.html", + "/%E0%A4%A", + "relative.html", + ]) { + expect(resolveExportFile(path, spy)).toBeNull(); + } + expect(looked).toEqual([]); + }); +}); From 033531b47f1896af2ed69253fb7500db8f706f07 Mon Sep 17 00:00:00 2001 From: Harvey Date: Tue, 17 Nov 2026 13:11:20 +0330 Subject: [PATCH 4/6] docs: document the desktop renderer export --- CHANGELOG.md | 37 +++++++++++++++++++ README.md | 3 +- .../specs/2026-11-15-desktop-architecture.md | 10 +++-- tests/TESTING.md | 18 +++++---- 4 files changed, 57 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c2bc296..6ee91a9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,43 @@ since the previous tag. ## [Unreleased] +### Desktop renderer export (P2.4) + +`bun run build:desktop` builds the desktop renderer: the static export the +Electron shell will load. The web build is unchanged. Its route table, client +chunks (names and sizes), manifests and every page apart from `/icon`'s URL +match `main`. The `/icon?` cache-buster changes because `app/icon.tsx` +gained `dynamic = "force-static"`; the PNG is byte-identical. + +#### Added + +- `bun run build:desktop` (`scripts/build-desktop.ts`) writes `out/` with + `NEXT_PUBLIC_APP_TARGET=desktop` and `output: "export"`. Desktop routes: + `/`, `/about`, `/_not-found`, `/icon`. It fails if a web-only route, a web + metadata tag or the Windows segment layout (#103) reaches `out/`. +- `desktop/shared/export-paths.ts`: the `app://` protocol handler's path rules + for P2.5. `/about` maps to `about.html`, RSC `.txt` files keep their + exported names, and the extension-less `/icon` is `image/png`. Unknown + types and traversal are refused. `scripts/serve-desktop-export.ts` serves + `out/` with them for tests. +- The `desktop` Playwright project runs on the export instead of `next start`. + It checks that every request the renderer makes is answered and none goes + to a web-only route. Nightly runs it on Linux (`desktop-renderer`). + +#### Changed + +- Web-only route handlers are `route.web.ts(x)` (`app/api/**`, `llms.txt`, + `pwa-icons/[id]`). `next.config.ts` switches `pageExtensions`, `output` and + `headers()` on the target flag. +- The export parks the five web metadata files and the `/privacy` and + `/offline` pages in `.desktop-export-parked/` for the build and puts them + back, as spike #115 measured is required. Renaming the pages would drop + their font preload on the web: Next 16.4.6 looks up `page.web` in a font + manifest keyed `page`. +- `next.config.ts` refuses a web build while anything is parked. +- The desktop build never registers the service worker, whose precache lists + `/privacy` (#117 follow-up). + ### Dark links on highlighted text Links inside highlighted text are readable in dark mode (#104). diff --git a/README.md b/README.md index 27f3b898..60318913 100644 --- a/README.md +++ b/README.md @@ -166,7 +166,7 @@ building; setting them at runtime has no effect. | `NEXT_PUBLIC_OFFLINE_CACHE` | on | `0` turns off offline document copies and deletes stored ones. | | `NEXT_PUBLIC_ACTION_PREVIEW` | on | `0` turns off colour previews: pointing at or arrowing to a swatch no longer shows it on the selection. | | `NEXT_PUBLIC_REMEMBER_CHOICES` | on | `0` stops the toolbar remembering choices (last colours, recent colours, list type, table size, Simplified toolbar) and the "Continue where you left off" place: it shows the defaults and writes nothing, and the Simplified toolbar item is disabled with the reason. Choices stay in this browser (`tinydocy-choices`, `tinydocy-ui`, `tinydocy-continue`) and never reach the document, the server, URLs or analytics. | -| `NEXT_PUBLIC_APP_TARGET` | `web` | `desktop` for the desktop app's build: Subscript moves to ⌘⇧, so ⌘, can open Settings; Privacy links to the website's page in a new window; X posts render as a link card with no X script, and the Embed dialog leaves X out. See arch §3.1 in the desktop architecture spec. | +| `NEXT_PUBLIC_APP_TARGET` | `web` | `desktop` for the desktop app's build: Subscript moves to ⌘⇧, so ⌘, can open Settings; Privacy links to the website's page in a new window; X posts render as a link card with no X script, and the Embed dialog leaves X out; the service worker never registers. `bun run build:desktop` sets it and writes the static export to `out/`, without the API, `/privacy`, `/offline`, `llms.txt`, the sitemap, robots, manifest and social images. See arch §3.1 in the desktop architecture spec. | | `NEXT_PUBLIC_BUILD_ID` | short git commit, else package version | Build identifier the client sends as `build=` on the socket URL; shows up in the server's per-minute `client_schema` log line. | | `NEXT_PUBLIC_MAX_EMBED_IMAGE_BYTES` | 262144 | Images are downscaled in the browser to this size before embedding. | | `NEXT_PUBLIC_MAX_TABS_PER_CLIENT` | 50 | Tab cap in the UI. | @@ -240,6 +240,7 @@ Release notes for each change, including deploy steps, are in the |---|---| | `make dev` | Next.js and Hocuspocus together. | | `bun run build` / `bun run start` | Production build and server. | +| `bun run build:desktop` | The desktop renderer: static export to `out/` (built on Linux for releases). | | `bun run test` | Unit tests with `bun test` (the stress probe runs with `test:stress`). | | `bun run test:e2e` | Playwright against `make dev` (set `CI=` to reuse running servers). | | `bun run test:pwa` | Service worker and offline tests against a production build (`PWA_BASE_URL`). | diff --git a/docs/superpowers/specs/2026-11-15-desktop-architecture.md b/docs/superpowers/specs/2026-11-15-desktop-architecture.md index 3733061e..226d8f73 100644 --- a/docs/superpowers/specs/2026-11-15-desktop-architecture.md +++ b/docs/superpowers/specs/2026-11-15-desktop-architecture.md @@ -139,10 +139,14 @@ desktop/ - The Privacy link goes to the website's page, `${SITE_URL}/privacy`, in a new window that the shell sends to the system browser, as a plain anchor that is never prefetched, because `/privacy` is web only (`components/site-page/privacy-link.tsx`, #101). - X posts render as a static link card: the kit's `x` node stays in the schema, so documents with X posts stay valid and a web client still embeds them, but its node view is replaced, so no oEmbed request and no `widgets.js` (`extensions/hyper-multimedia/x-link-card.ts`, #99). The spike's `X: false` would have dropped the node from the desktop schema. The card's stylesheet loads by `import()` inside the desktop branch: a static stylesheet import survives tree shaking and would ship to the web. - The Embed dialog neither lists nor accepts X; pasting an X URL into the document still makes the card (`use-media-embed.ts`, #99). - - The `desktop` Playwright project checks a desktop-flag production build: no request for `/privacy`, and none to X's hosts (`tests/e2e/desktop-seams.spec.ts`). - - `next.config.ts` switches three things on that literal: `output: "export"`, `headers()` (web only), and `pageExtensions`: web `["web.tsx", "web.ts", "tsx", "ts"]`, desktop `["desktop.tsx", "tsx", "ts"]`. + - The service worker never registers: it precaches web-only pages (`SHELL_PATHS` has `/privacy`), and the renderer loads from disk (`components/pwa/service-worker-registration.tsx`, P2.4). + - **The export** (P2.4): `bun run build:desktop` (`scripts/build-desktop.ts`) writes `out/` and fails if a web-only route, a web metadata tag (`rel="manifest"`, `og:image`, `twitter:image`, `apple-touch-icon`, `href="/privacy"`) or a `__next.*` directory reaches it. Desktop routes: `/`, `/about`, `/_not-found`, `/icon`. + - The `desktop` Playwright project runs on that export, served by `scripts/serve-desktop-export.ts` with the protocol handler's path rules (`desktop/shared/export-paths.ts`, which P2.5's handler reuses: `/about` → `about.html`, RSC `.txt` files under their exported names, `/icon` as `image/png`, unknown types and traversal refused). It checks that every request the renderer makes is answered and none goes to a web-only route, no request for `/privacy`, and none to X's hosts (`tests/e2e/desktop-seams.spec.ts`). Nightly runs it on Linux (`desktop-renderer`). + - `next.config.ts` switches three things on that literal: `output: "export"`, `headers()` (web only), and `pageExtensions`: web `["web.tsx", "web.ts", "tsx", "ts"]`, desktop `["desktop.tsx", "tsx", "ts"]`. The web-only route handlers are `route.web.ts(x)`: `app/api/**`, `llms.txt`, `pwa-icons/[id]`. + - **Web-only pages are parked, not renamed.** Next 16.4.6 drops the root layout's font preload from a `page.web.tsx`: `getPreloadableFonts` strips only the last extension, so it looks up `app/privacy/page.web` in a font manifest keyed `app/privacy/page`. Renaming `/privacy` and `/offline` would change their web HTML, so they join the parked metadata files below. - **S1 (2026-11-16):** Turbopack honours `pageExtensions` for `page` and `route` files but not for metadata files: in the web build `sitemap.web.ts` became the route `/sitemap.web`. So `sitemap`, `robots`, `opengraph-image`, `manifest` and `apple-icon` keep their plain names, and a prebuild step moves them out of `app/` for the desktop build and puts them back (the overlay fallback). - - It parks them inside the checkout: a rename across drives fails with `EXDEV` on Windows runners (#111, proved on `windows-latest` with the default temp dir). Before moving anything it puts back files that an interrupted run left parked; otherwise the next web build would silently lose them. + - It parks them inside the checkout, in `.desktop-export-parked/` (gitignored): a rename across drives fails with `EXDEV` on Windows runners (#111, proved on `windows-latest` with the default temp dir). Before moving anything it puts back files that an interrupted run left parked, and it puts them back in `finally` and on SIGINT or SIGTERM. A file both in `app/` and parked stops the build. + - `next.config.ts` refuses a web build while anything is parked, so a killed export (SIGKILL included) can't ship a web build without its sitemap, manifest or privacy page. - **The overlay stays in Phase 2** ([Windows export spike](../../research/2026-11-17-spike-windows-export.md), 2026-11-17). The desktop build flag alone can't replace it. Left in `app/`, the five files fail the export (`force-static` not configured). With `dynamic = "force-static"` the export passes, but every desktop page then carries ``, the web `og:image` and `apple-touch-icon`. Deleting the files from `out/` afterwards would leave those tags pointing at nothing. - **Built once, on Linux** (#103). Next 16.4.6 writes segment-prefetch files on Windows as `__next./__PAGE__.txt` instead of `__next..__PAGE__.txt`, so prefetch 404s (upstream vercel/next.js#85374, still unfixed in 16.5 canary). Windows never exports the renderer: the release and nightly pipelines build `out/` once, in a Linux job, and hand the same bytes to every OS's packaging job (test and release strategy §2.4). The PR job `electron-mac` may export on its own macOS runner. The protocol handler maps no names. - `icon.tsx` needs `export const dynamic = "force-static"`, and `tsconfig.json` excludes `out/` (the export copies the service worker's `.ts` source into `out/_next/static/media/`). diff --git a/tests/TESTING.md b/tests/TESTING.md index 7fa81fef..a514e513 100644 --- a/tests/TESTING.md +++ b/tests/TESTING.md @@ -55,11 +55,12 @@ tests/ │ ├── helpers/ # canMapDecorations, computeSection, fold-storage, filter-url, move-section, tab-api, media-embed URL gate │ ├── hooks/ # useSyncedTabs bootstrap + active-tab resolution (mocked Hocuspocus provider) │ ├── api/ # Route handlers: DELETE rate limit; soft close, batch restore and Recently closed list (temp DB_PATH) -│ ├── scripts/ # Retention purge (stale and closed documents), operator delete-document, Hocus client gate and root sweep +│ ├── scripts/ # Retention purge (stale and closed documents), operator delete-document, Hocus client gate and root sweep, desktop export parking and output check │ ├── lib/ # Image embed planner and pipeline; `assets/` PNG, WebP and JPEG metadata stripper; security guardrails (incl. closed-documents store), import boundaries (server entries never reach `lib/tab-api` or `@hocuspocus/provider`), legacy Yjs mark migration (link/code → hyperlink/inlineCode), `addToHistory: false` kept with appended heading-id transactions (y-tiptap patch), design-token contrast (`token-contrast.test.ts`: `--primary-ink` ≥ 4.5:1 on every surface, no `text-primary`/`border-primary` utility in TSX and no `var(--primary)` text or border declaration in stylesheets, document link colour ≥ 4.5:1 on background and card in both themes), theme boot script and System theme (`theme.test.ts`), identity validation and blocked storage (`user-identity.test.ts`) │ ├── editor-actions/ # Action contract and core actions; shortcut-bindings.test.ts: every advertised key bound once, tab-bar keys kept out of the editor keymap, Subscript by build target; playground-regenerate.test.ts: Regenerate Playground offered in the Playground only │ ├── components/ # React components in happy-dom (toolbar button, menus, insert menu, ThemeToggle's phone cycle in `theme-toggle.test.tsx`); the identity dialog's inline name errors and the normalised broadcast (`user-identity-dialog.test.tsx`) │ ├── extensions/ # Render-once, CaretBlockVisible, fast TOC, incremental code highlighting, media controls kept across plugin view rebuilds, remote caret names and colours clamped at render (`safe-caret-render.test.ts`) +│ ├── desktop/ # Desktop shared modules: the static export's path rules (`export-paths.test.ts`) │ ├── ci/ # Workflow rules: read-only tokens, no persisted credentials, SHA-pinned actions │ ├── fuzz/ # Chaos fuzz (5000 ops) + structured schema fuzz (5000 ops) │ └── stress/ # Headless stress probe (binary search for heading ceiling) @@ -87,7 +88,7 @@ tests/ │ ├── offline-copies.spec.ts # IndexedDB copies: repeat visit, reload, deletion, clearing │ ├── tab-close-undo.spec.ts # Undo pill after closing, Recently closed, purge after the closed window │ ├── continue-chip.spec.ts # "Continue where you left off" chip (reopen, Go, dismissal, phone, leaks, axe) -│ ├── desktop-seams.spec.ts # Desktop-flag build: no /privacy request, X post as a link card, no X request (desktop project) +│ ├── desktop-seams.spec.ts # Desktop static export: every request answers, no web-only route or /privacy request, X post as a link card (desktop project) │ ├── toc-sidebar.spec.ts # TOC rendering + scroll-to-heading │ ├── toc-drag.spec.ts # TOC drag-and-drop reorder + level change │ ├── tabs.spec.ts # Tab bar: regenerate, Mod+Shift+R on the Playground aligns right, Alt+/ › Regenerate Playground (Playground only), new tab, close-all @@ -313,20 +314,23 @@ PWA_BASE_URL=http://localhost:3847 CI= bun run test:pwa Offline is simulated with `context.setOffline(true)`, which also cuts the worker's own fetches in Chromium. Unit tests for the routing rules live in `tests/unit/lib/pwa-sw-routing.test.ts`. -### Desktop-flag build +### Desktop renderer (static export) | Test | Project | Validates | |------|---------|-----------| -| `desktop-seams.spec.ts` | `desktop` (production build with `NEXT_PUBLIC_APP_TARGET=desktop`) | `/about` and the editor never request `/privacy` (the Privacy links go to the website's page in a new window); a pasted X post renders as the static link card, its button opens the post in a new window, and nothing is requested from X's hosts or loads `widgets.js` | +| `desktop-seams.spec.ts` | `desktop` (the desktop static export, `bun run build:desktop`, served with the `app://` protocol handler's path rules) | Every same-origin request the renderer makes on `/about`, a client navigation to `/` and a synced editor answers (pages as `.html`, RSC `.txt` payloads and segment prefetches, `/icon` as `image/png`), and none goes to a web-only route (manifest, Open Graph image, Apple icon, sitemap, robots, `/api`, `/privacy`, `/offline`); `/about` and the editor never request `/privacy` (the Privacy links go to the website's page in a new window); a pasted X post renders as the static link card, its button opens the post in a new window, and nothing is requested from X's hosts or loads `widgets.js` | -Prefetch runs only in production builds, so this needs one. Use free ports and localhost only: +Prefetch runs only in production builds, so this runs on the export. Nightly runs it on Linux (`desktop-renderer` in `nightly.yml`), where releases build the renderer (#103). Use free ports and localhost only: ```bash -NEXT_PUBLIC_APP_TARGET=desktop NEXT_PUBLIC_HOCUS_URL=ws://127.0.0.1:1296 bun run build && PORT=3849 bun run start +NEXT_PUBLIC_HOCUS_URL=ws://127.0.0.1:1296 bun run build:desktop +PORT=3849 bun scripts/serve-desktop-export.ts HOCUS_PORT=1296 HOCUS_THROTTLE=0 HOCUS_ALLOW_ISOLATED_TABS_DOCS=1 bun run hocus -DESKTOP_BASE_URL=http://localhost:3849 CI= bun playwright test --project=desktop +DESKTOP_BASE_URL=http://127.0.0.1:3849 CI= bun playwright test --project=desktop ``` +`bun run build:desktop` parks the web-only metadata files and pages for the build, puts them back, and fails if a web-only route, a web metadata tag or the Windows segment layout reaches `out/`. Its parking rules are unit tested in `tests/unit/scripts/desktop-export.test.ts`, the path rules in `tests/unit/desktop/export-paths.test.ts`, and the desktop build never registering the service worker in `tests/unit/components/service-worker-registration.test.ts`. + The web behaviour with the flag off, and the flag-on branches, are unit tested in `tests/unit/extensions/x-link-card.test.ts`, `tests/unit/helpers/media-embed.test.ts` and `tests/unit/components/privacy-link.test.tsx`. Manual install checklist (localhost production build): From 226e2e2b4218635e8d9bc47eb221b1bd289f8bd8 Mon Sep 17 00:00:00 2001 From: Harvey Date: Tue, 17 Nov 2026 13:22:05 +0330 Subject: [PATCH 5/6] fix(desktop): skip Next's type pass in the desktop export After a next dev run, .next/dev/types imports the /privacy and /offline pages, which the export parks, so the export failed its type check. bun run typecheck already checks every file, desktop ones included. --- docs/superpowers/specs/2026-11-15-desktop-architecture.md | 2 +- next.config.ts | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/superpowers/specs/2026-11-15-desktop-architecture.md b/docs/superpowers/specs/2026-11-15-desktop-architecture.md index 226d8f73..09cf881f 100644 --- a/docs/superpowers/specs/2026-11-15-desktop-architecture.md +++ b/docs/superpowers/specs/2026-11-15-desktop-architecture.md @@ -140,7 +140,7 @@ desktop/ - X posts render as a static link card: the kit's `x` node stays in the schema, so documents with X posts stay valid and a web client still embeds them, but its node view is replaced, so no oEmbed request and no `widgets.js` (`extensions/hyper-multimedia/x-link-card.ts`, #99). The spike's `X: false` would have dropped the node from the desktop schema. The card's stylesheet loads by `import()` inside the desktop branch: a static stylesheet import survives tree shaking and would ship to the web. - The Embed dialog neither lists nor accepts X; pasting an X URL into the document still makes the card (`use-media-embed.ts`, #99). - The service worker never registers: it precaches web-only pages (`SHELL_PATHS` has `/privacy`), and the renderer loads from disk (`components/pwa/service-worker-registration.tsx`, P2.4). - - **The export** (P2.4): `bun run build:desktop` (`scripts/build-desktop.ts`) writes `out/` and fails if a web-only route, a web metadata tag (`rel="manifest"`, `og:image`, `twitter:image`, `apple-touch-icon`, `href="/privacy"`) or a `__next.*` directory reaches it. Desktop routes: `/`, `/about`, `/_not-found`, `/icon`. + - **The export** (P2.4): `bun run build:desktop` (`scripts/build-desktop.ts`) writes `out/` and fails if a web-only route, a web metadata tag (`rel="manifest"`, `og:image`, `twitter:image`, `apple-touch-icon`, `href="/privacy"`) or a `__next.*` directory reaches it. Desktop routes: `/`, `/about`, `/_not-found`, `/icon`. It skips Next's own type pass (`typescript.ignoreBuildErrors` on desktop only): with web-only files parked, the route types a `next dev` run left in `.next/dev/types` import files that aren't there, and `bun run typecheck` already checks every file. - The `desktop` Playwright project runs on that export, served by `scripts/serve-desktop-export.ts` with the protocol handler's path rules (`desktop/shared/export-paths.ts`, which P2.5's handler reuses: `/about` → `about.html`, RSC `.txt` files under their exported names, `/icon` as `image/png`, unknown types and traversal refused). It checks that every request the renderer makes is answered and none goes to a web-only route, no request for `/privacy`, and none to X's hosts (`tests/e2e/desktop-seams.spec.ts`). Nightly runs it on Linux (`desktop-renderer`). - `next.config.ts` switches three things on that literal: `output: "export"`, `headers()` (web only), and `pageExtensions`: web `["web.tsx", "web.ts", "tsx", "ts"]`, desktop `["desktop.tsx", "tsx", "ts"]`. The web-only route handlers are `route.web.ts(x)`: `app/api/**`, `llms.txt`, `pwa-icons/[id]`. - **Web-only pages are parked, not renamed.** Next 16.4.6 drops the root layout's font preload from a `page.web.tsx`: `getPreloadableFonts` strips only the last extension, so it looks up `app/privacy/page.web` in a font manifest keyed `app/privacy/page`. Renaming `/privacy` and `/offline` would change their web HTML, so they join the parked metadata files below. diff --git a/next.config.ts b/next.config.ts index e4041bd9..3812094e 100644 --- a/next.config.ts +++ b/next.config.ts @@ -54,6 +54,10 @@ const nextConfig: NextConfig = { pageExtensions: isDesktop ? ["desktop.tsx", "tsx", "ts"] : ["web.tsx", "web.ts", "tsx", "ts"], + // The export type-checks a tree with web-only files parked, which the + // route types `next dev` generated (.next/dev/types) still import. + // `bun run typecheck` checks every file, desktop ones included. + ...(isDesktop ? { typescript: { ignoreBuildErrors: true } } : {}), // Next 16.4+ rewrites AGENTS.md when it detects a coding agent; that file // holds curated repo conventions, so keep it hand-maintained. agentRules: false, From 8496a306317f00bdcc01c5fefc97214e1ee1a967 Mon Sep 17 00:00:00 2001 From: Harvey Date: Tue, 17 Nov 2026 13:39:44 +0330 Subject: [PATCH 6/6] fix(desktop): export only in the desktop production build Under a desktop-target next dev the web metadata files aren't parked, and output: "export" made each of them a 500 that every page links. The config is now a phase function; the web config object is unchanged. --- .../specs/2026-11-15-desktop-architecture.md | 2 +- next.config.ts | 20 +++++++++++++------ 2 files changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/superpowers/specs/2026-11-15-desktop-architecture.md b/docs/superpowers/specs/2026-11-15-desktop-architecture.md index bf4e429a..b994cbe8 100644 --- a/docs/superpowers/specs/2026-11-15-desktop-architecture.md +++ b/docs/superpowers/specs/2026-11-15-desktop-architecture.md @@ -143,7 +143,7 @@ desktop/ - The service worker never registers: it precaches web-only pages (`SHELL_PATHS` has `/privacy`), and the renderer loads from disk (`components/pwa/service-worker-registration.tsx`, P2.4). - **The export** (P2.4): `bun run build:desktop` (`scripts/build-desktop.ts`) writes `out/` and fails if a web-only route, a web metadata tag (`rel="manifest"`, `og:image`, `twitter:image`, `apple-touch-icon`, `href="/privacy"`) or a `__next.*` directory reaches it. Desktop routes: `/`, `/about`, `/_not-found`, `/icon`. It skips Next's own type pass (`typescript.ignoreBuildErrors` on desktop only): with web-only files parked, the route types a `next dev` run left in `.next/dev/types` import files that aren't there, and `bun run typecheck` already checks every file. - The `desktop` Playwright project runs on that export, served by `scripts/serve-desktop-export.ts` with the protocol handler's path rules (`desktop/shared/export-paths.ts`, which P2.5's handler reuses: `/about` → `about.html`, RSC `.txt` files under their exported names, `/icon` as `image/png`, unknown types and traversal refused). It checks that every request the renderer makes is answered and none goes to a web-only route, no request for `/privacy`, and none to X's hosts (`tests/e2e/desktop-seams.spec.ts`). Nightly runs it on Linux (`desktop-renderer`). - - `next.config.ts` switches three things on that literal: `output: "export"`, `headers()` (web only), and `pageExtensions`: web `["web.tsx", "web.ts", "tsx", "ts"]`, desktop `["desktop.tsx", "tsx", "ts"]`. The web-only route handlers are `route.web.ts(x)`: `app/api/**`, `llms.txt`, `pwa-icons/[id]`. + - `next.config.ts` switches three things on that literal: `output: "export"` (in the production build phase only: under `next dev`, as in the `local` project, the metadata files aren't parked, and exporting would make each a 500 that every page links), `headers()` (web only), and `pageExtensions`: web `["web.tsx", "web.ts", "tsx", "ts"]`, desktop `["desktop.tsx", "tsx", "ts"]`. The web-only route handlers are `route.web.ts(x)`: `app/api/**`, `llms.txt`, `pwa-icons/[id]`. - **Web-only pages are parked, not renamed.** Next 16.4.6 drops the root layout's font preload from a `page.web.tsx`: `getPreloadableFonts` strips only the last extension, so it looks up `app/privacy/page.web` in a font manifest keyed `app/privacy/page`. Renaming `/privacy` and `/offline` would change their web HTML, so they join the parked metadata files below. - **S1 (2026-11-16):** Turbopack honours `pageExtensions` for `page` and `route` files but not for metadata files: in the web build `sitemap.web.ts` became the route `/sitemap.web`. So `sitemap`, `robots`, `opengraph-image`, `manifest` and `apple-icon` keep their plain names, and a prebuild step moves them out of `app/` for the desktop build and puts them back (the overlay fallback). - It parks them inside the checkout, in `.desktop-export-parked/` (gitignored): a rename across drives fails with `EXDEV` on Windows runners (#111, proved on `windows-latest` with the default temp dir). Before moving anything it puts back files that an interrupted run left parked, and it puts them back in `finally` and on SIGINT or SIGTERM. A file both in `app/` and parked stops the build. diff --git a/next.config.ts b/next.config.ts index 3812094e..6990e9fd 100644 --- a/next.config.ts +++ b/next.config.ts @@ -2,6 +2,7 @@ import { execSync } from "node:child_process"; import { readFileSync } from "node:fs"; import type { NextConfig } from "next"; +import { PHASE_PRODUCTION_BUILD } from "next/constants"; import { GA_MEASUREMENT_ID } from "./lib/analytics-config"; import { buildContentSecurityPolicy } from "./lib/security/content-security-policy"; @@ -46,11 +47,10 @@ const nextConfig: NextConfig = { // branches; an unset NEXT_PUBLIC_* stays a runtime lookup. NEXT_PUBLIC_APP_TARGET: process.env.NEXT_PUBLIC_APP_TARGET ?? "web", }, - // Desktop is a static export loaded from app://tinydocy. Web-only route - // handlers are `route.web.ts(x)`, which the desktop extensions don't - // match; `*.desktop.tsx` is the desktop-only counterpart. Web-only pages - // and metadata files are parked instead (scripts/desktop-export.ts). - ...(isDesktop ? { output: "export" as const } : {}), + // Web-only route handlers are `route.web.ts(x)`, which the desktop + // extensions don't match; `*.desktop.tsx` is the desktop-only + // counterpart. Web-only pages and metadata files are parked instead + // (scripts/desktop-export.ts). pageExtensions: isDesktop ? ["desktop.tsx", "tsx", "ts"] : ["web.tsx", "web.ts", "tsx", "ts"], @@ -97,4 +97,12 @@ async function webHeaders() { ]; } -export default nextConfig; +// Desktop is a static export loaded from app://tinydocy. Only the build +// exports: under `next dev` (the `local` Playwright project) the web +// metadata files aren't parked, and `output: "export"` would make each of +// them a 500 that every page links. +export default function config(phase: string): NextConfig { + return isDesktop && phase === PHASE_PRODUCTION_BUILD + ? { ...nextConfig, output: "export" } + : nextConfig; +}