@olares/lares-core 0.15.7 → 0.15.9

package/README.md

@@ -11,8 +11,9 @@ Import surfaces (`@olares/lares-core/<export>`):
 - `workspace/*`: workspace boundaries, default seed, and dsh session-to-workspace resolution.
 - `files/*`: intake, preview workspace, markdown rewrite, Host upload/preview HTTP.
 - `drive/*`: path policy, tool execution, present cards, and agent tool definitions.
+- `media/*`: ffmpeg encodes, Router-bound image re-encoding, and `media_generate`: submit, wait, publish, and the session ledger that recovers a generation an earlier turn never saw finish.
 - `voice/*`, `search/*`: STT/search settings, Host payloads, and client API contracts.
-- `olares/*`: Olares entrance identity, trusted-host loopback, and CLI session materialization.
+- `olares/*`: Olares entrance identity and trusted-host loopback. The olares-cli session is not one of them: it comes from the credential app-service mounts.
 - `larepass/host`: find the Lares entrance from LarePass `myApps`, PC-test proxy URLs, Host probe, `hostConfigFromEnv` / `hostTarget` / `hostKey`, and `laresPortsFromAccount`.
 - `larepass/rpc`, `larepass/transcript`, `larepass/context-provenance`, `larepass/tool-row`, `larepass/stage-copy`, `larepass/chat`, `larepass/mux`, `larepass/session-cache`, `larepass/runtime`, `larepass/settings`: dsh host-RPC envelope, session timeline fold (user / context / reasoning / tool / retry / files; same classification as dsh conversation nodes), English stage chrome copy and tool-row variants, browser mux as WebSocket (same frames as PC), per-session page cache (switch reads cache; history/mux write only on change), the LarePass chat runtime (UI only subscribes), and Host HTTP for model / voice / search settings.
 - `brand/identity`, `brand/manifest`: product identity and PWA manifest consumed by the Host and clients.

package/brand/identity.js

@@ -19,12 +19,13 @@ export function identityPrompt() {
   return [
     `You are ${PRODUCT_NAME}, a helpful assistant running on ${PLATFORM_NAME}.`,
     `Prefer olares-cli for ${PLATFORM_NAME} platform tasks when skills apply.`,
-    `olares-cli is on PATH; edge login materializes HOME / OLARES_CLI_* for bash when the user opens ${PRODUCT_NAME} via the ${PLATFORM_NAME} entrance.`,
-    "For image, video, audio, or 3D generation and creation, follow the lares-media-create skill.",
+    `olares-cli is on PATH and already signed in as the user: ${PLATFORM_NAME} mounts this application's credential into the container. Never run profile login or profile import — a platform-issued profile refuses both.`,
+    "For image, video, audio, or 3D generation, creation, or image editing — including FlowStudio scenes and workflows (T2V, I2V, R2V) — follow the lares-media-create skill: list that family on Router, then call media_generate, which waits for the result and publishes it. Do not curl FlowStudio. Do not diagnose Router or sync catalogs unless that list is empty.",
     "Use read/write/edit for files; use background jobs for long shell work.",
     "User-visible files belong in the session workspace (cwd) as relative paths. Do not write them under /app: that is the application overlay, and the chat preview cannot open it.",
     "For the current date or time, run `date`; the process TZ is the user's configured Olares time zone.",
     "Images the user attaches are already in context; read_image is only for image files that exist on disk, never for an attachment.",
+    "Write every user-visible message — progress updates as well as the final answer — in the language of the user's latest message, whatever language tool output, skills, or errors are in.",
     `If asked who you are, answer as ${PRODUCT_NAME} on ${PLATFORM_NAME}.`,
   ].join(" ");
 }
