codex-overleaf-link 1.1.3 → 1.2.0

package/README.md

@@ -3,7 +3,7 @@
   <h1>Codex Overleaf Link</h1>
   <p><strong>Empower Overleaf with Codex.</strong></p>
   <p>
-    <img src="https://img.shields.io/badge/version-1.1.3-blue" alt="version">
+    <img src="https://img.shields.io/badge/version-1.2.0-blue" alt="version">
     <img src="https://img.shields.io/badge/platform-macOS%20%2F%20Windows%20%2F%20Linux-lightgrey" alt="platform">
     <img src="https://img.shields.io/badge/chrome-MV3-green" alt="chrome manifest v3">
     <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="node version">
@@ -34,10 +34,10 @@ The recommended release path is npm-first for the native host, plus Chrome's req
 1. Install or update the native host with the pinned npm package:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.1.3 -- install-native
+npm exec --yes codex-overleaf-link@1.2.0 -- install-native
 ```
 
-2. Download `codex-overleaf-link-extension-v1.1.3.zip` from the [v1.1.3 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.1.3), then unzip it to a stable local folder.
+2. Download `codex-overleaf-link-extension-v1.2.0.zip` from the [v1.2.0 GitHub Release](https://github.com/Ghqqqq/codex-overleaf-link/releases/tag/v1.2.0), then unzip it to a stable local folder.
 
 3. Open `chrome://extensions`, enable **Developer mode**, click **Load unpacked**, and select the unzipped extension folder.
 
@@ -48,14 +48,14 @@ If you modify the extension key or load a custom build that gets a different id,
 Source installer fallback for macOS / Linux, mainly for development or source checkout installs:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.1.3 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.1.3/install.sh)"
+CODEX_OVERLEAF_REF=v1.2.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.0/install.sh)"
 ```
 
 Source installer fallback for Windows from PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.1.3/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.1.3'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.0/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v1.2.0'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
@@ -66,19 +66,19 @@ npm installs, updates, uninstalls, and diagnoses the native host only. npm does
 Install or update the native host for the official release extension id:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.1.3 -- install-native
+npm exec --yes codex-overleaf-link@1.2.0 -- install-native
 ```
 
 Diagnose the registered native host:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.1.3 -- doctor
+npm exec --yes codex-overleaf-link@1.2.0 -- doctor
 ```
 
 Uninstall the native host:
 
 ```bash
-npm exec --yes codex-overleaf-link@1.1.3 -- uninstall-native
+npm exec --yes codex-overleaf-link@1.2.0 -- uninstall-native
 ```
 
 Use `--extension-id <chrome-extension-id>` only for a custom/dev unpacked extension id that differs from the official bundled id.
@@ -116,10 +116,10 @@ If Chrome assigns a different extension id, rerun `npm run install:native -- --e
 <details>
 <summary><strong>Update</strong></summary>
 
-For a deterministic v1.1.3 update, run the pinned npm command. This is also the native mismatch recovery command shown by the popup and panel when they report **Native host update required**.
+For a deterministic v1.2.0 update, run the pinned npm command. This is also the native mismatch recovery command shown by the popup and panel when they report **Native host update required**.
 
 ```bash
-npm exec --yes codex-overleaf-link@1.1.3 -- install-native
+npm exec --yes codex-overleaf-link@1.2.0 -- install-native
 ```
 
 If npm is unavailable, use the GitHub Release script fallback for your platform.
@@ -127,14 +127,14 @@ If npm is unavailable, use the GitHub Release script fallback for your platform.
 macOS / Linux:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.1.3 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.1.3/install.sh)"
+CODEX_OVERLEAF_REF=v1.2.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.0/install.sh)"
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.1.3/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.1.3'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.0/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v1.2.0'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
@@ -144,13 +144,13 @@ Then reload the extension in `chrome://extensions` and refresh the Overleaf page
 
 ## GitHub Release Artifacts
 
-The v1.1.3 GitHub Release contains:
+The v1.2.0 GitHub Release contains:
 
-- `codex-overleaf-link-extension-v1.1.3.zip`: loadable Chrome extension package for manual unpacked installation.
-- `codex-overleaf-native-host-v1.1.3.tar.gz`: native host runtime files used by the installer and release verification.
-- `codex-overleaf-link-1.1.3.tgz`: npm native host CLI package for pinned install, doctor, and uninstall flows.
-- `install.sh`: release-pinned macOS / Linux installer that defaults to `v1.1.3` when run directly from the release artifact.
-- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.1.3` when run directly from the release artifact.
+- `codex-overleaf-link-extension-v1.2.0.zip`: loadable Chrome extension package for manual unpacked installation.
+- `codex-overleaf-native-host-v1.2.0.tar.gz`: native host runtime files used by the installer and release verification.
+- `codex-overleaf-link-1.2.0.tgz`: npm native host CLI package for pinned install, doctor, and uninstall flows.
+- `install.sh`: release-pinned macOS / Linux installer that defaults to `v1.2.0` when run directly from the release artifact.
+- `install.ps1`: release-pinned Windows PowerShell installer that defaults to `v1.2.0` when run directly from the release artifact.
 - `uninstall-native-host.mjs`: native host uninstaller that removes the Chrome Native Messaging manifest, bridge executable, and runtime copy.
 - `nativeHostPlatform.js`, `manifest.js`, `runtimeInstaller.js`: helper files required by the loose uninstaller asset.
 - `SHA256SUMS` and `release-manifest.json`: checksum and artifact metadata for release verification.
@@ -202,7 +202,7 @@ The uninstaller removes the Native Messaging registration, bridge executable, an
 Linux Chromium install or update:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.1.3 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.1.3/install.sh)" -- --browser chromium
+CODEX_OVERLEAF_REF=v1.2.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.0/install.sh)" -- --browser chromium
 ```
 
 Linux Chromium uninstall:
