@arcote.tech/arc-cli 0.8.3 → 0.8.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcote.tech/arc-cli",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "CLI tool for Arc framework",
   "module": "index.ts",
   "main": "dist/index.js",
@@ -12,13 +12,13 @@
     "build": "bun build --target=bun ./src/index.ts --outdir=dist --external @arcote.tech/arc --external @arcote.tech/arc-ds --external @arcote.tech/arc-react --external @arcote.tech/platform --external @arcote.tech/arc-map --external '@opentelemetry/*' && chmod +x dist/index.js"
   },
   "dependencies": {
-    "@arcote.tech/arc": "^0.8.3",
-    "@arcote.tech/arc-ds": "^0.8.3",
-    "@arcote.tech/arc-react": "^0.8.3",
-    "@arcote.tech/arc-host": "^0.8.3",
-    "@arcote.tech/arc-adapter-db-sqlite": "^0.8.3",
-    "@arcote.tech/arc-adapter-db-postgres": "^0.8.3",
-    "@arcote.tech/arc-otel": "^0.8.3",
+    "@arcote.tech/arc": "^0.8.5",
+    "@arcote.tech/arc-ds": "^0.8.5",
+    "@arcote.tech/arc-react": "^0.8.5",
+    "@arcote.tech/arc-host": "^0.8.5",
+    "@arcote.tech/arc-adapter-db-sqlite": "^0.8.5",
+    "@arcote.tech/arc-adapter-db-postgres": "^0.8.5",
+    "@arcote.tech/arc-otel": "^0.8.5",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/api-logs": "^0.57.0",
     "@opentelemetry/core": "^1.30.0",
@@ -31,8 +31,8 @@
     "@opentelemetry/sdk-trace-base": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
     "@opentelemetry/semantic-conventions": "^1.27.0",
-    "@arcote.tech/platform": "^0.8.3",
-    "@arcote.tech/arc-map": "^0.8.3",
+    "@arcote.tech/platform": "^0.8.5",
+    "@arcote.tech/arc-map": "^0.8.5",
     "@clack/prompts": "^0.9.0",
     "commander": "^11.1.0",
     "chokidar": "^3.5.3",

package/src/builder/module-builder.ts

@@ -840,10 +840,14 @@ export interface BrowserGroupEntry {
   readonly hash: string;
   /** Module names registered by this group (for manifest filterability). */
   readonly modules: readonly string[];
+  /** Shared chunks this entry statically imports (transitive closure). The
+   *  server `<link rel=modulepreload>`s them so the browser fetches them in
+   *  parallel with the entry instead of discovering them after parse. */
+  readonly staticChunks: readonly string[];
 }
 
 export interface BrowserAppResult {
-  readonly initial: { file: string; hash: string };
+  readonly initial: { file: string; hash: string; staticChunks: readonly string[] };
   /** Keyed by token.name. `initial` is NOT here — it's separate. */
   readonly groups: Record<string, BrowserGroupEntry>;
   /** Auto-shared chunks emitted by Bun.build splitting. Public, unsigned. */
@@ -859,6 +863,33 @@ interface BrowserOutFile {
   bytes: Uint8Array;
 }
 
+/** Statyczne `import"./chunk-x.js"` / `from"./chunk-x.js"` (NIE `import(...)`). */
+const STATIC_CHUNK_IMPORT =
+  /(?:^|[;}\s])import\s*["']\.\/(chunk-[a-z0-9]+\.js)["']|from\s*["']\.\/(chunk-[a-z0-9]+\.js)["']/g;
+
+/** Tranzytywne domknięcie shared-chunków statycznie importowanych przez entry
+ *  — z bajtów w pamięci. `chunkBytes` = nazwa chunku → bajty. */
+function staticChunkClosure(
+  entryBytes: Uint8Array,
+  chunkBytes: Map<string, Uint8Array>,
+): string[] {
+  const seen = new Set<string>();
+  const stack: Uint8Array[] = [entryBytes];
+  while (stack.length) {
+    const src = Buffer.from(stack.pop()!).toString("utf8");
+    STATIC_CHUNK_IMPORT.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = STATIC_CHUNK_IMPORT.exec(src))) {
+      const chunk = m[1] ?? m[2]!;
+      if (seen.has(chunk)) continue;
+      seen.add(chunk);
+      const b = chunkBytes.get(chunk);
+      if (b) stack.push(b);
+    }
+  }
+  return [...seen];
+}
+
 // ---------------------------------------------------------------------------
 // Build stats (ARC_BUILD_STATS=1) — rozbicie każdego chunku na biblioteki.
 //