@@ -49,7 +50,8 @@ export function agentsMarkdown() {
 You are helping inside an ${PLATFORM_NAME} workspace via ${PRODUCT_NAME}.
 
 - Prefer olares-cli skills for platform tasks (market, cluster, files, router, …).
-- For image / video / audio / 3D generation, follow the lares-media-create skill.
+- olares-cli is already signed in as the user from the credential ${PLATFORM_NAME} mounts into this container. Never run \`profile login\` or \`profile import\`; a platform-issued profile refuses both.
+- For image / video / audio / 3D generation, including FlowStudio scenes and workflows, follow the lares-media-create skill: list that family, POST the matching Router shim route, land the file. Do not curl FlowStudio.
 - Stay inside the workspace for file edits unless the user explicitly asks otherwise.
 - Write files the user should open as workspace-relative paths (session cwd). \`/app\` is the running application and is not previewable.
 - Prefer structured fs tools (read / write / edit) over shell for file work.
@@ -65,9 +67,36 @@ export const LEGACY_AGENTS_SEEDS = [
 
 You are helping inside an Olares workspace via Lares.
 
+- Prefer olares-cli skills for platform tasks (market, cluster, files, router, …).
+- For image / video / audio / 3D generation, including FlowStudio scenes and workflows, follow the lares-media-create skill: list that family, POST the matching Router shim route, land the file. Do not curl FlowStudio.
+- Stay inside the workspace for file edits unless the user explicitly asks otherwise.
+- Write files the user should open as workspace-relative paths (session cwd). \`/app\` is the running application and is not previewable.
+- Prefer structured fs tools (read / write / edit) over shell for file work.
+- Long-running shell work can use background jobs; check results with job_output.
+- \`@path\` in a user message is workspace-relative, not absolute; \`/id\` names a skill.
+- If asked who you are, you are Lares on Olares.
+`,
+  `# AGENTS.md
+
+You are helping inside an Olares workspace via Lares.
+
+- Prefer olares-cli skills for platform tasks (market, cluster, files, router, …).
+- For image / video / audio / 3D generation, follow the lares-media-create skill: list that family, call Router, land the file.
+- Stay inside the workspace for file edits unless the user explicitly asks otherwise.
+- Write files the user should open as workspace-relative paths (session cwd). \`/app\` is the running application and is not previewable.
+- Prefer structured fs tools (read / write / edit) over shell for file work.
+- Long-running shell work can use background jobs; check results with job_output.
+- \`@path\` in a user message is workspace-relative, not absolute; \`/id\` names a skill.
+- If asked who you are, you are Lares on Olares.
+`,
+  `# AGENTS.md
+
+You are helping inside an Olares workspace via Lares.
+
 - Prefer olares-cli skills for platform tasks (market, cluster, files, router, …).
 - For image / video / audio / 3D generation, follow the lares-media-create skill.
 - Stay inside the workspace for file edits unless the user explicitly asks otherwise.
+- Write files the user should open as workspace-relative paths (session cwd). \`/app\` is the running application and is not previewable.
 - Prefer structured fs tools (read / write / edit) over shell for file work.
 - Long-running shell work can use background jobs; check results with job_output.
 - \`@path\` in a user message is workspace-relative, not absolute; \`/id\` names a skill.
@@ -78,6 +107,7 @@ You are helping inside an Olares workspace via Lares.
 You are helping inside an Olares workspace via Lares.
 
 - Prefer olares-cli skills for platform tasks (market, cluster, files, router, …).
+- For image / video / audio / 3D generation, follow the lares-media-create skill.
 - Stay inside the workspace for file edits unless the user explicitly asks otherwise.
 - Prefer structured fs tools (read / write / edit) over shell for file work.
 - Long-running shell work can use background jobs; check results with job_output.

package/drive/cat.js

@@ -0,0 +1,62 @@
+import { spawn } from "node:child_process";
+import { parseFilesPath } from "./files-path.js";
+
+const STDERR_LIMIT = 2000;
+const STDOUT_LIMIT = 64 * 1024;
+const CAT_TIMEOUT_MS = 8_000;
+
+function lookupError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/**
+ * Read one files-backend file as UTF-8 text (`olares-cli files cat`).
+ * Identity is already in `process.env`.
+ * @param spawnFn - seam for tests; the real spawn otherwise.
+ */
+export function runOlaresCat(source, options = {}) {
+  const path = parseFilesPath(source);
+  const { spawnFn = spawn } = options;
+  const timeout = AbortSignal.timeout(CAT_TIMEOUT_MS);
+  const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+  return new Promise((resolve, reject) => {
+    const child = spawnFn("olares-cli", ["files", "cat", path], {
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+      ...(signal ? { signal } : {}),
+    });
+    let stdout = "";
+    let stderr = "";
+    let truncated = false;
+    child.stdout?.on("data", (chunk) => {
+      if (truncated) return;
+      stdout += chunk;
+      if (stdout.length > STDOUT_LIMIT) {
+        truncated = true;
+        stdout = "";
+      }
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr = `${stderr}${chunk}`.slice(-STDERR_LIMIT);
+    });
+    child.on("error", (error) => {
+      reject(lookupError("files_unavailable", `olares-cli files cat failed: ${error.message}`));
+    });
+    child.on("close", (code) => {
+      if (truncated) {
+        reject(lookupError("files_unavailable", "olares-cli files cat output exceeded the read limit"));
+        return;
+      }
+      if (code !== 0) {
+        reject(lookupError(
+          "files_unavailable",
+          `olares-cli files cat exited ${code}: ${stderr.trim() || "no output"}`,
+        ));
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}

package/drive/download.js

@@ -6,9 +6,9 @@ const STDERR_LIMIT = 2000;
 /**
  * Stream one files-backend file onto local disk.
  *
- * The edge identity is already materialized into `process.env` (HOME /
- * OLARES_CLI_*) by `lares-olares-identity`, which is what the bash tool relies
- * on too, so the child inherits it rather than resolving a profile of its own.
+ * The CLI credential is the one app-service mounts into this container, not
+ * anything this process sets up, so the child inherits `process.env` and
+ * resolves the platform-issued profile the same way the bash tool does.
  * @param spawnFn - seam for tests; the real spawn otherwise.
  */
 export function runOlaresDownload(source, absolutePath, options = {}) {

package/drive/execute.js

@@ -9,6 +9,7 @@ import {
 } from "../workspace/path.js";
 import { runOlaresDownload } from "./download.js";
 import { statFilesFile } from "./ls.js";
+import { isMediaDeliverablePath } from "../files/preview-groups.js";
 import {
   describeFetch,
   describeFfmpegEncode,
@@ -21,6 +22,11 @@ import {
 } from "./paths.js";
 import { downloadUrl, saveDataUrl } from "./url-download.js";
 
+/** Only image / video / audio / 3D fetches become Produced; research files do not. */
+function producedFetchPath(destination) {
+  return destination && isMediaDeliverablePath(destination) ? destination : undefined;
+}
+
 export async function executeDriveFetch(args, exec, download) {
   const run = download ?? runOlaresDownload;
   const { source, destination } = resolveFetch(args);
@@ -110,7 +116,7 @@ export function presentDriveFetch(args) {
   const fetched = describeFetch(args);
   return producedEditCard(
     `Fetch ${fetched?.source ?? String(args.path ?? "")}`,
-    fetched?.destination,
+    producedFetchPath(fetched?.destination),
   );
 }
 
@@ -120,7 +126,7 @@ export function presentUrlFetch(args) {
     fetched?.kind === "data"
       ? `Save ${fetched.destination}`
       : `Download ${fetched?.source ?? String(args.url ?? "").slice(0, 160)}`,
-    fetched?.destination,
+    producedFetchPath(fetched?.destination),
   );
 }
 

package/drive/files-path.js

@@ -53,3 +53,36 @@ export function isFilesPath(value) {
     return false;
   }
 }
+
+/**
+ * A downloadable Files namespace, including directories and other addresses
+ * `parseFilesPath` rejects. Preview origin dispatch uses this so a Files
+ * folder never falls through to a workspace 404.
+ */
+export function isFilesNamespace(value) {
+  const source = canonicalizeFilesAddress(value);
+  if (source === "" || source.includes("\0")) return false;
+  if (source.startsWith("/") || /^[a-z]+:/i.test(source)) return false;
+  return DOWNLOADABLE.has(source.split("/")[0]);
+}
+
+/**
+ * dsh ChatView joins a relative path onto the session cwd before
+ * `workspaces.openPath`. A Files address is relative in its own namespace, so
+ * it arrives as `$cwd/drive/Home/…`. The suffix after `prefix` is that address
+ * when it belongs to a downloadable namespace — a directory stays Files, too.
+ */
+export function filesPathAfterPrefix(prefix, requestedPath) {
+  if (typeof prefix !== "string" || !prefix.trim()) return null;
+  if (typeof requestedPath !== "string" || !requestedPath) return null;
+  const root = prefix.replace(/\\/g, "/").replace(/\/+$/, "");
+  const joined = requestedPath.replace(/\\/g, "/");
+  if (root === "" || !joined.startsWith(`${root}/`)) return null;
+  const rest = joined.slice(root.length + 1);
+  if (!isFilesNamespace(rest)) return null;
+  try {
+    return parseFilesPath(rest);
+  } catch {
+    return canonicalizeFilesAddress(rest);
+  }
+}

package/drive/flowstudio-files.js

@@ -0,0 +1,87 @@
+import { runOlaresCat } from "./cat.js";
+
+/** Files-backend prefix of FlowStudio appData userData. */
+export const FLOWSTUDIO_FILES_PREFIX = "drive/Data/flowstudio/userData";
+
+function safeSegment(value) {
+  const text = String(value ?? "").trim();
+  if (!text || text === "." || text === "..") return "";
+  if (/[\\/\0]/.test(text)) return "";
+  return text;
+}
+
+/**
+ * Files address of the one-line pointer FlowStudio writes per JobOutput id.
+ * Only needed behind a Router old enough to drop `files_path`; it still
+ * forwards `outputs[].id`, which is that UUID.
+ */
+export function flowstudioOutputPointerPath(owner, outputId) {
+  const user = safeSegment(owner);
+  const id = safeSegment(outputId);
+  if (!user || !id) return null;
+  return `${FLOWSTUDIO_FILES_PREFIX}/${user}/comfyui/outputs/.by-id/${id}`;
+}
+
+/** First line of a pointer file must be the stored artifact's Files address. */
+export function parseFlowstudioFilesPointer(text) {
+  const line = String(text ?? "").trim().split(/\r?\n/, 1)[0]?.trim() ?? "";
+  if (!line.startsWith(`${FLOWSTUDIO_FILES_PREFIX}/`)) return null;
+  if (line.includes("..") || line.includes("\\") || line.includes("\0")) return null;
+  return line;
+}
+
+export async function resolveFlowstudioFilesPath(owner, outputId, options = {}) {
+  const pointer = flowstudioOutputPointerPath(owner, outputId);
+  if (!pointer) return null;
+  try {
+    const text = await (options.cat ?? runOlaresCat)(pointer, options);
+    return parseFlowstudioFilesPointer(text);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Publish a completed generation's outputs at the top level with a
+ * `files_path` on each, which is the shape callers read.
+ *
+ * A current Router carries the address on the wire and there is nothing to
+ * resolve. An older one drops it, and the address is then recovered from the
+ * Files pointer named by `output.id`; an output with neither is published
+ * unchanged rather than held back, since `content_url` still fetches it.
+ *
+ * Hoisting is the other half. Router nests the FlowStudio adapter's untouched
+ * snapshot under `response`, so a FlowStudio job can list its outputs there
+ * instead, and those outputs have to reach the top level whether or not this
+ * function had anything to add to them.
+ */
+export async function attachFlowstudioFilesPaths(payload, owner, options = {}) {
+  if (payload == null || typeof payload !== "object" || Array.isArray(payload)) {
+    return payload;
+  }
+  if (String(payload.status ?? "").toLowerCase() !== "completed") return payload;
+  const hoisted = !Array.isArray(payload.outputs);
+  const outputs = hoisted
+    ? (Array.isArray(payload.response?.outputs) ? payload.response.outputs : [])
+    : payload.outputs;
+  if (outputs.length === 0) return payload;
+  let changed = false;
+  const next = [];
+  for (const output of outputs) {
+    if (output == null || typeof output !== "object" || Array.isArray(output)) {
+      next.push(output);
+      continue;
+    }
+    // FlowStudio serializes camelCase and Router relays snake_case, so an
+    // address can arrive under either name; callers read only the one.
+    const onWire = String(output.files_path ?? output.filesPath ?? "").trim();
+    const path = onWire || (await resolveFlowstudioFilesPath(owner, output.id, options));
+    if (!path || path === output.files_path) {
+      next.push(output);
+      continue;
+    }
+    changed = true;
+    next.push({ ...output, files_path: path });
+  }
+  return changed || hoisted ? { ...payload, outputs: next } : payload;
+}

package/drive/ls.js

@@ -33,19 +33,19 @@ function itemLeaf(item) {
   return parts.at(-1) ?? "";
 }
 
-function isDirectoryItem(item) {
+export function isDirectoryItem(item) {
   if (item?.isDir === true || item?.isDirectory === true) return true;
   const type = String(item?.type ?? "").toLowerCase();
   if (type === "dir" || type === "directory") return true;
   return typeof item?.name === "string" && item.name.endsWith("/");
 }
 
-function itemSize(item) {
+export function itemSize(item) {
   const n = Number(item?.size ?? item?.fileSize);
   return Number.isFinite(n) && n >= 0 ? n : 0;
 }
 
-function itemModifiedAt(item) {
+export function itemModifiedAt(item) {
   const t = Date.parse(item?.modified ?? item?.mtime ?? item?.modTime ?? "");
   return Number.isFinite(t) ? t : 0;
 }

package/drive/paths.js

@@ -2,13 +2,13 @@
  * An Olares files path (`<fileType>/<extend>/<subPath…>`) names one object on
  * the user's files backend. Preview serves it in place; drive_fetch copies it
  * into the session workspace only when a later edit or transcode needs a local
- * file. A produced-file chip is rendered from `presentCall` before the tool
- * runs, so the path in the arguments is the path the UI opens.
+ * file. The durable preview projection is rebuilt from successful persisted
+ * tool call/result pairs; `presentCall` only describes the transient tool row.
  */
 import { posixBasename as basename, posixExtname as extname, sanitizeFilename } from "../files/filename.js";
-import { isFilesPath, parseFilesPath } from "./files-path.js";
+import { isFilesNamespace, parseFilesPath } from "./files-path.js";
 
-export { isFilesPath, parseFilesPath } from "./files-path.js";
+export { filesPathAfterPrefix, isFilesNamespace, isFilesPath, parseFilesPath } from "./files-path.js";
 
 const DEFAULT_DIRECTORY = "downloads";
 
@@ -55,12 +55,23 @@ export const DRIVE_IMPORT_PROMPT = [
   "Olares files paths (drive/…, sync/…, cache/…, external/…, and the cloud-account namespaces)",
   "are previewable in this app. Any file under drive/Home is included — Documents, Pictures, Music,",
   "Movies, Downloads, Code, and the rest — not only Downloads. After knowledge / Wise / yt-dlp /",
-  "torrent lands a file there, workspace_publish that files path immediately and name it in",
-  "markdown inline code. Do not copy it into the workspace only to preview it.",
+  "torrent lands a file there, workspace_publish that files path immediately. Do not copy it into",
+  "the workspace only to preview it, and do not close the reply with that path as inline code or a",
+  "link — the turn-tail preview already shows it. FlowStudio",
+  "generations whose poll JSON includes `files_path` (`drive/Data/flowstudio/…`) are the same",
+  "rule: publish that address; do not GET `/content` or copy the file into Home.",
   "Direct public HTTP(S) file URLs and data: URLs use url_fetch; never curl, wget, or shell.",
   "Give destination a meaningful filename with the correct extension whenever the URL path lacks one.",
+  "Produced chips only keep durable media from url_fetch / drive_fetch (image, video, audio, 3D).",
+  "Research fetches — git/GitHub APIs, chart YAML/JSON, READMEs, and other non-media references —",
+  "are workspace scratch (often under downloads/). They are not Produced; delete them when done.",
+  "Do not delete image / video / audio / 3D files the user should still open. Final artifacts the",
+  "user keeps (charts, app sources, outputs) belong outside downloads/ via write / edit, or via",
+  "workspace_publish when they already exist.",
+  "Before the turn closes, Lares re-checks durable Produced paths are still openable. If a check",
+  "fails, you will be steered to restore or republish — do not end while naming a broken path.",
   "drive_fetch copies one files-backend file into the workspace when a later edit or transcode",
-  "(for example ffmpeg_encode) needs it there. url_fetch and ffmpeg_encode already publish their",
+  "(for example ffmpeg_encode) needs it there. url_fetch and ffmpeg_encode already publish media",
   "workspace output. workspace_publish is for a file that already exists in the workspace or on",
   "the files backend that those tools did not produce. Do not call it after drive_fetch, url_fetch,",
   "or ffmpeg_encode. A subagent's own tool calls belong to its child turn: when a subagent reports",
@@ -72,11 +83,10 @@ export const DRIVE_IMPORT_PROMPT = [
   "subtitles into an input video. Do not transcode merely so a file can be previewed: webm, mp4,",
   "images, and audio preview as-is from a files path or after url_fetch. Do not run ffmpeg or ffprobe",
   "in the shell for those jobs. Report the encoder and speed from the tool result.",
-  "Name every returned workspace or Olares files path in markdown inline code so the UI can open it.",
-  "The conversation renders produced images, video, and audio right below the reply, so put those",
-  "mentions in the closing sentences and end the reply there: never name a produced file mid-reply",
-  "and then continue with more prose, alternatives, or follow-up questions, which would strand the",
-  "player far below the path.",
+  "After workspace_publish (or url_fetch / ffmpeg_encode), stop. The turn-tail preview under the",
+  "reply is the surface for produced images, video, audio, and 3D. Do not also write the path as",
+  "markdown inline code, a hyperlink, or a trailing file chip: that duplicates the preview. Name the",
+  "file in ordinary prose if the user needs the title; never leave a produced path as the last token.",
 ].join(" ");
 
 function parseDestination(value, source) {
@@ -193,7 +203,7 @@ export function describeUrlFetch(args) {
 
 export function resolveWorkspacePublish(args) {
   const raw = String(args?.path ?? "").trim().replace(/\\/g, "/");
-  if (isFilesPath(raw)) {
+  if (isFilesNamespace(raw)) {
     return { path: parseFilesPath(raw), origin: "files" };
   }
   const segments = raw.split("/");

package/drive/tools.js

@@ -60,8 +60,10 @@ export function urlFetchDefinition(download) {
     description:
       "Download one public HTTP(S) URL, or a data: URL / base64 payload, into the session workspace"
       + " and publish it for preview. This is the default for a pasted or requested online file; do"
-      + " not answer with only the URL. Use after web search, or when olares-cli router / FlowStudio"
-      + " returns a URL or inline bytes. Size is not a reason to skip.",
+      + " not answer with only the URL. Use after web search, or when a cloud generate returns a URL"
+      + " or inline bytes. When a generation poll already returned an Olares files path"
+      + " (`files_path` / `drive/…`), workspace_publish that path instead of downloading. Size is not"
+      + " a reason to skip.",
     parameters: {
       url: {
         type: "string",

package/entrance/surface.js

@@ -0,0 +1,96 @@
+/**
+ * Same-origin PC / phone split for the Lares entrance.
+ *
+ * FlowStudio serves both SPAs from `/` and picks the bundle per request
+ * (query, then cookie, then Client Hints, then User-Agent). Lares does the
+ * same: the phone page and the dsh desktop shell share the entrance host.
+ * Named routes (`/api`, `/llm`) never reach this choice.
+ */
+
+const MOBILE_UA_RE = /android|webos|iphone|ipad|ipod|blackberry|iemobile|opera mini|mobile/i;
+const IPAD_DESKTOP_UA_RE = /macintosh.*mobile\/|mobile\/.*macintosh|iphone os|cpu os \d+/i;
+
+export const UI_COOKIE_NAME = "lares_ui";
+export const UI_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+
+const STATIC_SUFFIXES = [
+  ".js", ".mjs", ".cjs", ".css", ".map", ".json", ".webmanifest",
+  ".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg", ".ico",
+  ".woff", ".woff2", ".ttf", ".otf", ".txt", ".wasm",
+];
+
+export function isMobileUserAgent(userAgent) {
+  if (!userAgent) return false;
+  if (MOBILE_UA_RE.test(userAgent)) return true;
+  return IPAD_DESKTOP_UA_RE.test(userAgent);
+}
+
+function forcedUi(value) {
+  const surface = String(value ?? "").trim().toLowerCase();
+  return surface === "mobile" || surface === "pc" ? surface : null;
+}
+
+function forcedUiFromCookie(cookieHeader) {
+  if (!cookieHeader) return null;
+  for (const part of String(cookieHeader).split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    if (part.slice(0, eq).trim() !== UI_COOKIE_NAME) continue;
+    return forcedUi(part.slice(eq + 1));
+  }
+  return null;
+}
+
+/**
+ * @param {{ userAgent?: string, cookie?: string, clientHint?: string, query?: string | URLSearchParams }} input
+ * @returns {{ surface: "mobile" | "pc", setCookie: "mobile" | "pc" | null }}
+ */
+export function resolveSpaSurface({ userAgent = "", cookie = "", clientHint = "", query = "" } = {}) {
+  const params = query instanceof URLSearchParams
+    ? query
+    : new URLSearchParams(String(query ?? "").replace(/^\?/, ""));
+  const fromQuery = forcedUi(params.get("ui"));
+  if (fromQuery) return { surface: fromQuery, setCookie: fromQuery };
+
+  const fromCookie = forcedUiFromCookie(cookie);
+  if (fromCookie) return { surface: fromCookie, setCookie: null };
+
+  if (String(clientHint ?? "").trim() === "?1") return { surface: "mobile", setCookie: null };
+
+  return { surface: isMobileUserAgent(userAgent) ? "mobile" : "pc", setCookie: null };
+}
+
+export function surfaceFromRequest(req) {
+  const url = new URL(req?.url ?? "/", "http://lares.invalid");
+  const headers = req?.headers ?? {};
+  return resolveSpaSurface({
+    userAgent: headers["user-agent"] || "",
+    cookie: headers.cookie || "",
+    clientHint: headers["sec-ch-ua-mobile"] || "",
+    query: url.searchParams,
+  });
+}
+
+export function uiCookieHeader(surface) {
+  return `${UI_COOKIE_NAME}=${surface}; Path=/; Max-Age=${UI_COOKIE_MAX_AGE}; SameSite=Lax`;
+}
+
+/** History routes fall back to index.html. Hashed assets must 404 as themselves. */
+export function isMobileIndexPath(pathname) {
+  const path = String(pathname ?? "/").replace(/\\/g, "/").split("?")[0];
+  const name = path.split("/").pop()?.toLowerCase() ?? "";
+  if (!name || name === "index.html") return true;
+  return !STATIC_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+
+export function spaCacheControl(pathname) {
+  const normalized = String(pathname ?? "").replace(/\\/g, "/").replace(/^\/+/, "");
+  const name = normalized.split("/").pop()?.toLowerCase() ?? "";
+  if (!name || name === "index.html" || name.endsWith(".html")) {
+    return "no-cache, no-store, must-revalidate";
+  }
+  if (normalized.startsWith("assets/") || normalized.includes("/assets/")) {
+    return "public, max-age=31536000, immutable";
+  }
+  return "no-cache";
+}

package/files/app-link.js

@@ -0,0 +1,64 @@
+import { parseFilesPath } from "../drive/files-path.js";
+import { entranceOrigin, userDomainOf } from "../olares/entrance.js";
+
+const FILES_LABEL = "files";
+
+function encoded(parts) {
+  return parts.map((part) => encodeURIComponent(part)).join("/");
+}
+
+function filesRoute(path) {
+  const [namespace, extend, ...rest] = parseFilesPath(path).split("/");
+  if (namespace === "drive") {
+    if (extend === "Data") return `/Data/${encoded(rest)}`;
+    if (extend === "Common") return `/Common/${encoded(rest)}`;
+    return `/Files/${encoded([extend, ...rest])}`;
+  }
+  if (namespace === "external") {
+    return `/Files/External/${encoded([extend, ...rest])}`;
+  }
+  if (namespace === "cache") return `/Cache/${encoded([extend, ...rest])}`;
+  if (["google", "dropbox", "awss3", "tencent"].includes(namespace)) {
+    return `/Drive/${namespace}/${encoded([extend, ...rest])}`;
+  }
+  if (namespace === "sync") {
+    const query = new URLSearchParams({ id: extend });
+    return `/Seahub/${encoded([extend, ...rest])}?${query}`;
+  }
+  return "";
+}
+
+function originFromEntrance(entrance) {
+  let url;
+  try {
+    url = new URL(String(entrance ?? ""));
+  } catch {
+    return "";
+  }
+  return entranceOrigin(FILES_LABEL, {
+    domain: userDomainOf(url.hostname),
+    protocol: url.protocol,
+    port: url.port,
+  });
+}
+
+function originFromAccount(accountDomain, protocol) {
+  return entranceOrigin(FILES_LABEL, {
+    domain: accountDomain,
+    protocol: String(protocol ?? "https:").trim().toLowerCase(),
+  });
+}
+
+export function filesAppUrl(path, options = {}) {
+  let route;
+  try {
+    route = filesRoute(path);
+  } catch {
+    return "";
+  }
+  if (!route) return "";
+  const entrance = options.entrance ?? globalThis.location?.origin ?? "";
+  const origin = originFromEntrance(entrance)
+    || originFromAccount(options.accountDomain, options.protocol);
+  return origin ? new URL(route, origin).href : "";
+}