@@ -344,7 +344,7 @@ Composer attachments are turn-scoped Codex context. Limits are 8 attachments per
 Run the pinned npm native-host installer, reload the extension in `chrome://extensions`, then refresh the Overleaf tab. This also fixes extension/native version mismatch and native protocol mismatch.
 
 ```bash
-npm exec --yes codex-overleaf-link@1.1.3 -- install-native
+npm exec --yes codex-overleaf-link@1.2.0 -- install-native
 ```
 
 If npm is unavailable, use the GitHub Release script fallback for your platform.
@@ -352,14 +352,14 @@ If npm is unavailable, use the GitHub Release script fallback for your platform.
 macOS/Linux:
 
 ```bash
-CODEX_OVERLEAF_REF=v1.1.3 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.1.3/install.sh)"
+CODEX_OVERLEAF_REF=v1.2.0 bash -c "$(curl -fsSL https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.0/install.sh)"
 ```
 
 Windows PowerShell:
 
 ```powershell
-iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.1.3/install.ps1 -OutFile install.ps1
-$env:CODEX_OVERLEAF_REF='v1.1.3'
+iwr https://raw.githubusercontent.com/Ghqqqq/codex-overleaf-link/v1.2.0/install.ps1 -OutFile install.ps1
+$env:CODEX_OVERLEAF_REF='v1.2.0'
 powershell -ExecutionPolicy Bypass -File install.ps1
 ```
 
@@ -418,8 +418,8 @@ Use this matrix for release-candidate signoff and compatibility reports. Record
 | Browser/channel/version | Google Chrome channel and version. | Google Chrome channel and version. | Google Chrome channel and version. | Chromium channel/package and version. |
 | Install mode | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout. | Manual unpacked extension from GitHub Release zip or checkout; native host installed with `--browser chromium`. |
 | Extension id | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. | Bundled id `illdpneeeopfffmiepaejglgmhpmdhdc`, or actual custom id passed with `--extension-id`. |
-| Installer/update command | `npm exec --yes codex-overleaf-link@1.1.3 -- install-native` | `npm exec --yes codex-overleaf-link@1.1.3 -- install-native` | `npm exec --yes codex-overleaf-link@1.1.3 -- install-native` | `npm exec --yes codex-overleaf-link@1.1.3 -- install-native --browser chromium` |
-| Uninstall command | `npm exec --yes codex-overleaf-link@1.1.3 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.1.3 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.1.3 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.1.3 -- uninstall-native --browser chromium` |
+| Installer/update command | `npm exec --yes codex-overleaf-link@1.2.0 -- install-native` | `npm exec --yes codex-overleaf-link@1.2.0 -- install-native` | `npm exec --yes codex-overleaf-link@1.2.0 -- install-native` | `npm exec --yes codex-overleaf-link@1.2.0 -- install-native --browser chromium` |
+| Uninstall command | `npm exec --yes codex-overleaf-link@1.2.0 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.2.0 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.2.0 -- uninstall-native` | `npm exec --yes codex-overleaf-link@1.2.0 -- uninstall-native --browser chromium` |
 | Manifest/registry path | `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.codex.overleaf.json` | `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.codex.overleaf` -> `%LOCALAPPDATA%\CodexOverleaf\native-host-runtime\com.codex.overleaf.json` | `~/.config/google-chrome/NativeMessagingHosts/com.codex.overleaf.json` | `~/.config/chromium/NativeMessagingHosts/com.codex.overleaf.json` |
 | Bridge/runtime/source path | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. | Bridge `%LOCALAPPDATA%\CodexOverleaf\codex-overleaf-bridge.cmd`; runtime `%LOCALAPPDATA%\CodexOverleaf\native-host-runtime`; source `%LOCALAPPDATA%\CodexOverleaf\source`. | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. | Bridge `~/.codex-overleaf/codex-overleaf-bridge`; runtime `~/.codex-overleaf/native-host-runtime`; source `~/.codex-overleaf/source`. |
 | Node/Git/Codex/TeX | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. | Node.js >= 20; Git; Codex CLI installed and logged in; TeX optional. |

package/extension/src/shared/compatibility.js

@@ -12,7 +12,7 @@
   const MIN_NATIVE_VERSION = '1.0.0';
   const MIN_COMPATIBLE_NATIVE_VERSION = '1.0.0';
   const MIN_COMPATIBLE_EXTENSION_VERSION = '1.0.0';
