Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions .github/workflows/nightly.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
#
Expand Down Expand Up @@ -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:
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
37 changes: 37 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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?<hash>` 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).

### Desktop P2.1b: `local-session`, the batcher and `MemoryDocStore`

The second half of desktop plan P2.1: the platform-neutral storage path that
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down Expand Up @@ -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`). |
Expand Down
File renamed without changes.
2 changes: 2 additions & 0 deletions app/icon.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand Down
File renamed without changes.
File renamed without changes.
7 changes: 5 additions & 2 deletions components/pwa/service-worker-registration.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
87 changes: 87 additions & 0 deletions desktop/shared/export-paths.ts
Original file line number Diff line number Diff line change
@@ -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<string, string> = {
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<string, string> = {
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/<rel>` 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;
}
10 changes: 7 additions & 3 deletions docs/superpowers/specs/2026-11-15-desktop-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -140,10 +140,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`. 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"` (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: 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 `<link rel="manifest">`, 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.<segment>/__PAGE__.txt` instead of `__next.<segment>.__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/`).
Expand Down
Loading
Loading