Spaces:
Sleeping
Sleeping
File size: 7,890 Bytes
82fdec7 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 |
# Chrome extension -- Rebrowse
## File structure
- place of manifest.json
at MacOS:
## Tech architecture
- overall

### UI arc
1. Chrome Extension UI (e.g., popup.html):
- Primary Role: Quick, in-context actions related to the active browser tab.
- Functionality:
- "Start Recording" button: Sends a message to background.js, which in turn will send a native message to host.py to initiate recording for the active tab.
- "Stop Recording" button: Similarly, tells host.py via background.js to stop recording and save the trace.
- Status: Could show very basic status like "Recording" / "Idle" / "Error". This status would likely be pushed from host.py back to background.js and then to the popup.
2. Gradio UI (webui.py):
- Primary Role: More comprehensive trace management, replay functionality, detailed status display, and configuration.
- Functionality:
- Trace Management: Listing, selecting trace files (as you currently have).
- Replay: Initiating and controlling the replay of selected traces (as you currently have).
- Detailed Status/Logs: Displaying logs and status updates originating from host.py (e.g., "Connected to browser," "CDP event received," "Recording started/stopped," errors from the native host). This is a key part of our minimal release.
- Configuration: (Future) Settings related to recording, replay, etc.
### Process Sequence
1. Triggering a trace from Gradio and replaying
- NamePipe: a Streaming method of inter-process communication (IPC) that allows processes to communicate through a shared memory buffer.
`host.py`(one-writer) adn `webui.py`(one-reader) is connected with namepipe.
- multi-thread: we’ll graduate to Unix-domain sockets or a message broker for multi-reader or cross-machine delivery.
- Note: The chosen path /tmp/rebrowse_host_status.pipe is common for temporary pipes on Unix-like systems (Linux, macOS). on Windows, pywin32 library or a different IPC mechanism like sockets.

| Step | Detail |
| ------------------------ | ------------------------ |
| 1. Gradio action | The “Replay” button in `webui.py` calls an async function that writes a JSON command to the **FIFO** or hits a tiny HTTP endpoint exposed by `host.py`. |
| 2. Native host picks tab | Because the extension already sent the active `tabId` when it started recording, `host.py` can resolve “same tab” by that ID or ask `background.js` for the current active tab if none recorded. |
| 3. Native-message bridge | `host.py` sends `{cmd:"replay", trace:<array_of_steps>, tabId}` via `stdout`. `background.js` receives it in `chrome.runtime.onMessageExternal`. |
| 4. Replay driver | The **simplest path** is for `background.js` to loop over the JSONL entries and translate each into a CDP call with `chrome.debugger.sendCommand`— ⚠️no Playwright needed for replay. If you already have a Playwright “replayer” written, run it inside `host.py` *connected to the same Chrome instance* (`chromium.connect_over_cdp("http://localhost:9222")`). |
| 5. Status back-flow | After each step, `background.js` posts `{"phase":"replay","step":n}` back to `host.py`, which writes “Replay 35 %” into the FIFO, so Gradio’s textbox autoscrolls. |
## Shipping layout
| Artifact | File(s) | How user gets it |
| ----------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **1. Chrome Extension** | `rebrowse_ext.zip` → Web Store | • Contains `manifest.json`, `background.js`, `content.js`, icons, popup.<br>• Lists permission `"nativeMessaging"` and host name `"com.rebrowse.host"`. |
| **2. Native Host bundle** | **macOS `.pkg` installer** <br>*(or `.dmg` drag-and-drop)* | • Installs `rebrowse_native` self-contained binary (PyInstaller/Nuitka) to `/usr/local/bin/`.<br>• Drops `com.rebrowse.host.json` into the NativeMessagingHosts folder, pointing at that binary.<br>• Optionally adds a LaunchAgent so the binary runs head-less at login (hosting Gradio on `localhost:7860`). |
| *(optional)* Thin menubar app | `RebrowseTray.app` | Bundled inside the same `.pkg`; just UI glue that talks to `localhost:7860`. |
## Functionalities must-stay at local
- Yes—cloud can own storage, scheduling, analytics, auth.
- No—real-time browser control still needs a local process (or all-JS code in the extension) because of Chrome security boundaries.
- Path forward: shrink host.py to a minimal relay, migrate everything else to your cloud dashboard, and revisit an all-extension architecture once your replay/record logic is fully ported to TypeScript.
| Need | Why cloud can’t replace it |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **CDP commands** (`Input.dispatchKeyEvent`, `DOM.click`) | Chrome blocks remote WebSockets from the public Internet; only a process on `127.0.0.1` that owns the debugging port can drive the tab. |
| **Native file dialogs / clipboard** | Clipboard / file-picker APIs are exposed only to extensions or native apps, not to remote origins. |
| **Low-latency event feedback** | 20-50 ms round-trip over localhost vs. 200 + ms to the nearest PoP; user-perceived lag matters for live overlays, type-ahead, etc. |
|