-  const BUILD_TARGET_VERSION = '1.1.3';
+  const BUILD_TARGET_VERSION = '1.2.0';
   const DEFAULT_CHROME_EXTENSION_ID = 'illdpneeeopfffmiepaejglgmhpmdhdc';
   const REQUIRED_CAPABILITIES = Object.freeze([
     'bridgePing',

package/extension/src/shared/lineReferences.js

@@ -0,0 +1,404 @@
+(function initLineReferences(root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.CodexOverleafLineReferences = factory();
+  }
+})(typeof globalThis !== 'undefined' ? globalThis : window, function lineReferencesFactory() {
+  'use strict';
+
+  const VALID_PARSE_MODES = new Set([
+    'plain-text-token',
+    'markdown-link-label',
+    'markdown-link-target'
+  ]);
+  const TEXT_EXTENSION_PATTERN = '(?:tex|bib|sty|cls|bst|bbx|cbx|lbx|cfg|def|clo|ist|txt|md|latex)';
+  const REFERENCE_PREFIX_PATTERN = '(^|[\\s\\[({"\'])';
+  const PATH_PATTERN = `([^\\s\\[\\](){}<>"'\`,;]+?\\.${TEXT_EXTENSION_PATTERN})`;
+  const MARKDOWN_LINK_PATTERN = /\[([^\]]*)\]\(([^)]*)\)/g;
+  const BARE_LOCAL_PATH_PATTERN = /(?:file:\/\/\/?[^\s)\]]+|[A-Za-z]:[\\/][^\s)\]]+|\/(?:Users|home|private|var|tmp)\/[^\s)\]]+|[^\s)\]]*[\\/]\.codex-overleaf[\\/]projects[\\/][^\s)\]]+)/gi;
+
+  function parseLineReferencesFromText({ text, mode }) {
+    return collectLineReferences(text, mode).map(toPublicReference);
+  }
+
+  function resolveProjectReference({ rawPath, projectFiles }) {
+    const normalizedRawPath = normalizeReferencePath(rawPath);
+    if (!normalizedRawPath || hasUnsafePathSegments(normalizedRawPath)) {
+      return null;
+    }
+
+    const textFiles = collectTextProjectFiles(projectFiles);
+    const exactMatch = textFiles.find(file => file.normalizedPath === normalizedRawPath);
+    if (exactMatch) {
+      return buildResolvedReference(exactMatch, 'exact');
+    }
+
+    const suffixMatches = textFiles.filter(file => normalizedRawPath.endsWith(`/${file.normalizedPath}`));
+    if (suffixMatches.length === 1) {
+      return buildResolvedReference(suffixMatches[0], 'suffix');
+    }
+
+    const rawBasename = getBasename(normalizedRawPath);
+    const basenameMatches = textFiles.filter(file => getBasename(file.normalizedPath) === rawBasename);
+    if (basenameMatches.length === 1) {
+      return buildResolvedReference(basenameMatches[0], 'basename');
+    }
+
+    return null;
+  }
+
+  function sanitizeLocalReferences(text, { projectFiles, context } = {}) {
+    if (typeof text !== 'string' || !text) {
+      return '';
+    }
+
+    let sanitized = text.replace(MARKDOWN_LINK_PATTERN, (rawMarkdown, label, target) => {
+      const sanitizedLabel = sanitizeLocalReferenceText(label, {
+        projectFiles,
+        placeholderBrackets: false
+      });
+      const trimmedTarget = String(target || '').trim();
+      if (/^https?:\/\//i.test(trimmedTarget)) {
+        return `[${sanitizedLabel}](${target})`;
+      }
+      if (containsLocalTarget(trimmedTarget)) {
+        return `[${sanitizedLabel}]`;
+      }
+      const sanitizedTarget = sanitizeLocalReferenceText(target, {
+        projectFiles,
+        placeholderBrackets: false
+      });
+      return `[${sanitizedLabel}](${sanitizedTarget})`;
+    });
+
+    sanitized = sanitizeLocalReferenceText(sanitized, {
+      projectFiles,
+      placeholderBrackets: true
+    });
+
+    if (context === 'render' || context === 'persist') {
+      return sanitized;
+    }
+    return sanitized;
+  }
+
+  function isLocalPathLike(value) {
+    if (typeof value !== 'string') {
+      return false;
+    }
+
+    const rawValue = value.trim();
+    if (!rawValue || /^https?:\/\//i.test(rawValue)) {
+      return false;
+    }
+
+    const normalizedPath = normalizeReferencePath(rawValue);
+    return /^file:\/\//i.test(rawValue)
+      || /^[A-Za-z]:[\\/]/.test(rawValue)
+      || rawValue.startsWith('/')
+      || rawValue.includes('.codex-overleaf/projects')
+      || rawValue.includes('.codex-overleaf\\projects')
+      || normalizedPath.includes('/.codex-overleaf/projects/')
+      || /^Users\/[^/]+\//.test(normalizedPath)
+      || /^home\/[^/]+\//.test(normalizedPath);
+  }
+
+  function normalizeReferencePath(value) {
+    if (typeof value !== 'string') {
+      return '';
+    }
+
+    let normalized = value.trim();
+    if (!normalized) {
+      return '';
+    }
+
+    if (/^file:\/\//i.test(normalized)) {
+      normalized = normalized.replace(/^file:\/\/\/?/i, '/');
+    }
+
+    try {
+      normalized = decodeURI(normalized);
+    } catch (_error) {
+      return '';
+    }
+
+    normalized = normalized
+      .replace(/\\/g, '/')
+      .replace(/\/+/g, '/')
+      .trim();
+
+    let previous;
+    do {
+      previous = normalized;
+      normalized = normalized
+        .replace(/^@+/, '')
+        .replace(/^\/+/, '')
+        .replace(/^\.\//, '');
+    } while (normalized !== previous);
+
+    return normalized;
+  }
+
+  function collectLineReferences(text, mode) {
+    if (!VALID_PARSE_MODES.has(mode) || typeof text !== 'string' || !text) {
+      return [];
+    }
+
+    const refs = [];
+    collectColonReferences(text, mode, refs);
+    collectLineWordReferences(text, mode, refs);
+    collectChineseLineReferences(text, mode, refs);
+
+    return refs
+      .filter(ref => !shouldSkipReference(ref))
+      .sort((left, right) => left.index - right.index || right.rawText.length - left.rawText.length)
+      .reduce((deduped, ref) => {
+        if (deduped.some(existing => rangesOverlap(existing, ref))) {
+          return deduped;
+        }
+        deduped.push(ref);
+        return deduped;
+      }, []);
+  }
+
+  function collectColonReferences(text, mode, refs) {
+    const pattern = new RegExp(`${REFERENCE_PREFIX_PATTERN}${PATH_PATTERN}:(\\d+)(?::(\\d+))?(?![-:\\d])`, 'gi');
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      const line = parsePositiveInteger(match[3]);
+      const column = match[4] ? parsePositiveInteger(match[4]) : null;
+      if (!line || (match[4] && !column)) {
+        continue;
+      }
+      const prefixLength = match[1].length;
+      const rawText = match[0].slice(prefixLength);
+      refs.push({
+        rawText,
+        displayText: rawText,
+        rawPath: match[2],
+        line,
+        column,
+        source: mode,
+        index: match.index + prefixLength
+      });
+    }
+  }
+
+  function collectLineWordReferences(text, mode, refs) {
+    const pattern = new RegExp(`${REFERENCE_PREFIX_PATTERN}${PATH_PATTERN}\\s+line\\s+(\\d+)(?![-:\\d])`, 'gi');
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      const line = parsePositiveInteger(match[3]);
+      if (!line) {
+        continue;
+      }
+      const prefixLength = match[1].length;
+      const rawText = match[0].slice(prefixLength);
+      refs.push({
+        rawText,
+        displayText: `${match[2]}:${line}`,
+        rawPath: match[2],
+        line,
+        column: null,
+        source: mode,
+        index: match.index + prefixLength
+      });
+    }
+  }
+
+  function collectChineseLineReferences(text, mode, refs) {
+    const pattern = new RegExp(`${REFERENCE_PREFIX_PATTERN}${PATH_PATTERN}\\s+第\\s*(\\d+)\\s*行`, 'gi');
+    let match;
+    while ((match = pattern.exec(text)) !== null) {
+      const line = parsePositiveInteger(match[3]);
+      if (!line) {
+        continue;
+      }
+      const prefixLength = match[1].length;
+      const rawText = match[0].slice(prefixLength);
+      refs.push({
+        rawText,
+        displayText: `${match[2]}:${line}`,
+        rawPath: match[2],
+        line,
+        column: null,
+        source: mode,
+        index: match.index + prefixLength
+      });
+    }
+  }
+
+  function sanitizeLocalReferenceText(text, { projectFiles, placeholderBrackets }) {
+    let sanitized = replaceLineReferences(String(text || ''), {
+      projectFiles,
+      placeholderBrackets
+    });
+    sanitized = replaceBareLocalPaths(sanitized, {
+      projectFiles,
+      placeholderBrackets
+    });
+    return sanitized;
+  }
+
+  function replaceLineReferences(text, { projectFiles, placeholderBrackets }) {
+    const refs = collectLineReferences(text, 'plain-text-token')
+      .filter(ref => isLocalPathLike(ref.rawPath))
+      .sort((left, right) => right.index - left.index);
+    let sanitized = text;
+    for (const ref of refs) {
+      const replacement = formatReferenceReplacement(ref, {
+        projectFiles,
+        placeholderBrackets
+      });
+      sanitized = `${sanitized.slice(0, ref.index)}${replacement}${sanitized.slice(ref.index + ref.rawText.length)}`;
+    }
+    return sanitized;
+  }
+
+  function replaceBareLocalPaths(text, { projectFiles, placeholderBrackets }) {
+    return text.replace(BARE_LOCAL_PATH_PATTERN, (rawPath, offset, fullText) => {
+      if (/^[A-Za-z]:[\\/]/.test(rawPath) && offset > 0 && /[A-Za-z]/.test(fullText[offset - 1])) {
+        return rawPath;
+      }
+      const { value, trailing } = splitTrailingPunctuation(rawPath);
+      const resolved = resolveProjectReference({ rawPath: value, projectFiles });
+      if (resolved) {
+        return `${resolved.path}${trailing}`;
+      }
+      return `${formatLocalPathPlaceholder(null, placeholderBrackets)}${trailing}`;
+    });
+  }
+
+  function formatReferenceReplacement(ref, { projectFiles, placeholderBrackets }) {
+    const resolved = resolveProjectReference({
+      rawPath: ref.rawPath,
+      projectFiles
+    });
+    if (resolved) {
+      return `${resolved.path}:${ref.line}${ref.column ? `:${ref.column}` : ''}`;
+    }
+    return formatLocalPathPlaceholder(ref.line, placeholderBrackets);
+  }
+
+  function formatLocalPathPlaceholder(line, includeBrackets) {
+    const value = line ? `local path:${line}` : 'local path';
+    return includeBrackets ? `[${value}]` : value;
+  }
+
+  function containsLocalTarget(target) {
+    if (!target) {
+      return false;
+    }
+    if (isLocalPathLike(target)) {
+      return true;
+    }
+    return collectLineReferences(target, 'markdown-link-target')
+      .some(ref => isLocalPathLike(ref.rawPath));
+  }
+
+  function collectTextProjectFiles(projectFiles) {
+    if (!Array.isArray(projectFiles)) {
+      return [];
+    }
+
+    const result = [];
+    for (const file of projectFiles) {
+      if (!file || file.kind !== 'text' || typeof file.path !== 'string') {
+        continue;
+      }
+
+      const normalizedPath = normalizeReferencePath(file.path);
+      if (!normalizedPath || hasUnsafePathSegments(normalizedPath)) {
+        continue;
+      }
+
+      result.push({
+        entry: file,
+        path: normalizedPath,
+        normalizedPath
+      });
+    }
+    return result;
+  }
+
+  function buildResolvedReference(file, resolution) {
+    return {
+      path: file.path,
+      file: file.entry,
+      normalizedPath: file.normalizedPath,
+      resolution
+    };
+  }
+
+  function shouldSkipReference(ref) {
+    const rawPath = String(ref.rawPath || '');
+    return /^https?:\/\//i.test(rawPath)
+      || isEmailLikePath(rawPath)
+      || hasUnsafeLineRange(ref.rawText);
+  }
+
+  function isEmailLikePath(rawPath) {
+    return /^[^@\s/\\]+@[^@\s/\\]+$/.test(rawPath);
+  }
+
+  function hasUnsafeLineRange(rawText) {
+    return /:\d+-\d+(?=$|[^\d])/.test(rawText);
+  }
+
+  function hasUnsafePathSegments(path) {
+    return normalizeReferencePath(path)
+      .split('/')
+      .some(segment => segment === '.' || segment === '..');
+  }
+
+  function rangesOverlap(left, right) {
+    const leftEnd = left.index + left.rawText.length;
+    const rightEnd = right.index + right.rawText.length;
+    return left.index < rightEnd && right.index < leftEnd;
+  }
+
+  function parsePositiveInteger(value) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+      return null;
+    }
+    return parsed;
+  }
+
+  function getBasename(path) {
+    const parts = String(path || '').split('/');
+    return parts[parts.length - 1] || '';
+  }
+
+  function splitTrailingPunctuation(value) {
+    const match = String(value || '').match(/^(.*?)([.,;!?]+)$/);
+    if (!match) {
+      return { value, trailing: '' };
+    }
+    return {
+      value: match[1],
+      trailing: match[2]
+    };
+  }
+
+  function toPublicReference(ref) {
+    return {
+      rawText: ref.rawText,
+      displayText: ref.displayText,
+      rawPath: ref.rawPath,
+      line: ref.line,
+      column: ref.column,
+      source: ref.source
+    };
+  }
+
+  return {
+    isLocalPathLike,
+    normalizeReferencePath,
+    parseLineReferencesFromText,
+    resolveProjectReference,
+    sanitizeLocalReferences
+  };
+});