@@ -1343,24 +1374,34 @@ export async function buildBrowserApp(
   // their name (Bun auto-emits `chunk-<hash>.js`); we leave those alone.
   let initialFile = "";
   let initialHash = "";
+  let initialStaticChunks: string[] = [];
   const groups: Record<string, BrowserGroupEntry> = {};
   const sharedChunks: string[] = [];
 
+  // Nazwa chunku → bajty (do policzenia per-wejście domknięcia importów).
+  const chunkBytes = new Map<string, Uint8Array>();
+  for (const out of outFiles) {
+    if (out.kind === "chunk") chunkBytes.set(out.name, out.bytes);
+  }
+
   for (const out of outFiles) {
     if (out.kind === "entry-point") {
       const hash = sha256Hex(out.bytes).slice(0, 16);
       const stem = out.name.replace(/\.js$/, "");
       const finalName = `${stem}.${hash}.js`;
       writeFileSync(join(outDir, finalName), out.bytes);
+      const staticChunks = staticChunkClosure(out.bytes, chunkBytes);
 
       if (stem === "initial") {
         initialFile = finalName;
         initialHash = hash;
+        initialStaticChunks = staticChunks;
       } else {
         groups[stem] = {
           file: finalName,
           hash,
           modules: groupModuleMap.get(stem) ?? [],
+          staticChunks,
         };
       }
     } else if (out.kind === "chunk") {
@@ -1402,7 +1443,7 @@ export async function buildBrowserApp(
   }
 
   const manifest: BrowserAppResult = {
-    initial: { file: initialFile, hash: initialHash },
+    initial: { file: initialFile, hash: initialHash, staticChunks: initialStaticChunks },
     groups,
     sharedChunks,
     cached: false,

package/src/builder/seed-guard.ts

@@ -0,0 +1,143 @@
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join, relative, sep } from "path";
+
+import type { WorkspacePackage } from "./module-builder";
+
+// ---------------------------------------------------------------------------
+// Seed leak guard
+//
+// `aggregate(...).seedWith([...])` / `.withSeeds([...])` przekazuje dane seed
+// jako ZWYKŁY argument-literał. Element wchodzi do modułu przez `context([...])`,
+// a build przeglądarki importuje CAŁY moduł (`import "${pkg.name}"`). Kasowanie
+// kodu serwerowego z bundla klienta stoi wyłącznie na `define ONLY_SERVER:"false"`
+// → składa `ONLY_SERVER && (...)` / `ONLY_SERVER ? ... : ...` do martwej gałęzi
+// → minify DCE. Argument seedWith NIE jest owinięty niczym, więc literał (często
+// dane referencyjne, konta serwisowe, sekrety w wierszach) PRZEŻYWA i ląduje
+// w PUBLICZNYM bundlu przeglądarki. Seedy czyta wyłącznie host (`runSeeds()`),
+// po stronie klienta nie mają żadnego zastosowania — czysty wyciek.
+//
+// Gejt wywołania to WARUNEK KONIECZNY (ten guard go egzekwuje), ale to, gdzie
+// fizycznie leży treść seeda, decyduje czy bajty realnie znikają. Zweryfikowane
+// empirycznie (migracja ndt+bmf, grep bundla klienta):
+//
+//   // mały seed — inline w gejtowanym literale (ZAWSZE działa: constant-fold):
+//   .seedWith(ONLY_SERVER ? [ { /* wiersze */ } ] : [])
+//
+//   // duży seed / osobny plik — gejtowany DYNAMICZNY import (jedyny niezawodny):
+//   const s = ONLY_SERVER ? await import("./seeds") : ({} as typeof import("./seeds"));
+//   ... .seedWith(ONLY_SERVER ? [...s.rows] : [])
+//
+// UWAGA (pułapki, MIMO gejtu wywołania treść zostaje w kliencie):
+//  - STATYCZNY `import * as`/`import` osobnego modułu seed — arc wymusza
+//    `sideEffects:true` na pakietach workspace, więc moduł bywa zatrzymany „dla
+//    side-effectów" (namespace = cały; nieczysty top-level `id.parse()`/`new Date()`).
+//    Named-import czystego modułu BYWA zdrzewkowany, ale nie polegaj na tym.
+//  - ZMIENNE POŚREDNIE z danymi (`const SEED_EMAIL = "…"`, `const rows = [...]`)
+//    w ciele modułu/funkcji — const referencjonowany tylko w martwej gałęzi i tak
+//    się bundluje. Wpisuj wartości WPROST w gejtowany literał lub ładuj dynamicznie.
+//
+// Ten guard to TWARDA bramka builda: skanuje źródła i wywala build, gdy
+// `.seedWith(`/`.withSeeds(` nie jest owinięte `ONLY_SERVER`. Rusza w Phase 0
+// `buildAll` (obok assertOneModulePerPackage) — NAJWCZEŚNIEJ, przed drogim
+// buildem serwera i access-extractorem, żeby fail był szybki i czytelny.
+// Skan idzie po ŹRÓDLE (nie po cache), więc łapie też stary niezgejtowany kod,
+// którego hash się nie zmienił.
+// ---------------------------------------------------------------------------
+
+/** Wywołanie `.seedWith(` / `.withSeeds(` (dowolne białe znaki wokół `(`). */
+const CALL = /\.(?:seedWith|withSeeds)\s*\(/g;
+/** To samo wywołanie, ale poprawnie zgejtowane `ONLY_SERVER` jako pierwszy token. */
+const GATED = /^\.(?:seedWith|withSeeds)\s*\(\s*ONLY_SERVER\b/;
+
+export interface SeedLeak {
+  /** Ścieżka względem rootDir, POSIX-owe separatory. */
+  relpath: string;
+  line: number;
+  snippet: string;
+}
+
+function walkTsFiles(dir: string, out: string[]): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === "node_modules" || entry.name === "dist") continue;
+    const abs = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "__tests__") continue;
+      walkTsFiles(abs, out);
+    } else if (entry.isFile() && /\.(ts|tsx)$/.test(entry.name) && !entry.name.endsWith(".d.ts")) {
+      out.push(abs);
+    }
+  }
+}
+
+/** Skanuje `src/` każdego pakietu i zwraca niezgejtowane wywołania seedWith. */
+export function findUngatedSeeds(
+  pkgs: readonly WorkspacePackage[],
+  rootDir: string,
+): SeedLeak[] {
+  const leaks: SeedLeak[] = [];
+  const scanned = new Set<string>();
+
+  for (const pkg of pkgs) {
+    const srcDir = join(pkg.path, "src");
+    if (scanned.has(srcDir) || !existsSync(srcDir)) continue;
+    scanned.add(srcDir);
+
+    const files: string[] = [];
+    walkTsFiles(srcDir, files);
+
+    for (const abs of files) {
+      const content = readFileSync(abs, "utf-8");
+      CALL.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      while ((m = CALL.exec(content)) !== null) {
+        const rest = content.slice(m.index);
+        if (GATED.test(rest)) continue;
+
+        // Odsiej wzmianki w komentarzu liniowym (`// … .seedWith(…)`).
+        const lineStart = content.lastIndexOf("\n", m.index) + 1;
+        if (content.slice(lineStart, m.index).includes("//")) continue;
+
+        // Odsiej wzmianki w komentarzu blokowym / JSDoc (`/** … .seedWith() … */`):
+        // wewnątrz bloku, gdy ostatni `/*` przed trafieniem nie został jeszcze
+        // zamknięty przez `*/`.
+        const before = content.slice(0, m.index);
+        if (before.lastIndexOf("/*") > before.lastIndexOf("*/")) continue;
+
+        const nlAfter = content.indexOf("\n", m.index);
+        const lineEnd = nlAfter === -1 ? content.length : nlAfter;
+        const line = content.slice(0, m.index).split("\n").length;
+        const relpath = relative(rootDir, abs).split(sep).join("/");
+        leaks.push({
+          relpath,
+          line,
+          snippet: content.slice(lineStart, lineEnd).trim().slice(0, 120),
+        });
+      }
+    }
+  }
+
+  return leaks;
+}
+
+/** Twardy fail builda przeglądarki, jeśli jakikolwiek seed nie jest server-gated. */
+export function assertSeedsServerGated(
+  pkgs: readonly WorkspacePackage[],
+  rootDir: string,
+): void {
+  const leaks = findUngatedSeeds(pkgs, rootDir);
+  if (leaks.length === 0) return;
+
+  const lines = leaks
+    .map((l) => `  • ${l.relpath}:${l.line}\n      ${l.snippet}`)
+    .join("\n");
+
+  throw new Error(
+    `Seed leak do bundla klienta: ${leaks.length} wywołań .seedWith(...)/.withSeeds(...) ` +
+      `nie jest owiniętych w ONLY_SERVER.\n\n${lines}\n\n` +
+      `Dane seed czyta wyłącznie host (runSeeds) — po stronie klienta są zbędne i ` +
+      `wyciekają do PUBLICZNEGO bundla przeglądarki. Zgejtuj argument w miejscu:\n` +
+      `  .seedWith(ONLY_SERVER ? [ /* wiersze */ ] : [])\n` +
+      `  .seedWith(ONLY_SERVER ? (await import("./seeds.server")).rows : [])\n` +
+      `Statyczny import z osobnego pliku NIE pomaga (build wymusza sideEffects:true).`,
+  );
+}

