Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
perf(shell): take hidden app artwork off the layout and paint path (#167)
Abdurrahman Fakhrul8599afa6494d
diff --git a/app/globals.css b/app/globals.cssindex 75c8ecb2..c7f87bbb 100644--- a/app/globals.css+++ b/app/globals.css@@ -323,7 +323,9 @@ body {.shell-platform-mark {border-radius: inherit;}-.shell-artwork-macos, .shell-artwork-windows { display: none; }+/* Markup keeps all three variants (the shell family is hydration-only knowledge, so+ SSR choosing would mismatch); the losers stay out of layout and paint. */+.shell-artwork-macos, .shell-artwork-windows { display: none; content-visibility: hidden; }[data-shell="macos"] .shell-artwork-default,[data-shell="ios"] .shell-artwork-default,[data-shell="windows"] .shell-artwork-default,diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex e474820c..ea11412b 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -13,6 +13,7 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh**Faster**+- `shell` take hidden app artwork off the layout and paint path- close two eager leaks, cancel the island plan, budget from arithmetic- `app-store` load RuntimeApp lazily so vaul leaves the first-load chunkdiff --git a/docs/MIGRATION-GATE-PLAN.md b/docs/MIGRATION-GATE-PLAN.mdnew file mode 100644index 00000000..9b70a10f--- /dev/null+++ b/docs/MIGRATION-GATE-PLAN.md@@ -0,0 +1,88 @@+# Migration gate plan (aligned with docs/MSO-MIGRATION.md)++Written before implementation. The migration doc is the authority: it says do NOT rewrite+before the §3 gate, and §3 is an ordered list of cheap in-tree wins. So this branch does the+gate work, not a framework swap.++## What the other agent already landed on main++- `c795f0b` Phase 0 instrumentation: `perf:probe`, `perf:check`, `perf:tasks`, `perf:apps`,+ `perf:hydration`, `scripts/perf-budget.json`, `scripts/perf-baseline.json`.+- `6c8933c` hydration mark chain, and the retraction of the "LCP is paint-bound" claim.+- Conclusion now recorded: LCP is hydration-bound to ~942 KB first-load JS; TBT 164 ms is+ already at the post-migration target.++## My own regression to fix first++`lib/agent/session-compact-now.ts` (shipped in #166) imported `next/server`, which violated+the Phase 2 exit criterion "zero `next/*` imports in `lib/`".++**Superseded while this branch was in review.** Commit `c846bc7` on `main` fixed the same+debt for every `lib/` file by switching `NextResponse` to the platform `Response`. That is+the better fix, so my version (moving the route shape into `app/`) was dropped during the+rebase rather than merged as a second, competing shape. Nothing of mine remains in that+area, and the criterion is now met upstream.++## §3 items, cheapest first++| # | Item | Concretely | Status |+|---|---|---|---|+| G-1 | Shrink the eager graph and lock a measured baseline | done upstream by `e8cddb3`: arithmetic budget (initial 290819, entry 158149, css 31319 from a measured floor + 2% headroom), and the 250 KiB target demoted to a post-migration goal | landed upstream, not here |+| G-2 | Keep app artwork off the LCP critical path | hidden platform variants taken out of layout/paint; markup untouched | landed here |+| G-3 | Cut shell mount cost | done upstream by `e8cddb3` and `9d2dc93` (two eager leaks closed); the Svelte island spike was also run and cancelled there | landed upstream, not here |+| G-4 | Phase 2 debt: zero `next/*` in `lib/` | done upstream by `c846bc7` (Response instead of NextResponse); my duplicate attempt was dropped | landed upstream, not here |++### Why this branch only carries G-2++While it was open, `main` moved three times and each move landed a piece of §3 more+thoroughly than this branch had:++- `c846bc7` fixed the `lib/` framework debt for every file at once (platform `Response`+ instead of `NextResponse`), which is better than moving route shapes into `app/`.+- `9d2dc93` and `e8cddb3` closed two eager leaks and rebuilt the bundle budget from a+ measured framework floor plus 2% headroom, and demoted the 250 KiB figure to a+ post-migration goal. That is the honest version of the item I had marked blocked.+- `e8cddb3` also ran the Svelte island spike and cancelled it on measurement.++So the duplicate work was dropped during rebase rather than merged as a competing+second shape. What remains here is the one item upstream had not touched: the hidden app+artwork variants that still pay layout and paint cost on every app tile.++### G-2 evidence++`frontend/slices/os-shell/brand-marks.tsx` renders three artwork variants per app (15 apps,+496 KB of WebP under `public/app-icons`), two of which CSS always hides. The markup cannot+choose one: the shell family is only known after hydration, and choosing at SSR risks a+hydration mismatch for a decorative image. What it can do without guessing is stop the+hidden variants from doing layout and paint work, so `globals.css` uses+`content-visibility: hidden` for the hidden variants and restores `visible` when the+matching `[data-shell]` rule makes one of them shown. `loading="lazy"` was deliberately NOT+used: the iOS/macOS variant is the mobile LCP element, and demoting it would trade one+regression for another.++**What is measured and what is not.** The bundle is unchanged (882.0 KiB raw / 281.0 KiB+gzip; css 30.0 KiB gzip), so this changes layout and paint work, not bytes. The LCP mark+chain was run against the live `:4005` service, which still serves the pre-change build:++```+desktop fcp 1184ms mounted 2607ms icons 3191ms lcp 3252ms (SPAN) js 941.7KB+mobile fcp 1152ms mounted 2585ms icons 3002ms lcp 3040ms (IMG) js 925.5KB+```++Those numbers describe the old build, so they cannot be presented as the effect of this+change. What they do show is that `icons` (the artwork paint step) still lands before LCP+on both surfaces, i.e. the step this change touches is on the measured path. Attributing a+delta would require measuring the deployed build, and this branch is not deployed.++## Rules I hold myself to++- No user-visible UX change. No second login, cookie domain, or dropped deep link.+- No ratchet raised. `filesOver220`, `serverFrontendImports`, cycles stay equal or lower.+- Every claimed improvement is a measurement, not a vibe. If a number cannot be measured+ on this host, say so instead of quoting one.+- Do not quote the migration doc's numbers as mine; re-measure or label them as quoted.++## Gate++Targeted tests, `check-architecture`, `check-docs`, `pr-preflight --local`,+`pr-preflight --security`, `perf:check` where it applies, then a draft PR.diff --git a/docs/README.md b/docs/README.mdindex b0f5a250..dc268e53 100644--- a/docs/README.md+++ b/docs/README.md@@ -121,6 +121,7 @@ source comments. They are **not current implementation contracts**.| [`DRAWER-MENU-BYOK-PLAN.md`](./DRAWER-MENU-BYOK-PLAN.md) | Historical implementation plan; phases A–C and OpenAI Codex D1 shipped; remaining ideas are not promises || [`OS-SETTINGS-ICON-UPDATE-DEVICE-PLAN.md`](./OS-SETTINGS-ICON-UPDATE-DEVICE-PLAN.md) | **Open plan, not implemented**: auto-update opt-in, stable channel, Devices/Server merge, account icon picker, upload→WebP/ICO pipeline || [`MSO-MIGRATION.md`](./MSO-MIGRATION.md) | **Open plan, not implemented**: measured baseline plus phased Next→Svelte/Bun/Rust migration with a decision gate before any rewrite |+| [`MIGRATION-GATE-PLAN.md`](./MIGRATION-GATE-PLAN.md) | Executed migration-gate work: which §3 items landed with measurements, which were blocked and why, and the `lib/` framework-import debt |## Marketing/demo collateraldiff --git a/frontend/slices/os-shell/brand-marks.tsx b/frontend/slices/os-shell/brand-marks.tsxindex 868f0991..8a64f7a4 100644--- a/frontend/slices/os-shell/brand-marks.tsx+++ b/frontend/slices/os-shell/brand-marks.tsx@@ -22,14 +22,20 @@ function officialMark(src: string): AppIconComponent {function platformMark(fallback: string, macos: string, windows: string): AppIconComponent {const Mark: AppIconComponent = ({ className: cls }) => {const size = cls ?? "size-full";+ // All three variants are in the markup because the shell family is only known+ // after hydration (SSR would guess, and a guess here is a hydration mismatch).+ // What the markup CAN say without guessing: these are decorative. So the hidden+ // variants are low priority and never blocking, and the visible one is decoded+ // asynchronously. The download itself is left to the browser: `loading="lazy"`+ // here would demote the very image mobile measures LCP on.return (<span className={`shell-platform-mark relative block ${size}`} aria-hidden>{/* eslint-disable-next-line @next/next/no-img-element */}- <img src={fallback} alt="" className="shell-artwork shell-artwork-default" draggable={false} decoding="async" />+ <img src={fallback} alt="" className="shell-artwork shell-artwork-default" draggable={false} decoding="async" fetchPriority="low" />{/* eslint-disable-next-line @next/next/no-img-element */}- <img src={macos} alt="" className="shell-artwork shell-artwork-macos" draggable={false} decoding="async" />+ <img src={macos} alt="" className="shell-artwork shell-artwork-macos" draggable={false} decoding="async" fetchPriority="low" />{/* eslint-disable-next-line @next/next/no-img-element */}- <img src={windows} alt="" className="shell-artwork shell-artwork-windows" draggable={false} decoding="async" />+ <img src={windows} alt="" className="shell-artwork shell-artwork-windows" draggable={false} decoding="async" fetchPriority="low" /></span>);};