package/extension/src/shared/sessionState.js

@@ -81,6 +81,7 @@
     /\b(?:sk|pk)-[A-Za-z0-9][A-Za-z0-9_-]{7,}\b/g,
     /\b(?:api[_-]?key|token|password|passwd|secret)\b\s*[:=]\s*["']?[^"'\s,;]+["']?/gi
   ];
+  const LineReferences = loadLineReferences();
 
   function normalizePanelState(input = {}, options = {}) {
     const state = {
@@ -143,7 +144,7 @@
   }
 
   function normalizeSession(session, fallbackState = DEFAULT_PANEL_STATE, options = {}) {
-    const history = Array.isArray(session.history) ? session.history.slice(-10) : [];
+    const history = normalizeHistoryEntries(session.history);
     const normalizedRuns = normalizeRuns(session.runs, options);
     const runs = normalizedRuns.length ? normalizedRuns : recoverRunsFromHistory(session, history);
     const rawTitle = typeof session.title === 'string' ? session.title.trim() : '';
@@ -159,7 +160,7 @@
       updatedAt: typeof session.updatedAt === 'string' ? session.updatedAt : new Date().toISOString(),
       history,
       runs,
-      task: typeof session.task === 'string' ? session.task : '',
+      task: sanitizeAssistantVisibleText(session.task),
       mode: VALID_MODES.has(session.mode) ? session.mode : fallbackState.mode,
       model: typeof session.model === 'string' && session.model ? session.model : fallbackState.model,
       reasoningEffort: VALID_REASONING.has(session.reasoningEffort)
@@ -267,9 +268,9 @@
       titleSource,
       createdAt: overrides.createdAt || new Date().toISOString(),
       updatedAt: overrides.updatedAt || new Date().toISOString(),
-      history: Array.isArray(overrides.history) ? overrides.history.slice(-10) : [],
+      history: normalizeHistoryEntries(overrides.history),
       runs,
-      task: typeof overrides.task === 'string' ? overrides.task : '',
+      task: sanitizeAssistantVisibleText(overrides.task),
       mode: VALID_MODES.has(overrides.mode) ? overrides.mode : DEFAULT_PANEL_STATE.mode,
       model: typeof overrides.model === 'string' && overrides.model ? overrides.model : DEFAULT_PANEL_STATE.model,
       reasoningEffort: VALID_REASONING.has(overrides.reasoningEffort)
@@ -286,6 +287,8 @@
 
   function recordSessionResult(session, entry) {
     const base = session?.id ? session : createSession();
+    const task = sanitizeAssistantVisibleText(entry?.task) || 'untitled task';
+    const result = sanitizeAssistantVisibleText(entry?.result || entry?.status) || 'completed';
     return {
       ...base,
       id: base.id,
@@ -293,12 +296,12 @@
       history: [
         ...(Array.isArray(base.history) ? base.history : []),
         {
-          task: entry.task || 'untitled task',
-          result: entry.result || entry.status || 'completed',
-          at: entry.at || new Date().toISOString()
+          task,
+          result,
+          at: entry?.at || new Date().toISOString()
         }
       ].slice(-10),
-      updatedAt: entry.at || new Date().toISOString()
+      updatedAt: entry?.at || new Date().toISOString()
     };
   }
 
@@ -419,7 +422,7 @@
   }
 
   function sanitizeAutoTitle(value) {
-    const title = String(value || '')
+    const title = sanitizeAssistantVisibleText(value)
       .replace(/@file:[^\s]+/g, ' ')
       .replace(/@(context|compile-log)\b/g, ' ')
       .replace(/\s+/g, ' ')
@@ -506,13 +509,13 @@
 
     return {
       id: run.id,
-      task: typeof run.task === 'string' && run.task ? run.task : 'untitled task',
+      task: sanitizeAssistantVisibleText(run.task) || 'untitled task',
       mode: typeof run.mode === 'string' ? run.mode : '',
       model: typeof run.model === 'string' ? run.model : '',
       reasoningEffort: typeof run.reasoningEffort === 'string' ? run.reasoningEffort : '',
       speedTier: typeof run.speedTier === 'string' ? run.speedTier : '',
       status: shouldStopRestoredRun ? 'failed' : normalizeRunStatus(run.status),
-      statusText: shouldStopRestoredRun ? '页面刷新后已停止跟踪' : typeof run.statusText === 'string' ? run.statusText : '',
+      statusText: shouldStopRestoredRun ? '页面刷新后已停止跟踪' : sanitizeAssistantVisibleText(run.statusText),
       startedAt: typeof run.startedAt === 'string' ? run.startedAt : '',
       finishedAt: shouldStopRestoredRun ? new Date().toISOString() : typeof run.finishedAt === 'string' ? run.finishedAt : '',
       events: events.slice(-MAX_RUN_EVENTS),
@@ -522,7 +525,7 @@
       undoBaseFiles: normalizeRunFiles(run.undoBaseFiles),
       undoTrackedChanges: normalizeRunTrackedChanges(run.undoTrackedChanges),
       undoExpectedFiles: normalizeRunFiles(run.undoExpectedFiles),
-      undoStatus: typeof run.undoStatus === 'string' ? redactSecretLikeText(run.undoStatus) : ''
+      undoStatus: sanitizeAssistantVisibleText(run.undoStatus)
     };
   }
 
@@ -538,14 +541,14 @@
     return (Array.isArray(events) ? events : [])
       .filter(event => event && typeof event.title === 'string')
       .map(event => ({
-        title: event.title,
+        title: sanitizeAssistantVisibleText(event.title) || 'Event',
         status: typeof event.status === 'string' ? event.status : 'info',
-        detail: event.detail,
+        detail: sanitizeAssistantVisibleValue(event.detail),
         timestamp: typeof event.timestamp === 'string' ? event.timestamp : '',
         kind: typeof event.kind === 'string' ? event.kind : 'activity',
-        technicalDetail: event.technicalDetail,
-        streamKey: typeof event.streamKey === 'string' ? event.streamKey : '',
-        streamRole: typeof event.streamRole === 'string' ? event.streamRole : ''
+        technicalDetail: sanitizeAssistantVisibleValue(event.technicalDetail),
+        streamKey: sanitizeAssistantVisibleText(event.streamKey),
+        streamRole: sanitizeAssistantVisibleText(event.streamRole)
       }))
       .slice(-MAX_RUN_EVENTS);
   }
