catalyst-core 0.2.0-beta.2 → 0.3.0-beta.1

package/dist/native/internalPluginUtils.js

@@ -1,7 +1,232 @@
-"use strict";const fs=require("fs");const path=require("path");function isDir(dirPath){return fs.existsSync(dirPath)&&fs.statSync(dirPath).isDirectory();}function mustBeNonEmptyString(value,fieldName,sourcePath){if(typeof value!=="string"||!value.trim()){throw new Error(`Invalid '${fieldName}' in ${sourcePath}`);}return value.trim();}function readStringArray(value,fieldName,sourcePath,{required=false,nonEmpty=false}={}){if(!Array.isArray(value)){if(required){throw new Error(`'${fieldName}' is required and must be an array in ${sourcePath}`);}return[];}const result=value.map(entry=>mustBeNonEmptyString(entry,`${fieldName}[]`,sourcePath));if(nonEmpty&&result.length===0){throw new Error(`'${fieldName}' is required and must be non-empty in ${sourcePath}`);}return result;}function readPlainObject(value,fieldName,sourcePath){if(value==null){return{};}if(!value||typeof value!=="object"||Array.isArray(value)){throw new Error(`'${fieldName}' must be an object in ${sourcePath}`);}return value;}function cloneJsonValue(value,fieldName,sourcePath){try{return JSON.parse(JSON.stringify(value));}catch(error){throw new Error(`'${fieldName}' must be JSON-serializable in ${sourcePath}`);}}function readIosUrlSchemes(value,fieldName,sourcePath){if(value==null){return[];}if(!Array.isArray(value)){throw new Error(`'${fieldName}' must be an array in ${sourcePath}`);}return value.map((entry,index)=>{const entryField=`${fieldName}[${index}]`;if(!entry||typeof entry!=="object"||Array.isArray(entry)){throw new Error(`'${entryField}' must be an object in ${sourcePath}`);}return{name:entry.name==null?null:mustBeNonEmptyString(entry.name,`${entryField}.name`,sourcePath),schemes:readStringArray(entry.schemes,`${entryField}.schemes`,sourcePath,{required:true,nonEmpty:true})};});}function readIosDependencies(value,fieldName,sourcePath){if(value==null){return[];}if(!Array.isArray(value)){throw new Error(`'${fieldName}' must be an array in ${sourcePath}`);}return value.map((entry,index)=>{const entryField=`${fieldName}[${index}]`;if(!entry||typeof entry!=="object"||Array.isArray(entry)){throw new Error(`'${entryField}' must be an object in ${sourcePath}`);}const url=mustBeNonEmptyString(entry.url,`${entryField}.url`,sourcePath);const packageIdentity=entry.package==null?derivePackageIdentityFromUrl(url,`${entryField}.url`,sourcePath):mustBeNonEmptyString(entry.package,`${entryField}.package`,sourcePath);const products=readStringArray(entry.products,`${entryField}.products`,sourcePath,{required:true,nonEmpty:true});if(new Set(products).size!==products.length){throw new Error(`Duplicate product(s) found in '${entryField}.products' in ${sourcePath}`);}const hasFrom=entry.from!=null;const hasExact=entry.exact!=null;if(hasFrom===hasExact){throw new Error(`'${entryField}' must define exactly one version requirement: 'from' or 'exact' in ${sourcePath}`);}return{url,package:packageIdentity,products,requirement:hasFrom?{type:"from",version:mustBeNonEmptyString(entry.from,`${entryField}.from`,sourcePath)}:{type:"exact",version:mustBeNonEmptyString(entry.exact,`${entryField}.exact`,sourcePath)}};});}function derivePackageIdentityFromUrl(url,fieldName,sourcePath){const sanitizedUrl=url.replace(/\/+$/,"");const packageIdentity=sanitizedUrl.split("/").pop()?.replace(/\.git$/,"");if(!packageIdentity){throw new Error(`Unable to derive package identity from '${fieldName}' in ${sourcePath}`);}return packageIdentity;}function parsePluginManifest(pluginDir){// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - pluginDir is discovered from the internal plugin root and the filename is fixed.
-const manifestPath=path.join(pluginDir,"manifest.json");if(!fs.existsSync(manifestPath)){return null;}let manifestContent;try{manifestContent=fs.readFileSync(manifestPath,"utf8");}catch(error){throw new Error(`Failed to read plugin manifest at ${manifestPath}: ${error.message}`);}let manifest;try{manifest=JSON.parse(manifestContent);}catch(error){throw new Error(`Invalid JSON in plugin manifest ${manifestPath}: ${error.message}`);}const id=mustBeNonEmptyString(manifest.id,"id",manifestPath);const configKey=mustBeNonEmptyString(manifest.configKey,"configKey",manifestPath);const platforms=readStringArray(manifest.platforms,"platforms",manifestPath,{required:true,nonEmpty:true});const androidConfig=platforms.includes("android")?manifest.android:null;const iosConfig=platforms.includes("ios")?manifest.ios:null;if(platforms.includes("android")&&(!androidConfig||typeof androidConfig!=="object")){throw new Error(`'android' config is required for plugin '${id}' in ${manifestPath}`);}if(platforms.includes("ios")&&(!iosConfig||typeof iosConfig!=="object")){throw new Error(`'ios' config is required for plugin '${id}' in ${manifestPath}`);}return{pluginDir,manifestPath,id,configKey,version:mustBeNonEmptyString(manifest.version,"version",manifestPath),displayName:mustBeNonEmptyString(manifest.displayName,"displayName",manifestPath),description:mustBeNonEmptyString(manifest.description,"description",manifestPath),category:mustBeNonEmptyString(manifest.category,"category",manifestPath),platforms,commands:readStringArray(manifest.commands,"commands",manifestPath,{required:true,nonEmpty:true}),android:androidConfig?{// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - pluginDir is discovered from the internal plugin root and the child directory is fixed.
-sourceDir:path.join(pluginDir,"android"),permissions:readStringArray(androidConfig.permissions,"android.permissions",manifestPath),dependencies:readStringArray(androidConfig.dependencies,"android.dependencies",manifestPath),className:mustBeNonEmptyString(androidConfig.className,"android.className",manifestPath)}:null,ios:iosConfig?{// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - pluginDir is discovered from the internal plugin root and the child directory is fixed.
-sourceDir:path.join(pluginDir,"ios"),dependencies:readIosDependencies(iosConfig.dependencies,"ios.dependencies",manifestPath),className:mustBeNonEmptyString(iosConfig.className,"ios.className",manifestPath),infoPlist:cloneJsonValue(readPlainObject(iosConfig.infoPlist,"ios.infoPlist",manifestPath),"ios.infoPlist",manifestPath),urlSchemes:readIosUrlSchemes(iosConfig.urlSchemes,"ios.urlSchemes",manifestPath),querySchemes:readStringArray(iosConfig.querySchemes,"ios.querySchemes",manifestPath),entitlements:cloneJsonValue(readPlainObject(iosConfig.entitlements,"ios.entitlements",manifestPath),"ios.entitlements",manifestPath),resources:readStringArray(iosConfig.resources,"ios.resources",manifestPath)}:null};}function discoverInternalPlugins(corePluginsRoot,log=()=>{}){if(!corePluginsRoot||!isDir(corePluginsRoot)){log(`No internal plugin directory found at ${corePluginsRoot||"<empty>"}`,"info");return[];}const plugins=[];const entries=fs.readdirSync(corePluginsRoot,{withFileTypes:true}).sort((left,right)=>left.name.localeCompare(right.name));for(const entry of entries){if(!entry.isDirectory()){continue;}// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - entry.name comes from readdirSync under the internal plugin root.
-const pluginDir=path.join(corePluginsRoot,entry.name);const parsed=parsePluginManifest(pluginDir);if(parsed){plugins.push(parsed);}}log(`Discovered ${plugins.length} internal plugin manifest(s)`,"info");return plugins;}function resolveInternalPluginsRoot(packageRoot){// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - These are fixed package-internal directories.
-const distPluginsPath=path.join(packageRoot,"dist","native","internal-plugins");// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - These are fixed package-internal directories.
-const srcPluginsPath=path.join(packageRoot,"src","native","internal-plugins");return fs.existsSync(distPluginsPath)?distPluginsPath:srcPluginsPath;}function resolvePluginConfig(WEBVIEW_CONFIG){const pluginConfig={};if(WEBVIEW_CONFIG.plugins!=null){if(typeof WEBVIEW_CONFIG.plugins!=="object"||Array.isArray(WEBVIEW_CONFIG.plugins)){throw new Error("'WEBVIEW_CONFIG.plugins' must be an object with boolean values");}for(const[key,value]of Object.entries(WEBVIEW_CONFIG.plugins)){if(typeof value!=="boolean"){throw new Error(`'WEBVIEW_CONFIG.plugins.${key}' must be boolean`);}pluginConfig[key]=value;}}return pluginConfig;}module.exports={discoverInternalPlugins,parsePluginManifest,resolvePluginConfig,resolveInternalPluginsRoot};
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+function isDir(dirPath) {
+  return fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory();
+}
+function mustBeNonEmptyString(value, fieldName, sourcePath) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`Invalid '${fieldName}' in ${sourcePath}`);
+  }
+  return value.trim();
+}
+function readStringArray(value, fieldName, sourcePath, {
+  required = false,
+  nonEmpty = false
+} = {}) {
+  if (!Array.isArray(value)) {
+    if (required) {
+      throw new Error(`'${fieldName}' is required and must be an array in ${sourcePath}`);
+    }
+    return [];
+  }
+  const result = value.map(entry => mustBeNonEmptyString(entry, `${fieldName}[]`, sourcePath));
+  if (nonEmpty && result.length === 0) {
+    throw new Error(`'${fieldName}' is required and must be non-empty in ${sourcePath}`);
+  }
+  return result;
+}
+function readPlainObject(value, fieldName, sourcePath) {
+  if (value == null) {
+    return {};
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`'${fieldName}' must be an object in ${sourcePath}`);
+  }
+  return value;
+}
+function cloneJsonValue(value, fieldName, sourcePath) {
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch (error) {
+    throw new Error(`'${fieldName}' must be JSON-serializable in ${sourcePath}`);
+  }
+}
+function readIosUrlSchemes(value, fieldName, sourcePath) {
+  if (value == null) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`'${fieldName}' must be an array in ${sourcePath}`);
+  }
+  return value.map((entry, index) => {
+    const entryField = `${fieldName}[${index}]`;
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`'${entryField}' must be an object in ${sourcePath}`);
+    }
+    return {
+      name: entry.name == null ? null : mustBeNonEmptyString(entry.name, `${entryField}.name`, sourcePath),
+      schemes: readStringArray(entry.schemes, `${entryField}.schemes`, sourcePath, {
+        required: true,
+        nonEmpty: true
+      })
+    };
+  });
+}
+function readIosDependencies(value, fieldName, sourcePath) {
+  if (value == null) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`'${fieldName}' must be an array in ${sourcePath}`);
+  }
+  return value.map((entry, index) => {
+    const entryField = `${fieldName}[${index}]`;
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`'${entryField}' must be an object in ${sourcePath}`);
+    }
+    const url = mustBeNonEmptyString(entry.url, `${entryField}.url`, sourcePath);
+    const packageIdentity = entry.package == null ? derivePackageIdentityFromUrl(url, `${entryField}.url`, sourcePath) : mustBeNonEmptyString(entry.package, `${entryField}.package`, sourcePath);
+    const products = readStringArray(entry.products, `${entryField}.products`, sourcePath, {
+      required: true,
+      nonEmpty: true
+    });
+    if (new Set(products).size !== products.length) {
+      throw new Error(`Duplicate product(s) found in '${entryField}.products' in ${sourcePath}`);
+    }
+    const hasFrom = entry.from != null;
+    const hasExact = entry.exact != null;
+    if (hasFrom === hasExact) {
+      throw new Error(`'${entryField}' must define exactly one version requirement: 'from' or 'exact' in ${sourcePath}`);
+    }
+    return {
+      url,
+      package: packageIdentity,
+      products,
+      requirement: hasFrom ? {
+        type: "from",
+        version: mustBeNonEmptyString(entry.from, `${entryField}.from`, sourcePath)
+      } : {
+        type: "exact",
+        version: mustBeNonEmptyString(entry.exact, `${entryField}.exact`, sourcePath)
+      }
+    };
+  });
+}
+function derivePackageIdentityFromUrl(url, fieldName, sourcePath) {
+  const sanitizedUrl = url.replace(/\/+$/, "");
+  const packageIdentity = sanitizedUrl.split("/").pop()?.replace(/\.git$/, "");
+  if (!packageIdentity) {
+    throw new Error(`Unable to derive package identity from '${fieldName}' in ${sourcePath}`);
+  }
+  return packageIdentity;
+}
+function parsePluginManifest(pluginDir) {
+  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - pluginDir is discovered from the internal plugin root and the filename is fixed.
+  const manifestPath = path.join(pluginDir, "manifest.json");
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+  let manifestContent;
+  try {
+    manifestContent = fs.readFileSync(manifestPath, "utf8");
+  } catch (error) {
+    throw new Error(`Failed to read plugin manifest at ${manifestPath}: ${error.message}`);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(manifestContent);
+  } catch (error) {
+    throw new Error(`Invalid JSON in plugin manifest ${manifestPath}: ${error.message}`);
+  }
+  const id = mustBeNonEmptyString(manifest.id, "id", manifestPath);
+  const configKey = mustBeNonEmptyString(manifest.configKey, "configKey", manifestPath);
+  const platforms = readStringArray(manifest.platforms, "platforms", manifestPath, {
+    required: true,
+    nonEmpty: true
+  });
+  const androidConfig = platforms.includes("android") ? manifest.android : null;
+  const iosConfig = platforms.includes("ios") ? manifest.ios : null;
+  if (platforms.includes("android") && (!androidConfig || typeof androidConfig !== "object")) {
+    throw new Error(`'android' config is required for plugin '${id}' in ${manifestPath}`);
+  }
+  if (platforms.includes("ios") && (!iosConfig || typeof iosConfig !== "object")) {
+    throw new Error(`'ios' config is required for plugin '${id}' in ${manifestPath}`);
+  }
+  return {
+    pluginDir,
+    manifestPath,
+    id,
+    configKey,
+    version: mustBeNonEmptyString(manifest.version, "version", manifestPath),
+    displayName: mustBeNonEmptyString(manifest.displayName, "displayName", manifestPath),
+    description: mustBeNonEmptyString(manifest.description, "description", manifestPath),
+    category: mustBeNonEmptyString(manifest.category, "category", manifestPath),
+    platforms,
+    commands: readStringArray(manifest.commands, "commands", manifestPath, {
+      required: true,
+      nonEmpty: true
+    }),
+    android: androidConfig ? {
+      // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - pluginDir is discovered from the internal plugin root and the child directory is fixed.
+      sourceDir: path.join(pluginDir, "android"),
+      permissions: readStringArray(androidConfig.permissions, "android.permissions", manifestPath),
+      dependencies: readStringArray(androidConfig.dependencies, "android.dependencies", manifestPath),
+      className: mustBeNonEmptyString(androidConfig.className, "android.className", manifestPath)
+    } : null,
+    ios: iosConfig ? {
+      // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - pluginDir is discovered from the internal plugin root and the child directory is fixed.
+      sourceDir: path.join(pluginDir, "ios"),
+      dependencies: readIosDependencies(iosConfig.dependencies, "ios.dependencies", manifestPath),
+      className: mustBeNonEmptyString(iosConfig.className, "ios.className", manifestPath),
+      infoPlist: cloneJsonValue(readPlainObject(iosConfig.infoPlist, "ios.infoPlist", manifestPath), "ios.infoPlist", manifestPath),
+      urlSchemes: readIosUrlSchemes(iosConfig.urlSchemes, "ios.urlSchemes", manifestPath),
+      querySchemes: readStringArray(iosConfig.querySchemes, "ios.querySchemes", manifestPath),
+      entitlements: cloneJsonValue(readPlainObject(iosConfig.entitlements, "ios.entitlements", manifestPath), "ios.entitlements", manifestPath),
+      resources: readStringArray(iosConfig.resources, "ios.resources", manifestPath)
+    } : null
+  };
+}
+function discoverInternalPlugins(corePluginsRoot, log = () => {}) {
+  if (!corePluginsRoot || !isDir(corePluginsRoot)) {
+    log(`No internal plugin directory found at ${corePluginsRoot || "<empty>"}`, "info");
+    return [];
+  }
+  const plugins = [];
+  const entries = fs.readdirSync(corePluginsRoot, {
+    withFileTypes: true
+  }).sort((left, right) => left.name.localeCompare(right.name));
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - entry.name comes from readdirSync under the internal plugin root.
+    const pluginDir = path.join(corePluginsRoot, entry.name);
+    const parsed = parsePluginManifest(pluginDir);
+    if (parsed) {
+      plugins.push(parsed);
+    }
+  }
+  log(`Discovered ${plugins.length} internal plugin manifest(s)`, "info");
+  return plugins;
+}
+function resolveInternalPluginsRoot(packageRoot) {
+  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - These are fixed package-internal directories.
+  const distPluginsPath = path.join(packageRoot, "dist", "native", "internal-plugins");
+  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - These are fixed package-internal directories.
+  const srcPluginsPath = path.join(packageRoot, "src", "native", "internal-plugins");
+  return fs.existsSync(distPluginsPath) ? distPluginsPath : srcPluginsPath;
+}
+function resolvePluginConfig(WEBVIEW_CONFIG) {
+  const pluginConfig = {};
+  if (WEBVIEW_CONFIG.plugins != null) {
+    if (typeof WEBVIEW_CONFIG.plugins !== "object" || Array.isArray(WEBVIEW_CONFIG.plugins)) {
+      throw new Error("'WEBVIEW_CONFIG.plugins' must be an object with boolean values");
+    }
+    for (const [key, value] of Object.entries(WEBVIEW_CONFIG.plugins)) {
+      if (typeof value !== "boolean") {
+        throw new Error(`'WEBVIEW_CONFIG.plugins.${key}' must be boolean`);
+      }
+      pluginConfig[key] = value;
+    }
+  }
+  return pluginConfig;
+}
+module.exports = {
+  discoverInternalPlugins,
+  parsePluginManifest,
+  resolvePluginConfig,
+  resolveInternalPluginsRoot
+};