package/src/deploy/bootstrap.ts

@@ -62,7 +62,11 @@ export interface BootstrapInputs {
   cliVersion: string;
   /** sha256 of deploy.arc.json — used for the remote state marker. */
   configHash: string;
-  /** Force the ansible run even when the host is already bootstrapped. */
+  /**
+   * `--force-bootstrap`: wymusza PEŁNY bootstrap mimo markera „ready" —
+   * zarówno Ansible, jak i upStack (re-render + wgranie Caddyfile/compose).
+   * Escape hatch po ręcznych edycjach hosta albo gdy marker się rozjechał.
+   */
   forceAnsible?: boolean;
 }
 
@@ -137,6 +141,17 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
     ok("Host bootstrapped");
   }
 
+  // Hash wyrenderowanych artefaktów stacku (Caddyfile + compose). Wykrywa
+  // zmianę GENERATORA w obrębie tej samej wersji CLI — bez tego republish tej
+  // samej wersji z poprawionym Caddyfile (np. dodane `encode`) NIE odświeżał
+  // configu na hoście (obraz aplikacji i tak leci co deploy, ale upStack był
+  // pomijany). Marker bez `artifactsHash` (starszy deploy) → undefined ≠ hash
+  // → jednorazowy upStack, po którym marker dostaje hash.
+  const artifactsHash = new Bun.CryptoHasher("sha256")
+    .update(generateCaddyfile(cfg))
+    .update(generateCompose({ cfg }))
+    .digest("hex");
+
   // Force upStack whenever:
   //   - stack isn't fully ready, OR
   //   - marker is missing (legacy v0.5 deploy with no .arc-state.json), OR
