Skip to content

[codex] Sync local validation and Firefox compatibility updates - #1

Merged
Utkarsh-Sinha0 merged 2 commits into
mainfrom
codex/sync-local-validation-firefox
Mar 17, 2026
Merged

Utkarsh-Sinha0 merged 2 commits into
mainfrom
codex/sync-local-validation-firefox

Conversation

@Utkarsh-Sinha0

@Utkarsh-Sinha0 Utkarsh-Sinha0 commented Mar 17, 2026

Copy link
Copy Markdown
Owner

Summary

This PR syncs GitHub with the full local SNAPV project state and carries the browser-extension validation and Firefox compatibility work that was completed locally. The branch is intended to make the remote repository match the current local tree exactly, including code, tests, build scripts, workflow updates, generated assets, and documentation.

What Changed

The diff includes the current local project state across the extension runtime, build pipeline, docs, tests, and supporting assets. The most important product-facing changes are:

  • Firefox runtime compatibility hardening across the extension surface.
  • Background-shell and browser-specific runtime splitting for Chromium and Firefox.
  • Offscreen and heavy-worker refactors, including browser-specific runtime adapters.
  • Packaging and validation updates for Firefox artifacts and lint baseline enforcement.
  • Expanded browser-matrix and security/performance validation coverage.
  • Documentation updates so the repo reflects the current architecture, QA process, API surface, and release expectations.

User Impact

Before this work, real Firefox usage exposed runtime gaps that did not show up clearly enough in the pre-existing local/CI flow. In particular, Firefox production tabs could miss the content-script receiver needed for page-backed actions, which could break behavior like DOM redaction and other tab-message-driven operations. That meant a build could look healthy in development while still failing in real browser-extension usage.

With this branch, the repository now includes the code and validation changes needed to keep the local project and GitHub aligned, and the extension behavior is validated more like a real shipped product across Chrome, Edge, and Firefox.

Root Cause

The main product issue found during real-browser validation was Firefox-specific runtime behavior around content-script availability and extension messaging. Some page-backed flows depended on a receiver being present in the tab, but Firefox production behavior could leave that receiver unavailable when the background service attempted to send messages. The result was transport failures in flows that relied on tab messaging.

A second issue was that the editor-side DOM redaction flow could treat malformed transport failures like successful responses, which hid the real error from the user.

Fix

The fix was to make the runtime more explicit and browser-aware:

  • Add on-demand bootstrapping of the packaged content script before sending page-backed messages in the background capture/pro flows.
  • Split background/runtime handling so Chromium and Firefox use the appropriate implementation paths.
  • Harden editor-side DOM-redaction response handling so transport/runtime failures are surfaced as errors instead of being mistaken for valid suggestions.
  • Update packaging, lint-baseline, and artifact-validation logic so Firefox release validation is enforced in a repeatable way.
  • Capture the resulting architecture and validation expectations in the repo documentation.

Validation

The local validation performed for this branch included:

  • npm run typecheck
  • npm run test:run
  • npm run test:e2e:extension:chromium
  • npm run test:e2e:extension:edge
  • npm run test:firefox:package
  • Real-browser manual smoke validation for installed extension flows across Chrome/Edge during the validation pass
  • Real-browser Firefox production-build smoke validation including popup readiness, visible capture, editor open, text annotation, PNG export/download, full-page capture, free-tier board gating, sponsor-slot placement, and board opening under local Pro state

One transient Chromium Playwright service-worker startup timeout occurred during an initial rerun of the full Chromium suite, but the isolated test passed immediately and the full Chromium matrix passed cleanly on rerun.

Remaining External Blocker

Live Stripe checkout/webhook verification is still blocked by missing test credentials and price IDs. The code and validation path for the browser-extension product have been updated, but the live licensing end-to-end pass still depends on the required Stripe test configuration being supplied.

Notes For Reviewers

This PR is intentionally broad because the request was to make the remote repository match the local project exactly. Reviewers should treat this as a repo-sync plus validation-hardening branch rather than a narrowly scoped single-feature change.

Summary by CodeRabbit

Release Notes v3.1.0

  • New Features

    • Added support for Microsoft Edge browser alongside Chrome and Firefox
    • Local ML redaction model bundled with extension for offline privacy
    • Comprehensive documentation and design system guidelines added
  • Improvements

    • Enhanced startup performance through optimized heavy-worker architecture
    • Cross-browser E2E testing (Chromium, Edge, Firefox)
    • Expanded Firefox package validation with strict lint baseline checks
  • Infrastructure

    • Multi-browser build and test matrix workflow
    • Improved artifact validation and caching mechanisms
    • Release readiness verification checklist

@Utkarsh-Sinha0

Copy link
Copy Markdown
Owner Author

Validation summary for this sync branch:

  • Branch pushed from the local repo state without trimming the working tree.
  • Local release gate passed: npm run typecheck, npm run test:run, npm run test:e2e:extension:chromium, npm run test:e2e:extension:edge, npm run test:firefox:package.
  • Real-browser extension smoke was validated during the local pass, including Firefox production-build flows.
  • Firefox runtime fixes now bootstrap the packaged content script on demand before page-backed tab messaging.
  • Editor DOM-redaction error handling was hardened so malformed transport failures surface clearly.