@@ -624,8 +627,8 @@
       normalized.push({
         key,
         id: typeof change.id === 'string' ? change.id : '',
-        path: typeof change.path === 'string' ? change.path : '',
-        label: typeof change.label === 'string' ? change.label : ''
+        path: sanitizeAssistantVisibleText(change.path),
+        label: sanitizeAssistantVisibleText(change.label)
       });
     }
     return normalized;
@@ -638,7 +641,7 @@
       if (typeof item !== 'string') {
         continue;
       }
-      const path = redactSecretLikeText(item.trim());
+      const path = sanitizeAssistantVisibleText(item.trim());
       if (!path || seen.has(path)) {
         continue;
       }
@@ -914,7 +917,7 @@
     if (typeof value !== 'string' || !value.trim()) {
       return '';
     }
-    const text = redactSecretLikeText(value);
+    const text = sanitizeAssistantVisibleText(value);
     if (isOmittedStorageSummary(text)) {
       return text;
     }
@@ -938,7 +941,7 @@
     for (const key of Object.keys(value)) {
       const item = value[key];
       if (/(^|[A-Z_])path$/i.test(key) && typeof item === 'string') {
-        const path = redactSecretLikeText(item).replace(/\\/g, '/').replace(/^\/+/, '').trim();
+        const path = sanitizeAssistantVisibleText(item).replace(/\\/g, '/').replace(/^\/+/, '').trim();
         if (path) {
           state.count += 1;
           if (!state.seen.has(path) && state.items.length < 5) {
@@ -991,13 +994,107 @@
   }
 
   function normalizeTextField(value, maxChars) {
-    const text = typeof value === 'string' ? redactSecretLikeText(value) : '';
+    const text = sanitizeAssistantVisibleText(value);
     if (!Number.isFinite(maxChars) || maxChars <= 0 || text.length <= maxChars) {
       return text;
     }
     return `${text.slice(0, Math.max(0, maxChars - 1))}…`;
   }
 
+  function normalizeHistoryEntries(history) {
+    return (Array.isArray(history) ? history : [])
+      .slice(-10)
+      .map(entry => ({
+        task: sanitizeAssistantVisibleText(entry?.task) || 'untitled task',
+        result: sanitizeAssistantVisibleText(entry?.result || entry?.status) || 'completed',
+        at: typeof entry?.at === 'string' ? entry.at : ''
+      }));
+  }
+
+  function sanitizeAssistantVisibleValue(value, depth = 0) {
+    if (typeof value === 'string') {
+      return sanitizeAssistantVisibleText(value);
+    }
+    if (value === undefined || value === null || typeof value === 'number' || typeof value === 'boolean') {
+      return value;
+    }
+    if (depth > 12) {
+      return '[redacted nested value]';
+    }
+    if (Array.isArray(value)) {
+      return value.map(item => sanitizeAssistantVisibleValue(item, depth + 1));
+    }
+    if (typeof value === 'object') {
+      const result = {};
+      for (const key of Object.keys(value)) {
+        const safeKey = sanitizeAssistantVisibleText(key) || key;
+        result[safeKey] = sanitizeAssistantVisibleValue(value[key], depth + 1);
+      }
+      return result;
+    }
+    return value;
+  }
+
+  function sanitizeAssistantVisibleText(value) {
+    if (typeof value !== 'string' || !value) {
+      return '';
+    }
+    const secretRedacted = redactSecretLikeText(value);
+    if (!mightContainLocalReferenceText(secretRedacted)) {
+      return secretRedacted;
+    }
+    if (LineReferences?.sanitizeLocalReferences) {
+      try {
+        return LineReferences.sanitizeLocalReferences(secretRedacted, {
+          projectFiles: [],
+          context: 'persist'
+        });
+      } catch (_error) {
+        return fallbackSanitizeLocalReferences(secretRedacted);
+      }
+    }
+    return fallbackSanitizeLocalReferences(secretRedacted);
+  }
+
+  function mightContainLocalReferenceText(value) {
+    return /(?:file:\/\/\/?|[A-Za-z]:[\\/]|\/(?:Users|home|private|var|tmp)\/|[\\/]\.codex-overleaf[\\/]projects[\\/]|\.codex-overleaf[\\/]projects[\\/])/i.test(String(value || ''));
+  }
+
+  function loadLineReferences() {
+    if (typeof globalThis !== 'undefined' && globalThis.CodexOverleafLineReferences) {
+      return globalThis.CodexOverleafLineReferences;
+    }
+    if (typeof require === 'function') {
+      try {
+        return require('./lineReferences');
+      } catch (_error) {
+        return null;
+      }
+    }
+    return null;
+  }
+
+  function fallbackSanitizeLocalReferences(value) {
+    return String(value || '')
+      .replace(/\[([^\]]*)\]\(([^)]*)\)/g, (_raw, label, target) => {
+        const safeLabel = fallbackSanitizeBareLocalPaths(label);
+        return /^https?:\/\//i.test(String(target || '').trim())
+          ? `[${safeLabel}](${target})`
+          : `[${safeLabel}]`;
+      })
+      .replace(/(?:file:\/\/\/?[^\s)\]]+|[A-Za-z]:[\\/][^\s)\]]+|\/(?:Users|home|private|var|tmp)\/[^\s)\]]+|[^\s)\]]*[\\/]\.codex-overleaf[\\/][^\s)\]]+)/gi, rawPath => {
+        const line = String(rawPath || '').match(/:(\d+)(?::\d+)?(?:[.,;!?])?$/)?.[1];
+        return line ? `[local path:${line}]` : '[local path]';
+      });
+  }
+
+  function fallbackSanitizeBareLocalPaths(value) {
+    return String(value || '').replace(/(?:file:\/\/\/?[^\s)\]]+|[A-Za-z]:[\\/][^\s)\]]+|\/(?:Users|home|private|var|tmp)\/[^\s)\]]+|[^\s)\]]*[\\/]\.codex-overleaf[\\/][^\s)\]]+)/gi, rawPath => {
+      const line = String(rawPath || '').match(/:(\d+)(?::\d+)?(?:[.,;!?])?$/)?.[1];
+      return line ? `[local path:${line}]` : '[local path]';
+    });
+  }
+
   function redactSecretLikeText(value) {
     if (typeof value !== 'string') {
       return '';

package/extension/src/shared/storageDb.js

@@ -812,13 +812,71 @@
   }
 
   function normalizeTextField(value, maxChars) {
-    var text = typeof value === 'string' ? redactSecretLikeText(value) : '';
+    var text = sanitizeAssistantVisibleText(value);
     if (!Number.isFinite(maxChars) || maxChars <= 0 || text.length <= maxChars) {
       return text;
     }
     return text.slice(0, Math.max(0, maxChars - 1)) + '…';
   }
 
+  function sanitizeAssistantVisibleText(value) {
+    if (typeof value !== 'string' || !value) {
+      return '';
+    }
+    var text = redactSecretLikeText(value);
+    if (!mightContainLocalReferenceText(text)) {
+      return text;
+    }
+    return sanitizeLocalReferencesForStorage(text);
+  }
+
+  function mightContainLocalReferenceText(value) {
+    return /(?:file:\/\/\/?|[A-Za-z]:[\\/]|\/(?:Users|home|private|var|tmp)\/|[\\/]\.codex-overleaf[\\/]projects[\\/]|\.codex-overleaf[\\/]projects[\\/])/i.test(String(value || ''));
+  }
+
+  function sanitizeLocalReferencesForStorage(value) {
+    return String(value || '')
+      .replace(/\[([^\]]*)\]\(([^)]*)\)/g, function (_raw, label, target) {
+        var safeLabel = sanitizeBareLocalPaths(label, false);
+        var trimmedTarget = String(target || '').trim();
+        if (/^https?:\/\//i.test(trimmedTarget)) {
+          return '[' + safeLabel + '](' + sanitizeHttpTarget(trimmedTarget) + ')';
+        }
+        if (mightContainLocalReferenceText(trimmedTarget)) {
+          return '[' + safeLabel + ']';
+        }
+        return '[' + safeLabel + '](' + sanitizeBareLocalPaths(trimmedTarget, false) + ')';
+      })
+      .replace(/(?:file:\/\/\/?[^\s)\]]+|[A-Za-z]:[\\/][^\s)\]]+|\/(?:Users|home|private|var|tmp)\/[^\s)\]]+|[^\s)\]]*[\\/]\.codex-overleaf[\\/]projects[\\/][^\s)\]]+)/gi, function (rawPath) {
+        return formatLocalPathPlaceholder(rawPath, true);
+      });
+  }
+
+  function sanitizeBareLocalPaths(value, includeBrackets) {
+    return String(value || '').replace(/(?:file:\/\/\/?[^\s)\]]+|[A-Za-z]:[\\/][^\s)\]]+|\/(?:Users|home|private|var|tmp)\/[^\s)\]]+|[^\s)\]]*[\\/]\.codex-overleaf[\\/]projects[\\/][^\s)\]]+)/gi, function (rawPath) {
+      return formatLocalPathPlaceholder(rawPath, includeBrackets);
+    });
+  }
+
+  function sanitizeHttpTarget(value) {
+    try {
+      var parsed = new URL(value);
+      if (mightContainLocalReferenceText(parsed.href)) {
+        parsed.search = '';
+        parsed.hash = '';
+      }
+      return parsed.href;
+    } catch (_error) {
+      return '';
+    }
+  }
+
+  function formatLocalPathPlaceholder(rawPath, includeBrackets) {
+    var lineMatch = String(rawPath || '').match(/:(\d+)(?::\d+)?(?:[.,;!?])?$/);
+    var value = lineMatch ? 'local path:' + lineMatch[1] : 'local path';
+    return includeBrackets ? '[' + value + ']' : value;
+  }
+
   function nonNegativeInteger(value) {
     var number = Number(value);
     return Number.isFinite(number) && number > 0 ? Math.floor(number) : 0;

package/native-host/src/codexPrompt.js

@@ -4,6 +4,7 @@ function buildCodexPrompt(request) {
   const project = request.project || {};
   const files = Array.isArray(project.files) ? project.files : [];
   const focusFiles = normalizeFocusFiles(request.focusFiles || request.session?.focusFiles);
+  const activePath = normalizeProjectPath(project.activePath);
   const orderedFiles = orderFilesByFocus(files, focusFiles);
   const inventory = orderedFiles.map(file => `- ${file.path} (${String(file.content || '').length} chars)`).join('\n') || '- no files supplied';
 
@@ -15,7 +16,7 @@ function buildCodexPrompt(request) {
     `Reasoning effort: ${request.reasoningEffort || 'default'}`,
     `Session: ${request.session?.id || 'none'}`,
     `Task: ${request.task}`,
-    `Active file: ${project.activePath || 'unknown'}`,
+    `Active file: ${activePath || 'unknown'}`,
     '',
     'Recent session history:',
     formatSessionHistory(request.session?.history),
@@ -23,6 +24,12 @@ function buildCodexPrompt(request) {
     'Focus files:',
     formatFocusFiles(focusFiles, files),
     '',
+    'Project location citation rules:',
+    formatProjectLocationCitationRules(),
+    '',
+    'Focused project file inventory:',
+    formatFocusedProjectFileInventory([activePath, ...focusFiles]),
+    '',
     'Files:',
     inventory,
     '',
@@ -62,10 +69,7 @@ function normalizeFocusFiles(value) {
   const seen = new Set();
   const files = [];
   for (const item of Array.isArray(value) ? value : []) {
-    if (typeof item !== 'string') {
-      continue;
-    }
-    const path = item.trim();
+    const path = normalizeProjectPath(item);
     if (!path || seen.has(path)) {
       continue;
     }
@@ -75,6 +79,42 @@ function normalizeFocusFiles(value) {
   return files.slice(0, 5);
 }
 
+function normalizeProjectPath(value) {
+  const path = String(value || '')
+    .replace(/^@file:/i, '')
+    .replace(/\\/g, '/')
+    .trim();
+  if (!path || /^file:\/\//i.test(path) || /^[A-Za-z]:\//.test(path)) {
+    return '';
+  }
+  const projectPath = path.replace(/^\/+/, '');
+  const wasAbsolutePath = path.startsWith('/');
+  if (wasAbsolutePath && /^(Users|home|tmp|var|private|Volumes)\//i.test(projectPath)) {
+    return '';
+  }
+  if (/(^|\/)\.codex-overleaf\/projects(\/|$)/.test(projectPath)) {
+    return '';
+  }
+  return projectPath;
+}
+
+function formatProjectLocationCitationRules() {
+  return [
+    '- In any user-visible output, cite project locations using only Overleaf project-relative paths from the project file inventory below.',
+    '- Use path:LINE[:COLUMN] (for example, path/to/file.tex:12:3).',
+    '- Do not cite local absolute paths, temporary workspace paths, file:// URLs, or markdown links to local files.',
+    '- If a line number is uncertain, cite only the project-relative file path.'
+  ].join('\n');
+}
+
+function formatFocusedProjectFileInventory(files) {
+  const focusFiles = normalizeFocusFiles(files);
+  if (!focusFiles.length) {
+    return '- none selected.';
+  }
+  return focusFiles.map(filePath => `- ${filePath}`).join('\n');
+}
+
 function formatFocusFiles(focusFiles, files) {
   if (!focusFiles.length) {
     return '- none (default to whole project)';

package/native-host/src/codexPromptAssembly.js

@@ -30,10 +30,15 @@ function buildCodexTurnPrompt(options = {}) {
     '',
     'Current Overleaf workspace:',
     `- Project: ${context.projectKey || context.projectId || 'unknown'}`,
-    `- Local workspace: ${context.workspacePath || 'current cwd'}`,
     '- The local workspace was synced from Overleaf immediately before this turn.',
     '- If the recent session history conflicts with the files in the workspace, trust the files.',
     '',
+    'Project location citation rules:',
+    formatProjectLocationCitationRules(),
+    '',
+    'Focused project file inventory:',
+    formatFocusedProjectFileInventory(context.focusFiles),
+    '',
     'Focus files:',
     formatFocusFiles(context.focusFiles),
     '',
@@ -222,11 +227,40 @@ function normalizeFocusFiles(value) {
 }
 
 function normalizeProjectPath(value) {
-  return String(value || '')
+  const path = String(value || '')
     .replace(/^@file:/i, '')
     .replace(/\\/g, '/')
-    .trim()
-    .replace(/^\/+/, '');
+    .trim();
+  if (!path || /^file:\/\//i.test(path) || /^[A-Za-z]:\//.test(path)) {
+    return '';
+  }
+  const projectPath = path.replace(/^\/+/, '');
+  const wasAbsolutePath = path.startsWith('/');
+  if (wasAbsolutePath && /^(Users|home|tmp|var|private|Volumes)\//i.test(projectPath)) {
+    return '';
+  }
+  if (/(^|\/)\.codex-overleaf\/projects(\/|$)/.test(projectPath)) {
+    return '';
+  }
+  return projectPath;
+}
+
+function formatProjectLocationCitationRules() {
+  return [
+    '- In any user-visible output, cite project locations using only Overleaf project-relative paths from the project file inventory below.',
+    '- Use path:LINE[:COLUMN] (for example, path/to/file.tex:12:3).',
+    '- Do not wrap project location citations in backticks or inline code; write main.tex:28 as normal text so the browser can turn it into a jump button.',
+    '- Do not cite local absolute paths, temporary workspace paths, file:// URLs, or markdown links to local files.',
+    '- If a line number is uncertain, cite only the project-relative file path.'
+  ].join('\n');
+}
+
+function formatFocusedProjectFileInventory(files) {
+  const focusFiles = normalizeFocusFiles(files);
+  if (!focusFiles.length) {
+    return '- none selected.';
+  }
+  return focusFiles.map(filePath => `- ${filePath}`).join('\n');
 }
 
 function formatFocusFiles(files) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-overleaf-link",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Cross-platform Chrome bridge that connects Codex to the active Overleaf project.",
   "license": "MIT",
   "type": "commonjs",