@@ -144,6 +159,9 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
   //   - the CLI version changed (generators evolve — compose/Caddyfile/
   //     observability configs must be re-rendered + re-uploaded even when
   //     deploy.arc.json itself is unchanged), OR
+  //   - the RENDERED artifacts differ (generator changed within same CLI
+  //     version — e.g. republished patch), OR
+  //   - `--force-bootstrap` (wymusza pełny bootstrap, nie tylko Ansible), OR
   //   - registry container isn't running (e.g. legacy stack predates v0.7)
   // Without this, an old v0.5 stack (no registry container) is classified as
   // "ready" and bootstrap is skipped — then `docker login` on the next step
@@ -153,6 +171,8 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
     state.marker === null ||
     state.marker.configHash !== inputs.configHash ||
     state.marker.cliVersion !== inputs.cliVersion ||
+    state.marker.artifactsHash !== artifactsHash ||
+    inputs.forceAnsible === true ||
     !(await isRegistryRunning(cfg));
 
   if (needUpStack) {
@@ -180,6 +200,7 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
   await writeStateMarker(cfg.target, {
     cliVersion: inputs.cliVersion,
     configHash: inputs.configHash,
+    artifactsHash,
     updatedAt: new Date().toISOString(),
   });
 }
@@ -393,6 +414,19 @@ async function upStack(inputs: BootstrapInputs): Promise<void> {
     `cd ${cfg.target.remoteDir} && docker compose pull --ignore-pull-failures caddy registry && docker compose up -d caddy registry`,
   );
 