package/dist/native/iosnativeWebView/Sources/Core/Constants/CatalystConstants.swift

@@ -54,6 +54,21 @@ public enum CatalystConstants {
 
     // MARK: - Bridge Limits / Validation
     public enum Bridge {
+        public static let isDebugBuild: Bool = {
+            #if DEBUG
+            return true
+            #else
+            return false
+            #endif
+        }()
+
+        public static func isTraceExportEnabled(
+            debugBuild: Bool = isDebugBuild,
+            profilerEnabled: Bool = ConfigConstants.Profiler.enabled
+        ) -> Bool {
+            debugBuild && profilerEnabled
+        }
+
         // Safety limit for inbound JS message size (128 KB)
         public static let maxMessageSize: Int = 128 * 1024
         // Command execution timeout window
@@ -86,6 +101,10 @@ public enum CatalystConstants {
                 "cancelTransition"
             ]
 
+            if isTraceExportEnabled() {
+                commands.insert("exportCatalystTrace")
+            }
+
             // Check if notifications are enabled via config
             // When enabled, CatalystNotifications module will be available at app layer
             if ConfigConstants.Notifications.enabled {

package/dist/native/iosnativeWebView/Sources/Core/Constants/ConfigConstants.swift

@@ -22,6 +22,10 @@ public enum ConfigConstants {
         public static let iosClientId = ""
     }
 
+    public enum Profiler {
+        public static let enabled = false
+    }
+
     public static let appInfo = "test-build"
     public static let cachePattern: [String] = []
     public static let LOCAL_IP = "localhost" // swiftlint:disable:this identifier_name

package/dist/native/iosnativeWebView/Sources/Core/Utils/BootTimingUtility.swift

@@ -9,6 +9,10 @@
 import Foundation
 import os
 
+enum AppBoot {
+    static let nativeStartMs = Int64(ProcessInfo.processInfo.systemUptime * 1000)
+}
+
 #if DEBUG
 // Global app launch timestamp for all timing measurements
 let APP_LAUNCH_TIME = CFAbsoluteTimeGetCurrent()
@@ -23,4 +27,4 @@ public func logWithTimestamp(_ message: String) {
 #else
 // No-op in release builds
 public func logWithTimestamp(_ message: String) {}
-#endif
+#endif

package/dist/native/iosnativeWebView/Sources/Core/Utils/CacheManager.swift

@@ -201,6 +201,7 @@ public final class CacheManager {
     
     private func revalidateResource(request: URLRequest) async {
         logger.info("🔄 Starting revalidation for: \(request.url?.absoluteString ?? "")")
+        let fetchStartMs = CatalystPerf.nativeTimeMs()
         
         do {
             let configuration = URLSessionConfiguration.ephemeral
@@ -210,6 +211,15 @@ public final class CacheManager {
             
             if let httpResponse = response as? HTTPURLResponse,
                isCacheableResponse(httpResponse, for: request) {
+                CatalystPerf.add([
+                    "type": "network-fetch-complete",
+                    "url": request.url?.absoluteString ?? "",
+                    "statusCode": httpResponse.statusCode,
+                    "resourceType": "document",
+                    "nativeTime": fetchStartMs,
+                    "nativeStartMs": fetchStartMs,
+                    "durationMs": CatalystPerf.nativeTimeMs() - fetchStartMs,
+                ])
                 storeCachedResponse(httpResponse, data: data, for: request)
                 logger.info("Resource revalidated: \(request.url?.absoluteString ?? "")")
             }

package/dist/native/iosnativeWebView/Sources/Core/Utils/DisplayLinkPerfMonitor.swift

@@ -0,0 +1,89 @@
+import UIKit
+import WebKit
+
+final class DisplayLinkPerfMonitor {
+    private weak var webView: WKWebView?
+    private var displayLink: CADisplayLink?
+    private var dropStartMs: Int64?
+    private var minFps: Double = 60
+    private var fpsSum: Double = 0
+    private var sampleCount = 0
+    private var lastTimestamp: CFTimeInterval?
+    private var lastStableFps: Double = 60
+    private var dropBaselineFps: Double = 60
+
+    private let dropThresholdFps = 55.0
+    private let minDropDurationMs: Int64 = 250
+
+    init(webView: WKWebView) {
+        self.webView = webView
+    }
+
+    func start() {
+        guard displayLink == nil else { return }
+        let link = CADisplayLink(target: self, selector: #selector(tick(_:)))
+        link.add(to: .main, forMode: .common)
+        displayLink = link
+    }
+
+    func stop() {
+        displayLink?.invalidate()
+        displayLink = nil
+        dropStartMs = nil
+        sampleCount = 0
+        fpsSum = 0
+        minFps = 60
+        lastTimestamp = nil
+        lastStableFps = 60
+        dropBaselineFps = 60
+    }
+
+    @objc private func tick(_ link: CADisplayLink) {
+        defer { lastTimestamp = link.timestamp }
+        guard let lastTimestamp else { return }
+        let frameDuration = link.timestamp - lastTimestamp
+        guard frameDuration > 0 else { return }
+        let fps = min(60.0, 1.0 / frameDuration)
+        let now = CatalystPerf.nativeTimeMs()
+
+        if fps < dropThresholdFps {
+            if dropStartMs == nil {
+                dropStartMs = now
+                minFps = fps
+                fpsSum = 0
+                sampleCount = 0
+                dropBaselineFps = lastStableFps
+            }
+            minFps = min(minFps, fps)
+            fpsSum += fps
+            sampleCount += 1
+            return
+        }
+
+        guard let startMs = dropStartMs else {
+            lastStableFps = fps
+            return
+        }
+        let durationMs = now - startMs
+        if durationMs >= minDropDurationMs, sampleCount > 0 {
+            CatalystPerf.emit([
+                "type": "fps-drop-episode",
+                "nativeTime": startMs,
+                "startNativeTime": startMs,
+                "endNativeTime": now,
+                "durationMs": durationMs,
+                "minFps": minFps,
+                "avgFps": fpsSum / Double(sampleCount),
+                "deltaFps": dropBaselineFps - minFps,
+                "baselineFps": dropBaselineFps,
+                "thread": Thread.current.name ?? "main",
+            ], to: webView)
+        }
+
+        lastStableFps = fps
+        dropStartMs = nil
+        sampleCount = 0
+        fpsSum = 0
+        minFps = 60
+    }
+}