diff --git a/.gitignore b/.gitignore index 90ffdcd..ed25b17 100644 --- a/.gitignore +++ b/.gitignore @@ -8,4 +8,5 @@ /node_modules npm-debug.log.** npm-debug.log -.DS_Store \ No newline at end of file +.DS_Store +/safari-xcode \ No newline at end of file diff --git a/documentation/safari-extension.md b/documentation/safari-extension.md new file mode 100644 index 0000000..ef1599a --- /dev/null +++ b/documentation/safari-extension.md @@ -0,0 +1,73 @@ +[SpectorJS](../readme.md) +========= + +## Safari Extension + +Spector.js is available as a Safari Web Extension for macOS. Since Safari requires extensions to be wrapped in a native macOS app, the build process involves both npm and Xcode. + +### Prerequisites + +- macOS with Xcode installed (Xcode 14+) +- [Apple Developer account](https://developer.apple.com/) (required for distribution; not needed for local testing) +- Node.js and npm + +### Building the Safari Extension + +1. **Build the Spector.js bundle:** + ```bash + npm install + npm run build + ``` + This compiles the core library and copies `spector.bundle.js` into `safari-extension/`. + +2. **Generate the Xcode project** (first time only): + ```bash + xcrun safari-web-extension-converter safari-extension/ \ + --project-location safari-xcode \ + --app-name "Spector.js" \ + --bundle-identifier com.babylonjs.spectorjs \ + --macos-only \ + --no-open + ``` + This creates a macOS app project in `safari-xcode/` that wraps the web extension. + +3. **Build and run from Xcode:** + - Open `safari-xcode/Spector.js/Spector.js.xcodeproj` in Xcode + - Select your development team under Signing & Capabilities + - Build and run (⌘R) + +### Development Workflow + +1. **Enable unsigned extensions** in Safari: + - Open Safari → Settings → Advanced → check "Show features for web developers" + - Then Safari → Settings → Developer → check "Allow unsigned extensions" + +2. **Build and run** the Xcode project — Safari will load the extension automatically. + +3. **Iterate on extension code:** After editing files in `safari-extension/`, rebuild in Xcode (⌘R). For changes to the core Spector library in `src/`, run `npm run build` first. + +4. **Test** using the sample pages at `http://localhost:1337/sample/index.html` (run `npm start` for the dev server). + +### Architecture Differences from Chrome/Firefox + +The Safari extension uses a single content script in the default ISOLATED world (Safari does not support Manifest V3's `"world": "MAIN"`). To interact with page-level JavaScript: + +- **getContext() interception** and **Spector initialization** are injected into the page via ` + + + + +
++ Drag previously saved captures here to open. +
+