+  // KRYTYCZNE: Caddyfile jest bind-mountowany (`:ro`), a `docker compose up -d`
+  // NIE recreatuje kontenera gdy zmienia się tylko TREŚĆ pliku (spec kontenera
+  // bez zmian) — Caddy dalej serwuje config wczytany przy starcie. Generowany
+  // Caddyfile ma `admin off`, więc `caddy reload` (admin API) też odpada.
+  // Bez restartu upStack wgrywał nowy Caddyfile (np. świeżo dodane `encode`),
+  // ale efekt był ZEROWY do najbliższego ręcznego restartu. `restart` wczytuje
+  // config od nowa (certy TLS są w wolumenie → bez re-issuance). Odpala się
+  // tylko w upStack, czyli gdy config faktycznie się zmienił — ~1s przestoju.
+  await assertExec(
+    cfg.target,
+    `cd ${cfg.target.remoteDir} && docker compose restart caddy`,
+  );
+
   // Wait for the registry vhost to respond (Caddy ACME issuance takes a few
   // seconds on first start), then docker login on the host. This caches
   // credentials in /home/<user>/.docker/config.json so subsequent `docker

package/src/deploy/remote-state.ts

@@ -24,6 +24,15 @@ export type RemoteState =
 export interface RemoteStateMarker {
   cliVersion: string;
   configHash: string;
+  /**
+   * sha256 wyrenderowanych artefaktów stacku (Caddyfile + docker-compose).
+   * Wykrywa zmianę GENERATORA w obrębie tej samej wersji CLI — bez tego
+   * republish tej samej wersji z poprawionym Caddyfile (np. dodane `encode`)
+   * nie odświeżał configu na hoście (needUpStack patrzył tylko na cliVersion
+   * i configHash). Opcjonalny: starsze markery go nie mają → traktowane jako
+   * zmiana (wymusza jednorazowy upStack, po którym marker dostaje hash).
+   */
+  artifactsHash?: string;
   updatedAt: string;
 }
 

package/src/platform/server.ts

@@ -8,7 +8,7 @@ import {
   type ArcServer,
 } from "@arcote.tech/arc-host";
 import { timingSafeEqual } from "crypto";
-import { existsSync, mkdirSync } from "fs";
+import { existsSync, mkdirSync, readFileSync } from "fs";
 import { join } from "path";
 import { readTranslationsConfig } from "../i18n";
 import { err, ok, type BuildManifest, type WorkspaceInfo } from "./shared";