Remaining blocker:

  • Live Stripe checkout/webhook verification still requires the Stripe test credentials and price IDs before that final end-to-end path can be marked complete.

@coderabbitai

coderabbitai Bot commented Mar 17, 2026

Copy link
Copy Markdown

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Free

Run ID: 46540091-a065-4363-98f3-59ba08f8c15c

📥 Commits

Reviewing files that changed from the base of the PR and between 641251d and a34d196.

⛔ Files ignored due to path filters (4)
  • package-lock.json is excluded by !**/package-lock.json
  • public/assets/ml/wasm/ort-wasm-simd-threaded.wasm is excluded by !**/*.wasm
  • src/generated/background-shell.ts is excluded by !**/generated/**
  • src/generated/heavy-worker-client.ts is excluded by !**/generated/**
📒 Files selected for processing (77)
  • .github/workflows/browser-matrix.yml
  • BUILD_CHECKLIST.md
  • README.md
  • SKILLS.md
  • UI_DESIGN_SYSTEM.md
  • components.mdc
  • core.mdc
  • docs/AGENTS.md
  • docs/API_SPECIFICATIONS.md
  • docs/CODEX_PROMPT.md
  • docs/DEPLOYMENT.md
  • docs/DEVELOPER_GUIDE.md
  • docs/FIREFOX_LINT_BASELINE.md
  • docs/INVARIANTS.md
  • docs/ML_REDACTION.md
  • docs/OFFSCREEN_ARCHITECTURE.md
  • docs/PERFORMANCE_STARTUP.md
  • docs/PRD.md
  • docs/SECURITY_PRIVACY.md
  • docs/TECHNICAL_ARCHITECTURE.md
  • docs/TESTING_QA.md
  • e2e/extension-fixtures.ts
  • e2e/performance.spec.ts
  • e2e/playwright.extension.config.ts
  • e2e/security.spec.ts
  • extension-arch.mdc
  • offscreen.mdc
  • package.json
  • public/assets/ml/redaction/config.json
  • public/assets/ml/redaction/onnx/model_quantized.onnx
  • public/assets/ml/redaction/preprocessor_config.json
  • public/assets/ml/wasm/ort-wasm-simd-threaded.mjs
  • scripts/build-target.mjs
  • scripts/check-firefox-lint.mjs
  • scripts/sync-browser-shells.mjs
  • scripts/validate-build-artifacts.mjs
  • scripts/zip-target.mjs
  • security.mdc
  • src/background/background-page.ts
  • src/background/background-shell.chromium.ts
  • src/background/background-shell.firefox.ts
  • src/background/background-shell.ts
  • src/background/capture-service.ts
  • src/background/e2e-bridge.ts
  • src/background/export-service.ts
  • src/background/heavy-handler.ts
  • src/background/index.ts
  • src/background/pro-service.ts
  • src/content/content-behaviors.ts
  • src/editor/editor-api.ts
  • src/offscreen/index.html
  • src/offscreen/ml-redaction.ts
  • src/offscreen/processor.ts
  • src/offscreen/runtime.chromium.ts
  • src/offscreen/runtime.firefox.ts
  • src/offscreen/runtime.ts
  • src/options/options-api.ts
  • src/popup/PopupApp.tsx
  • src/popup/popup-api.ts
  • src/shared/heavy-worker-client.chromium.ts
  • src/shared/heavy-worker-client.firefox.ts
  • src/shared/heavy-worker-service.lazy.ts
  • src/shared/heavy-worker-service.ts
  • src/shared/offscreen-adapter.ts
  • src/shared/webextension-namespace.ts
  • testing.mdc
  • tests/background/capture-service.test.ts
  • tests/background/export-service.test.ts
  • tests/background/pro-service.test.ts
  • tests/editor/editor-app.test.tsx
  • tests/offscreen/ml-redaction.test.ts
  • tests/offscreen/offscreen.test.ts
  • tests/popup/popup-app.test.tsx
  • tests/shared/heavy-worker-client.firefox.test.ts
  • tests/shared/offscreen-adapter.test.ts
  • tests/shared/webextension-namespace.test.ts
  • wxt.config.ts

📝 Walkthrough

Walkthrough

Transforms SnapVault's architecture from offscreen-specific to multi-browser heavy-worker pattern, adding Edge support, comprehensive documentation (design system, testing rules, architecture guides), ML model bundling with local WASM assets, centralized heavy-worker service, dynamic browser-shell synchronization, and new CI/CD infrastructure for cross-browser testing and Firefox linting.

Changes

Cohort / File(s) Summary
GitHub Actions & CI Infrastructure
.github/workflows/browser-matrix.yml, scripts/build-target.mjs, scripts/zip-target.mjs, scripts/check-firefox-lint.mjs, scripts/sync-browser-shells.mjs, scripts/validate-build-artifacts.mjs
New workflow matrix for Chrome/Firefox/Edge builds with quality gates, packaging per browser, extension E2E tests. Build scripts refactored with retry logic, artifact cleanup, browser-shell synchronization, manifest validation, and Firefox lint baseline checks.
Documentation & Rules
README.md, BUILD_CHECKLIST.md, SKILLS.md, UI_DESIGN_SYSTEM.md, docs/*, *.mdc (core, extension-arch, offscreen, components, security, testing)
Comprehensive project documentation: product overview, architecture guides, design system with tokens/typography/motion, testing rules, security invariants, ML strategy, performance budgets, dev workflows, and AI agent skill mappings.
Heavy-Worker & Offscreen Architecture
src/shared/heavy-worker-service.ts, src/shared/heavy-worker-service.lazy.ts, src/shared/heavy-worker-client.chromium.ts, src/shared/heavy-worker-client.firefox.ts, src/shared/offscreen-adapter.ts, src/offscreen/runtime.chromium.ts, src/offscreen/runtime.firefox.ts, src/offscreen/runtime.ts, src/offscreen/processor.ts
Centralizes heavy-work (stitching, encoding, PDF, ML) into shared service with lazy loading; implements browser-specific client routing (Chromium uses offscreen + fallback, Firefox uses background); replaces per-browser inline handlers with unified service.
ML Redaction Refactor
src/offscreen/ml-redaction.ts, public/assets/ml/redaction/config.json, public/assets/ml/redaction/preprocessor_config.json, public/assets/ml/wasm/ort-wasm-simd-threaded.mjs
Switches from ONNX file path to bundled local WASM assets; uses HuggingFace Transformers with device:wasm, dtype:q8; adds ImageBitmap handling and explicit wasmPaths configuration; bundles YOLOs-tiny model config and ONNX WASM runtime.
Background Service Changes
src/background/index.ts, src/background/background-shell.ts, src/background/background-shell.chromium.ts, src/background/background-shell.firefox.ts, src/background/background-page.ts, src/background/heavy-handler.ts, src/background/e2e-bridge.ts, src/background/capture-service.ts, src/background/export-service.ts, src/background/pro-service.ts
Introduces background shells per browser; refactors capture/export/pro services to use webextension namespace; adds content-script readiness pattern; implements artifact caching and Firefox blob downloads; adds E2E test bridge with full-page stitching.
Content & UI Layer
src/content/content-behaviors.ts, src/editor/editor-api.ts, src/popup/PopupApp.tsx, src/popup/popup-api.ts, src/options/options-api.ts, src/offscreen/index.html
Migrates from direct chrome global to getWebExtensionNamespace abstraction; adds runtime response unwrapping for error handling; updates capture flow to support interactive region selection with pending state; adjusts CAPTURE_REGION payload structure.
Shared Utilities
src/shared/webextension-namespace.ts
New utility to safely retrieve browser/chrome namespace from globalThis, abstracting platform differences.
E2E Tests & Test Infrastructure
e2e/extension-fixtures.ts, e2e/playwright.extension.config.ts, e2e/performance.spec.ts, e2e/security.spec.ts, tests/.../*.test.ts, tests/.../*.test.tsx
Adds Edge extension support with dynamic path/channel selection; implements service-worker cold-start measurement; adds sponsor iframe sandbox verification; expands tests for pending region capture, export caching, Firefox downloads, ML pipeline config, heavy-worker routing, and WebExtension namespace.
Configuration & Dependencies
package.json, wxt.config.ts
Adds multi-browser npm scripts (dev:edge, build:all, zip:all, test:firefox:package); introduces web-ext and HuggingFace transformers dependencies; implements strict TARGET_BROWSER validation; adds E2E flag injection; increases chunk size warning limit.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Poem

🐰 Whiskers twitching with delight,
Heavy workers see the light,
Shells dance free from Chrome to Edge,
ML bundled, no more ledge,
One great service, shared and bright!

📝 Coding Plan
  • Generate coding plan for human review comments

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

Comment @coderabbitai help to get the list of available commands and usage tips.

Tip

CodeRabbit can approve the review once all CodeRabbit's comments are resolved.

Enable the reviews.request_changes_workflow setting to automatically approve the review once all CodeRabbit's comments are resolved.

@Utkarsh-Sinha0

Copy link
Copy Markdown
Owner Author

Added a new top-level README.md to make the GitHub repo reviewable as a product and engineering project.

Included in the README:

  • product-positioning copy tied to the actual repo
  • browser/runtime support table
  • Mermaid workflow diagram
  • Mermaid architecture diagram
  • Mermaid GitHub Actions / release-flow diagram
  • verified tech stack and command references
  • direct links into the detailed docs set

@Utkarsh-Sinha0
Utkarsh-Sinha0 marked this pull request as ready for review March 17, 2026 11:49
@Utkarsh-Sinha0
Utkarsh-Sinha0 merged commit d63cdfc into main Mar 17, 2026
4 of 7 checks passed
@Utkarsh-Sinha0
Utkarsh-Sinha0 deleted the codex/sync-local-validation-firefox branch March 17, 2026 11:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants