codex-overleaf-link 2.2.0 → 2.3.0

package/extension/src/pageBridge.js

@@ -2,7 +2,8 @@
   'use strict';
 
   const PAGE_BRIDGE_INSTALL_VERSION = window.CodexOverleafCompatibility?.BUILD_TARGET_VERSION || 'dev';
-  const PAGE_BRIDGE_INSTALL_REVISION = '2026-05-21-editor-readiness-v11';
+  const pageRpcContract = window.CodexOverleafPageRpcContract;
+  const PAGE_BRIDGE_INSTALL_REVISION = pageRpcContract.REVISION;
   if (window.__codexOverleafPageBridgeInstalledVersion === PAGE_BRIDGE_INSTALL_VERSION
     && window.__codexOverleafPageBridgeInstalledRevision === PAGE_BRIDGE_INSTALL_REVISION) {
     return;
@@ -152,10 +153,7 @@
         result = await dispatch(method, params || {});
       }
     } catch (error) {
-      result = {
-        ok: false,
-        error: error.message
-      };
+      result = pageRpcContract.normalizeFailure(method, error);
     }
 
     window.postMessage({
@@ -187,111 +185,62 @@
     return writeCancellationSequence;
   }
 
-  async function dispatch(method, params) {
-    if (method === 'probe') {
-      return probe(params);
-    }
-    if (method === 'cancelActiveWrite') {
+  const pageRpcHandlers = {
+    probe,
+    cancelActiveWrite() {
       const sequence = bumpWriteCancellationSequence();
       return { ok: true, cancelled: true, sequence };
-    }
-    if (method === 'getProjectSnapshot') {
-      return projectSnapshotBridge.getProjectSnapshot(withSnapshotCacheIdentity(params));
-    }
-    if (method === 'getProjectFileList') {
-      return projectSnapshotBridge.getProjectFileList(params);
-    }
-    if (method === 'invalidateProjectSnapshot') {
+    },
+    getProjectSnapshot: params => projectSnapshotBridge.getProjectSnapshot(withSnapshotCacheIdentity(params)),
+    getProjectFileList: params => projectSnapshotBridge.getProjectFileList(params),
+    invalidateProjectSnapshot(params) {
       projectSnapshotBridge.invalidateProjectSnapshot(params);
       return { ok: true };
-    }
-    if (method === 'createCheckpoint') {
-      return createCheckpoint(params.label);
-    }
-    if (method === 'ensureReviewing') {
-      // Gate the Reviewing-mode toggle with the same writeGuard the per-write
-      // path uses. Without this, a mid-flight SPA navigation could leave the
-      // pre-flight toggle flipping Track Changes in a different Overleaf
-      // project than the run was bound to. params.runProjectId is set by
-      // the content-side caller (preflightWriteSafety / ensureReviewingBeforeWrite);
-      // when absent (defensive), the guard short-circuits via its own
-      // missing-runProjectId branch.
-      if (typeof params?.runProjectId === 'string' && params.runProjectId) {
-        const blocked = await writeGuard.runWriteGuard(params);
-        if (blocked) return blocked;
-      }
-      return ensureReviewing(params);
-    }
-    if (method === 'ensureEditing') {
-      if (typeof params?.runProjectId === 'string' && params.runProjectId) {
-        const blocked = await writeGuard.runWriteGuard(params);
-        if (blocked) return blocked;
-      }
-      return ensureEditing(params);
-    }
-    if (method === 'applyOperations') {
-      // Welcome-panel + write-guard:
-      // First gate: runProjectId vs page-side editorProjectId. Runs before
-      // any reviewing / save-state / open-file readiness check so a
-      // mid-run navigation cannot write into a different project. runWriteGuard
-      // is async because it retries the page-side editorProjectId reader with
-      // backoff to ride out Overleaf's hydration window.
-      const blocked = await writeGuard.runWriteGuard(params);
-      if (blocked) return blocked;
-      return applyOperations(params.operations || [], {
+    },
+    createCheckpoint: params => createCheckpoint(params.label),
+    ensureReviewing,
+    ensureEditing,
+    applyOperations: params => applyOperations(params.operations || [], {
         baseFiles: params.baseFiles || null,
         reviewingPolicy: params.reviewingPolicy || '',
         requireReviewing: params.requireReviewing === true,
         requireEditing: params.requireEditing === true,
-        // Propagate runProjectId so the writeback router's defense-in-depth
-        // missing-runProjectId check sees it on this in-bridge dispatch path.
         runProjectId: typeof params.runProjectId === 'string' ? params.runProjectId : ''
-      });
-    }
-    if (method === 'jumpToPosition') {
-      return jumpToPosition(params);
-    }
-    if (method === 'rejectTrackedChanges') {
-      const blocked = await writeGuard.runWriteGuard(params);
-      if (blocked) return blocked;
-      return rejectTrackedChanges(params);
+      }),
+    jumpToPosition,
+    rejectTrackedChanges,
+    acceptTrackedChanges,
+    triggerCompile: params => compileBridge.triggerCompile(params),
+    getCompileLog: params => compileBridge.getCompileLog(params),
+    getCompileState: () => compileBridge.getCompileState(),
+    waitForSaveState,
+    startOtObserver: params => otObserver.start(params),
+    stopOtObserver: () => otObserver.stop(),
+    getOtStatus: () => otObserver.getStatus(),
+    drainOtEvents() {
+      return { ok: true, events: otObserver.drainEvents().map(sanitizeOtEventForContent) };
     }
-    if (method === 'acceptTrackedChanges') {
+  };
+
+  async function dispatch(method, params) {
+    const contract = pageRpcContract.getMethod(method);
+    if (!contract || method === PAGE_BRIDGE_CAPABILITY_METHOD) {
+      return { ok: false, error: `Unknown page bridge method: ${method}` };
+    }
+    const handler = pageRpcHandlers[method];
+    if (typeof handler !== 'function') {
+      return { ok: false, error: `Page bridge handler unavailable: ${method}` };
+    }
+    const hasRunProjectId = typeof params?.runProjectId === 'string'
+      && params.runProjectId.trim().length > 0;
+    if (
+      contract.projectIdentity === 'required'
+      || (contract.projectIdentity === 'optional' && hasRunProjectId)
+    ) {
       const blocked = await writeGuard.runWriteGuard(params);
       if (blocked) return blocked;
-      return acceptTrackedChanges(params);
-    }
-    if (method === 'triggerCompile') {
-      return compileBridge.triggerCompile(params);
-    }
-    if (method === 'getCompileLog') {
-      return compileBridge.getCompileLog(params);
-    }
-    if (method === 'getCompileState') {
-      return compileBridge.getCompileState();
-    }
-    if (method === 'waitForSaveState') {
-      return waitForSaveState(params);
     }
-    if (method === 'startOtObserver') {
-      return otObserver.start(params);
-    }
-    if (method === 'stopOtObserver') {
-      return otObserver.stop();
-    }
-    if (method === 'getOtStatus') {
-      return otObserver.getStatus();
-    }
-    if (method === 'drainOtEvents') {
-      return {
-        ok: true,
-        events: otObserver.drainEvents().map(sanitizeOtEventForContent)
-      };
-    }
-    return {
-      ok: false,
-      error: `Unknown page bridge method: ${method}`
-    };
+    return handler(params);
   }
 
   function sanitizeOtEventForContent(event = {}) {
@@ -468,7 +417,7 @@
       reviewing: window.CodexOverleafReviewing.detectReviewingFromSignals(reviewingSignals),
       reviewingDiagnostics: reviewingSignals.diagnostics,
       editor,
-      capabilities: collectPageCapabilities(editor),
+      capabilities: pageRpcContract.withCapabilityReport(collectPageCapabilities(editor)),
       editorDiagnostics: buildEditorDiagnostics(editor),
       projectDiagnostics: {
         internalRootKeys: collectInternalRootKeys(),

package/extension/src/shared/agentTranscript.js

@@ -5,11 +5,14 @@
       getI18n: function getI18nCjs() { return require('./i18n.js'); }
     });
   } else {
-    // Browser script-tag load order is determined by manifest.json content_scripts;
-    // resolve dependencies lazily so this module can be listed before its deps.
-    root.CodexOverleafAgentTranscript = factory({
-      getFailureReasons: function getFailureReasonsWindow() { return root.CodexOverleafFailureReasons || null; },
-      getI18n: function getI18nWindow() { return root.CodexOverleafI18n || null; }
+    root.CodexOverleafModuleRegistry.define('AgentTranscript', [
+      'FailureReasons',
+      'I18n'
+    ], function createAgentTranscript(FailureReasons, I18n) {
+      return factory({
+        getFailureReasons: function getFailureReasonsWindow() { return FailureReasons; },
+        getI18n: function getI18nWindow() { return I18n; }
+      });
     });
   }
 })(typeof globalThis !== 'undefined' ? globalThis : window, function agentTranscriptFactory(deps) {

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 = '2.2.0';
+  const BUILD_TARGET_VERSION = '2.3.0';
   const DEFAULT_CHROME_EXTENSION_ID = 'illdpneeeopfffmiepaejglgmhpmdhdc';
   const REQUIRED_CAPABILITIES = Object.freeze([
     'bridgePing',

package/extension/src/shared/governanceRules.js

@@ -8,7 +8,7 @@
     }
     module.exports = factory(projectFiles);
   } else {
-    root.CodexOverleafGovernanceRules = factory(root.CodexOverleafProjectFiles);
+    root.CodexOverleafModuleRegistry.define('GovernanceRules', ['ProjectFiles'], factory);
   }
 })(typeof globalThis !== 'undefined' ? globalThis : window, function governanceRulesFactory(projectFiles) {
   'use strict';

package/extension/src/shared/managedUpdateProjection.js

@@ -0,0 +1,337 @@
+(function initCodexOverleafManagedUpdateProjection(root) {
+  'use strict';
+
+  const PHASE_ALIASES = Object.freeze({
+    waiting: 'waiting_for_idle',
+    waiting_for_safe_point: 'waiting_for_idle',
+    awaiting_health_check: 'awaiting_health',
+    health_checking: 'awaiting_health'
+  });
+
+  const PHASES = Object.freeze([
+    'idle',
+    'up_to_date',
+    'checking',
+    'update_available',
+    'downloading',
+    'staged',
+    'waiting_for_idle',
+    'applying',
+    'awaiting_health',
+    'committed',
+    'failed',
+    'rolling_back',
+    'rolled_back',
+    'deferred'
+  ]);
+
+  const PHASE_TIMEOUTS = Object.freeze({
+    checking: 30 * 1000,
+    downloading: 2 * 60 * 1000,
+    applying: 90 * 1000,
+    awaiting_health: 2 * 60 * 1000,
+    rolling_back: 60 * 1000
+  });
+
+  const PROGRESS = Object.freeze({
+    checking: 8,
+    update_available: 0,
+    downloading: 25,
+    staged: 48,
+    waiting_for_idle: 55,
+    applying: 75,
+    awaiting_health: 90,
+    committed: 100,
+    rolled_back: 100
+  });
+
+  const ACTIVE_STAGE = Object.freeze({
+    downloading: 0,
+    staged: 1,
+    waiting_for_idle: 1,
+    applying: 2,
+    awaiting_health: 2,
+    committed: 3
+  });
+
+  const ACTIVE_PHASES = Object.freeze({
+    update_page: Object.freeze([
+      'checking',
+      'downloading',
+      'staged',
+      'waiting_for_idle',
+      'applying',
+      'awaiting_health'
+    ]),
+    panel: Object.freeze([
+      'downloading',
+      'staged',
+      'waiting_for_idle',
+      'applying',
+      'awaiting_health'
+    ])
+  });
+
+  const TRANSITIONS = Object.freeze({
+    idle: Object.freeze(['checking']),
+    up_to_date: Object.freeze(['checking', 'idle']),
+    checking: Object.freeze(['idle', 'up_to_date', 'update_available', 'failed']),
+    update_available: Object.freeze(['checking', 'downloading', 'deferred', 'failed']),
+    downloading: Object.freeze(['staged', 'failed']),
+    staged: Object.freeze(['waiting_for_idle', 'applying', 'update_available', 'deferred', 'failed']),
+    waiting_for_idle: Object.freeze(['applying', 'update_available', 'deferred', 'failed']),
+    applying: Object.freeze(['staged', 'awaiting_health', 'rolling_back', 'failed']),
+    awaiting_health: Object.freeze(['staged', 'committed', 'rolling_back', 'failed']),
+    committed: Object.freeze(['checking', 'idle']),
+    failed: Object.freeze(['checking', 'rolling_back', 'update_available', 'idle']),
+    rolling_back: Object.freeze(['rolled_back', 'failed']),
+    rolled_back: Object.freeze(['checking', 'idle']),
+    deferred: Object.freeze(['checking', 'update_available', 'idle'])
+  });
+
+  function asObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  }
+
+  function unwrap(value) {
+    const source = asObject(value);
+    return source.state && typeof source.state === 'object' && !Array.isArray(source.state)
+      ? source.state
+      : source;
+  }
+
+  function normalizePhase(value) {
+    const normalized = String(value || 'idle').trim().toLowerCase().replace(/[- ]+/g, '_');
+    return PHASE_ALIASES[normalized] || normalized || 'idle';
+  }
+
+  function phaseOf(value) {
+    if (typeof value === 'string') {
+      return normalizePhase(value);
+    }
+    const source = unwrap(value);
+    return normalizePhase(source.phase || source.status || source.state || source.lifecycle || 'idle');
+  }
+
+  function normalizeBlockers(values, normalizeFn) {
+    if (typeof normalizeFn === 'function') {
+      return normalizeFn(values);
+    }
+    const result = [];
+    const seen = new Set();
+    for (const value of Array.isArray(values) ? values : [values]) {
+      const code = String(value || '').trim();
+      if (!code || seen.has(code)) continue;
+      seen.add(code);
+      result.push(code);
+    }
+    return result;
+  }
+
+  function normalize(value, options = {}) {
+    const source = unwrap(value);
+    const currentVersion = String(
+      source.currentVersion || options.currentVersion || source.latestVersion || ''
+    ).replace(/^v/i, '');
+    const latestVersion = String(
+      source.latestVersion || source.targetVersion || currentVersion
+    ).replace(/^v/i, '');
+    const blockers = normalizeBlockers(
+      Array.isArray(source.blockers) ? source.blockers : (source.blocker ? [source.blocker] : []),
+      options.normalizeBlockers
+    );
+    return {
+      ...source,
+      state: phaseOf(source),
+      managed: source.managed !== false,
+      currentVersion,
+      latestVersion,
+      etag: String(source.etag || ''),
+      lastCheckedAt: Number(source.lastCheckedAt || 0),
+      stagedAt: Number(source.stagedAt || 0),
+      postponeUntil: Number(source.postponeUntil || 0),
+      transactionId: String(source.transactionId || ''),
+      blocker: blockers[0] || '',
+      blockers,
+      code: String(source.code || ''),
+      message: String(source.message || '').slice(0, 300),
+      phaseStartedAt: Number(source.phaseStartedAt || 0),
+      deadlineAt: Number(source.deadlineAt || 0),
+      heartbeatAt: Number(source.heartbeatAt || 0)
+    };
+  }
+
+  function getPhaseTimeoutMs(value) {
+    return Number(PHASE_TIMEOUTS[phaseOf(value)] || 0);
+  }
+
+  function ensurePhaseMetadata(value, options = {}) {
+    const normalized = normalize(value, options);
+    const phase = phaseOf(normalized);
+    const timeoutMs = getPhaseTimeoutMs(phase);
+    if (!timeoutMs) {
+      return {
+        ...normalized,
+        phaseStartedAt: 0,
+        deadlineAt: 0,
+        heartbeatAt: 0
+      };
+    }
+    const now = Number(options.now || Date.now());
+    const phaseStartedAt = Number(normalized.phaseStartedAt || now);
+    return {
+      ...normalized,
+      phaseStartedAt,
+      deadlineAt: Number(normalized.deadlineAt || (phaseStartedAt + timeoutMs)),
+      heartbeatAt: Number(normalized.heartbeatAt || now)
+    };
+  }
+
+  function transition(previous, patch, options = {}) {
+    const prior = normalize(previous, options);
+    const nextSource = buildTransitionSource(prior, patch, options);
+    const nextPhase = phaseOf(nextSource);
+    const previousPhase = phaseOf(prior);
+    if (nextPhase !== previousPhase) {
+      nextSource.phaseStartedAt = 0;
+      nextSource.deadlineAt = 0;
+      nextSource.heartbeatAt = 0;
+    }
+    const transitioned = ensurePhaseMetadata(nextSource, options);
+    if (getPhaseTimeoutMs(nextPhase)) {
+      transitioned.heartbeatAt = Number(options.now || Date.now());
+    }
+    return transitioned;
+  }
+
+  function transitionCommand(previous, patch, options = {}) {
+    const prior = normalize(previous, options);
+    const nextSource = buildTransitionSource(prior, patch, options);
+    const previousPhase = phaseOf(prior);
+    const nextPhase = phaseOf(nextSource);
+    if (!isLegalTransition(previousPhase, nextPhase)) {
+      const error = new Error(`Illegal managed update transition: ${previousPhase} -> ${nextPhase}`);
+      error.code = 'managed_update_transition_invalid';
+      error.from = previousPhase;
+      error.to = nextPhase;
+      throw error;
+    }
+    return transition(prior, nextSource, { ...options, merge: false });
+  }
+
+  function buildTransitionSource(prior, patch, options = {}) {
+    return options.merge === false
+      ? asObject(patch)
+      : { ...prior, ...asObject(patch) };
+  }
+
+  function isLegalTransition(from, to) {
+    const fromPhase = phaseOf(from);
+    const toPhase = phaseOf(to);
+    if (fromPhase === toPhase) return true;
+    return (TRANSITIONS[fromPhase] || []).includes(toPhase);
+  }
+
+  function reconcile(value, transaction, options = {}) {
+    const state = normalize(value, options);
+    const native = asObject(transaction);
+    if (native.state === 'rolled_back') {
+      return {
+        action: 'reload_tabs',
+        state: transition(state, {
+          state: 'rolled_back',
+          currentVersion: native.sourceVersion || state.currentVersion,
+          transactionId: native.id || state.transactionId,
+          code: native.reasonCode || state.code || 'update_rolled_back'
+        }, options)
+      };
+    }
+    if (native.state === 'committed') {
+      const targetVersion = native.targetVersion || state.latestVersion || state.currentVersion;
+      return {
+        action: 'reload_tabs',
+        state: transition(state, {
+          state: 'committed',
+          currentVersion: targetVersion,
+          latestVersion: targetVersion,
+          transactionId: '',
+          blocker: '',
+          blockers: [],
+          code: '',
+          message: ''
+        }, options)
+      };
+    }
+    if (native.state === 'staged' && ['applying', 'awaiting_health'].includes(phaseOf(state))) {
+      return {
+        action: 'retry_install',
+        state: transition(state, {
+          state: 'staged',
+          transactionId: native.id || state.transactionId,
+          blocker: '',
+          blockers: [],
+          code: '',
+          message: ''
+        }, options)
+      };
+    }
+    if (!native.state && ['applying', 'awaiting_health', 'rolling_back'].includes(phaseOf(state))) {
+      return {
+        action: 'none',
+        state: transition(state, {
+          state: 'failed',
+          code: 'update_transaction_lost',
+          message: options.transactionLostMessage
+            || 'The managed update transaction could not be recovered. Use the manual update command.'
+        }, options)
+      };
+    }
+    return { action: 'none', state };
+  }
+
+  function progressFor(value) {
+    const source = asObject(value);
+    const raw = asObject(source.progress).percent
+      ?? asObject(source.progress).value
+      ?? source.progressPercent
+      ?? (typeof source.progress === 'number' ? source.progress : undefined);
+    if (Number.isFinite(Number(raw))) {
+      const numeric = Number(raw);
+      return Math.max(0, Math.min(100, numeric <= 1 ? numeric * 100 : numeric));
+    }
+    return Number(PROGRESS[phaseOf(value)] || 0);
+  }
+
+  function activeStageFor(value) {
+    return ACTIVE_STAGE[phaseOf(value)] ?? -1;
+  }
+
+  function activePhases(surface = 'update_page') {
+    return [...(ACTIVE_PHASES[surface] || ACTIVE_PHASES.update_page)];
+  }
+
+  function isActive(value, surface = 'update_page') {
+    return activePhases(surface).includes(phaseOf(value));
+  }
+
+  root.CodexOverleafManagedUpdateProjection = Object.freeze({
+    ACTIVE_PHASES,
+    PHASE_ALIASES,
+    PHASE_TIMEOUTS,
+    PHASES,
+    PROGRESS,
+    TRANSITIONS,
+    activePhases,
+    activeStageFor,
+    ensurePhaseMetadata,
+    getPhaseTimeoutMs,
+    isActive,
+    isLegalTransition,
+    normalize,
+    phaseOf,
+    progressFor,
+    reconcile,
+    transition,
+    transitionCommand
+  });
+})(typeof window !== 'undefined' ? window : globalThis);

package/extension/src/shared/nativeRequestIdentity.js

@@ -0,0 +1,60 @@
+(function initNativeRequestIdentity(root, factory) {
+  const api = factory();
+  if (typeof module === "object" && module.exports) {
+    module.exports = api;
+  }
+  if (root) {
+    root.CodexOverleafNativeRequestIdentity = api;
+  }
+})(typeof globalThis !== "undefined" ? globalThis : this, function createNativeRequestIdentity() {
+  "use strict";
+
+  const MAX_REQUEST_ID_CHARS = 160;
+
+  function invalidIdentity(value) {
+    return {
+      ok: false,
+      error: {
+        code: "native_request_id_invalid",
+        message:
+          `Native request id must be a finite number or a non-empty string no longer than ${MAX_REQUEST_ID_CHARS} characters.`,
+        details: {
+          actualType: value === null ? "null" : typeof value,
+          actualLength: typeof value === "string" ? value.length : null,
+          limit: MAX_REQUEST_ID_CHARS
+        }
+      }
+    };
+  }
+
+  function validate(value) {
+    if (typeof value === "number") {
+      return Number.isFinite(value) ? { ok: true, id: value } : invalidIdentity(value);
+    }
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_REQUEST_ID_CHARS) {
+      return invalidIdentity(value);
+    }
+    return { ok: true, id: value };
+  }
+
+  function resolve(value, randomUUID) {
+    if (value === undefined || value === null || value === "") {
+      const generate =
+        typeof randomUUID === "function"
+          ? randomUUID
+          : typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+            ? () => crypto.randomUUID()
+            : null;
+      if (!generate) {
+        return invalidIdentity(value);
+      }
+      return validate(generate());
+    }
+    return validate(value);
+  }
+
+  return Object.freeze({
+    MAX_REQUEST_ID_CHARS,
+    resolve
+  });
+});

package/extension/src/shared/otText.js

@@ -274,28 +274,9 @@
 
   function hashText(text) {
     const value = String(text ?? '');
-    const nodeCrypto = getNodeCrypto();
-    if (nodeCrypto) {
-      return nodeCrypto.createHash('sha256').update(value, 'utf8').digest('hex');
-    }
     return sha256Hex(utf8Bytes(value));
   }
 
-  function getNodeCrypto() {
-    if (typeof require !== 'function') {
-      return null;
-    }
-    try {
-      return require('node:crypto');
-    } catch (error) {
-      try {
-        return require('crypto');
-      } catch (fallbackError) {
-        return null;
-      }
-    }
-  }
-
   function normalizePath(value) {
     return String(value || '')
       .replace(/\s+/g, ' ')