@@ -125,19 +125,104 @@ async function resolveDbAdapterFactory(dbPath: string) {
 // Shell HTML
 // ---------------------------------------------------------------------------
 
-export function generateShellHtml(
-  appName: string,
-  manifest?: { title: string; favicon?: string },
-  initial?: { file: string; hash: string },
-  stylesHash?: string,
-  shell?: {
-    imports: Readonly<Record<string, string>>;
-    peers: Readonly<Record<string, string>>;
-  },
+/** Escape a JSON string for safe inlining inside `<script>` (prevents an
+ *  embedded `</script>` or `<!--` from breaking out of the element). */
+function inlineJson(value: unknown): string {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    // U+2028/U+2029 są terminatorami linii w JS — zepsułyby inline <script>.
+    .replace(/[\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16)}`);
+}
+
+/** Decode every `arc_token*` cookie in a Cookie header to token payloads (JWT
+ *  decoded WITHOUT verification — same as `/api/modules` manifest filtering;
+ *  runtime API calls re-verify). Lets the server personalize the HTML shell. */
+function tokenPayloadsFromCookies(cookieHeader: string | null): any[] {
+  if (!cookieHeader) return [];
+  const payloads: any[] = [];
+  for (const part of cookieHeader.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const name = part.slice(0, eq).trim();
+    if (name !== "arc_token" && !name.startsWith("arc_token_")) continue;
+    const payload = decodeTokenPayload(decodeURIComponent(part.slice(eq + 1).trim()));
+    if (payload) payloads.push(payload);
+  }
+  return payloads;
+}
+
+/** Pick the render locale: `arc-locale` cookie → Accept-Language (first match
+ *  against available locales, exact or language-prefix) → sourceLocale. */
+function pickLocale(
+  cookieHeader: string | null,
+  acceptLanguage: string | null,
+  locales: string[],
+  sourceLocale: string,
 ): string {
+  const fromCookie = cookieHeader?.match(/(?:^|;)\s*arc-locale=([^;]+)/)?.[1];
+  if (fromCookie && locales.includes(decodeURIComponent(fromCookie))) {
+    return decodeURIComponent(fromCookie);
+  }
+  for (const tag of (acceptLanguage ?? "").split(",")) {
+    const lang = tag.split(";")[0].trim();
+    if (!lang) continue;
+    const exact = locales.find((l) => l.toLowerCase() === lang.toLowerCase());
+    if (exact) return exact;
+    const prefix = locales.find(
+      (l) => l.toLowerCase().split("-")[0] === lang.toLowerCase().split("-")[0],
+    );
+    if (prefix) return prefix;
+  }
+  return sourceLocale;
+}
+
+export interface ShellHtmlOptions {
+  appName: string;
+  /** PWA/app manifest metadata ({title, favicon}). */
+  appManifest?: { title: string; favicon?: string };
+  /** Full build manifest (initial + groups + sharedChunks + stylesHash + shell). */
+  buildManifest?: BuildManifest;
+  /** Access rules for per-token manifest filtering at render time. */
+  moduleAccessMap: Map<string, ModuleAccess>;
+  /** Workspace `.arc/platform` dir — to load compiled locale catalogs + config. */
+  arcDir: string;
+  rootDir: string;
+  /** Request `Cookie` header (tokens + locale) and `Accept-Language`. */
+  cookieHeader: string | null;
+  acceptLanguage: string | null;
+}
+
+/**
+ * Render the SPA shell HTML — PERSONALIZED per request from cookies. Reads the
+ * caller's `arc_token*` cookies to inline exactly the module manifest they can
+ * access (`window.__ARC_MANIFEST__`) + `<link rel=modulepreload>` for the
+ * chunks they'll load, and their locale's catalog (`window.__ARC_I18N__`). This
+ * collapses the boot waterfall: no `/api/modules`, `/api/translations`, or
+ * startup `/locales/*.json` round-trip, and chunks fetch in parallel with the
+ * initial bundle instead of being discovered after parse.
+ */
+export async function generateShellHtml(opts: ShellHtmlOptions): Promise<string> {
+  const {
+    appName,
+    appManifest,
+    buildManifest,
+    moduleAccessMap,
+    arcDir,
+    rootDir,
+    cookieHeader,
+    acceptLanguage,
+  } = opts;
+
+  if (!buildManifest?.initial) {
+    throw new Error("generateShellHtml: initial bundle missing from manifest");
+  }
+  const initial = buildManifest.initial;
+  const initialUrl = `/browser/${initial.file}`;
+  const shell = buildManifest.shell;
+
   // OpenTelemetry config — injected as a global so the browser SDK chunk
-  // (lazy-loaded by start-app.ts) can pick it up without a fetch. Endpoint
-  // is same-origin so Caddy can apply CORS + auth uniformly.
+  // (lazy-loaded by start-app.ts) can pick it up without a fetch.
   const otelConfig = process.env.ARC_OTEL_ENABLED === "true"
     ? {
         enabled: true,
@@ -148,36 +233,82 @@ export function generateShellHtml(
       }
     : null;
   const otelTag = otelConfig
-    ? `\n  <script>window.__ARC_OTEL_CONFIG=${JSON.stringify(otelConfig)};</script>`
+    ? `\n  <script>window.__ARC_OTEL_CONFIG=${inlineJson(otelConfig)};</script>`
     : "";
-  // Initial bundle carries framework, public modules, and PlatformApp re-export.
-  // Bundled build: no importmap — splitting:true dedups everything into
-  // chunk-<hash>.js. Federated build (arc.federation): framework peers są
-  // external i rozwiązuje je import mapa peer-shella; obowiązuje ona też
-  // moduły importowane cross-origin (chunki aplikacji partnerskich) —
-  // spec/module-federation.md.
-  const initialUrl = initial ? `/browser/${initial.file}` : null;
-  if (!initialUrl) {
-    throw new Error("generateShellHtml: initial bundle missing from manifest");
-  }
+
+  // Federated build only: framework peers are external → import map (peer-shell).
   const importMapTag = shell
-    ? `\n  <script type="importmap">${JSON.stringify({ imports: shell.imports })}</script>` +
-      `\n  <script>window.__ARC_PEERS__=${JSON.stringify(shell.peers)};</script>`
+    ? `\n  <script type="importmap">${inlineJson({ imports: shell.imports })}</script>` +
+      `\n  <script>window.__ARC_PEERS__=${inlineJson(shell.peers)};</script>`
+    : "";
+
+  const stylesQs = buildManifest.stylesHash
+    ? `?v=${buildManifest.stylesHash.slice(0, 16)}`
     : "";
-  // Append the styles content hash as a query string. Filenames are stable
-  // (/styles.css, /theme.css) but their content changes between builds; the
-  // hash invalidates the browser cache exactly when the content changes,
-  // letting us serve them with `Cache-Control: immutable`.
-  const stylesQs = stylesHash ? `?v=${stylesHash.slice(0, 16)}` : "";
+
+  // --- Per-request manifest: only the groups the caller's tokens unlock, each
+  // with a signed URL. Same function `/api/modules` uses, so the inlined
+  // manifest is identical to what the client would have fetched. ---
+  const tokenPayloads = tokenPayloadsFromCookies(cookieHeader);
+  const filtered = await filterManifestForTokens(
+    buildManifest,
+    moduleAccessMap,
+    tokenPayloads,
+  );
+
+  // --- Preloads: chunks the browser will need, fetched in parallel with the
+  // initial bundle. initial's static closure + each accessible group's entry +
+  // its static closure. Deduped; all `/browser/` immutable content-addressed. ---
+  const preloadUrls = new Set<string>();
+  preloadUrls.add(initialUrl);
+  for (const c of initial.staticChunks ?? []) preloadUrls.add(`/browser/${c}`);
+  for (const group of Object.values(filtered.groups)) {
+    if (group.url) preloadUrls.add(group.url);
+    for (const c of group.staticChunks ?? []) preloadUrls.add(`/browser/${c}`);
+  }
+  const preloadTags = [...preloadUrls]
+    .map((u) => `\n  <link rel="modulepreload" href="${u}" />`)
+    .join("");
+
+  const manifestTag = `\n  <script>window.__ARC_MANIFEST__=${inlineJson({
+    initial: filtered.initial,
+    groups: filtered.groups,
+    sharedChunks: filtered.sharedChunks,
+    stylesHash: filtered.stylesHash,
+    buildTime: filtered.buildTime,
+  })};</script>`;
+
+  // --- i18n: detect locale from cookie/Accept-Language, inline the catalog so
+  // the client renders translated on first paint (no /api/translations +
+  // /locales round-trips, no render-blocking wait). ---
+  // Always inline __ARC_I18N__ (even when the app has no translations) so the
+  // client NEVER round-trips to /api/translations or the startup /locales/*.json.
+  let lang = "en";
+  const tconfig = readTranslationsConfig(rootDir);
+  let messages: Record<string, string> = {};
+  if (tconfig) {
+    lang = pickLocale(cookieHeader, acceptLanguage, tconfig.locales, tconfig.sourceLocale);
+    try {
+      messages = JSON.parse(readFileSync(join(arcDir, "locales", `${lang}.json`), "utf-8"));
+    } catch {
+      // catalog missing (e.g. sourceLocale has no .po) → empty; <Trans> falls
+      // back to the source string. No round-trip regression either way.
+    }
+  }
+  const i18nTag = `\n  <script>window.__ARC_I18N__=${inlineJson({
+    locale: lang,
+    config: tconfig,
+    messages,
+  })};</script>`;
+
   return `<!doctype html>
-<html lang="en">
+<html lang="${lang}">
 <head>
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
-  <title>${manifest?.title ?? appName}</title>${manifest?.favicon ? `\n  <link rel="icon" href="${manifest.favicon}">` : ""}${manifest ? `\n  <link rel="manifest" href="/manifest.json${stylesQs}">` : ""}
+  <title>${appManifest?.title ?? appName}</title>${appManifest?.favicon ? `\n  <link rel="icon" href="${appManifest.favicon}">` : ""}${appManifest ? `\n  <link rel="manifest" href="/manifest.json${stylesQs}">` : ""}
   <link rel="stylesheet" href="/styles.css${stylesQs}" />
-  <link rel="stylesheet" href="/theme.css${stylesQs}" />${importMapTag}
-  <link rel="modulepreload" href="${initialUrl}" />${otelTag}
+  <link rel="stylesheet" href="/theme.css${stylesQs}" />${importMapTag}${preloadTags}${manifestTag}${i18nTag}${otelTag}
 </head>
 <body>
   <div id="root"></div>
@@ -868,17 +999,20 @@ function headlessFallbackHandler(
   };
 }
 
-function spaFallbackHandler(getShellHtml: () => string): ArcHttpHandler {
-  return (_req, _url, ctx) => {
-    return new Response(getShellHtml(), {
+function spaFallbackHandler(
+  getShellHtml: (req: Request) => Promise<string>,
+): ArcHttpHandler {
+  return async (req, _url, ctx) => {
+    return new Response(await getShellHtml(req), {
       headers: {
         ...ctx.corsHeaders,
         "Content-Type": "text/html",
-        // Stabilny URL, zmienna treść (embeduje initial.<hash>.js + styles ?v=).
-        // Kotwica całego łańcucha — musi być zawsze rewalidowana, inaczej po
-        // deployu przeglądarka/CDN podaje stary shell wskazujący na nieistniejące
-        // już bundle. Hash nie pomoże: to URL trasy, którego nie da się zahashować.
-        "Cache-Control": "no-cache, must-revalidate",
+        // Stabilny URL, zmienna treść — teraz PERSONALIZOWANA per cookie
+        // (manifest modułów + preloady + katalog i18n zależą od tokenów/locale
+        // usera). `private` żeby proxy/CDN nie współdzieliło HTML między userami;
+        // `no-cache` bo initial.<hash>.js/styles ?v= zmieniają się co build.
+        "Cache-Control": "no-cache, must-revalidate, private",
+        Vary: "Cookie, Accept-Language",
       },
     });
   };
@@ -942,16 +1076,20 @@ export async function startPlatformServer(
   };
   const getMapUrl = () => mapUrl;
 
-  // Recompute on every request — manifest.initial.hash changes when public
-  // modules are rebuilt in dev, and we want the new URL in the HTML.
-  const getShellHtml = (): string =>
-    generateShellHtml(
-      ws.appName,
-      ws.manifest,
-      manifest?.initial,
-      manifest?.stylesHash,
-      manifest?.shell,
-    );
+  // Recompute on every request — the shell is personalized from the request's
+  // cookies (module manifest + preloads + i18n) and manifest.initial.hash
+  // changes when public modules are rebuilt in dev.
+  const getShellHtml = (req: Request): Promise<string> =>
+    generateShellHtml({
+      appName: ws.appName,
+      appManifest: ws.manifest,
+      buildManifest: manifest,
+      moduleAccessMap,
+      arcDir: ws.arcDir,
+      rootDir: ws.rootDir,
+      cookieHeader: req.headers.get("Cookie"),
+      acceptLanguage: req.headers.get("Accept-Language"),
+    });
   const sseClients = new Set<ReadableStreamDefaultController>();
 
   // Headless: bez shella SPA — fallback JSON (spec/platform-headless.md).