Merge pull request #1995 from lightpanda-io/ci-wba-test

ci: don't run wba test on PR

.github/actions/install/action.yml

@@ -1,28 +1,67 @@
 name: "Browsercore install"
 description: "Install deps for the project browsercore"
 
+inputs:
+  arch:
+    description: 'CPU arch used to select the v8 lib'
+    required: false
+    default: 'x86_64'
+  os:
+    description: 'OS used to select the v8 lib'
+    required: false
+    default: 'linux'
+  zig-v8:
+    description: 'zig v8 version to install'
+    required: false
+    default: 'v0.3.4'
+  v8:
+    description: 'v8 version to install'
+    required: false
+    default: '14.0.365.4'
+  cache-dir:
+    description: 'cache dir to use'
+    required: false
+    default: '~/.cache'
+  debug:
+    description: 'enable v8 pre-built debug version, only available for linux x86_64'
+    required: false
+    default: 'false'
+
 runs:
   using: "composite"
 
   steps:
+    - name: Install apt deps
+      if: ${{ inputs.os == 'linux' }}
+      shell: bash
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y wget xz-utils ca-certificates clang make git
+
+    # Zig version used from the `minimum_zig_version` field in build.zig.zon
+    - uses: mlugg/setup-zig@v2
+
+    # Rust Toolchain for html5ever
+    - uses: dtolnay/rust-toolchain@stable
+
+    - name: Cache v8
+      id: cache-v8
+      uses: actions/cache@v5
+      env:
+        cache-name: cache-v8
+      with:
+        path: ${{ inputs.cache-dir }}/v8
+        key: libc_v8_${{ inputs.v8 }}_${{ inputs.os }}_${{ inputs.arch }}_${{ inputs.zig-v8 }}${{inputs.debug == 'true' && '_debug' || '' }}.a
+
+    - if: ${{ steps.cache-v8.outputs.cache-hit != 'true' }}
+      shell: bash
+      run: |
+        mkdir -p ${{ inputs.cache-dir }}/v8
+
+        wget -O ${{ inputs.cache-dir }}/v8/libc_v8.a https://github.com/lightpanda-io/zig-v8-fork/releases/download/${{ inputs.zig-v8 }}/libc_v8_${{ inputs.v8 }}_${{ inputs.os }}_${{ inputs.arch }}${{inputs.debug == 'true' && '_debug' || '' }}.a
+
     - name: install v8
       shell: bash
       run: |
-        mkdir -p vendor/zig-js-runtime/vendor/v8/${{env.ARCH}}/debug
-        ln -s /usr/local/lib/libc_v8.a vendor/zig-js-runtime/vendor/v8/${{env.ARCH}}/debug/libc_v8.a
-
-        mkdir -p vendor/zig-js-runtime/vendor/v8/${{env.ARCH}}/release
-        ln -s /usr/local/lib/libc_v8.a vendor/zig-js-runtime/vendor/v8/${{env.ARCH}}/release/libc_v8.a
-
-    - name: libiconv
-      shell: bash
-      run: |
-        ln -s /usr/local/lib/libiconv vendor/libiconv
-
-    - name: build mimalloc
-      shell: bash
-      run: make install-mimalloc
-
-    - name: build netsurf
-      shell: bash
-      run: make install-netsurf
+        mkdir -p v8
+        ln -s ${{ inputs.cache-dir }}/v8/libc_v8.a v8/libc_v8${{inputs.debug == 'true' && '_debug' || '' }}.a

.github/workflows/cla.yml

@@ -0,0 +1,34 @@
+name: "CLA Assistant"
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened,closed,synchronize]
+
+permissions:
+  actions: write
+  contents: read
+  pull-requests: write
+  statuses: write
+
+jobs:
+  CLAAssistant:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: "CLA Assistant"
+        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
+        uses: contributor-assistant/github-action@v2.6.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PERSONAL_ACCESS_TOKEN: ${{ secrets.CLA_GH_PAT }}
+        with:
+          path-to-signatures: 'signatures/browser/version1/cla.json'
+          path-to-document: 'https://github.com/lightpanda-io/browser/blob/main/CLA.md'
+          # branch should not be protected
+          branch: 'main'
+          allowlist: krichprollsch,francisbouvier,katie-lpd,sjorsdonkers,bornlex
+
+          remote-organization-name: lightpanda-io
+          remote-repository-name: cla

.github/workflows/e2e-integration-test.yml

@@ -0,0 +1,66 @@
+name: e2e-integration-test
+
+env:
+  LIGHTPANDA_DISABLE_TELEMETRY: true
+
+on:
+  schedule:
+    - cron: "4 4 * * *"
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  zig-build-release:
+    name: zig build release
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    # Don't run the CI with draft PR.
+    if: github.event.pull_request.draft == false
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/install
+
+      - name: zig build release
+        run: zig build -Dprebuilt_v8_path=v8/libc_v8.a -Doptimize=ReleaseFast -Dcpu=x86_64
+
+      - name: upload artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: lightpanda-build-release
+          path: |
+            zig-out/bin/lightpanda
+          retention-days: 1
+
+  demo-scripts:
+    name: demo-integration-scripts
+    needs: zig-build-release
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          repository: 'lightpanda-io/demo'
+          fetch-depth: 0
+
+      - run: npm install
+
+      - name: download artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: lightpanda-build-release
+
+      - run: chmod a+x ./lightpanda
+
+      - name: run end to end integration tests
+        run: |
+          ./lightpanda serve --log-level error & echo $! > LPD.pid
+          go run integration/main.go
+          kill `cat LPD.pid`

.github/workflows/e2e-test.yml

@@ -0,0 +1,386 @@
+name: e2e-test
+
+env:
+  AWS_ACCESS_KEY_ID: ${{ vars.LPD_PERF_AWS_ACCESS_KEY_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.LPD_PERF_AWS_SECRET_ACCESS_KEY }}
+  AWS_BUCKET: ${{ vars.LPD_PERF_AWS_BUCKET }}
+  AWS_REGION: ${{ vars.LPD_PERF_AWS_REGION }}
+  LIGHTPANDA_DISABLE_TELEMETRY: true
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - ".github/**"
+      - "src/**"
+      - "build.zig"
+      - "build.zig.zon"
+
+  pull_request:
+
+    # By default GH trigger on types opened, synchronize and reopened.
+    # see https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
+    # Since we skip the job when the PR is in draft state, we want to force CI
+    # running when the PR is marked ready_for_review w/o other change.
+    # see https://github.com/orgs/community/discussions/25722#discussioncomment-3248917
+    types: [opened, synchronize, reopened, ready_for_review]
+
+    paths:
+      - ".github/**"
+      - "src/**"
+      - "build.zig"
+      - "build.zig.zon"
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  zig-build-release:
+    name: zig build release
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    # Don't run the CI with draft PR.
+    if: github.event.pull_request.draft == false
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/install
+
+      - name: zig build release
+        run: zig build -Dprebuilt_v8_path=v8/libc_v8.a -Doptimize=ReleaseFast -Dcpu=x86_64
+
+      - name: upload artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: lightpanda-build-release
+          path: |
+            zig-out/bin/lightpanda
+          retention-days: 1
+
+  demo-scripts:
+    name: demo-scripts
+    needs: zig-build-release
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          repository: 'lightpanda-io/demo'
+          fetch-depth: 0
+
+      - run: npm install
+
+      - name: download artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: lightpanda-build-release
+
+      - run: chmod a+x ./lightpanda
+
+      - name: run end to end tests
+        run: |
+          ./lightpanda serve & echo $! > LPD.pid
+          go run runner/main.go
+          kill `cat LPD.pid`
+
+      - name: build proxy
+        run: |
+          cd proxy
+          go build
+
+      - name: run end to end tests through proxy
+        run: |
+          ./proxy/proxy & echo $! > PROXY.id
+          ./lightpanda serve --http-proxy 'http://127.0.0.1:3000' & echo $! > LPD.pid
+          go run runner/main.go
+          kill `cat LPD.pid` `cat PROXY.id`
+
+      - name: run request interception through proxy
+        run: |
+          export PROXY_USERNAME=username PROXY_PASSWORD=password
+          ./proxy/proxy & echo $! > PROXY.id
+          ./lightpanda serve & echo $! > LPD.pid
+          URL=https://demo-browser.lightpanda.io/campfire-commerce/ node puppeteer/proxy_auth.js
+          BASE_URL=https://demo-browser.lightpanda.io/ node playwright/proxy_auth.js
+          kill `cat LPD.pid` `cat PROXY.id`
+
+  # e2e tests w/ web-bot-auth configuration on.
+  wba-demo-scripts:
+    name: wba-demo-scripts
+    needs: zig-build-release
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          repository: 'lightpanda-io/demo'
+          fetch-depth: 0
+
+      - run: npm install
+
+      - name: download artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: lightpanda-build-release
+
+      - run: chmod a+x ./lightpanda
+
+      - run: echo "${{ secrets.WBA_PRIVATE_KEY_PEM }}" > private_key.pem
+
+      - name: run end to end tests
+        run: |
+          ./lightpanda serve \
+            --web-bot-auth-key-file private_key.pem \
+            --web-bot-auth-keyid ${{ vars.WBA_KEY_ID }} \
+            --web-bot-auth-domain ${{ vars.WBA_DOMAIN }} \
+            & echo $! > LPD.pid
+          go run runner/main.go
+          kill `cat LPD.pid`
+
+      - name: build proxy
+        run: |
+          cd proxy
+          go build
+
+      - name: run end to end tests through proxy
+        run: |
+          ./proxy/proxy & echo $! > PROXY.id
+          ./lightpanda serve \
+            --web-bot-auth-key-file private_key.pem \
+            --web-bot-auth-keyid ${{ vars.WBA_KEY_ID }} \
+            --web-bot-auth-domain ${{ vars.WBA_DOMAIN }} \
+            --http-proxy 'http://127.0.0.1:3000' \
+            & echo $! > LPD.pid
+          go run runner/main.go
+          kill `cat LPD.pid` `cat PROXY.id`
+
+      - name: run request interception through proxy
+        run: |
+          export PROXY_USERNAME=username PROXY_PASSWORD=password
+          ./proxy/proxy & echo $! > PROXY.id
+          ./lightpanda serve & echo $! > LPD.pid
+          URL=https://demo-browser.lightpanda.io/campfire-commerce/ node puppeteer/proxy_auth.js
+          BASE_URL=https://demo-browser.lightpanda.io/ node playwright/proxy_auth.js
+          kill `cat LPD.pid` `cat PROXY.id`
+
+  wba-test:
+    name: wba-test
+    needs: zig-build-release
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    # Don't execute on PR
+    if: github.event_name != 'pull_request'
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          repository: 'lightpanda-io/demo'
+          fetch-depth: 0
+
+      - name: download artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: lightpanda-build-release
+
+      - run: chmod a+x ./lightpanda
+
+      # force a wakup of the auth server before requesting it w/ the test itself
+      - run: curl https://${{ vars.WBA_DOMAIN }}
+
+      - name: run wba test
+        shell: bash
+        run: |
+          node webbotauth/validator.js &
+          VALIDATOR_PID=$!
+          sleep 5
+
+          exec 3<<< "${{ secrets.WBA_PRIVATE_KEY_PEM }}"
+
+          ./lightpanda fetch --dump http://127.0.0.1:8989/ \
+            --web-bot-auth-key-file /proc/self/fd/3 \
+            --web-bot-auth-keyid ${{ vars.WBA_KEY_ID }} \
+            --web-bot-auth-domain ${{ vars.WBA_DOMAIN }}
+
+          wait $VALIDATOR_PID
+          exec 3>&-
+
+  cdp-and-hyperfine-bench:
+    name: cdp-and-hyperfine-bench
+    needs: zig-build-release
+
+    env:
+      MAX_VmHWM: 28000 # 28MB (KB)
+      MAX_CG_PEAK: 8000 # 8MB (KB)
+      MAX_AVG_DURATION: 17
+
+      # How to give cgroups access to the user actions-runner on the host:
+      # $ sudo apt install cgroup-tools
+      # $ sudo chmod o+w /sys/fs/cgroup/cgroup.procs
+      # $ sudo mkdir -p /sys/fs/cgroup/actions-runner
+      # $ sudo chown -R actions-runner:actions-runner /sys/fs/cgroup/actions-runner
+      CG_ROOT: /sys/fs/cgroup
+      CG: actions-runner/lpd_${{ github.run_id }}_${{ github.run_attempt }}
+
+    # use a self host runner.
+    runs-on: lpd-bench-hetzner
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          repository: 'lightpanda-io/demo'
+          fetch-depth: 0
+
+      - run: npm install
+
+      - name: download artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: lightpanda-build-release
+
+      - run: chmod a+x ./lightpanda
+
+      - name: start http
+        run: |
+          go run ws/main.go & echo $! > WS.pid
+          sleep 2
+
+      - name: run lightpanda in cgroup
+        run: |
+          if [ ! -f /sys/fs/cgroup/cgroup.controllers ]; then
+            echo "cgroup v2 not available: /sys/fs/cgroup/cgroup.controllers missing"
+            exit 1
+          fi
+
+          mkdir -p $CG_ROOT/$CG
+          cgexec -g memory:$CG ./lightpanda serve & echo $! > LPD.pid
+
+          sleep 2
+
+      - name: run puppeteer
+        run: |
+          RUNS=100 npm run bench-puppeteer-cdp > puppeteer.out || exit 1
+          cat /proc/`cat LPD.pid`/status |grep VmHWM|grep -oP '\d+' > LPD.VmHWM
+          kill `cat LPD.pid`
+
+          PID=$(cat LPD.pid)
+          while kill -0 $PID 2>/dev/null; do
+            sleep 1
+          done
+          if [ ! -f $CG_ROOT/$CG/memory.peak ]; then
+            echo "memory.peak not available in $CG"
+            exit 1
+          fi
+          cat $CG_ROOT/$CG/memory.peak > LPD.cg_mem_peak
+
+      - name: puppeteer result
+        run: cat puppeteer.out
+
+      - name: cgroup memory regression
+        run: |
+          PEAK_BYTES=$(cat LPD.cg_mem_peak)
+          PEAK_KB=$((PEAK_BYTES / 1024))
+          echo "memory.peak_bytes=$PEAK_BYTES"
+          echo "memory.peak_kb=$PEAK_KB"
+          test "$PEAK_KB" -le "$MAX_CG_PEAK"
+
+      - name: virtual memory regression
+        run: |
+          export LPD_VmHWM=`cat LPD.VmHWM`
+          echo "Peak resident set size: $LPD_VmHWM"
+          test "$LPD_VmHWM" -le "$MAX_VmHWM"
+
+      - name: cleanup cgroup
+        run: rmdir $CG_ROOT/$CG
+
+      - name: duration regression
+        run: |
+          export PUPPETEER_AVG_DURATION=`cat puppeteer.out|grep 'avg run'|sed 's/avg run duration (ms) //'`
+          echo "puppeteer avg duration: $PUPPETEER_AVG_DURATION"
+          test "$PUPPETEER_AVG_DURATION" -le "$MAX_AVG_DURATION"
+
+      - name: json output
+        run: |
+          export AVG_DURATION=`cat puppeteer.out|grep 'avg run'|sed 's/avg run duration (ms) //'`
+          export TOTAL_DURATION=`cat puppeteer.out|grep 'total duration'|sed 's/total duration (ms) //'`
+          export LPD_VmHWM=`cat LPD.VmHWM`
+          export LPD_CG_PEAK_KB=$(( $(cat LPD.cg_mem_peak) / 1024 ))
+          echo "{\"duration_total\":${TOTAL_DURATION},\"duration_avg\":${AVG_DURATION},\"mem_peak\":${LPD_VmHWM},\"cg_mem_peak\":${LPD_CG_PEAK_KB}}" > bench.json
+          cat bench.json
+
+      - name: run hyperfine
+        run: |
+          hyperfine --export-json=hyperfine.json --warmup 3 --runs 20 --shell=none "./lightpanda --dump http://127.0.0.1:1234/campfire-commerce/"
+
+      - name: stop http
+        run: kill `cat WS.pid`
+
+      - name: write commit
+        run: |
+          echo "${{github.sha}}" > commit.txt
+
+      - name: upload artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: bench-results
+          path: |
+            bench.json
+            hyperfine.json
+            commit.txt
+          retention-days: 10
+
+
+  perf-fmt:
+    name: perf-fmt
+    needs: cdp-and-hyperfine-bench
+
+    # Don't execute on PR
+    if: github.event_name != 'pull_request'
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    container:
+      image: ghcr.io/lightpanda-io/perf-fmt:latest
+      credentials:
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - name: download artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: bench-results
+
+      - name: format and send json result
+        run: /perf-fmt cdp ${{ github.sha }} bench.json
+
+      - name: format and send json result
+        run: /perf-fmt hyperfine ${{ github.sha }} hyperfine.json
+
+  browser-fetch:
+    name: browser fetch
+    needs: zig-build-release
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: download artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: lightpanda-build-release
+
+      - run: chmod a+x ./lightpanda
+
+      - run: ./lightpanda fetch https://demo-browser.lightpanda.io/campfire-commerce/

.github/workflows/nightly.yml

@@ -0,0 +1,186 @@
+name: nightly build
+
+env:
+  AWS_ACCESS_KEY_ID: ${{ vars.NIGHTLY_BUILD_AWS_ACCESS_ID }}
+  AWS_SECRET_ACCESS_KEY: ${{ secrets.NIGHTLY_BUILD_AWS_SECRET_ACCESS_KEY }}
+  AWS_BUCKET: ${{ vars.NIGHTLY_BUILD_AWS_BUCKET }}
+  AWS_REGION: ${{ vars.NIGHTLY_BUILD_AWS_REGION }}
+
+  RELEASE: ${{ github.ref_type == 'tag' && github.ref_name || 'nightly' }}
+  VERSION: ${{ github.ref_type == 'tag' && github.ref_name || '1.0.0-nightly' }}
+
+on:
+  push:
+    tags:
+      - '*'
+  schedule:
+    - cron: "2 2 * * *"
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-linux-x86_64:
+    env:
+      ARCH: x86_64
+      OS: linux
+
+    runs-on: ubuntu-22.04
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/install
+        with:
+          os: ${{env.OS}}
+          arch: ${{env.ARCH}}
+
+      - name: v8 snapshot
+        run: zig build -Dprebuilt_v8_path=v8/libc_v8.a -Doptimize=ReleaseFast snapshot_creator -- src/snapshot.bin
+
+      - name: zig build
+        run: zig build -Dsnapshot_path=../../snapshot.bin -Dprebuilt_v8_path=v8/libc_v8.a -Doptimize=ReleaseFast -Dcpu=x86_64 -Dversion_string=${{ env.VERSION }}
+
+      - name: Rename binary
+        run: mv zig-out/bin/lightpanda lightpanda-${{ env.ARCH }}-${{ env.OS }}
+
+      - name: upload on s3
+        run: |
+          export DIR=`git show --no-patch --no-notes --pretty='%cs_%h'`
+          aws s3 cp --storage-class=GLACIER_IR lightpanda-${{ env.ARCH }}-${{ env.OS }} s3://lpd-nightly-build/${DIR}/lightpanda-${{ env.ARCH }}-${{ env.OS }}
+
+      - name: Upload the build
+        uses: ncipollo/release-action@v1
+        with:
+          allowUpdates: true
+          artifacts: lightpanda-${{ env.ARCH }}-${{ env.OS }}
+          tag: ${{ env.RELEASE }}
+          makeLatest: true
+
+  build-linux-aarch64:
+    env:
+      ARCH: aarch64
+      OS: linux
+
+    runs-on: ubuntu-22.04-arm
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/install
+        with:
+          os: ${{env.OS}}
+          arch: ${{env.ARCH}}
+
+      - name: v8 snapshot
+        run: zig build -Dprebuilt_v8_path=v8/libc_v8.a -Doptimize=ReleaseFast snapshot_creator -- src/snapshot.bin
+
+      - name: zig build
+        run: zig build -Dsnapshot_path=../../snapshot.bin -Dprebuilt_v8_path=v8/libc_v8.a -Doptimize=ReleaseFast -Dcpu=generic -Dversion_string=${{ env.VERSION }}
+
+      - name: Rename binary
+        run: mv zig-out/bin/lightpanda lightpanda-${{ env.ARCH }}-${{ env.OS }}
+
+      - name: upload on s3
+        run: |
+          export DIR=`git show --no-patch --no-notes --pretty='%cs_%h'`
+          aws s3 cp --storage-class=GLACIER_IR lightpanda-${{ env.ARCH }}-${{ env.OS }} s3://lpd-nightly-build/${DIR}/lightpanda-${{ env.ARCH }}-${{ env.OS }}
+
+      - name: Upload the build
+        uses: ncipollo/release-action@v1
+        with:
+          allowUpdates: true
+          artifacts: lightpanda-${{ env.ARCH }}-${{ env.OS }}
+          tag: ${{ env.RELEASE }}
+          makeLatest: true
+
+  build-macos-aarch64:
+    env:
+      ARCH: aarch64
+      OS: macos
+
+    # macos-14 runs on arm CPU. see
+    # https://github.com/actions/runner-images?tab=readme-ov-file
+    runs-on: macos-14
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/install
+        with:
+          os: ${{env.OS}}
+          arch: ${{env.ARCH}}
+
+      - name: v8 snapshot
+        run: zig build -Dprebuilt_v8_path=v8/libc_v8.a -Doptimize=ReleaseFast snapshot_creator -- src/snapshot.bin
+
+      - name: zig build
+        run: zig build -Dsnapshot_path=../../snapshot.bin -Dprebuilt_v8_path=v8/libc_v8.a -Doptimize=ReleaseFast -Dversion_string=${{ env.VERSION }}
+
+      - name: Rename binary
+        run: mv zig-out/bin/lightpanda lightpanda-${{ env.ARCH }}-${{ env.OS }}
+
+      - name: upload on s3
+        run: |
+          export DIR=`git show --no-patch --no-notes --pretty='%cs_%h'`
+          aws s3 cp --storage-class=GLACIER_IR lightpanda-${{ env.ARCH }}-${{ env.OS }} s3://lpd-nightly-build/${DIR}/lightpanda-${{ env.ARCH }}-${{ env.OS }}
+
+      - name: Upload the build
+        uses: ncipollo/release-action@v1
+        with:
+          allowUpdates: true
+          artifacts: lightpanda-${{ env.ARCH }}-${{ env.OS }}
+          tag: ${{ env.RELEASE }}
+          makeLatest: true
+
+  build-macos-x86_64:
+    env:
+      ARCH: x86_64
+      OS: macos
+
+    runs-on: macos-14-large
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/install
+        with:
+          os: ${{env.OS}}
+          arch: ${{env.ARCH}}
+
+      - name: v8 snapshot
+        run: zig build -Dprebuilt_v8_path=v8/libc_v8.a -Doptimize=ReleaseFast snapshot_creator -- src/snapshot.bin
+
+      - name: zig build
+        run: zig build -Dsnapshot_path=../../snapshot.bin -Dprebuilt_v8_path=v8/libc_v8.a -Doptimize=ReleaseFast -Dversion_string=${{ env.VERSION }}
+
+      - name: Rename binary
+        run: mv zig-out/bin/lightpanda lightpanda-${{ env.ARCH }}-${{ env.OS }}
+
+      - name: upload on s3
+        run: |
+          export DIR=`git show --no-patch --no-notes --pretty='%cs_%h'`
+          aws s3 cp --storage-class=GLACIER_IR lightpanda-${{ env.ARCH }}-${{ env.OS }} s3://lpd-nightly-build/${DIR}/lightpanda-${{ env.ARCH }}-${{ env.OS }}
+
+      - name: Upload the build
+        uses: ncipollo/release-action@v1
+        with:
+          allowUpdates: true
+          artifacts: lightpanda-${{ env.ARCH }}-${{ env.OS }}
+          tag: ${{ env.RELEASE }}
+          makeLatest: true

.github/workflows/wpt.yml

@@ -1,88 +1,130 @@
 name: wpt
 
 env:
-  ARCH: x86_64-linux
   AWS_ACCESS_KEY_ID: ${{ vars.LPD_PERF_AWS_ACCESS_KEY_ID }}
   AWS_SECRET_ACCESS_KEY: ${{ secrets.LPD_PERF_AWS_SECRET_ACCESS_KEY }}
   AWS_BUCKET: ${{ vars.LPD_PERF_AWS_BUCKET }}
   AWS_REGION: ${{ vars.LPD_PERF_AWS_REGION }}
+  AWS_CF_DISTRIBUTION: ${{ vars.AWS_CF_DISTRIBUTION }}
+  LIGHTPANDA_DISABLE_TELEMETRY: true
 
 on:
-  push:
-    branches:
-      - main
-    paths:
-      - "build.zig"
-      - "src/**/*.zig"
-      - "src/*.zig"
-      - "tests/wpt/**"
-      - "vendor/**"
-      - ".github/**"
-  pull_request:
+  schedule:
+    - cron: "21 2 * * *"
 
-    # By default GH trigger on types opened, synchronize and reopened.
-    # see https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
-    # Since we skip the job when the PR is in draft state, we want to force CI
-    # running when the PR is marked ready_for_review w/o other change.
-    # see https://github.com/orgs/community/discussions/25722#discussioncomment-3248917
-    types: [opened, synchronize, reopened, ready_for_review]
-
-    paths:
-      - ".github/**"
-      - "build.zig"
-      - "src/**/*.zig"
-      - "src/*.zig"
-      - "tests/wpt/**"
-      - "vendor/**"
-      - ".github/**"
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
 jobs:
-  wpt:
-    name: web platform tests
+  wpt-build-release:
+    name: zig build release
 
-    # Don't run the CI with draft PR.
-    if: github.event.pull_request.draft == false
+    env:
+      ARCH: aarch64
+      OS: linux
 
-    runs-on: ubuntu-latest
-    container:
-      image: ghcr.io/lightpanda-io/zig-browsercore:0.12.1
-      credentials:
-       username: ${{ github.actor }}
-       password: ${{ secrets.GITHUB_TOKEN }}
-
-      # docker blocks io_uring syscalls by default now.
-      # see https://github.com/tigerbeetle/tigerbeetle/pull/1995
-      # see https://github.com/moby/moby/pull/46762
-      options: "--security-opt seccomp=unconfined"
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 20
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          token: ${{ secrets.GH_CI_PAT }}
-          # fetch submodules recusively, to get zig-js-runtime submodules also.
-          submodules: recursive
 
       - uses: ./.github/actions/install
+        with:
+          os: ${{env.OS}}
+          arch: ${{env.ARCH}}
 
-      - run: zig build wpt -Dengine=v8 -- --safe --summary
+      - name: v8 snapshot
+        run: zig build -Dprebuilt_v8_path=v8/libc_v8.a -Doptimize=ReleaseFast snapshot_creator -- src/snapshot.bin
 
-        # For now WPT tests doesn't pass at all.
-        # We accept then to continue the job on failure.
-        # TODO remove the continue-on-error when tests will pass.
-        continue-on-error: true
+      - name: zig build release
+        run: zig build -Dsnapshot_path=../../snapshot.bin -Dprebuilt_v8_path=v8/libc_v8.a -Doptimize=ReleaseFast -Dcpu=generic
 
-      - name: json output
-        run: zig build wpt -Dengine=v8 -- --safe --json > wpt.json
+      - name: upload artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: lightpanda-build-release
+          path: |
+            zig-out/bin/lightpanda
+          retention-days: 1
+
+  wpt-build-runner:
+    name: build wpt runner
+
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          repository: 'lightpanda-io/demo'
+          fetch-depth: 0
+
+      - run: |
+          cd ./wptrunner
+          CGO_ENABLED=0 go build
+
+      - name: upload artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: wptrunner
+          path: |
+            wptrunner/wptrunner
+          retention-days: 1
+
+  run-wpt:
+    name: web platform tests json output
+    needs:
+      - wpt-build-release
+      - wpt-build-runner
+
+    # use a self host runner.
+    runs-on: lpd-wpt-aws
+    timeout-minutes: 600
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: fork
+          repository: 'lightpanda-io/wpt'
+          fetch-depth: 0
+
+      # The hosts are configured manually on the self host runner.
+      # - name: create custom hosts
+      #   run: ./wpt make-hosts-file | sudo tee -a /etc/hosts
+
+      - name: generate manifest
+        run: ./wpt manifest
+
+      - name: download lightpanda release
+        uses: actions/download-artifact@v8
+        with:
+          name: lightpanda-build-release
+
+      - run: chmod a+x ./lightpanda
+
+      - name: download wptrunner
+        uses: actions/download-artifact@v8
+        with:
+          name: wptrunner
+
+      - run: chmod a+x ./wptrunner
+
+      - name: run test with json output
+        run: |
+          ./wpt serve 2> /dev/null & echo $! > WPT.pid
+          sleep 20s
+          ./wptrunner -lpd-path ./lightpanda -json -concurrency 5 -pool 5 --mem-limit 400 > wpt.json
+          kill `cat WPT.pid`
 
       - name: write commit
         run: |
           echo "${{github.sha}}" > commit.txt
 
       - name: upload artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: wpt-results
           path: |
@@ -92,12 +134,11 @@ jobs:
 
   perf-fmt:
     name: perf-fmt
-    needs: wpt
-
-    # Don't execute on PR
-    if: github.event_name != 'pull_request'
+    needs: run-wpt
 
     runs-on: ubuntu-latest
+    timeout-minutes: 15
+
     container:
       image: ghcr.io/lightpanda-io/perf-fmt:latest
       credentials:
@@ -106,7 +147,7 @@ jobs:
 
     steps:
       - name: download artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: wpt-results
 

.github/workflows/zig-fmt.yml

@@ -1,62 +0,0 @@
-name: zig-fmt
-
-on:
-  pull_request:
-
-    # By default GH trigger on types opened, synchronize and reopened.
-    # see https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
-    # Since we skip the job when the PR is in draft state, we want to force CI
-    # running when the PR is marked ready_for_review w/o other change.
-    # see https://github.com/orgs/community/discussions/25722#discussioncomment-3248917
-    types: [opened, synchronize, reopened, ready_for_review]
-
-    paths:
-      - ".github/**"
-      - "build.zig"
-      - "src/**/*.zig"
-      - "src/*.zig"
-  # Allows you to run this workflow manually from the Actions tab
-  workflow_dispatch:
-
-jobs:
-  zig-fmt:
-    name: zig fmt
-
-    # Don't run the CI with draft PR.
-    if: github.event.pull_request.draft == false
-
-    runs-on: ubuntu-latest
-    container:
-      image: ghcr.io/lightpanda-io/zig:0.12.1
-      credentials:
-       username: ${{ github.actor }}
-       password: ${{ secrets.GITHUB_TOKEN }}
-    outputs:
-      zig_fmt_errs: ${{ steps.fmt.outputs.zig_fmt_errs }}
-
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Run zig fmt
-        id: fmt
-        run: |
-          zig fmt --check ./*.zig ./**/*.zig 2> zig-fmt.err > zig-fmt.err2 || echo "Failed"
-          delimiter="$(openssl rand -hex 8)"
-          echo "zig_fmt_errs<<${delimiter}" >> "${GITHUB_OUTPUT}"
-
-          if [ -s zig-fmt.err ]; then
-            echo "// The following errors occurred:" >> "${GITHUB_OUTPUT}"
-            cat zig-fmt.err >> "${GITHUB_OUTPUT}"
-          fi
-
-          if [ -s zig-fmt.err2 ]; then
-            echo "// The following files were not formatted:" >> "${GITHUB_OUTPUT}"
-            cat zig-fmt.err2 >> "${GITHUB_OUTPUT}"
-          fi
-
-          echo "${delimiter}" >> "${GITHUB_OUTPUT}"
-      - name: Fail the job
-        if: steps.fmt.outputs.zig_fmt_errs != ''
-        run: exit 1

.github/workflows/zig-test.yml

@@ -1,24 +1,22 @@
 name: zig-test
 
 env:
-  ARCH: x86_64-linux
   AWS_ACCESS_KEY_ID: ${{ vars.LPD_PERF_AWS_ACCESS_KEY_ID }}
   AWS_SECRET_ACCESS_KEY: ${{ secrets.LPD_PERF_AWS_SECRET_ACCESS_KEY }}
   AWS_BUCKET: ${{ vars.LPD_PERF_AWS_BUCKET }}
   AWS_REGION: ${{ vars.LPD_PERF_AWS_REGION }}
+  LIGHTPANDA_DISABLE_TELEMETRY: true
 
 on:
   push:
-    branches:
-      - main
+    branches: [main]
     paths:
-      - "build.zig"
-      - "src/**/*.zig"
-      - "src/*.zig"
-      - "vendor/zig-js-runtime"
       - ".github/**"
-  pull_request:
+      - "src/**"
+      - "build.zig"
+      - "build.zig.zon"
 
+  pull_request:
     # By default GH trigger on types opened, synchronize and reopened.
     # see https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
     # Since we skip the job when the PR is in draft state, we want to force CI
@@ -28,104 +26,95 @@ on:
 
     paths:
       - ".github/**"
+      - "src/**"
       - "build.zig"
-      - "src/**/*.zig"
-      - "src/*.zig"
-      - "vendor/**"
-      - ".github/**"
+      - "build.zig.zon"
+
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
 jobs:
-  zig-build-dev:
-    name: zig build dev
+  zig-fmt:
+    name: zig fmt
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
 
-    # Don't run the CI with draft PR.
     if: github.event.pull_request.draft == false
 
-    runs-on: ubuntu-latest
-    container:
-      image: ghcr.io/lightpanda-io/zig-browsercore:0.12.1
-      credentials:
-       username: ${{ github.actor }}
-       password: ${{ secrets.GITHUB_TOKEN }}
-
     steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.GH_CI_PAT }}
-          # fetch submodules recusively, to get zig-js-runtime submodules also.
-          submodules: recursive
+      - uses: actions/checkout@v6
 
-      - uses: ./.github/actions/install
+      # Zig version used from the `minimum_zig_version` field in build.zig.zon
+      - uses: mlugg/setup-zig@v2
 
-      - name: zig build debug
-        run: zig build -Dengine=v8
+      - name: Run zig fmt
+        id: fmt
+        run: |
+          zig fmt --check ./*.zig ./**/*.zig 2> zig-fmt.err > zig-fmt.err2 || echo "Failed"
+          delimiter="$(openssl rand -hex 8)"
+          echo "zig_fmt_errs<<${delimiter}" >> "${GITHUB_OUTPUT}"
 
-  zig-build-release:
-    name: zig build release
+          if [ -s zig-fmt.err ]; then
+            echo "// The following errors occurred:" >> "${GITHUB_OUTPUT}"
+            cat zig-fmt.err >> "${GITHUB_OUTPUT}"
+          fi
 
-    # Don't run the CI on PR
-    if: github.event_name != 'pull_request'
+          if [ -s zig-fmt.err2 ]; then
+            echo "// The following files were not formatted:" >> "${GITHUB_OUTPUT}"
+            cat zig-fmt.err2 >> "${GITHUB_OUTPUT}"
+          fi
+
+          echo "${delimiter}" >> "${GITHUB_OUTPUT}"
+
+      - name: Fail the job
+        if: steps.fmt.outputs.zig_fmt_errs != ''
+        run: exit 1
+
+  zig-test-debug:
+    name: zig test using v8 in debug mode
 
     runs-on: ubuntu-latest
-    container:
-      image: ghcr.io/lightpanda-io/zig-browsercore:0.12.1
-      credentials:
-       username: ${{ github.actor }}
-       password: ${{ secrets.GITHUB_TOKEN }}
+    timeout-minutes: 15
+
+    if: github.event.pull_request.draft == false
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          token: ${{ secrets.GH_CI_PAT }}
-          # fetch submodules recusively, to get zig-js-runtime submodules also.
-          submodules: recursive
 
       - uses: ./.github/actions/install
+        with:
+          debug: true
 
-      - name: zig build release
-        run: zig build -Doptimize=ReleaseSafe -Dengine=v8
+      - name: zig build test
+        run: zig build -Dprebuilt_v8_path=v8/libc_v8_debug.a -Dtsan=true test
 
-  zig-test:
+  zig-test-release:
     name: zig test
 
-    # Don't run the CI with draft PR.
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
     if: github.event.pull_request.draft == false
 
-    runs-on: ubuntu-latest
-    container:
-      image: ghcr.io/lightpanda-io/zig-browsercore:0.12.1
-      credentials:
-       username: ${{ github.actor }}
-       password: ${{ secrets.GITHUB_TOKEN }}
-
-      # docker blocks io_uring syscalls by default now.
-      # see https://github.com/tigerbeetle/tigerbeetle/pull/1995
-      # see https://github.com/moby/moby/pull/46762
-      options: "--security-opt seccomp=unconfined"
-
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          token: ${{ secrets.GH_CI_PAT }}
-          # fetch submodules recusively, to get zig-js-runtime submodules also.
-          submodules: recursive
 
       - uses: ./.github/actions/install
 
       - name: zig build test
-        run: zig build test -Dengine=v8 -- --json > bench.json
+        run: METRICS=true zig build -Dprebuilt_v8_path=v8/libc_v8.a test > bench.json
 
       - name: write commit
         run: |
           echo "${{github.sha}}" > commit.txt
 
       - name: upload artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: bench-results
           path: |
@@ -135,21 +124,22 @@ jobs:
 
   bench-fmt:
     name: perf-fmt
-    needs: zig-test
-
-    # Don't execute on PR
-    if: github.event_name != 'pull_request'
+    needs: zig-test-release
 
     runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    if: github.event_name != 'pull_request'
+
     container:
       image: ghcr.io/lightpanda-io/perf-fmt:latest
       credentials:
-       username: ${{ github.actor }}
-       password: ${{ secrets.GITHUB_TOKEN }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
 
     steps:
       - name: download artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: bench-results
 

.gitignore

@@ -1,6 +1,6 @@
-zig-cache
+/.zig-cache/
+/.lp-cache/
 zig-out
-/vendor/netsurf/build/
-/vendor/netsurf/lib/
-/vendor/netsurf/include/
-/vendor/libiconv/
+lightpanda.id
+/src/html5ever/target/
+src/snapshot.bin

.gitmodules

@@ -1,24 +0,0 @@
-[submodule "vendor/zig-js-runtime"]
-	path = vendor/zig-js-runtime
-	url = git@github.com:lightpanda-io/zig-js-runtime.git
-[submodule "vendor/netsurf/libwapcaplet"]
-	path = vendor/netsurf/libwapcaplet
-	url = git@github.com:lightpanda-io/libwapcaplet.git
-[submodule "vendor/netsurf/libparserutils"]
-	path = vendor/netsurf/libparserutils
-	url = git@github.com:lightpanda-io/libparserutils.git
-[submodule "vendor/netsurf/libdom"]
-	path = vendor/netsurf/libdom
-	url = git@github.com:lightpanda-io/libdom.git
-[submodule "vendor/netsurf/share/netsurf-buildsystem"]
-	path = vendor/netsurf/share/netsurf-buildsystem
-	url = https://source.netsurf-browser.org/buildsystem.git
-[submodule "vendor/netsurf/libhubbub"]
-	path = vendor/netsurf/libhubbub
-	url = git@github.com:lightpanda-io/libhubbub.git
-[submodule "tests/wpt"]
-	path = tests/wpt
-	url = https://github.com/lightpanda-io/wpt
-[submodule "vendor/mimalloc"]
-	path = vendor/mimalloc
-	url = git@github.com:microsoft/mimalloc.git

CLA.md

@@ -0,0 +1,93 @@
+# Lightpanda (Selecy SAS) Grant and Contributor License Agreement (“Agreement”)
+
+This agreement is based on the Apache Software Foundation Contributor License
+Agreement. (v r190612)
+
+Thank you for your interest in software projects stewarded by Lightpanda
+(Selecy SAS) (“Lightpanda”). In order to clarify the intellectual property
+license granted with Contributions from any person or entity, Lightpanda must
+have a Contributor License Agreement (CLA) on file that has been agreed to by
+each Contributor, indicating agreement to the license terms below. This license
+is for your protection as a Contributor as well as the protection of Lightpanda
+and its users; it does not change your rights to use your own Contributions for
+any other purpose. This Agreement allows an individual to contribute to
+Lightpanda on that individual’s own behalf, or an entity (the “Corporation”) to
+submit Contributions to Lightpanda, to authorize Contributions submitted by its
+designated employees to Lightpanda, and to grant copyright and patent licenses
+thereto.
+
+You accept and agree to the following terms and conditions for Your present and
+future Contributions submitted to Lightpanda. Except for the license granted
+herein to Lightpanda and recipients of software distributed by Lightpanda, You
+reserve all right, title, and interest in and to Your Contributions.
+
+1. Definitions. “You” (or “Your”) shall mean the copyright owner or legal
+   entity authorized by the copyright owner that is making this Agreement with
+   Lightpanda. For legal entities, the entity making a Contribution and all
+   other entities that control, are controlled by, or are under common control
+   with that entity are considered to be a single Contributor. For the purposes
+   of this definition, “control” means (i) the power, direct or indirect, to
+   cause the direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+   “Contribution” shall mean any work, as well as any modifications or
+   additions to an existing work, that is intentionally submitted by You to
+   Lightpanda for inclusion in, or documentation of, any of the products owned
+   or managed by Lightpanda (the “Work”). For the purposes of this definition,
+   “submitted” means any form of electronic, verbal, or written communication
+   sent to Lightpanda or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems (such
+   as GitHub), and issue tracking systems that are managed by, or on behalf of,
+   Lightpanda for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise designated
+   in writing by You as “Not a Contribution.”
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+   Agreement, You hereby grant to Lightpanda and to recipients of software
+   distributed by Lightpanda a perpetual, worldwide, non-exclusive, no-charge,
+   royalty-free, irrevocable copyright license to reproduce, prepare derivative
+   works of, publicly display, publicly perform, sublicense, and distribute
+   Your Contributions and such derivative works.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+   Agreement, You hereby grant to Lightpanda and to recipients of software
+   distributed by Lightpanda a perpetual, worldwide, non-exclusive, no-charge,
+   royalty-free, irrevocable (except as stated in this section) patent license
+   to make, have made, use, offer to sell, sell, import, and otherwise transfer
+   the Work, where such license applies only to those patent claims licensable
+   by You that are necessarily infringed by Your Contribution(s) alone or by
+   combination of Your Contribution(s) with the Work to which such
+   Contribution(s) were submitted. If any entity institutes patent litigation
+   against You or any other entity (including a cross-claim or counterclaim in
+   a lawsuit) alleging that your Contribution, or the Work to which you have
+   contributed, constitutes direct or contributory patent infringement, then
+   any patent licenses granted to that entity under this Agreement for that
+   Contribution or Work shall terminate as of the date such litigation is
+   filed.
+
+4. You represent that You are legally entitled to grant the above license. If
+   You are an individual, and if Your employer(s) has rights to intellectual
+   property that you create that includes Your Contributions, you represent
+   that You have received permission to make Contributions on behalf of that
+   employer, or that Your employer has waived such rights for your
+   Contributions to Lightpanda. If You are a Corporation, any individual who
+   makes a contribution from an account associated with You will be considered
+   authorized to Contribute on Your behalf.
+
+5. You represent that each of Your Contributions is Your original creation (see
+   section 7 for submissions on behalf of others).
+
+6. You are not expected to provide support for Your Contributions,except to the
+   extent You desire to provide support. You may provide support for free, for
+   a fee, or not at all. Unless required by applicable law or agreed to in
+   writing, You provide Your Contributions on an “AS IS” BASIS, WITHOUT
+   WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including,
+   without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,
+   MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+7. Should You wish to submit work that is not Your original creation, You may
+   submit it to Lightpanda separately from any Contribution, identifying the
+   complete details of its source and of any license or other restriction
+   (including, but not limited to, related patents, trademarks, and license
+   agreements) of which you are personally aware, and conspicuously marking the
+   work as “Submitted on behalf of a third-party: [named here]”.

CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing
+
+Lightpanda accepts pull requests through GitHub.
+
+You have to sign our [CLA](CLA.md) during your first pull request process
+otherwise we're not able to accept your contributions.
+
+The process signature uses the [CLA assistant
+lite](https://github.com/marketplace/actions/cla-assistant-lite). You can see
+an example of the process in [#303](https://github.com/lightpanda-io/browser/pull/303).

Dockerfile

@@ -0,0 +1,77 @@
+FROM debian:stable-slim
+
+ARG MINISIG=0.12
+ARG ZIG_MINISIG=RWSGOq2NVecA2UPNdBUZykf1CCb147pkmdtYxgb3Ti+JO/wCYvhbAb/U
+ARG V8=14.0.365.4
+ARG ZIG_V8=v0.3.4
+ARG TARGETPLATFORM
+
+RUN apt-get update -yq && \
+    apt-get install -yq xz-utils ca-certificates \
+        pkg-config libglib2.0-dev \
+        clang make curl git
+
+# Get Rust
+RUN curl https://sh.rustup.rs -sSf | sh -s -- --profile minimal -y
+ENV PATH="/root/.cargo/bin:${PATH}"
+
+# install minisig
+RUN curl --fail -L -O https://github.com/jedisct1/minisign/releases/download/${MINISIG}/minisign-${MINISIG}-linux.tar.gz && \
+    tar xvzf minisign-${MINISIG}-linux.tar.gz -C /
+
+# clone lightpanda
+RUN git clone https://github.com/lightpanda-io/browser.git
+WORKDIR /browser
+
+# install zig
+RUN ZIG=$(grep '\.minimum_zig_version = "' "build.zig.zon" | cut -d'"' -f2) && \
+    case $TARGETPLATFORM in \
+      "linux/arm64") ARCH="aarch64" ;; \
+      *) ARCH="x86_64" ;; \
+    esac && \
+    curl --fail -L -O https://ziglang.org/download/${ZIG}/zig-${ARCH}-linux-${ZIG}.tar.xz && \
+    curl --fail -L -O https://ziglang.org/download/${ZIG}/zig-${ARCH}-linux-${ZIG}.tar.xz.minisig && \
+    /minisign-linux/${ARCH}/minisign -Vm zig-${ARCH}-linux-${ZIG}.tar.xz -P ${ZIG_MINISIG} && \
+    tar xvf zig-${ARCH}-linux-${ZIG}.tar.xz && \
+    mv zig-${ARCH}-linux-${ZIG} /usr/local/lib && \
+    ln -s /usr/local/lib/zig-${ARCH}-linux-${ZIG}/zig /usr/local/bin/zig
+
+# download and install v8
+RUN case $TARGETPLATFORM in \
+    "linux/arm64") ARCH="aarch64" ;; \
+    *) ARCH="x86_64" ;; \
+    esac && \
+    curl --fail -L -o libc_v8.a https://github.com/lightpanda-io/zig-v8-fork/releases/download/${ZIG_V8}/libc_v8_${V8}_linux_${ARCH}.a && \
+    mkdir -p v8/ && \
+    mv libc_v8.a v8/libc_v8.a
+
+# build v8 snapshot
+RUN zig build -Doptimize=ReleaseFast \
+    -Dprebuilt_v8_path=v8/libc_v8.a \
+    snapshot_creator -- src/snapshot.bin
+
+# build release
+RUN zig build -Doptimize=ReleaseFast \
+    -Dsnapshot_path=../../snapshot.bin \
+    -Dprebuilt_v8_path=v8/libc_v8.a
+
+FROM debian:stable-slim
+
+RUN apt-get update -yq && \
+    apt-get install -yq tini
+
+FROM debian:stable-slim
+
+# copy ca certificates
+COPY --from=0 /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
+
+COPY --from=0 /browser/zig-out/bin/lightpanda /bin/lightpanda
+COPY --from=1 /usr/bin/tini /usr/bin/tini
+
+EXPOSE 9222/tcp
+
+# Lightpanda install only some signal handlers, and PID 1 doesn't have a default SIGTERM signal handler.
+# Using "tini" as PID1 ensures that signals work as expected, so e.g. "docker stop" will not hang.
+# (See https://github.com/krallin/tini#why-tini).
+ENTRYPOINT ["/usr/bin/tini", "--"]
+CMD ["/bin/lightpanda", "serve", "--host", "0.0.0.0", "--port", "9222", "--log-level", "info"]

LICENSING.md

@@ -0,0 +1,6 @@
+# Licensing
+
+License names used in this document are as per [SPDX License
+List](https://spdx.org/licenses/).
+
+The default license for this project is [AGPL-3.0-only](LICENSE).

Makefile

@@ -3,6 +3,30 @@
 
 ZIG := zig
 BC := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
+# option test filter make test F="server"
+F=
+
+# OS and ARCH
+kernel = $(shell uname -ms)
+ifeq ($(kernel), Darwin arm64)
+	OS := macos
+	ARCH := aarch64
+else ifeq ($(kernel), Darwin x86_64)
+	OS := macos
+	ARCH := x86_64
+else ifeq ($(kernel), Linux aarch64)
+	OS := linux
+	ARCH := aarch64
+else ifeq ($(kernel), Linux arm64)
+	OS := linux
+	ARCH := aarch64
+else ifeq ($(kernel), Linux x86_64)
+	OS := linux
+	ARCH := x86_64
+else
+	$(error "Unhandled kernel: $(kernel)")
+endif
+
 
 # Infos
 # -----
@@ -10,7 +34,7 @@ BC := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
 
 ## Display this help screen
 help:
-	@printf "\e[36m%-35s %s\e[0m\n" "Command" "Usage"
+	@printf "\033[36m%-35s %s\033[0m\n" "Command" "Usage"
 	@sed -n -e '/^## /{'\
 		-e 's/## //g;'\
 		-e 'h;'\
@@ -23,191 +47,57 @@ help:
 
 # $(ZIG) commands
 # ------------
-.PHONY: build build-dev run run-release shell test bench download-zig wpt
+.PHONY: build build-v8-snapshot build-dev run run-release test bench data end2end
 
-zig_version = $(shell grep 'recommended_zig_version = "' "vendor/zig-js-runtime/build.zig" | cut -d'"' -f2)
-kernel = $(shell uname -ms)
+## Build v8 snapshot
+build-v8-snapshot:
+	@printf "\033[36mBuilding v8 snapshot (release safe)...\033[0m\n"
+	@$(ZIG) build -Doptimize=ReleaseFast snapshot_creator -- src/snapshot.bin || (printf "\033[33mBuild ERROR\033[0m\n"; exit 1;)
+	@printf "\033[33mBuild OK\033[0m\n"
 
-## Download the zig recommended version
-download-zig:
-ifeq ($(kernel), Darwin x86_64)
-	$(eval target="macos")
-	$(eval arch="x86_64")
-else ifeq ($(kernel), Darwin arm64)
-	$(eval target="macos")
-	$(eval arch="aarch64")
-else ifeq ($(kernel), Linux aarch64)
-	$(eval target="linux")
-	$(eval arch="aarch64")
-else ifeq ($(kernel), Linux arm64)
-	$(eval target="linux")
-	$(eval arch="aarch64")
-else ifeq ($(kernel), Linux x86_64)
-	$(eval target="linux")
-	$(eval arch="x86_64")
-else
-	$(error "Unhandled kernel: $(kernel)")
-endif
-	$(eval url = "https://ziglang.org/builds/zig-$(target)-$(arch)-$(zig_version).tar.xz")
-	$(eval dest = "/tmp/zig-$(target)-$(arch)-$(zig_version).tar.xz")
-	@printf "\e[36mDownload zig version $(zig_version)...\e[0m\n"
-	@curl -o "$(dest)" -L "$(url)" || (printf "\e[33mBuild ERROR\e[0m\n"; exit 1;)
-	@printf "\e[33mDownloaded $(dest)\e[0m\n"
-
-## Build in release-safe mode
-build:
-	@printf "\e[36mBuilding (release safe)...\e[0m\n"
-	@$(ZIG) build -Doptimize=ReleaseSafe -Dengine=v8 || (printf "\e[33mBuild ERROR\e[0m\n"; exit 1;)
-	@printf "\e[33mBuild OK\e[0m\n"
+## Build in release-fast mode
+build: build-v8-snapshot
+	@printf "\033[36mBuilding (release fast)...\033[0m\n"
+	@$(ZIG) build -Doptimize=ReleaseFast -Dsnapshot_path=../../snapshot.bin || (printf "\033[33mBuild ERROR\033[0m\n"; exit 1;)
+	@printf "\033[33mBuild OK\033[0m\n"
 
 ## Build in debug mode
 build-dev:
-	@printf "\e[36mBuilding (debug)...\e[0m\n"
-	@$(ZIG) build -Dengine=v8 || (printf "\e[33mBuild ERROR\e[0m\n"; exit 1;)
-	@printf "\e[33mBuild OK\e[0m\n"
+	@printf "\033[36mBuilding (debug)...\033[0m\n"
+	@$(ZIG) build || (printf "\033[33mBuild ERROR\033[0m\n"; exit 1;)
+	@printf "\033[33mBuild OK\033[0m\n"
+
+## Run the server in release mode
+run: build
+	@printf "\033[36mRunning...\033[0m\n"
+	@./zig-out/bin/lightpanda || (printf "\033[33mRun ERROR\033[0m\n"; exit 1;)
 
 ## Run the server in debug mode
-run: build
-	@printf "\e[36mRunning...\e[0m\n"
-	@./zig-out/bin/browsercore || (printf "\e[33mRun ERROR\e[0m\n"; exit 1;)
+run-debug: build-dev
+	@printf "\033[36mRunning...\033[0m\n"
+	@./zig-out/bin/lightpanda || (printf "\033[33mRun ERROR\033[0m\n"; exit 1;)
 
-## Run a JS shell in debug mode
-shell:
-	@printf "\e[36mBuilding shell...\e[0m\n"
-	@$(ZIG) build shell -Dengine=v8 || (printf "\e[33mBuild ERROR\e[0m\n"; exit 1;)
-
-## Run WPT tests
-wpt:
-	@printf "\e[36mBuilding wpt...\e[0m\n"
-	@$(ZIG) build wpt -Dengine=v8 -- --safe $(filter-out $@,$(MAKECMDGOALS)) || (printf "\e[33mBuild ERROR\e[0m\n"; exit 1;)
-
-wpt-summary:
-	@printf "\e[36mBuilding wpt...\e[0m\n"
-	@$(ZIG) build wpt -Dengine=v8 -- --safe --summary $(filter-out $@,$(MAKECMDGOALS)) || (printf "\e[33mBuild ERROR\e[0m\n"; exit 1;)
-
-## Test
+## Test - `grep` is used to filter out the huge compile command on build
+ifeq ($(OS), macos)
 test:
-	@printf "\e[36mTesting...\e[0m\n"
-	@$(ZIG) build test -Dengine=v8 || (printf "\e[33mTest ERROR\e[0m\n"; exit 1;)
-	@printf "\e[33mTest OK\e[0m\n"
+	@script -q /dev/null sh -c 'TEST_FILTER="${F}" $(ZIG) build test -freference-trace' 2>&1 \
+		| grep --line-buffered -v "^/.*zig test -freference-trace"
+else
+test:
+	@script -qec 'TEST_FILTER="${F}" $(ZIG) build test -freference-trace' /dev/null 2>&1 \
+		| grep --line-buffered -v "^/.*zig test -freference-trace"
+endif
+
+## Run demo/runner end to end tests
+end2end:
+	@test -d ../demo
+	cd ../demo && go run runner/main.go
 
 # Install and build required dependencies commands
 # ------------
-.PHONY: install-submodule
-.PHONY: install-zig-js-runtime install-zig-js-runtime-dev install-libiconv
-.PHONY: _install-netsurf install-netsurf clean-netsurf test-netsurf install-netsurf-dev
-.PHONY: install-mimalloc install-mimalloc-dev clean-mimalloc
-.PHONY: install-dev install
+.PHONY: install
 
-## Install and build dependencies for release
-install: install-submodule install-zig-js-runtime install-netsurf install-mimalloc
+install: build
 
-## Install and build dependencies for dev
-install-dev: install-submodule install-zig-js-runtime-dev install-netsurf-dev install-mimalloc-dev
-
-install-netsurf-dev: _install-netsurf
-install-netsurf-dev: OPTCFLAGS := -O0 -g -DNDEBUG
-
-install-netsurf: _install-netsurf
-install-netsurf: OPTCFLAGS := -DNDEBUG
-
-BC_NS := $(BC)vendor/netsurf
-ICONV := $(BC)vendor/libiconv
-# TODO: add Linux iconv path (I guess it depends on the distro)
-# TODO: this way of linking libiconv is not ideal. We should have a more generic way
-# and stick to a specif version. Maybe build from source. Anyway not now.
-_install-netsurf: install-libiconv
-	@printf "\e[36mInstalling NetSurf...\e[0m\n" && \
-	ls $(ICONV) 1> /dev/null || (printf "\e[33mERROR: you need to install libiconv in your system (on MacOS on with Homebrew)\e[0m\n"; exit 1;) && \
-	export PREFIX=$(BC_NS) && \
-	export OPTLDFLAGS="-L$(ICONV)/lib" && \
-	export OPTCFLAGS="$(OPTCFLAGS) -I$(ICONV)/include" && \
-	printf "\e[33mInstalling libwapcaplet...\e[0m\n" && \
-	cd vendor/netsurf/libwapcaplet && \
-	BUILDDIR=$(BC_NS)/build/libwapcaplet make install && \
-	cd ../libparserutils && \
-	printf "\e[33mInstalling libparserutils...\e[0m\n" && \
-	BUILDDIR=$(BC_NS)/build/libparserutils make install && \
-	cd ../libhubbub && \
-	printf "\e[33mInstalling libhubbub...\e[0m\n" && \
-	BUILDDIR=$(BC_NS)/build/libhubbub make install && \
-	rm src/treebuilder/autogenerated-element-type.c && \
-	cd ../libdom && \
-	printf "\e[33mInstalling libdom...\e[0m\n" && \
-	BUILDDIR=$(BC_NS)/build/libdom make install && \
-	printf "\e[33mRunning libdom example...\e[0m\n" && \
-	cd examples && \
-	zig cc \
-	-I$(ICONV)/include \
-	-I$(BC_NS)/include \
-	-L$(ICONV)/lib \
-	-L$(BC_NS)/lib \
-	-liconv \
-	-ldom \
-	-lhubbub \
-	-lparserutils \
-	-lwapcaplet \
-	-o a.out \
-	dom-structure-dump.c \
-	$(ICONV)/lib/libiconv.a && \
-	./a.out > /dev/null && \
-	rm a.out && \
-	printf "\e[36mDone NetSurf $(OS)\e[0m\n"
-
-clean-netsurf:
-	@printf "\e[36mCleaning NetSurf build...\e[0m\n" && \
-	cd vendor/netsurf && \
-	rm -R build && \
-	rm -R lib && \
-	rm -R include
-
-test-netsurf:
-	@printf "\e[36mTesting NetSurf...\e[0m\n" && \
-	export PREFIX=$(BC_NS) && \
-	export LDFLAGS="-L$(ICONV)/lib -L$(BC_NS)/lib" && \
-	export CFLAGS="-I$(ICONV)/include -I$(BC_NS)/include" && \
-	cd vendor/netsurf/libdom && \
-	BUILDDIR=$(BC_NS)/build/libdom make test
-
-install-libiconv:
-ifeq ("$(wildcard vendor/libiconv/lib/libiconv.a)","")
-	@mkdir -p vendor/libiconv
-	@cd vendor/libiconv && \
-	curl https://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.17.tar.gz | tar -xvzf -
-	@cd vendor/libiconv/libiconv-1.17 && \
-	./configure --prefix=$(BC)vendor/libiconv --enable-static && \
-	make && make install
-endif
-
-install-zig-js-runtime-dev:
-	@cd vendor/zig-js-runtime && \
-	make install-dev
-
-install-zig-js-runtime:
-	@cd vendor/zig-js-runtime && \
-	make install
-
-.PHONY: _build_mimalloc
-_build_mimalloc:
-	@cd vendor/mimalloc && \
-		mkdir -p out/include && \
-		cp include/mimalloc.h out/include/ && \
-		cd out && \
-		cmake -DMI_BUILD_SHARED=OFF -DMI_BUILD_OBJECT=OFF -DMI_BUILD_TESTS=OFF -DMI_OVERRIDE=OFF $(OPTS) .. && \
-		make
-
-install-mimalloc-dev: _build_mimalloc
-install-mimalloc-dev: OPTS=-DCMAKE_BUILD_TYPE=Debug
-install-mimalloc-dev:
-	@cd vendor/mimalloc/out && \
-		mv libmimalloc-debug.a libmimalloc.a
-
-install-mimalloc: _build_mimalloc
-
-clean-mimalloc:
-	@rm -fr vendor/mimalloc/lib/*
-
-## Init and update git submodule
-install-submodule:
-	@git submodule init && \
-	git submodule update
+data:
+	cd src/data && go run public_suffix_list_gen.go > public_suffix_list.zig

README.md

@@ -1,160 +1,250 @@
 <p align="center">
   <a href="https://lightpanda.io"><img src="https://cdn.lightpanda.io/assets/images/logo/lpd-logo.png" alt="Logo" height=170></a>
 </p>
+<h1 align="center">Lightpanda Browser</h1>
+<p align="center">
+<strong>The headless browser built from scratch for AI agents and automation.</strong><br>
+Not a Chromium fork. Not a WebKit patch. A new browser, written in Zig.
+</p>
 
-<h1 align="center">Lightpanda</h1>
-
-<div align="center">
-	<br />
 </div>
+<div align="center">
+
+[![License](https://img.shields.io/github/license/lightpanda-io/browser)](https://github.com/lightpanda-io/browser/blob/main/LICENSE)
+[![Twitter Follow](https://img.shields.io/twitter/follow/lightpanda_io)](https://twitter.com/lightpanda_io)
+[![GitHub stars](https://img.shields.io/github/stars/lightpanda-io/browser)](https://github.com/lightpanda-io/browser)
+[![Discord](https://img.shields.io/discord/1391984864894521354?style=flat-square&label=discord)](https://discord.gg/K63XeymfB5)
+
+</div>
+<div align="center">
+
+[<img width="350px" src="https://cdn.lightpanda.io/assets/images/github/execution-time-v2.svg">
+](https://github.com/lightpanda-io/demo)
+&emsp;
+[<img width="350px" src="https://cdn.lightpanda.io/assets/images/github/memory-frame-v2.svg">
+](https://github.com/lightpanda-io/demo)
+</div>
+
+_chromedp requesting 933 real web pages over the network on a AWS EC2 m5.large instance.
+See [benchmark details](https://github.com/lightpanda-io/demo/blob/main/BENCHMARKS.md#crawler-benchmark)._
 
 Lightpanda is the open-source browser made for headless usage:
 
 - Javascript execution
-- Support of the Web APIs (partial, WIP)
-- Compatible with Playwright, Puppeteer through CDP (WIP)
+- Support of Web APIs (partial, WIP)
+- Compatible with Playwright[^1], Puppeteer, chromedp through [CDP](https://chromedevtools.github.io/devtools-protocol/)
 
-Fast scraping and web automation with minimal memory footprint:
+Fast web automation for AI agents, LLM training, scraping and testing:
 
-- Ultra-low memory footprint (12x less than Chrome)
-- Blazingly fast & instant startup (64x faster than Chrome)
+- Ultra-low memory footprint (9x less than Chrome)
+- Exceptionally fast execution (11x faster than Chrome)
+- Instant startup
 
-<img width=500px src="https://cdn.lightpanda.io/assets/images/benchmark2.png">
+[^1]: **Playwright support disclaimer:**
+Due to the nature of Playwright, a script that works with the current version of the browser may not function correctly with a future version. Playwright uses an intermediate JavaScript layer that selects an execution strategy based on the browser's available features. If Lightpanda adds a new [Web API](https://developer.mozilla.org/en-US/docs/Web/API), Playwright may choose to execute different code for the same script. This new code path could attempt to use features that are not yet implemented. Lightpanda makes an effort to add compatibility tests, but we can't cover all scenarios. If you encounter an issue, please create a [GitHub issue](https://github.com/lightpanda-io/browser/issues) and include the last known working version of the script.
 
-See [benchmark details](https://github.com/lightpanda-io/demo).
+## Quick start
 
-## Why?
+### Install
+**Install from the nightly builds**
 
-### Javascript execution is mandatory for the modern web
+You can download the last binary from the [nightly
+builds](https://github.com/lightpanda-io/browser/releases/tag/nightly) for
+Linux x86_64 and MacOS aarch64.
 
-Back in the good old times, grabbing a webpage was as easy as making an HTTP request, cURL-like. It’s not possible anymore, because Javascript is everywhere, like it or not:
+*For Linux*
+```console
+curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux && \
+chmod a+x ./lightpanda
+```
 
-- Ajax, Single Page App, Infinite loading, “click to display”, instant search, etc.
-- JS web frameworks: React, Vue, Angular & others
+*For MacOS*
+```console
+curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos && \
+chmod a+x ./lightpanda
+```
 
-### Chrome is not the right tool
+*For Windows + WSL2*
 
-So if we need Javascript, why not use a real web browser. Let’s take a huge desktop application, hack it, and run it on the server, right? Hundreds of instance of Chrome if you use it at scale. Are you sure it’s such a good idea?
+The Lightpanda browser is compatible to run on windows inside WSL. Follow the Linux instruction for installation from a WSL terminal.
+It is recommended to install clients like Puppeteer on the Windows host.
 
-- Heavy on RAM and CPU, expensive to run
-- Hard to package, deploy and maintain at scale
-- Bloated, lots of features are not useful in headless usage
+**Install from Docker**
 
-### Lightpanda is built for performance
+Lightpanda provides [official Docker
+images](https://hub.docker.com/r/lightpanda/browser) for both Linux amd64 and
+arm64 architectures.
+The following command fetches the Docker image and starts a new container exposing Lightpanda's CDP server on port `9222`.
+```console
+docker run -d --name lightpanda -p 9222:9222 lightpanda/browser:nightly
+```
 
-If we want both Javascript and performance, for a real headless browser, we need to start from scratch. Not yet another iteration of Chromium, really from a blank page. Crazy right? But that’s we did:
+### Dump a URL
 
-- Not based on Chromium, Blink or WebKit
-- Low-level system programming language (Zig) with optimisations in mind
-- Opinionated, no rendering
+```console
+./lightpanda fetch --obey-robots --log-format pretty  --log-level info https://demo-browser.lightpanda.io/campfire-commerce/
+```
+```console
+INFO  telemetry : telemetry status . . . . . . . . . . . . .  [+0ms]
+      disabled = false
+
+INFO  page : navigate . . . . . . . . . . . . . . . . . . . . [+6ms]
+      url = https://demo-browser.lightpanda.io/campfire-commerce/
+      method = GET
+      reason = address_bar
+      body = false
+      req_id = 1
+
+INFO  browser : executing script . . . . . . . . . . . . . .  [+118ms]
+      src = https://demo-browser.lightpanda.io/campfire-commerce/script.js
+      kind = javascript
+      cacheable = true
+
+INFO  http : request complete . . . . . . . . . . . . . . . . [+140ms]
+      source = xhr
+      url = https://demo-browser.lightpanda.io/campfire-commerce/json/product.json
+      status = 200
+      len = 4770
+
+INFO  http : request complete . . . . . . . . . . . . . . . . [+141ms]
+      source = fetch
+      url = https://demo-browser.lightpanda.io/campfire-commerce/json/reviews.json
+      status = 200
+      len = 1615
+<!DOCTYPE html>
+```
+
+### Start a CDP server
+
+```console
+./lightpanda serve --obey-robots --log-format pretty  --log-level info --host 127.0.0.1 --port 9222
+```
+```console
+INFO  telemetry : telemetry status . . . . . . . . . . . . .  [+0ms]
+      disabled = false
+
+INFO  app : server running . . . . . . . . . . . . . . . . .  [+0ms]
+      address = 127.0.0.1:9222
+```
+
+Once the CDP server started, you can run a Puppeteer script by configuring the
+`browserWSEndpoint`.
+
+```js
+'use strict'
+
+import puppeteer from 'puppeteer-core';
+
+// use browserWSEndpoint to pass the Lightpanda's CDP server address.
+const browser = await puppeteer.connect({
+  browserWSEndpoint: "ws://127.0.0.1:9222",
+});
+
+// The rest of your script remains the same.
+const context = await browser.createBrowserContext();
+const page = await context.newPage();
+
+// Dump all the links from the page.
+await page.goto('https://demo-browser.lightpanda.io/amiibo/', {waitUntil: "networkidle0"});
+
+const links = await page.evaluate(() => {
+  return Array.from(document.querySelectorAll('a')).map(row => {
+    return row.getAttribute('href');
+  });
+});
+
+console.log(links);
+
+await page.close();
+await context.close();
+await browser.disconnect();
+```
+
+### Telemetry
+By default, Lightpanda collects and sends usage telemetry. This can be disabled by setting an environment variable `LIGHTPANDA_DISABLE_TELEMETRY=true`. You can read Lightpanda's privacy policy at: [https://lightpanda.io/privacy-policy](https://lightpanda.io/privacy-policy).
 
 ## Status
 
-Lightpanda is still a work in progress and is currently at the Alpha stage.
+Lightpanda is in Beta and currently a work in progress. Stability and coverage are improving and many websites now work.
+You may still encounter errors or crashes. Please open an issue with specifics if so.
 
-Here are the key features we want to implement before releasing a Beta version:
+Here are the key features we have implemented:
 
-- [x] Loader
-- [x] HTML parser and DOM tree
-- [x] Javascript support
-- [x] Basic DOM APIs
+- [x] HTTP loader ([Libcurl](https://curl.se/libcurl/))
+- [x] HTML parser ([html5ever](https://github.com/servo/html5ever))
+- [x] DOM tree
+- [x] Javascript support ([v8](https://v8.dev/))
+- [x] DOM APIs
 - [x] Ajax
   - [x] XHR API
-  - [ ] Fetch API
+  - [x] Fetch API
 - [x] DOM dump
-- [ ] Basic CDP server
+- [x] CDP/websockets server
+- [x] Click
+- [x] Input form
+- [x] Cookies
+- [x] Custom HTTP headers
+- [x] Proxy support
+- [x] Network interception
+- [x] Respect `robots.txt` with option `--obey-robots`
 
-We will not provide binary versions until we reach at least the Beta stage.
-
-NOTE: There are hundreds of Web APIs. Developing a browser, even just for headless mode, is a huge task. It's more about coverage than a _working/not working_ binary situation.
-
-You can also follow the progress of our Javascript support in our dedicated [zig-js-runtime](https://github.com/lightpanda-io/zig-js-runtime#development) project.
+NOTE: There are hundreds of Web APIs. Developing a browser (even just for headless mode) is a huge task. Coverage will increase over time.
 
 ## Build from sources
 
-We do not provide yet binary versions of Lightpanda, you have to compile it from source.
-
 ### Prerequisites
 
-Lightpanda is written with [Zig](https://ziglang.org/) `0.12.1`. You have to
+Lightpanda is written with [Zig](https://ziglang.org/) `0.15.2`. You have to
 install it with the right version in order to build the project.
 
 Lightpanda also depends on
-[zig-js-runtime](https://github.com/lightpanda-io/zig-js-runtime/) (with v8),
-[Netsurf libs](https://www.netsurf-browser.org/) and
-[Mimalloc](https://microsoft.github.io/mimalloc).
+[v8](https://chromium.googlesource.com/v8/v8.git),
+[Libcurl](https://curl.se/libcurl/) and [html5ever](https://github.com/servo/html5ever).
 
-To be able to build the v8 engine for zig-js-runtime, you have to install some libs:
+To be able to build the v8 engine, you have to install some libs:
 
-For Debian/Ubuntu based Linux:
+For **Debian/Ubuntu based Linux**:
 
 ```
-sudo apt install xz-utils \
-    python3 ca-certificates git \
+sudo apt install xz-utils ca-certificates \
     pkg-config libglib2.0-dev \
-    gperf libexpat1-dev \
-    cmake clang
+    clang make curl git
+```
+You also need to [install Rust](https://rust-lang.org/tools/install/).
+
+For systems with [**Nix**](https://nixos.org/download/), you can use the devShell:
+```
+nix develop
 ```
 
-For MacOS, you only need cmake:
-
+For **MacOS**, you need cmake and [Rust](https://rust-lang.org/tools/install/).
 ```
 brew install cmake
 ```
 
-### Install and build dependencies
+### Build and run
 
-#### All in one build
+You an build the entire browser with `make build` or `make build-dev` for debug
+env.
 
-You can run `make install` to install deps all in one (or `make install-dev` if you need the development versions).
+But you can directly use the zig command: `zig build run`.
 
-Be aware that the build task is very long and cpu consuming, as you will build from sources all dependancies, including the v8 Javascript engine.
+#### Embed v8 snapshot
 
-#### Step by step build dependancy
-
-The project uses git submodules for dependencies.
-
-To init or update the submodules in the `vendor/` directory:
+Lighpanda uses v8 snapshot. By default, it is created on startup but you can
+embed it by using the following commands:
 
+Generate the snapshot.
 ```
-make install-submodule
+zig build snapshot_creator -- src/snapshot.bin
 ```
 
-**Netsurf libs**
-
-Netsurf libs are used for HTML parsing and DOM tree generation.
-
+Build using the snapshot binary.
 ```
-make install-netsurf
+zig build -Dsnapshot_path=../../snapshot.bin
 ```
 
-For dev env, use `make install-netsurf-dev`.
-
-**Mimalloc**
-
-Mimalloc is used as a C memory allocator.
-
-```
-make install-mimalloc
-```
-
-For dev env, use `make install-mimalloc-dev`.
-
-Note: when Mimalloc is built in dev mode, you can dump memory stats with the
-env var `MIMALLOC_SHOW_STATS=1`. See
-[https://microsoft.github.io/mimalloc/environment.html](https://microsoft.github.io/mimalloc/environment.html).
-
-**zig-js-runtime**
-
-Our own Zig/Javascript runtime, which includes the v8 Javascript engine.
-
-This build task is very long and cpu consuming, as you will build v8 from sources.
-
-```
-make install-zig-js-runtime
-```
-
-For dev env, use `make iinstall-zig-js-runtime-dev`.
+See [#1279](https://github.com/lightpanda-io/browser/pull/1279) for more details.
 
 ## Test
 
@@ -162,37 +252,123 @@ For dev env, use `make iinstall-zig-js-runtime-dev`.
 
 You can test Lightpanda by running `make test`.
 
+### End to end tests
+
+To run end to end tests, you need to clone the [demo
+repository](https://github.com/lightpanda-io/demo) into `../demo` dir.
+
+You have to install the [demo's node
+requirements](https://github.com/lightpanda-io/demo?tab=readme-ov-file#dependencies-1)
+
+You also need to install [Go](https://go.dev) > v1.24.
+
+```
+make end2end
+```
+
 ### Web Platform Tests
 
 Lightpanda is tested against the standardized [Web Platform
 Tests](https://web-platform-tests.org/).
 
-The relevant tests cases are committed in a [dedicated repository](https://github.com/lightpanda-io/wpt) which is fetched by the `make install-submodule` command.
-
-All the tests cases executed are located in the `tests/wpt` sub-directory.
+We use [a fork](https://github.com/lightpanda-io/wpt/tree/fork) including a custom
+[`testharnessreport.js`](https://github.com/lightpanda-io/wpt/commit/01a3115c076a3ad0c84849dbbf77a6e3d199c56f).
 
 For reference, you can easily execute a WPT test case with your browser via
 [wpt.live](https://wpt.live).
 
+#### Configure WPT HTTP server
+
+To run the test, you must clone the repository, configure the custom hosts and generate the
+`MANIFEST.json` file.
+
+Clone the repository with the `fork` branch.
+```
+git clone -b fork --depth=1 git@github.com:lightpanda-io/wpt.git
+```
+
+Enter into the `wpt/` dir.
+
+Install custom domains in your `/etc/hosts`
+```
+./wpt make-hosts-file | sudo tee -a /etc/hosts
+```
+
+Generate `MANIFEST.json`
+```
+./wpt manifest
+```
+Use the [WPT's setup
+guide](https://web-platform-tests.org/running-tests/from-local-system.html) for
+details.
+
 #### Run WPT test suite
 
-To run all the tests:
+An external [Go](https://go.dev) runner is provided by
+[github.com/lightpanda-io/demo/](https://github.com/lightpanda-io/demo/)
+repository, located into `wptrunner/` dir.
+You need to clone the project first.
+
+First start the WPT's HTTP server from your `wpt/` clone dir.
+```
+./wpt serve
+```
+
+Run a Lightpanda browser
 
 ```
-make wpt
+zig build run -- --insecure-disable-tls-host-verification
+```
+
+Then you can start the wptrunner from the Demo's clone dir:
+```
+cd wptrunner && go run .
 ```
 
 Or one specific test:
 
 ```
-make wpt Node-childNodes.html
+cd wptrunner && go run . Node-childNodes.html
 ```
 
-#### Add a new WPT test case
+`wptrunner` command accepts `--summary` and `--json` options modifying output.
+Also `--concurrency` define the concurrency limit.
 
-We add new relevant tests cases files when we implemented changes in Lightpanda.
+:warning: Running the whole test suite will take a long time. In this case,
+it's useful to build in `releaseFast` mode to make tests faster.
 
-To add a new test, copy the file you want from the [WPT
-repo](https://github.com/web-platform-tests/wpt) into the `tests/wpt` directory.
+```
+zig build -Doptimize=ReleaseFast run
+```
 
-:warning: Please keep the original directory tree structure of `tests/wpt`.
+## Contributing
+
+Lightpanda accepts pull requests through GitHub.
+
+You have to sign our [CLA](CLA.md) during the pull request process otherwise
+we're not able to accept your contributions.
+
+## Why?
+
+### Javascript execution is mandatory for the modern web
+
+In the good old days, scraping a webpage was as easy as making an HTTP request, cURL-like. It’s not possible anymore, because Javascript is everywhere, like it or not:
+
+- Ajax, Single Page App, infinite loading, “click to display”, instant search, etc.
+- JS web frameworks: React, Vue, Angular & others
+
+### Chrome is not the right tool
+
+If we need Javascript, why not use a real web browser? Take a huge desktop application, hack it, and run it on the server. Hundreds or thousands of instances of Chrome if you use it at scale. Are you sure it’s such a good idea?
+
+- Heavy on RAM and CPU, expensive to run
+- Hard to package, deploy and maintain at scale
+- Bloated, lots of features are not useful in headless usage
+
+### Lightpanda is built for performance
+
+If we want both Javascript and performance in a true headless browser, we need to start from scratch. Not another iteration of Chromium, really from a blank page. Crazy right? But that’s what we did:
+
+- Not based on Chromium, Blink or WebKit
+- Low-level system programming language (Zig) with optimisations in mind
+- Opinionated: without graphical rendering

build.zig

@@ -17,206 +17,743 @@
 // along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 const std = @import("std");
-
 const builtin = @import("builtin");
 
-const jsruntime_path = "vendor/zig-js-runtime/";
-const jsruntime = @import("vendor/zig-js-runtime/build.zig");
-const jsruntime_pkgs = jsruntime.packages(jsruntime_path);
+const lightpanda_version = std.SemanticVersion.parse(@import("build.zig.zon").version) catch unreachable;
+const min_zig_version = std.SemanticVersion.parse(@import("build.zig.zon").minimum_zig_version) catch unreachable;
 
-/// Do not rename this constant. It is scanned by some scripts to determine
-/// which zig version to install.
-const recommended_zig_version = jsruntime.recommended_zig_version;
-
-pub fn build(b: *std.Build) !void {
-    switch (comptime builtin.zig_version.order(std.SemanticVersion.parse(recommended_zig_version) catch unreachable)) {
-        .eq => {},
-        .lt => {
-            @compileError("The minimum version of Zig required to compile is '" ++ recommended_zig_version ++ "', found '" ++ builtin.zig_version_string ++ "'.");
-        },
-        .gt => {
-            std.debug.print(
-                "WARNING: Recommended Zig version '{s}', but found '{s}', build may fail...\n\n",
-                .{ recommended_zig_version, builtin.zig_version_string },
-            );
-        },
+const Build = blk: {
+    if (builtin.zig_version.order(min_zig_version) == .lt) {
+        const message = std.fmt.comptimePrint(
+            \\Zig version is too old:
+            \\  current Zig version: {f}
+            \\  minimum Zig version: {f}
+        , .{ builtin.zig_version, min_zig_version });
+        @compileError(message);
+    } else {
+        break :blk std.Build;
     }
+};
 
+pub fn build(b: *Build) !void {
     const target = b.standardTargetOptions(.{});
-    const mode = b.standardOptimizeOption(.{});
+    const optimize = b.standardOptimizeOption(.{});
 
-    const options = try jsruntime.buildOptions(b);
+    const prebuilt_v8_path = b.option([]const u8, "prebuilt_v8_path", "Path to prebuilt libc_v8.a");
+    const snapshot_path = b.option([]const u8, "snapshot_path", "Path to v8 snapshot");
 
-    // browser
-    // -------
+    const version = resolveVersion(b);
+    var stdout = std.fs.File.stdout().writer(&.{});
+    try stdout.interface.print("Lightpanda {f}\n", .{version});
 
-    // compile and install
-    const exe = b.addExecutable(.{
-        .name = "browsercore",
-        .root_source_file = b.path("src/main.zig"),
-        .target = target,
-        .optimize = mode,
-    });
-    try common(b, exe, options);
-    b.installArtifact(exe);
+    var opts = b.addOptions();
+    opts.addOption([]const u8, "version", b.fmt("{f}", .{version}));
+    opts.addOption(?[]const u8, "snapshot_path", snapshot_path);
 
-    // run
-    const run_cmd = b.addRunArtifact(exe);
-    if (b.args) |args| {
-        run_cmd.addArgs(args);
-    }
+    const enable_tsan = b.option(bool, "tsan", "Enable Thread Sanitizer") orelse false;
+    const enable_asan = b.option(bool, "asan", "Enable Address Sanitizer") orelse false;
+    const enable_csan = b.option(std.zig.SanitizeC, "csan", "Enable C Sanitizers");
 
-    // step
-    const run_step = b.step("run", "Run the app");
-    run_step.dependOn(&run_cmd.step);
+    const lightpanda_module = blk: {
+        const mod = b.addModule("lightpanda", .{
+            .root_source_file = b.path("src/lightpanda.zig"),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = true,
+            .link_libcpp = true,
+            .sanitize_c = enable_csan,
+            .sanitize_thread = enable_tsan,
+        });
+        mod.addImport("lightpanda", mod); // allow circular "lightpanda" import
+        mod.addImport("build_config", opts.createModule());
 
-    // shell
-    // -----
+        // Format check
+        const fmt_step = b.step("fmt", "Check code formatting");
+        const fmt = b.addFmt(.{
+            .paths = &.{ "src", "build.zig", "build.zig.zon" },
+            .check = true,
+        });
+        fmt_step.dependOn(&fmt.step);
 
-    // compile and install
-    const shell = b.addExecutable(.{
-        .name = "browsercore-shell",
-        .root_source_file = b.path("src/main_shell.zig"),
-        .target = target,
-        .optimize = mode,
-    });
-    try common(b, shell, options);
-    try jsruntime_pkgs.add_shell(shell);
+        // Set default behavior
+        b.default_step.dependOn(fmt_step);
 
-    // run
-    const shell_cmd = b.addRunArtifact(shell);
-    if (b.args) |args| {
-        shell_cmd.addArgs(args);
-    }
+        try linkV8(b, mod, enable_asan, enable_tsan, prebuilt_v8_path);
+        try linkCurl(b, mod, enable_tsan);
+        try linkHtml5Ever(b, mod);
 
-    // step
-    const shell_step = b.step("shell", "Run JS shell");
-    shell_step.dependOn(&shell_cmd.step);
-
-    // test
-    // ----
-
-    // compile
-    const tests = b.addTest(.{
-        .root_source_file = b.path("src/run_tests.zig"),
-        .test_runner = b.path("src/test_runner.zig"),
-        .target = target,
-        .optimize = mode,
-    });
-    try common(b, tests, options);
-
-    // add jsruntime pretty deps
-    tests.root_module.addAnonymousImport("pretty", .{
-        .root_source_file = b.path("vendor/zig-js-runtime/src/pretty.zig"),
-    });
-
-    const run_tests = b.addRunArtifact(tests);
-    if (b.args) |args| {
-        run_tests.addArgs(args);
-    }
-
-    // step
-    const test_step = b.step("test", "Run unit tests");
-    test_step.dependOn(&run_tests.step);
-
-    // wpt
-    // -----
-
-    // compile and install
-    const wpt = b.addExecutable(.{
-        .name = "browsercore-wpt",
-        .root_source_file = b.path("src/main_wpt.zig"),
-        .target = target,
-        .optimize = mode,
-    });
-    try common(b, wpt, options);
-
-    // run
-    const wpt_cmd = b.addRunArtifact(wpt);
-    if (b.args) |args| {
-        wpt_cmd.addArgs(args);
-    }
-    // step
-    const wpt_step = b.step("wpt", "WPT tests");
-    wpt_step.dependOn(&wpt_cmd.step);
-
-    // get
-    // -----
-
-    // compile and install
-    const get = b.addExecutable(.{
-        .name = "browsercore-get",
-        .root_source_file = b.path("src/main_get.zig"),
-        .target = target,
-        .optimize = mode,
-    });
-    try common(b, get, options);
-    b.installArtifact(get);
-
-    // run
-    const get_cmd = b.addRunArtifact(get);
-    if (b.args) |args| {
-        get_cmd.addArgs(args);
-    }
-    // step
-    const get_step = b.step("get", "request URL");
-    get_step.dependOn(&get_cmd.step);
-}
-
-fn common(
-    b: *std.Build,
-    step: *std.Build.Step.Compile,
-    options: jsruntime.Options,
-) !void {
-    const jsruntimemod = try jsruntime_pkgs.module(
-        b,
-        options,
-        step.root_module.optimize.?,
-        step.root_module.resolved_target.?,
-    );
-    step.root_module.addImport("jsruntime", jsruntimemod);
-
-    const netsurf = moduleNetSurf(b);
-    netsurf.addImport("jsruntime", jsruntimemod);
-    step.root_module.addImport("netsurf", netsurf);
-}
-
-fn moduleNetSurf(b: *std.Build) *std.Build.Module {
-    const mod = b.addModule("netsurf", .{
-        .root_source_file = b.path("src/netsurf/netsurf.zig"),
-    });
-    // iconv
-    mod.addObjectFile(b.path("vendor/libiconv/lib/libiconv.a"));
-    mod.addIncludePath(b.path("vendor/libiconv/include"));
-
-    // mimalloc
-    mod.addImport("mimalloc", moduleMimalloc(b));
-
-    // netsurf libs
-    const ns = "vendor/netsurf";
-    mod.addIncludePath(b.path(ns ++ "/include"));
-
-    const libs: [4][]const u8 = .{
-        "libdom",
-        "libhubbub",
-        "libparserutils",
-        "libwapcaplet",
+        break :blk mod;
     };
-    inline for (libs) |lib| {
-        mod.addObjectFile(b.path(ns ++ "/lib/" ++ lib ++ ".a"));
-        mod.addIncludePath(b.path(ns ++ "/" ++ lib ++ "/src"));
+
+    {
+        // browser
+        const exe = b.addExecutable(.{
+            .name = "lightpanda",
+            .use_llvm = true,
+            .root_module = b.createModule(.{
+                .root_source_file = b.path("src/main.zig"),
+                .target = target,
+                .optimize = optimize,
+                .sanitize_c = enable_csan,
+                .sanitize_thread = enable_tsan,
+                .imports = &.{
+                    .{ .name = "lightpanda", .module = lightpanda_module },
+                },
+            }),
+        });
+        b.installArtifact(exe);
+
+        const run_cmd = b.addRunArtifact(exe);
+        if (b.args) |args| {
+            run_cmd.addArgs(args);
+        }
+        const run_step = b.step("run", "Run the app");
+        run_step.dependOn(&run_cmd.step);
+
+        const version_info_step = b.step("version", "Print the resolved version information");
+        const version_info_run = b.addRunArtifact(exe);
+        version_info_run.addArg("version");
+        version_info_step.dependOn(&version_info_run.step);
     }
 
-    return mod;
+    {
+        // snapshot creator
+        const exe = b.addExecutable(.{
+            .name = "lightpanda-snapshot-creator",
+            .use_llvm = true,
+            .root_module = b.createModule(.{
+                .root_source_file = b.path("src/main_snapshot_creator.zig"),
+                .target = target,
+                .optimize = optimize,
+                .imports = &.{
+                    .{ .name = "lightpanda", .module = lightpanda_module },
+                },
+            }),
+        });
+        b.installArtifact(exe);
+
+        const run_cmd = b.addRunArtifact(exe);
+        if (b.args) |args| {
+            run_cmd.addArgs(args);
+        }
+        const run_step = b.step("snapshot_creator", "Generate a v8 snapshot");
+        run_step.dependOn(&run_cmd.step);
+    }
+
+    {
+        // test
+        const tests = b.addTest(.{
+            .root_module = lightpanda_module,
+            .use_llvm = true,
+            .test_runner = .{ .path = b.path("src/test_runner.zig"), .mode = .simple },
+        });
+        const run_tests = b.addRunArtifact(tests);
+        const test_step = b.step("test", "Run unit tests");
+        test_step.dependOn(&run_tests.step);
+    }
+
+    {
+        // browser
+        const exe = b.addExecutable(.{
+            .name = "legacy_test",
+            .use_llvm = true,
+            .root_module = b.createModule(.{
+                .root_source_file = b.path("src/main_legacy_test.zig"),
+                .target = target,
+                .optimize = optimize,
+                .sanitize_c = enable_csan,
+                .sanitize_thread = enable_tsan,
+                .imports = &.{
+                    .{ .name = "lightpanda", .module = lightpanda_module },
+                },
+            }),
+        });
+        b.installArtifact(exe);
+
+        const run_cmd = b.addRunArtifact(exe);
+        if (b.args) |args| {
+            run_cmd.addArgs(args);
+        }
+        const run_step = b.step("legacy_test", "Run the app");
+        run_step.dependOn(&run_cmd.step);
+    }
 }
 
-fn moduleMimalloc(b: *std.Build) *std.Build.Module {
-    const mod = b.addModule("mimalloc", .{
-        .root_source_file = b.path("src/mimalloc/mimalloc.zig"),
+fn linkV8(
+    b: *Build,
+    mod: *Build.Module,
+    is_asan: bool,
+    is_tsan: bool,
+    prebuilt_v8_path: ?[]const u8,
+) !void {
+    const target = mod.resolved_target.?;
+
+    const dep = b.dependency("v8", .{
+        .target = target,
+        .optimize = mod.optimize.?,
+        .is_asan = is_asan,
+        .is_tsan = is_tsan,
+        .inspector_subtype = false,
+        .v8_enable_sandbox = is_tsan,
+        .cache_root = b.pathFromRoot(".lp-cache"),
+        .prebuilt_v8_path = prebuilt_v8_path,
+    });
+    mod.addImport("v8", dep.module("v8"));
+}
+
+fn linkHtml5Ever(b: *Build, mod: *Build.Module) !void {
+    const is_debug = if (mod.optimize.? == .Debug) true else false;
+
+    const exec_cargo = b.addSystemCommand(&.{
+        "cargo",           "build",
+        "--profile",       if (is_debug) "dev" else "release",
+        "--manifest-path", "src/html5ever/Cargo.toml",
     });
 
-    mod.addObjectFile(b.path("vendor/mimalloc/out/libmimalloc.a"));
-    mod.addIncludePath(b.path("vendor/mimalloc/out/include"));
+    // TODO: We can prefer `--artifact-dir` once it become stable.
+    const out_dir = exec_cargo.addPrefixedOutputDirectoryArg("--target-dir=", "html5ever");
 
-    return mod;
+    const html5ever_step = b.step("html5ever", "Install html5ever dependency (requires cargo)");
+    html5ever_step.dependOn(&exec_cargo.step);
+
+    const obj = out_dir.path(b, if (is_debug) "debug" else "release").path(b, "liblitefetch_html5ever.a");
+    mod.addObjectFile(obj);
+}
+
+fn linkCurl(b: *Build, mod: *Build.Module, is_tsan: bool) !void {
+    const target = mod.resolved_target.?;
+
+    const curl = buildCurl(b, target, mod.optimize.?, is_tsan);
+    mod.linkLibrary(curl);
+
+    const zlib = buildZlib(b, target, mod.optimize.?, is_tsan);
+    curl.root_module.linkLibrary(zlib);
+
+    const brotli = buildBrotli(b, target, mod.optimize.?, is_tsan);
+    for (brotli) |lib| curl.root_module.linkLibrary(lib);
+
+    const nghttp2 = buildNghttp2(b, target, mod.optimize.?, is_tsan);
+    curl.root_module.linkLibrary(nghttp2);
+
+    const boringssl = buildBoringSsl(b, target, mod.optimize.?);
+    for (boringssl) |lib| curl.root_module.linkLibrary(lib);
+
+    switch (target.result.os.tag) {
+        .macos => {
+            // needed for proxying on mac
+            mod.addSystemFrameworkPath(.{ .cwd_relative = "/System/Library/Frameworks" });
+            mod.linkFramework("CoreFoundation", .{});
+            mod.linkFramework("SystemConfiguration", .{});
+        },
+        else => {},
+    }
+}
+
+fn buildZlib(b: *Build, target: Build.ResolvedTarget, optimize: std.builtin.OptimizeMode, is_tsan: bool) *Build.Step.Compile {
+    const dep = b.dependency("zlib", .{});
+
+    const mod = b.createModule(.{
+        .target = target,
+        .optimize = optimize,
+        .link_libc = true,
+        .sanitize_thread = is_tsan,
+    });
+
+    const lib = b.addLibrary(.{ .name = "z", .root_module = mod });
+    lib.installHeadersDirectory(dep.path(""), "", .{});
+    lib.addCSourceFiles(.{
+        .root = dep.path(""),
+        .flags = &.{
+            "-DHAVE_SYS_TYPES_H",
+            "-DHAVE_STDINT_H",
+            "-DHAVE_STDDEF_H",
+            "-DHAVE_UNISTD_H",
+        },
+        .files = &.{
+            "adler32.c", "compress.c", "crc32.c",
+            "deflate.c", "gzclose.c",  "gzlib.c",
+            "gzread.c",  "gzwrite.c",  "infback.c",
+            "inffast.c", "inflate.c",  "inftrees.c",
+            "trees.c",   "uncompr.c",  "zutil.c",
+        },
+    });
+
+    return lib;
+}
+
+fn buildBrotli(b: *Build, target: Build.ResolvedTarget, optimize: std.builtin.OptimizeMode, is_tsan: bool) [3]*Build.Step.Compile {
+    const dep = b.dependency("brotli", .{});
+
+    const mod = b.createModule(.{
+        .target = target,
+        .optimize = optimize,
+        .link_libc = true,
+        .sanitize_thread = is_tsan,
+    });
+    mod.addIncludePath(dep.path("c/include"));
+
+    const brotlicmn = b.addLibrary(.{ .name = "brotlicommon", .root_module = mod });
+    const brotlidec = b.addLibrary(.{ .name = "brotlidec", .root_module = mod });
+    const brotlienc = b.addLibrary(.{ .name = "brotlienc", .root_module = mod });
+
+    brotlicmn.installHeadersDirectory(dep.path("c/include/brotli"), "brotli", .{});
+    brotlicmn.addCSourceFiles(.{
+        .root = dep.path("c/common"),
+        .files = &.{
+            "transform.c",  "shared_dictionary.c", "platform.c",
+            "dictionary.c", "context.c",           "constants.c",
+        },
+    });
+    brotlidec.addCSourceFiles(.{
+        .root = dep.path("c/dec"),
+        .files = &.{
+            "bit_reader.c", "decode.c", "huffman.c",
+            "prefix.c",     "state.c",  "static_init.c",
+        },
+    });
+    brotlienc.addCSourceFiles(.{
+        .root = dep.path("c/enc"),
+        .files = &.{
+            "backward_references.c",        "backward_references_hq.c", "bit_cost.c",
+            "block_splitter.c",             "brotli_bit_stream.c",      "cluster.c",
+            "command.c",                    "compound_dictionary.c",    "compress_fragment.c",
+            "compress_fragment_two_pass.c", "dictionary_hash.c",        "encode.c",
+            "encoder_dict.c",               "entropy_encode.c",         "fast_log.c",
+            "histogram.c",                  "literal_cost.c",           "memory.c",
+            "metablock.c",                  "static_dict.c",            "static_dict_lut.c",
+            "static_init.c",                "utf8_util.c",
+        },
+    });
+
+    return .{ brotlicmn, brotlidec, brotlienc };
+}
+
+fn buildBoringSsl(b: *Build, target: Build.ResolvedTarget, optimize: std.builtin.OptimizeMode) [2]*Build.Step.Compile {
+    const dep = b.dependency("boringssl-zig", .{
+        .target = target,
+        .optimize = optimize,
+        .force_pic = true,
+    });
+
+    const ssl = dep.artifact("ssl");
+    ssl.bundle_ubsan_rt = false;
+
+    const crypto = dep.artifact("crypto");
+    crypto.bundle_ubsan_rt = false;
+
+    return .{ ssl, crypto };
+}
+
+fn buildNghttp2(b: *Build, target: Build.ResolvedTarget, optimize: std.builtin.OptimizeMode, is_tsan: bool) *Build.Step.Compile {
+    const dep = b.dependency("nghttp2", .{});
+
+    const mod = b.createModule(.{
+        .target = target,
+        .optimize = optimize,
+        .link_libc = true,
+        .sanitize_thread = is_tsan,
+    });
+    mod.addIncludePath(dep.path("lib/includes"));
+
+    const config = b.addConfigHeader(.{
+        .include_path = "nghttp2ver.h",
+        .style = .{ .cmake = dep.path("lib/includes/nghttp2/nghttp2ver.h.in") },
+    }, .{
+        .PACKAGE_VERSION = "1.68.90",
+        .PACKAGE_VERSION_NUM = 0x016890,
+    });
+    mod.addConfigHeader(config);
+
+    const lib = b.addLibrary(.{ .name = "nghttp2", .root_module = mod });
+
+    lib.installConfigHeader(config);
+    lib.installHeadersDirectory(dep.path("lib/includes/nghttp2"), "nghttp2", .{});
+    lib.addCSourceFiles(.{
+        .root = dep.path("lib"),
+        .flags = &.{
+            "-DNGHTTP2_STATICLIB",
+            "-DHAVE_TIME_H",
+            "-DHAVE_ARPA_INET_H",
+            "-DHAVE_NETINET_IN_H",
+        },
+        .files = &.{
+            "sfparse.c",                 "nghttp2_alpn.c",   "nghttp2_buf.c",
+            "nghttp2_callbacks.c",       "nghttp2_debug.c",  "nghttp2_extpri.c",
+            "nghttp2_frame.c",           "nghttp2_hd.c",     "nghttp2_hd_huffman.c",
+            "nghttp2_hd_huffman_data.c", "nghttp2_helper.c", "nghttp2_http.c",
+            "nghttp2_map.c",             "nghttp2_mem.c",    "nghttp2_option.c",
+            "nghttp2_outbound_item.c",   "nghttp2_pq.c",     "nghttp2_priority_spec.c",
+            "nghttp2_queue.c",           "nghttp2_rcbuf.c",  "nghttp2_session.c",
+            "nghttp2_stream.c",          "nghttp2_submit.c", "nghttp2_version.c",
+            "nghttp2_ratelim.c",         "nghttp2_time.c",
+        },
+    });
+
+    return lib;
+}
+
+fn buildCurl(
+    b: *Build,
+    target: Build.ResolvedTarget,
+    optimize: std.builtin.OptimizeMode,
+    is_tsan: bool,
+) *Build.Step.Compile {
+    const dep = b.dependency("curl", .{});
+
+    const mod = b.createModule(.{
+        .target = target,
+        .optimize = optimize,
+        .link_libc = true,
+        .sanitize_thread = is_tsan,
+    });
+    mod.addIncludePath(dep.path("lib"));
+    mod.addIncludePath(dep.path("include"));
+
+    const os = target.result.os.tag;
+    const abi = target.result.abi;
+
+    const is_gnu = abi.isGnu();
+    const is_ios = os == .ios;
+    const is_android = abi.isAndroid();
+    const is_linux = os == .linux;
+    const is_darwin = os.isDarwin();
+    const is_windows = os == .windows;
+    const is_netbsd = os == .netbsd;
+    const is_openbsd = os == .openbsd;
+    const is_freebsd = os == .freebsd;
+
+    const byte_size = struct {
+        fn it(b2: *std.Build, target2: Build.ResolvedTarget, name: []const u8, comptime ctype: std.Target.CType) []const u8 {
+            const size = target2.result.cTypeByteSize(ctype);
+            return std.fmt.allocPrint(b2.allocator, "#define SIZEOF_{s} {d}", .{ name, size }) catch @panic("OOM");
+        }
+    }.it;
+
+    const config = .{
+        .HAVE_LIBZ = true,
+        .HAVE_BROTLI = true,
+        .USE_NGHTTP2 = true,
+
+        .USE_OPENSSL = true,
+        .OPENSSL_IS_BORINGSSL = true,
+        .CURL_CA_PATH = null,
+        .CURL_CA_BUNDLE = null,
+        .CURL_CA_FALLBACK = false,
+        .CURL_CA_SEARCH_SAFE = false,
+        .CURL_DEFAULT_SSL_BACKEND = "openssl",
+
+        .CURL_DISABLE_AWS = true,
+        .CURL_DISABLE_DICT = true,
+        .CURL_DISABLE_DOH = true,
+        .CURL_DISABLE_FILE = true,
+        .CURL_DISABLE_FTP = true,
+        .CURL_DISABLE_GOPHER = true,
+        .CURL_DISABLE_KERBEROS_AUTH = true,
+        .CURL_DISABLE_IMAP = true,
+        .CURL_DISABLE_IPFS = true,
+        .CURL_DISABLE_LDAP = true,
+        .CURL_DISABLE_LDAPS = true,
+        .CURL_DISABLE_MQTT = true,
+        .CURL_DISABLE_NTLM = true,
+        .CURL_DISABLE_PROGRESS_METER = true,
+        .CURL_DISABLE_POP3 = true,
+        .CURL_DISABLE_RTSP = true,
+        .CURL_DISABLE_SMB = true,
+        .CURL_DISABLE_SMTP = true,
+        .CURL_DISABLE_TELNET = true,
+        .CURL_DISABLE_TFTP = true,
+
+        .ssize_t = null,
+        ._FILE_OFFSET_BITS = 64,
+
+        .USE_IPV6 = true,
+        .CURL_OS = switch (os) {
+            .linux => if (is_android) "\"android\"" else "\"linux\"",
+            else => std.fmt.allocPrint(b.allocator, "\"{s}\"", .{@tagName(os)}) catch @panic("OOM"),
+        },
+
+        // Adjusts the sizes of variables
+        .SIZEOF_INT_CODE = byte_size(b, target, "INT", .int),
+        .SIZEOF_LONG_CODE = byte_size(b, target, "LONG", .long),
+        .SIZEOF_LONG_LONG_CODE = byte_size(b, target, "LONG_LONG", .longlong),
+
+        .SIZEOF_OFF_T_CODE = byte_size(b, target, "OFF_T", .longlong),
+        .SIZEOF_CURL_OFF_T_CODE = byte_size(b, target, "CURL_OFF_T", .longlong),
+        .SIZEOF_CURL_SOCKET_T_CODE = byte_size(b, target, "CURL_SOCKET_T", .int),
+
+        .SIZEOF_SIZE_T_CODE = byte_size(b, target, "SIZE_T", .longlong),
+        .SIZEOF_TIME_T_CODE = byte_size(b, target, "TIME_T", .longlong),
+
+        // headers availability
+        .HAVE_ARPA_INET_H = !is_windows,
+        .HAVE_DIRENT_H = true,
+        .HAVE_FCNTL_H = true,
+        .HAVE_IFADDRS_H = !is_windows,
+        .HAVE_IO_H = is_windows,
+        .HAVE_LIBGEN_H = true,
+        .HAVE_LINUX_TCP_H = is_linux and is_gnu,
+        .HAVE_LOCALE_H = true,
+        .HAVE_NETDB_H = !is_windows,
+        .HAVE_NETINET_IN6_H = is_android,
+        .HAVE_NETINET_IN_H = !is_windows,
+        .HAVE_NETINET_TCP_H = !is_windows,
+        .HAVE_NETINET_UDP_H = !is_windows,
+        .HAVE_NET_IF_H = !is_windows,
+        .HAVE_POLL_H = !is_windows,
+        .HAVE_PWD_H = !is_windows,
+        .HAVE_STDATOMIC_H = true,
+        .HAVE_STDBOOL_H = true,
+        .HAVE_STDDEF_H = true,
+        .HAVE_STDINT_H = true,
+        .HAVE_STRINGS_H = true,
+        .HAVE_STROPTS_H = false,
+        .HAVE_SYS_EVENTFD_H = is_linux or is_freebsd or is_netbsd,
+        .HAVE_SYS_FILIO_H = !is_linux and !is_windows,
+        .HAVE_SYS_IOCTL_H = !is_windows,
+        .HAVE_SYS_PARAM_H = true,
+        .HAVE_SYS_POLL_H = !is_windows,
+        .HAVE_SYS_RESOURCE_H = !is_windows,
+        .HAVE_SYS_SELECT_H = !is_windows,
+        .HAVE_SYS_SOCKIO_H = !is_linux and !is_windows,
+        .HAVE_SYS_TYPES_H = true,
+        .HAVE_SYS_UN_H = !is_windows,
+        .HAVE_SYS_UTIME_H = is_windows,
+        .HAVE_TERMIOS_H = !is_windows,
+        .HAVE_TERMIO_H = is_linux,
+        .HAVE_UNISTD_H = true,
+        .HAVE_UTIME_H = true,
+        .STDC_HEADERS = true,
+
+        // general environment
+        .CURL_KRB5_VERSION = null,
+        .HAVE_ALARM = !is_windows,
+        .HAVE_ARC4RANDOM = is_android,
+        .HAVE_ATOMIC = true,
+        .HAVE_BOOL_T = true,
+        .HAVE_BUILTIN_AVAILABLE = true,
+        .HAVE_CLOCK_GETTIME_MONOTONIC = !is_darwin and !is_windows,
+        .HAVE_CLOCK_GETTIME_MONOTONIC_RAW = is_linux,
+        .HAVE_FILE_OFFSET_BITS = true,
+        .HAVE_GETEUID = !is_windows,
+        .HAVE_GETPPID = !is_windows,
+        .HAVE_GETTIMEOFDAY = true,
+        .HAVE_GLIBC_STRERROR_R = is_gnu,
+        .HAVE_GMTIME_R = !is_windows,
+        .HAVE_LOCALTIME_R = !is_windows,
+        .HAVE_LONGLONG = !is_windows,
+        .HAVE_MACH_ABSOLUTE_TIME = is_darwin,
+        .HAVE_MEMRCHR = !is_darwin and !is_windows,
+        .HAVE_POSIX_STRERROR_R = !is_gnu and !is_windows,
+        .HAVE_PTHREAD_H = !is_windows,
+        .HAVE_SETLOCALE = true,
+        .HAVE_SETRLIMIT = !is_windows,
+        .HAVE_SIGACTION = !is_windows,
+        .HAVE_SIGINTERRUPT = !is_windows,
+        .HAVE_SIGNAL = true,
+        .HAVE_SIGSETJMP = !is_windows,
+        .HAVE_SIZEOF_SA_FAMILY_T = false,
+        .HAVE_SIZEOF_SUSECONDS_T = false,
+        .HAVE_SNPRINTF = true,
+        .HAVE_STRCASECMP = !is_windows,
+        .HAVE_STRCMPI = false,
+        .HAVE_STRDUP = true,
+        .HAVE_STRERROR_R = !is_windows,
+        .HAVE_STRICMP = false,
+        .HAVE_STRUCT_TIMEVAL = true,
+        .HAVE_TIME_T_UNSIGNED = false,
+        .HAVE_UTIME = true,
+        .HAVE_UTIMES = !is_windows,
+        .HAVE_WRITABLE_ARGV = !is_windows,
+        .HAVE__SETMODE = is_windows,
+        .USE_THREADS_POSIX = !is_windows,
+
+        // filesystem, network
+        .HAVE_ACCEPT4 = is_linux or is_freebsd or is_netbsd or is_openbsd,
+        .HAVE_BASENAME = true,
+        .HAVE_CLOSESOCKET = is_windows,
+        .HAVE_DECL_FSEEKO = !is_windows,
+        .HAVE_EVENTFD = is_linux or is_freebsd or is_netbsd,
+        .HAVE_FCNTL = !is_windows,
+        .HAVE_FCNTL_O_NONBLOCK = !is_windows,
+        .HAVE_FNMATCH = !is_windows,
+        .HAVE_FREEADDRINFO = true,
+        .HAVE_FSEEKO = !is_windows,
+        .HAVE_FSETXATTR = is_darwin or is_linux or is_netbsd,
+        .HAVE_FSETXATTR_5 = is_linux or is_netbsd,
+        .HAVE_FSETXATTR_6 = is_darwin,
+        .HAVE_FTRUNCATE = true,
+        .HAVE_GETADDRINFO = true,
+        .HAVE_GETADDRINFO_THREADSAFE = is_linux or is_freebsd or is_netbsd,
+        .HAVE_GETHOSTBYNAME_R = is_linux or is_freebsd,
+        .HAVE_GETHOSTBYNAME_R_3 = false,
+        .HAVE_GETHOSTBYNAME_R_3_REENTRANT = false,
+        .HAVE_GETHOSTBYNAME_R_5 = false,
+        .HAVE_GETHOSTBYNAME_R_5_REENTRANT = false,
+        .HAVE_GETHOSTBYNAME_R_6 = is_linux,
+        .HAVE_GETHOSTBYNAME_R_6_REENTRANT = is_linux,
+        .HAVE_GETHOSTNAME = true,
+        .HAVE_GETIFADDRS = if (is_windows) false else !is_android or target.result.os.versionRange().linux.android >= 24,
+        .HAVE_GETPASS_R = is_netbsd,
+        .HAVE_GETPEERNAME = true,
+        .HAVE_GETPWUID = !is_windows,
+        .HAVE_GETPWUID_R = !is_windows,
+        .HAVE_GETRLIMIT = !is_windows,
+        .HAVE_GETSOCKNAME = true,
+        .HAVE_IF_NAMETOINDEX = !is_windows,
+        .HAVE_INET_NTOP = !is_windows,
+        .HAVE_INET_PTON = !is_windows,
+        .HAVE_IOCTLSOCKET = is_windows,
+        .HAVE_IOCTLSOCKET_CAMEL = false,
+        .HAVE_IOCTLSOCKET_CAMEL_FIONBIO = false,
+        .HAVE_IOCTLSOCKET_FIONBIO = is_windows,
+        .HAVE_IOCTL_FIONBIO = !is_windows,
+        .HAVE_IOCTL_SIOCGIFADDR = !is_windows,
+        .HAVE_MSG_NOSIGNAL = !is_windows,
+        .HAVE_OPENDIR = true,
+        .HAVE_PIPE = !is_windows,
+        .HAVE_PIPE2 = is_linux or is_freebsd or is_netbsd or is_openbsd,
+        .HAVE_POLL = !is_windows,
+        .HAVE_REALPATH = !is_windows,
+        .HAVE_RECV = true,
+        .HAVE_SA_FAMILY_T = !is_windows,
+        .HAVE_SCHED_YIELD = !is_windows,
+        .HAVE_SELECT = true,
+        .HAVE_SEND = true,
+        .HAVE_SENDMMSG = !is_darwin and !is_windows,
+        .HAVE_SENDMSG = !is_windows,
+        .HAVE_SETMODE = !is_linux,
+        .HAVE_SETSOCKOPT_SO_NONBLOCK = false,
+        .HAVE_SOCKADDR_IN6_SIN6_ADDR = !is_windows,
+        .HAVE_SOCKADDR_IN6_SIN6_SCOPE_ID = true,
+        .HAVE_SOCKET = true,
+        .HAVE_SOCKETPAIR = !is_windows,
+        .HAVE_STRUCT_SOCKADDR_STORAGE = true,
+        .HAVE_SUSECONDS_T = is_android or is_ios,
+        .USE_UNIX_SOCKETS = !is_windows,
+    };
+
+    const curl_config = b.addConfigHeader(.{
+        .include_path = "curl_config.h",
+        .style = .{ .cmake = dep.path("lib/curl_config-cmake.h.in") },
+    }, .{
+        .CURL_EXTERN_SYMBOL = "__attribute__ ((__visibility__ (\"default\"))",
+    });
+    curl_config.addValues(config);
+
+    const lib = b.addLibrary(.{ .name = "curl", .root_module = mod });
+    lib.addConfigHeader(curl_config);
+    lib.installHeadersDirectory(dep.path("include/curl"), "curl", .{});
+    lib.addCSourceFiles(.{
+        .root = dep.path("lib"),
+        .flags = &.{
+            "-D_GNU_SOURCE",
+            "-DHAVE_CONFIG_H",
+            "-DCURL_STATICLIB",
+            "-DBUILDING_LIBCURL",
+        },
+        .files = &.{
+            // You can include all files from lib, libcurl uses #ifdef-guards to exclude code for disabled functions
+            "altsvc.c",              "amigaos.c",              "asyn-ares.c",
+            "asyn-base.c",           "asyn-thrdd.c",           "bufq.c",
+            "bufref.c",              "cf-h1-proxy.c",          "cf-h2-proxy.c",
+            "cf-haproxy.c",          "cf-https-connect.c",     "cf-ip-happy.c",
+            "cf-socket.c",           "cfilters.c",             "conncache.c",
+            "connect.c",             "content_encoding.c",     "cookie.c",
+            "cshutdn.c",             "curl_addrinfo.c",        "curl_endian.c",
+            "curl_fnmatch.c",        "curl_fopen.c",           "curl_get_line.c",
+            "curl_gethostname.c",    "curl_gssapi.c",          "curl_memrchr.c",
+            "curl_ntlm_core.c",      "curl_range.c",           "curl_rtmp.c",
+            "curl_sasl.c",           "curl_sha512_256.c",      "curl_share.c",
+            "curl_sspi.c",           "curl_threads.c",         "curl_trc.c",
+            "curlx/base64.c",        "curlx/dynbuf.c",         "curlx/fopen.c",
+            "curlx/inet_ntop.c",     "curlx/inet_pton.c",      "curlx/multibyte.c",
+            "curlx/nonblock.c",      "curlx/strcopy.c",        "curlx/strerr.c",
+            "curlx/strparse.c",      "curlx/timediff.c",       "curlx/timeval.c",
+            "curlx/version_win32.c", "curlx/wait.c",           "curlx/warnless.c",
+            "curlx/winapi.c",        "cw-out.c",               "cw-pause.c",
+            "dict.c",                "dllmain.c",              "doh.c",
+            "dynhds.c",              "easy.c",                 "easygetopt.c",
+            "easyoptions.c",         "escape.c",               "fake_addrinfo.c",
+            "file.c",                "fileinfo.c",             "formdata.c",
+            "ftp.c",                 "ftplistparser.c",        "getenv.c",
+            "getinfo.c",             "gopher.c",               "hash.c",
+            "headers.c",             "hmac.c",                 "hostip.c",
+            "hostip4.c",             "hostip6.c",              "hsts.c",
+            "http.c",                "http1.c",                "http2.c",
+            "http_aws_sigv4.c",      "http_chunks.c",          "http_digest.c",
+            "http_negotiate.c",      "http_ntlm.c",            "http_proxy.c",
+            "httpsrr.c",             "idn.c",                  "if2ip.c",
+            "imap.c",                "ldap.c",                 "llist.c",
+            "macos.c",               "md4.c",                  "md5.c",
+            "memdebug.c",            "mime.c",                 "mprintf.c",
+            "mqtt.c",                "multi.c",                "multi_ev.c",
+            "multi_ntfy.c",          "netrc.c",                "noproxy.c",
+            "openldap.c",            "parsedate.c",            "pingpong.c",
+            "pop3.c",                "progress.c",             "psl.c",
+            "rand.c",                "ratelimit.c",            "request.c",
+            "rtsp.c",                "select.c",               "sendf.c",
+            "setopt.c",              "sha256.c",               "slist.c",
+            "smb.c",                 "smtp.c",                 "socketpair.c",
+            "socks.c",               "socks_gssapi.c",         "socks_sspi.c",
+            "splay.c",               "strcase.c",              "strdup.c",
+            "strequal.c",            "strerror.c",             "system_win32.c",
+            "telnet.c",              "tftp.c",                 "transfer.c",
+            "uint-bset.c",           "uint-hash.c",            "uint-spbset.c",
+            "uint-table.c",          "url.c",                  "urlapi.c",
+            "vauth/cleartext.c",     "vauth/cram.c",           "vauth/digest.c",
+            "vauth/digest_sspi.c",   "vauth/gsasl.c",          "vauth/krb5_gssapi.c",
+            "vauth/krb5_sspi.c",     "vauth/ntlm.c",           "vauth/ntlm_sspi.c",
+            "vauth/oauth2.c",        "vauth/spnego_gssapi.c",  "vauth/spnego_sspi.c",
+            "vauth/vauth.c",         "version.c",              "vquic/curl_ngtcp2.c",
+            "vquic/curl_osslq.c",    "vquic/curl_quiche.c",    "vquic/vquic-tls.c",
+            "vquic/vquic.c",         "vssh/libssh.c",          "vssh/libssh2.c",
+            "vssh/vssh.c",           "vtls/apple.c",           "vtls/cipher_suite.c",
+            "vtls/gtls.c",           "vtls/hostcheck.c",       "vtls/keylog.c",
+            "vtls/mbedtls.c",        "vtls/openssl.c",         "vtls/rustls.c",
+            "vtls/schannel.c",       "vtls/schannel_verify.c", "vtls/vtls.c",
+            "vtls/vtls_scache.c",    "vtls/vtls_spack.c",      "vtls/wolfssl.c",
+            "vtls/x509asn1.c",       "ws.c",
+        },
+    });
+
+    return lib;
+}
+
+/// Returns `MAJOR.MINOR.PATCH-dev` when `git describe` fails.
+fn resolveVersion(b: *std.Build) std.SemanticVersion {
+    const version_string = b.option([]const u8, "version_string", "Override the version of this build");
+    if (version_string) |semver_string| {
+        return std.SemanticVersion.parse(semver_string) catch |err| {
+            std.debug.panic("Expected -Dversion-string={s} to be a semantic version: {}", .{ semver_string, err });
+        };
+    }
+
+    // If it's a stable release (no pre or build metadata in build.zig.zon), use it as is
+    if (lightpanda_version.pre == null and lightpanda_version.build == null) return lightpanda_version;
+
+    // For dev/nightly versions, calculate the commit count and hash
+    const git_hash_raw = runGit(b, &.{ "rev-parse", "--short", "HEAD" }) catch return lightpanda_version;
+    const commit_hash = std.mem.trim(u8, git_hash_raw, " \n\r");
+
+    const git_count_raw = runGit(b, &.{ "rev-list", "--count", "HEAD" }) catch return lightpanda_version;
+    const commit_count = std.mem.trim(u8, git_count_raw, " \n\r");
+
+    return .{
+        .major = lightpanda_version.major,
+        .minor = lightpanda_version.minor,
+        .patch = lightpanda_version.patch,
+        .pre = b.fmt("{s}.{s}", .{ lightpanda_version.pre.?, commit_count }),
+        .build = commit_hash,
+    };
+}
+
+/// Helper function to run git commands and return stdout
+fn runGit(b: *std.Build, args: []const []const u8) ![]const u8 {
+    var code: u8 = undefined;
+    const dir = b.pathFromRoot(".");
+    var command: std.ArrayList([]const u8) = .empty;
+    defer command.deinit(b.allocator);
+    try command.appendSlice(b.allocator, &.{ "git", "-C", dir });
+    try command.appendSlice(b.allocator, args);
+    return b.runAllowFail(command.items, &code, .Ignore);
 }

build.zig.zon

@@ -0,0 +1,35 @@
+.{
+    .name = .browser,
+    .version = "1.0.0-dev",
+    .fingerprint = 0xda130f3af836cea0, // Changing this has security and trust implications.
+    .minimum_zig_version = "0.15.2",
+    .dependencies = .{
+        .v8 = .{
+            .url = "https://github.com/lightpanda-io/zig-v8-fork/archive/refs/tags/v0.3.4.tar.gz",
+            .hash = "v8-0.0.0-xddH6_F3BAAiFvKY6R1H-gkuQlk19BkDQ0--uZuTrSup",
+        },
+        // .v8 = .{ .path = "../zig-v8-fork" },
+        .brotli = .{
+            // v1.2.0
+            .url = "https://github.com/google/brotli/archive/028fb5a23661f123017c060daa546b55cf4bde29.tar.gz",
+            .hash = "N-V-__8AAJudKgCQCuIiH6MJjAiIJHfg_tT_Ew-0vZwVkCo_",
+        },
+        .zlib = .{
+            .url = "https://github.com/madler/zlib/releases/download/v1.3.2/zlib-1.3.2.tar.gz",
+            .hash = "N-V-__8AAJ2cNgAgfBtAw33Bxfu1IWISDeKKSr3DAqoAysIJ",
+        },
+        .nghttp2 = .{
+            .url = "https://github.com/nghttp2/nghttp2/releases/download/v1.68.0/nghttp2-1.68.0.tar.gz",
+            .hash = "N-V-__8AAL15vQCI63ZL6Zaz5hJg6JTEgYXGbLnMFSnf7FT3",
+        },
+        .@"boringssl-zig" = .{
+            .url = "git+https://github.com/Syndica/boringssl-zig.git#c53df00d06b02b755ad88bbf4d1202ed9687b096",
+            .hash = "boringssl-0.1.0-VtJeWehMAAA4RNnwRnzEvKcS9rjsR1QVRw1uJrwXxmVK",
+        },
+        .curl = .{
+            .url = "https://github.com/curl/curl/releases/download/curl-8_18_0/curl-8.18.0.tar.gz",
+            .hash = "N-V-__8AALp9QAGn6CCHZ6fK_FfMyGtG824LSHYHHasM3w-y",
+        },
+    },
+    .paths = .{""},
+}

flake.lock

@@ -0,0 +1,219 @@
+{
+  "nodes": {
+    "fenix": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "rust-analyzer-src": "rust-analyzer-src"
+      },
+      "locked": {
+        "lastModified": 1770708269,
+        "narHash": "sha256-OnZW86app7hHJJoB5lC9GNXY5QBBIESJB+sIdwEyld0=",
+        "owner": "nix-community",
+        "repo": "fenix",
+        "rev": "6b5325a017a9a9fe7e6252ccac3680cc7181cd63",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "fenix",
+        "type": "github"
+      }
+    },
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1696426674,
+        "narHash": "sha256-kvjfFW7WAETZlt09AgDn1MrtKzP7t90Vf7vypd3OL1U=",
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "0f9255e01c2351cc7d116c072cb317785dd33b33",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "flake-utils_2": {
+      "inputs": {
+        "systems": "systems_2"
+      },
+      "locked": {
+        "lastModified": 1705309234,
+        "narHash": "sha256-uNRRNRKmJyCRC/8y1RqBkqWBLM034y4qN7EprSdmgyA=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "1ef2e671c3b0c19053962c07dbda38332dcebf26",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "gitignore": {
+      "inputs": {
+        "nixpkgs": [
+          "zlsPkg",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1709087332,
+        "narHash": "sha256-HG2cCnktfHsKV0s4XW83gU3F57gaTljL9KNSuG6bnQs=",
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "rev": "637db329424fd7e46cf4185293b9cc8c88c95394",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1768649915,
+        "narHash": "sha256-jc21hKogFnxU7KXSVTRmxC7u5D4RHwm9BAvDf5/Z1Uo=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "3e3f3c7f9977dc123c23ee21e8085ed63daf8c37",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "release-25.05",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "fenix": "fenix",
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs",
+        "zigPkgs": "zigPkgs",
+        "zlsPkg": "zlsPkg"
+      }
+    },
+    "rust-analyzer-src": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1770668050,
+        "narHash": "sha256-Q05yaIZtQrBKHpyWaPmyJmDRj0lojnVf8nUFE0vydcY=",
+        "owner": "rust-lang",
+        "repo": "rust-analyzer",
+        "rev": "9efc1f709f3c8134c3acac5d3592a8e4c184a0c6",
+        "type": "github"
+      },
+      "original": {
+        "owner": "rust-lang",
+        "ref": "nightly",
+        "repo": "rust-analyzer",
+        "type": "github"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    },
+    "systems_2": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    },
+    "zigPkgs": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "flake-utils": "flake-utils_2",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1770598090,
+        "narHash": "sha256-k+82IDgTd9o5sxHIqGlvfwseKln3Ejx1edGtDltuPXo=",
+        "owner": "mitchellh",
+        "repo": "zig-overlay",
+        "rev": "142495696982c88edddc8e17e4da90d8164acadf",
+        "type": "github"
+      },
+      "original": {
+        "owner": "mitchellh",
+        "repo": "zig-overlay",
+        "type": "github"
+      }
+    },
+    "zlsPkg": {
+      "inputs": {
+        "gitignore": "gitignore",
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "zig-overlay": [
+          "zigPkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1756048867,
+        "narHash": "sha256-GFzSHUljcxy7sM1PaabbkQUdUnLwpherekPWJFxXtnk=",
+        "owner": "zigtools",
+        "repo": "zls",
+        "rev": "ce6c8f02c78e622421cfc2405c67c5222819ec03",
+        "type": "github"
+      },
+      "original": {
+        "owner": "zigtools",
+        "ref": "0.15.0",
+        "repo": "zls",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,85 @@
+{
+  description = "headless browser designed for AI and automation";
+
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/release-25.05";
+
+    zigPkgs.url = "github:mitchellh/zig-overlay";
+    zigPkgs.inputs.nixpkgs.follows = "nixpkgs";
+
+    zlsPkg.url = "github:zigtools/zls/0.15.0";
+    zlsPkg.inputs.zig-overlay.follows = "zigPkgs";
+    zlsPkg.inputs.nixpkgs.follows = "nixpkgs";
+
+    fenix = {
+      url = "github:nix-community/fenix";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs =
+    {
+      nixpkgs,
+      zigPkgs,
+      zlsPkg,
+      fenix,
+      flake-utils,
+      ...
+    }:
+    flake-utils.lib.eachDefaultSystem (
+      system:
+      let
+        overlays = [
+          (final: prev: {
+            zigpkgs = zigPkgs.packages.${prev.system};
+            zls = zlsPkg.packages.${prev.system}.default;
+          })
+        ];
+
+        pkgs = import nixpkgs {
+          inherit system overlays;
+        };
+
+        rustToolchain = fenix.packages.${system}.stable.toolchain;
+
+        # We need crtbeginS.o for building.
+        crtFiles = pkgs.runCommand "crt-files" { } ''
+          mkdir -p $out/lib
+          cp -r ${pkgs.gcc.cc}/lib/gcc $out/lib/gcc
+        '';
+
+        # This build pipeline is very unhappy without an FHS-compliant env.
+        fhs = pkgs.buildFHSEnv {
+          name = "fhs-shell";
+          multiArch = true;
+          targetPkgs =
+            pkgs: with pkgs; [
+              # Build Tools
+              zigpkgs."0.15.2"
+              zls
+              rustToolchain
+              python3
+              pkg-config
+              cmake
+              gperf
+
+              # GCC
+              gcc
+              gcc.cc.lib
+              crtFiles
+
+              # Libaries
+              expat.dev
+              glib.dev
+              glibc.dev
+              zlib
+            ];
+        };
+      in
+      {
+        devShells.default = fhs.env;
+      }
+    );
+}

src/App.zig

@@ -0,0 +1,115 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+
+const Allocator = std.mem.Allocator;
+
+const log = @import("log.zig");
+const Config = @import("Config.zig");
+const Snapshot = @import("browser/js/Snapshot.zig");
+const Platform = @import("browser/js/Platform.zig");
+const Telemetry = @import("telemetry/telemetry.zig").Telemetry;
+
+const Network = @import("network/Runtime.zig");
+pub const ArenaPool = @import("ArenaPool.zig");
+
+const App = @This();
+
+network: Network,
+config: *const Config,
+platform: Platform,
+snapshot: Snapshot,
+telemetry: Telemetry,
+allocator: Allocator,
+arena_pool: ArenaPool,
+app_dir_path: ?[]const u8,
+
+pub fn init(allocator: Allocator, config: *const Config) !*App {
+    const app = try allocator.create(App);
+    errdefer allocator.destroy(app);
+
+    app.* = .{
+        .config = config,
+        .allocator = allocator,
+        .network = undefined,
+        .platform = undefined,
+        .snapshot = undefined,
+        .app_dir_path = undefined,
+        .telemetry = undefined,
+        .arena_pool = undefined,
+    };
+
+    app.network = try Network.init(allocator, config);
+    errdefer app.network.deinit();
+
+    app.platform = try Platform.init();
+    errdefer app.platform.deinit();
+
+    app.snapshot = try Snapshot.load();
+    errdefer app.snapshot.deinit();
+
+    app.app_dir_path = getAndMakeAppDir(allocator);
+
+    app.telemetry = try Telemetry.init(app, config.mode);
+    errdefer app.telemetry.deinit(allocator);
+
+    app.arena_pool = ArenaPool.init(allocator, 512, 1024 * 16);
+    errdefer app.arena_pool.deinit();
+
+    return app;
+}
+
+pub fn shutdown(self: *const App) bool {
+    return self.network.shutdown.load(.acquire);
+}
+
+pub fn deinit(self: *App) void {
+    const allocator = self.allocator;
+    if (self.app_dir_path) |app_dir_path| {
+        allocator.free(app_dir_path);
+        self.app_dir_path = null;
+    }
+    self.telemetry.deinit(allocator);
+    self.network.deinit();
+    self.snapshot.deinit();
+    self.platform.deinit();
+    self.arena_pool.deinit();
+
+    allocator.destroy(self);
+}
+
+fn getAndMakeAppDir(allocator: Allocator) ?[]const u8 {
+    if (@import("builtin").is_test) {
+        return allocator.dupe(u8, "/tmp") catch unreachable;
+    }
+    const app_dir_path = std.fs.getAppDataDir(allocator, "lightpanda") catch |err| {
+        log.warn(.app, "get data dir", .{ .err = err });
+        return null;
+    };
+
+    std.fs.cwd().makePath(app_dir_path) catch |err| switch (err) {
+        error.PathAlreadyExists => return app_dir_path,
+        else => {
+            allocator.free(app_dir_path);
+            log.warn(.app, "create data dir", .{ .err = err, .path = app_dir_path });
+            return null;
+        },
+    };
+    return app_dir_path;
+}

src/ArenaPool.zig

@@ -0,0 +1,272 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const builtin = @import("builtin");
+
+const Allocator = std.mem.Allocator;
+const ArenaAllocator = std.heap.ArenaAllocator;
+
+const ArenaPool = @This();
+
+const IS_DEBUG = builtin.mode == .Debug;
+
+allocator: Allocator,
+retain_bytes: usize,
+free_list_len: u16 = 0,
+free_list: ?*Entry = null,
+free_list_max: u16,
+entry_pool: std.heap.MemoryPool(Entry),
+mutex: std.Thread.Mutex = .{},
+// Debug mode: track acquire/release counts per debug name to detect leaks and double-frees
+_leak_track: if (IS_DEBUG) std.StringHashMapUnmanaged(isize) else void = if (IS_DEBUG) .empty else {},
+
+const Entry = struct {
+    next: ?*Entry,
+    arena: ArenaAllocator,
+    debug: if (IS_DEBUG) []const u8 else void = if (IS_DEBUG) "" else {},
+};
+
+pub const DebugInfo = struct {
+    debug: []const u8 = "",
+};
+
+pub fn init(allocator: Allocator, free_list_max: u16, retain_bytes: usize) ArenaPool {
+    return .{
+        .allocator = allocator,
+        .free_list_max = free_list_max,
+        .retain_bytes = retain_bytes,
+        .entry_pool = .init(allocator),
+        ._leak_track = if (IS_DEBUG) .empty else {},
+    };
+}
+
+pub fn deinit(self: *ArenaPool) void {
+    if (IS_DEBUG) {
+        var has_leaks = false;
+        var it = self._leak_track.iterator();
+        while (it.next()) |kv| {
+            if (kv.value_ptr.* != 0) {
+                std.debug.print("ArenaPool leak detected: '{s}' count={d}\n", .{ kv.key_ptr.*, kv.value_ptr.* });
+                has_leaks = true;
+            }
+        }
+        if (has_leaks) {
+            @panic("ArenaPool: leaked arenas detected");
+        }
+        self._leak_track.deinit(self.allocator);
+    }
+
+    var entry = self.free_list;
+    while (entry) |e| {
+        entry = e.next;
+        e.arena.deinit();
+    }
+    self.entry_pool.deinit();
+}
+
+pub fn acquire(self: *ArenaPool, dbg: DebugInfo) !Allocator {
+    self.mutex.lock();
+    defer self.mutex.unlock();
+
+    if (self.free_list) |entry| {
+        self.free_list = entry.next;
+        self.free_list_len -= 1;
+        if (IS_DEBUG) {
+            entry.debug = dbg.debug;
+            const gop = try self._leak_track.getOrPut(self.allocator, dbg.debug);
+            if (!gop.found_existing) {
+                gop.value_ptr.* = 0;
+            }
+            gop.value_ptr.* += 1;
+        }
+        return entry.arena.allocator();
+    }
+
+    const entry = try self.entry_pool.create();
+    entry.* = .{
+        .next = null,
+        .arena = ArenaAllocator.init(self.allocator),
+        .debug = if (IS_DEBUG) dbg.debug else {},
+    };
+
+    if (IS_DEBUG) {
+        const gop = try self._leak_track.getOrPut(self.allocator, dbg.debug);
+        if (!gop.found_existing) {
+            gop.value_ptr.* = 0;
+        }
+        gop.value_ptr.* += 1;
+    }
+    return entry.arena.allocator();
+}
+
+pub fn release(self: *ArenaPool, allocator: Allocator) void {
+    const arena: *std.heap.ArenaAllocator = @ptrCast(@alignCast(allocator.ptr));
+    const entry: *Entry = @fieldParentPtr("arena", arena);
+
+    // Reset the arena before acquiring the lock to minimize lock hold time
+    _ = arena.reset(.{ .retain_with_limit = self.retain_bytes });
+
+    self.mutex.lock();
+    defer self.mutex.unlock();
+
+    if (IS_DEBUG) {
+        if (self._leak_track.getPtr(entry.debug)) |count| {
+            count.* -= 1;
+            if (count.* < 0) {
+                std.debug.print("ArenaPool double-free detected: '{s}'\n", .{entry.debug});
+                @panic("ArenaPool: double-free detected");
+            }
+        } else {
+            std.debug.print("ArenaPool release of untracked arena: '{s}'\n", .{entry.debug});
+            @panic("ArenaPool: release of untracked arena");
+        }
+    }
+
+    const free_list_len = self.free_list_len;
+    if (free_list_len == self.free_list_max) {
+        arena.deinit();
+        self.entry_pool.destroy(entry);
+        return;
+    }
+
+    entry.next = self.free_list;
+    self.free_list_len = free_list_len + 1;
+    self.free_list = entry;
+}
+
+pub fn reset(_: *const ArenaPool, allocator: Allocator, retain: usize) void {
+    const arena: *std.heap.ArenaAllocator = @ptrCast(@alignCast(allocator.ptr));
+    _ = arena.reset(.{ .retain_with_limit = retain });
+}
+
+pub fn resetRetain(_: *const ArenaPool, allocator: Allocator) void {
+    const arena: *std.heap.ArenaAllocator = @ptrCast(@alignCast(allocator.ptr));
+    _ = arena.reset(.retain_capacity);
+}
+
+const testing = std.testing;
+
+test "arena pool - basic acquire and use" {
+    var pool = ArenaPool.init(testing.allocator, 512, 1024 * 16);
+    defer pool.deinit();
+
+    const alloc = try pool.acquire(.{ .debug = "test" });
+    const buf = try alloc.alloc(u8, 64);
+    @memset(buf, 0xAB);
+    try testing.expectEqual(@as(u8, 0xAB), buf[0]);
+
+    pool.release(alloc);
+}
+
+test "arena pool - reuse entry after release" {
+    var pool = ArenaPool.init(testing.allocator, 512, 1024 * 16);
+    defer pool.deinit();
+
+    const alloc1 = try pool.acquire(.{ .debug = "test" });
+    try testing.expectEqual(@as(u16, 0), pool.free_list_len);
+
+    pool.release(alloc1);
+    try testing.expectEqual(@as(u16, 1), pool.free_list_len);
+
+    // The same entry should be returned from the free list.
+    const alloc2 = try pool.acquire(.{ .debug = "test" });
+    try testing.expectEqual(@as(u16, 0), pool.free_list_len);
+    try testing.expectEqual(alloc1.ptr, alloc2.ptr);
+
+    pool.release(alloc2);
+}
+
+test "arena pool - multiple concurrent arenas" {
+    var pool = ArenaPool.init(testing.allocator, 512, 1024 * 16);
+    defer pool.deinit();
+
+    const a1 = try pool.acquire(.{ .debug = "test1" });
+    const a2 = try pool.acquire(.{ .debug = "test2" });
+    const a3 = try pool.acquire(.{ .debug = "test3" });
+
+    // All three must be distinct arenas.
+    try testing.expect(a1.ptr != a2.ptr);
+    try testing.expect(a2.ptr != a3.ptr);
+    try testing.expect(a1.ptr != a3.ptr);
+
+    _ = try a1.alloc(u8, 16);
+    _ = try a2.alloc(u8, 32);
+    _ = try a3.alloc(u8, 48);
+
+    pool.release(a1);
+    pool.release(a2);
+    pool.release(a3);
+
+    try testing.expectEqual(@as(u16, 3), pool.free_list_len);
+}
+
+test "arena pool - free list respects max limit" {
+    // Cap the free list at 1 so the second release discards its arena.
+    var pool = ArenaPool.init(testing.allocator, 1, 1024 * 16);
+    defer pool.deinit();
+
+    const a1 = try pool.acquire(.{ .debug = "test1" });
+    const a2 = try pool.acquire(.{ .debug = "test2" });
+
+    pool.release(a1);
+    try testing.expectEqual(@as(u16, 1), pool.free_list_len);
+
+    // The free list is full; a2's arena should be destroyed, not queued.
+    pool.release(a2);
+    try testing.expectEqual(@as(u16, 1), pool.free_list_len);
+}
+
+test "arena pool - reset clears memory without releasing" {
+    var pool = ArenaPool.init(testing.allocator, 512, 1024 * 16);
+    defer pool.deinit();
+
+    const alloc = try pool.acquire(.{ .debug = "test" });
+
+    const buf = try alloc.alloc(u8, 128);
+    @memset(buf, 0xFF);
+
+    // reset() frees arena memory but keeps the allocator in-flight.
+    pool.reset(alloc, 0);
+
+    // The free list must stay empty; the allocator was not released.
+    try testing.expectEqual(@as(u16, 0), pool.free_list_len);
+
+    // Allocating again through the same arena must still work.
+    const buf2 = try alloc.alloc(u8, 64);
+    @memset(buf2, 0x00);
+    try testing.expectEqual(@as(u8, 0x00), buf2[0]);
+
+    pool.release(alloc);
+}
+
+test "arena pool - deinit with entries in free list" {
+    // Verifies that deinit properly cleans up free-listed arenas (no leaks
+    // detected by the test allocator).
+    var pool = ArenaPool.init(testing.allocator, 512, 1024 * 16);
+
+    const a1 = try pool.acquire(.{ .debug = "test1" });
+    const a2 = try pool.acquire(.{ .debug = "test2" });
+    _ = try a1.alloc(u8, 256);
+    _ = try a2.alloc(u8, 512);
+    pool.release(a1);
+    pool.release(a2);
+    try testing.expectEqual(@as(u16, 2), pool.free_list_len);
+
+    pool.deinit();
+}

src/Config.zig

@@ -0,0 +1,984 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const builtin = @import("builtin");
+const Allocator = std.mem.Allocator;
+
+const log = @import("log.zig");
+const dump = @import("browser/dump.zig");
+
+const WebBotAuthConfig = @import("network/WebBotAuth.zig").Config;
+
+pub const RunMode = enum {
+    help,
+    fetch,
+    serve,
+    version,
+    mcp,
+};
+
+pub const MAX_LISTENERS = 16;
+pub const CDP_MAX_HTTP_REQUEST_SIZE = 4096;
+
+// max message size
+// +14 for max websocket payload overhead
+// +140 for the max control packet that might be interleaved in a message
+pub const CDP_MAX_MESSAGE_SIZE = 512 * 1024 + 14 + 140;
+
+mode: Mode,
+exec_name: []const u8,
+http_headers: HttpHeaders,
+
+const Config = @This();
+
+pub fn init(allocator: Allocator, exec_name: []const u8, mode: Mode) !Config {
+    var config = Config{
+        .mode = mode,
+        .exec_name = exec_name,
+        .http_headers = undefined,
+    };
+    config.http_headers = try HttpHeaders.init(allocator, &config);
+    return config;
+}
+
+pub fn deinit(self: *const Config, allocator: Allocator) void {
+    self.http_headers.deinit(allocator);
+}
+
+pub fn tlsVerifyHost(self: *const Config) bool {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| opts.common.tls_verify_host,
+        else => unreachable,
+    };
+}
+
+pub fn obeyRobots(self: *const Config) bool {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| opts.common.obey_robots,
+        else => unreachable,
+    };
+}
+
+pub fn httpProxy(self: *const Config) ?[:0]const u8 {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| opts.common.http_proxy,
+        else => unreachable,
+    };
+}
+
+pub fn proxyBearerToken(self: *const Config) ?[:0]const u8 {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| opts.common.proxy_bearer_token,
+        .help, .version => null,
+    };
+}
+
+pub fn httpMaxConcurrent(self: *const Config) u8 {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| opts.common.http_max_concurrent orelse 10,
+        else => unreachable,
+    };
+}
+
+pub fn httpMaxHostOpen(self: *const Config) u8 {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| opts.common.http_max_host_open orelse 4,
+        else => unreachable,
+    };
+}
+
+pub fn httpConnectTimeout(self: *const Config) u31 {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| opts.common.http_connect_timeout orelse 0,
+        else => unreachable,
+    };
+}
+
+pub fn httpTimeout(self: *const Config) u31 {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| opts.common.http_timeout orelse 5000,
+        else => unreachable,
+    };
+}
+
+pub fn httpMaxRedirects(_: *const Config) u8 {
+    return 10;
+}
+
+pub fn httpMaxResponseSize(self: *const Config) ?usize {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| opts.common.http_max_response_size,
+        else => unreachable,
+    };
+}
+
+pub fn logLevel(self: *const Config) ?log.Level {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| opts.common.log_level,
+        else => unreachable,
+    };
+}
+
+pub fn logFormat(self: *const Config) ?log.Format {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| opts.common.log_format,
+        else => unreachable,
+    };
+}
+
+pub fn logFilterScopes(self: *const Config) ?[]const log.Scope {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| opts.common.log_filter_scopes,
+        else => unreachable,
+    };
+}
+
+pub fn userAgentSuffix(self: *const Config) ?[]const u8 {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| opts.common.user_agent_suffix,
+        .help, .version => null,
+    };
+}
+
+pub fn cdpTimeout(self: *const Config) usize {
+    return switch (self.mode) {
+        .serve => |opts| if (opts.timeout > 604_800) 604_800_000 else @as(usize, opts.timeout) * 1000,
+        else => unreachable,
+    };
+}
+
+pub fn port(self: *const Config) u16 {
+    return switch (self.mode) {
+        .serve => |opts| opts.port,
+        else => unreachable,
+    };
+}
+
+pub fn advertiseHost(self: *const Config) []const u8 {
+    return switch (self.mode) {
+        .serve => |opts| opts.advertise_host orelse opts.host,
+        else => unreachable,
+    };
+}
+
+pub fn webBotAuth(self: *const Config) ?WebBotAuthConfig {
+    return switch (self.mode) {
+        inline .serve, .fetch, .mcp => |opts| WebBotAuthConfig{
+            .key_file = opts.common.web_bot_auth_key_file orelse return null,
+            .keyid = opts.common.web_bot_auth_keyid orelse return null,
+            .domain = opts.common.web_bot_auth_domain orelse return null,
+        },
+        .help, .version => null,
+    };
+}
+
+pub fn maxConnections(self: *const Config) u16 {
+    return switch (self.mode) {
+        .serve => |opts| opts.cdp_max_connections,
+        else => unreachable,
+    };
+}
+
+pub fn maxPendingConnections(self: *const Config) u31 {
+    return switch (self.mode) {
+        .serve => |opts| opts.cdp_max_pending_connections,
+        else => unreachable,
+    };
+}
+
+pub const Mode = union(RunMode) {
+    help: bool, // false when being printed because of an error
+    fetch: Fetch,
+    serve: Serve,
+    version: void,
+    mcp: Mcp,
+};
+
+pub const Serve = struct {
+    host: []const u8 = "127.0.0.1",
+    port: u16 = 9222,
+    advertise_host: ?[]const u8 = null,
+    timeout: u31 = 10,
+    cdp_max_connections: u16 = 16,
+    cdp_max_pending_connections: u16 = 128,
+    common: Common = .{},
+};
+
+pub const Mcp = struct {
+    common: Common = .{},
+};
+
+pub const DumpFormat = enum {
+    html,
+    markdown,
+    wpt,
+    semantic_tree,
+    semantic_tree_text,
+};
+
+pub const WaitUntil = enum {
+    load,
+    domcontentloaded,
+    networkidle,
+    done,
+};
+
+pub const Fetch = struct {
+    url: [:0]const u8,
+    dump_mode: ?DumpFormat = null,
+    common: Common = .{},
+    with_base: bool = false,
+    with_frames: bool = false,
+    strip: dump.Opts.Strip = .{},
+    wait_ms: u32 = 5000,
+    wait_until: WaitUntil = .load,
+};
+
+pub const Common = struct {
+    obey_robots: bool = false,
+    proxy_bearer_token: ?[:0]const u8 = null,
+    http_proxy: ?[:0]const u8 = null,
+    http_max_concurrent: ?u8 = null,
+    http_max_host_open: ?u8 = null,
+    http_timeout: ?u31 = null,
+    http_connect_timeout: ?u31 = null,
+    http_max_response_size: ?usize = null,
+    tls_verify_host: bool = true,
+    log_level: ?log.Level = null,
+    log_format: ?log.Format = null,
+    log_filter_scopes: ?[]log.Scope = null,
+    user_agent_suffix: ?[]const u8 = null,
+
+    web_bot_auth_key_file: ?[]const u8 = null,
+    web_bot_auth_keyid: ?[]const u8 = null,
+    web_bot_auth_domain: ?[]const u8 = null,
+};
+
+/// Pre-formatted HTTP headers for reuse across Http and Client.
+/// Must be initialized with an allocator that outlives all HTTP connections.
+pub const HttpHeaders = struct {
+    const user_agent_base: [:0]const u8 = "Lightpanda/1.0";
+
+    user_agent: [:0]const u8, // User agent value (e.g. "Lightpanda/1.0")
+    user_agent_header: [:0]const u8,
+
+    proxy_bearer_header: ?[:0]const u8,
+
+    pub fn init(allocator: Allocator, config: *const Config) !HttpHeaders {
+        const user_agent: [:0]const u8 = if (config.userAgentSuffix()) |suffix|
+            try std.fmt.allocPrintSentinel(allocator, "{s} {s}", .{ user_agent_base, suffix }, 0)
+        else
+            user_agent_base;
+        errdefer if (config.userAgentSuffix() != null) allocator.free(user_agent);
+
+        const user_agent_header = try std.fmt.allocPrintSentinel(allocator, "User-Agent: {s}", .{user_agent}, 0);
+        errdefer allocator.free(user_agent_header);
+
+        const proxy_bearer_header: ?[:0]const u8 = if (config.proxyBearerToken()) |token|
+            try std.fmt.allocPrintSentinel(allocator, "Proxy-Authorization: Bearer {s}", .{token}, 0)
+        else
+            null;
+
+        return .{
+            .user_agent = user_agent,
+            .user_agent_header = user_agent_header,
+            .proxy_bearer_header = proxy_bearer_header,
+        };
+    }
+
+    pub fn deinit(self: *const HttpHeaders, allocator: Allocator) void {
+        if (self.proxy_bearer_header) |hdr| {
+            allocator.free(hdr);
+        }
+        allocator.free(self.user_agent_header);
+        if (self.user_agent.ptr != user_agent_base.ptr) {
+            allocator.free(self.user_agent);
+        }
+    }
+};
+
+pub fn printUsageAndExit(self: *const Config, success: bool) void {
+    //                                                                     MAX_HELP_LEN|
+    const common_options =
+        \\
+        \\--insecure-disable-tls-host-verification
+        \\                Disables host verification on all HTTP requests. This is an
+        \\                advanced option which should only be set if you understand
+        \\                and accept the risk of disabling host verification.
+        \\
+        \\--obey-robots
+        \\                Fetches and obeys the robots.txt (if available) of the web pages
+        \\                we make requests towards.
+        \\                Defaults to false.
+        \\
+        \\--http-proxy    The HTTP proxy to use for all HTTP requests.
+        \\                A username:password can be included for basic authentication.
+        \\                Defaults to none.
+        \\
+        \\--proxy-bearer-token
+        \\                The <token> to send for bearer authentication with the proxy
+        \\                Proxy-Authorization: Bearer <token>
+        \\
+        \\--http-max-concurrent
+        \\                The maximum number of concurrent HTTP requests.
+        \\                Defaults to 10.
+        \\
+        \\--http-max-host-open
+        \\                The maximum number of open connection to a given host:port.
+        \\                Defaults to 4.
+        \\
+        \\--http-connect-timeout
+        \\                The time, in milliseconds, for establishing an HTTP connection
+        \\                before timing out. 0 means it never times out.
+        \\                Defaults to 0.
+        \\
+        \\--http-timeout
+        \\                The maximum time, in milliseconds, the transfer is allowed
+        \\                to complete. 0 means it never times out.
+        \\                Defaults to 10000.
+        \\
+        \\--http-max-response-size
+        \\                Limits the acceptable response size for any request
+        \\                (e.g. XHR, fetch, script loading, ...).
+        \\                Defaults to no limit.
+        \\
+        \\--log-level     The log level: debug, info, warn, error or fatal.
+        \\                Defaults to
+    ++ (if (builtin.mode == .Debug) " info." else "warn.") ++
+        \\
+        \\
+        \\--log-format    The log format: pretty or logfmt.
+        \\                Defaults to
+    ++ (if (builtin.mode == .Debug) " pretty." else " logfmt.") ++
+        \\
+        \\
+        \\--log-filter-scopes
+        \\                Filter out too verbose logs per scope:
+        \\                http, unknown_prop, event, ...
+        \\
+        \\--user-agent-suffix
+        \\                Suffix to append to the Lightpanda/X.Y User-Agent
+        \\
+        \\--web-bot-auth-key-file
+        \\                Path to the Ed25519 private key PEM file.
+        \\
+        \\--web-bot-auth-keyid
+        \\                The JWK thumbprint of your public key.
+        \\
+        \\--web-bot-auth-domain
+        \\                Your domain e.g. yourdomain.com
+    ;
+
+    //                                                                     MAX_HELP_LEN|
+    const usage =
+        \\usage: {s} command [options] [URL]
+        \\
+        \\Command can be either 'fetch', 'serve', 'mcp' or 'help'
+        \\
+        \\fetch command
+        \\Fetches the specified URL
+        \\Example: {s} fetch --dump html https://lightpanda.io/
+        \\
+        \\Options:
+        \\--dump          Dumps document to stdout.
+        \\                Argument must be 'html', 'markdown', 'semantic_tree', or 'semantic_tree_text'.
+        \\                Defaults to no dump.
+        \\
+        \\--strip-mode    Comma separated list of tag groups to remove from dump
+        \\                the dump. e.g. --strip-mode js,css
+        \\                  - "js" script and link[as=script, rel=preload]
+        \\                  - "ui" includes img, picture, video, css and svg
+        \\                  - "css" includes style and link[rel=stylesheet]
+        \\                  - "full" includes js, ui and css
+        \\
+        \\--with-base     Add a <base> tag in dump. Defaults to false.
+        \\
+        \\--with-frames   Includes the contents of iframes. Defaults to false.
+        \\
+        \\--wait-ms       Wait time in milliseconds.
+        \\                Defaults to 5000.
+        \\
+        \\--wait-until    Wait until the specified event.
+        \\                Supported events: load, domcontentloaded, networkidle, done.
+        \\                Defaults to 'done'.
+        \\
+    ++ common_options ++
+        \\
+        \\serve command
+        \\Starts a websocket CDP server
+        \\Example: {s} serve --host 127.0.0.1 --port 9222
+        \\
+        \\Options:
+        \\--host          Host of the CDP server
+        \\                Defaults to "127.0.0.1"
+        \\
+        \\--port          Port of the CDP server
+        \\                Defaults to 9222
+        \\
+        \\--advertise-host
+        \\                The host to advertise, e.g. in the /json/version response.
+        \\                Useful, for example, when --host is 0.0.0.0.
+        \\                Defaults to --host value
+        \\
+        \\--timeout       Inactivity timeout in seconds before disconnecting clients
+        \\                Defaults to 10 (seconds). Limited to 604800 (1 week).
+        \\
+        \\--cdp-max-connections
+        \\                Maximum number of simultaneous CDP connections.
+        \\                Defaults to 16.
+        \\
+        \\--cdp-max-pending-connections
+        \\                Maximum pending connections in the accept queue.
+        \\                Defaults to 128.
+        \\
+    ++ common_options ++
+        \\
+        \\mcp command
+        \\Starts an MCP (Model Context Protocol) server over stdio
+        \\Example: {s} mcp
+        \\
+    ++ common_options ++
+        \\
+        \\version command
+        \\Displays the version of {s}
+        \\
+        \\help command
+        \\Displays this message
+        \\
+    ;
+    std.debug.print(usage, .{ self.exec_name, self.exec_name, self.exec_name, self.exec_name, self.exec_name });
+    if (success) {
+        return std.process.cleanExit();
+    }
+    std.process.exit(1);
+}
+
+pub fn parseArgs(allocator: Allocator) !Config {
+    var args = try std.process.argsWithAllocator(allocator);
+    defer args.deinit();
+
+    const exec_name = try allocator.dupe(u8, std.fs.path.basename(args.next().?));
+
+    const mode_string = args.next() orelse "";
+    const run_mode = std.meta.stringToEnum(RunMode, mode_string) orelse blk: {
+        const inferred_mode = inferMode(mode_string) orelse
+            return init(allocator, exec_name, .{ .help = false });
+        // "command" wasn't a command but an option. We can't reset args, but
+        // we can create a new one. Not great, but this fallback is temporary
+        // as we transition to this command mode approach.
+        args.deinit();
+
+        args = try std.process.argsWithAllocator(allocator);
+        // skip the exec_name
+        _ = args.skip();
+
+        break :blk inferred_mode;
+    };
+
+    const mode: Mode = switch (run_mode) {
+        .help => .{ .help = true },
+        .serve => .{ .serve = parseServeArgs(allocator, &args) catch
+            return init(allocator, exec_name, .{ .help = false }) },
+        .fetch => .{ .fetch = parseFetchArgs(allocator, &args) catch
+            return init(allocator, exec_name, .{ .help = false }) },
+        .mcp => .{ .mcp = parseMcpArgs(allocator, &args) catch
+            return init(allocator, exec_name, .{ .help = false }) },
+        .version => .{ .version = {} },
+    };
+    return init(allocator, exec_name, mode);
+}
+
+fn inferMode(opt: []const u8) ?RunMode {
+    if (opt.len == 0) {
+        return .serve;
+    }
+
+    if (std.mem.startsWith(u8, opt, "--") == false) {
+        return .fetch;
+    }
+
+    if (std.mem.eql(u8, opt, "--dump")) {
+        return .fetch;
+    }
+
+    if (std.mem.eql(u8, opt, "--noscript")) {
+        return .fetch;
+    }
+
+    if (std.mem.eql(u8, opt, "--strip-mode") or std.mem.eql(u8, opt, "--strip_mode")) {
+        return .fetch;
+    }
+
+    if (std.mem.eql(u8, opt, "--with-base") or std.mem.eql(u8, opt, "--with_base")) {
+        return .fetch;
+    }
+
+    if (std.mem.eql(u8, opt, "--with-frames") or std.mem.eql(u8, opt, "--with_frames")) {
+        return .fetch;
+    }
+
+    if (std.mem.eql(u8, opt, "--host")) {
+        return .serve;
+    }
+
+    if (std.mem.eql(u8, opt, "--port")) {
+        return .serve;
+    }
+
+    if (std.mem.eql(u8, opt, "--timeout")) {
+        return .serve;
+    }
+
+    return null;
+}
+
+fn parseServeArgs(
+    allocator: Allocator,
+    args: *std.process.ArgIterator,
+) !Serve {
+    var serve: Serve = .{};
+
+    while (args.next()) |opt| {
+        if (std.mem.eql(u8, "--host", opt)) {
+            const str = args.next() orelse {
+                log.fatal(.app, "missing argument value", .{ .arg = "--host" });
+                return error.InvalidArgument;
+            };
+            serve.host = try allocator.dupe(u8, str);
+            continue;
+        }
+
+        if (std.mem.eql(u8, "--port", opt)) {
+            const str = args.next() orelse {
+                log.fatal(.app, "missing argument value", .{ .arg = "--port" });
+                return error.InvalidArgument;
+            };
+
+            serve.port = std.fmt.parseInt(u16, str, 10) catch |err| {
+                log.fatal(.app, "invalid argument value", .{ .arg = "--port", .err = err });
+                return error.InvalidArgument;
+            };
+            continue;
+        }
+
+        if (std.mem.eql(u8, "--advertise-host", opt) or std.mem.eql(u8, "--advertise_host", opt)) {
+            const str = args.next() orelse {
+                log.fatal(.app, "missing argument value", .{ .arg = opt });
+                return error.InvalidArgument;
+            };
+            serve.advertise_host = try allocator.dupe(u8, str);
+            continue;
+        }
+
+        if (std.mem.eql(u8, "--timeout", opt)) {
+            const str = args.next() orelse {
+                log.fatal(.app, "missing argument value", .{ .arg = "--timeout" });
+                return error.InvalidArgument;
+            };
+
+            serve.timeout = std.fmt.parseInt(u31, str, 10) catch |err| {
+                log.fatal(.app, "invalid argument value", .{ .arg = "--timeout", .err = err });
+                return error.InvalidArgument;
+            };
+            continue;
+        }
+
+        if (std.mem.eql(u8, "--cdp-max-connections", opt) or std.mem.eql(u8, "--cdp_max_connections", opt)) {
+            const str = args.next() orelse {
+                log.fatal(.app, "missing argument value", .{ .arg = opt });
+                return error.InvalidArgument;
+            };
+
+            serve.cdp_max_connections = std.fmt.parseInt(u16, str, 10) catch |err| {
+                log.fatal(.app, "invalid argument value", .{ .arg = opt, .err = err });
+                return error.InvalidArgument;
+            };
+            continue;
+        }
+
+        if (std.mem.eql(u8, "--cdp-max-pending-connections", opt) or std.mem.eql(u8, "--cdp_max_pending_connections", opt)) {
+            const str = args.next() orelse {
+                log.fatal(.app, "missing argument value", .{ .arg = opt });
+                return error.InvalidArgument;
+            };
+
+            serve.cdp_max_pending_connections = std.fmt.parseInt(u16, str, 10) catch |err| {
+                log.fatal(.app, "invalid argument value", .{ .arg = opt, .err = err });
+                return error.InvalidArgument;
+            };
+            continue;
+        }
+
+        if (try parseCommonArg(allocator, opt, args, &serve.common)) {
+            continue;
+        }
+
+        log.fatal(.app, "unknown argument", .{ .mode = "serve", .arg = opt });
+        return error.UnkownOption;
+    }
+
+    return serve;
+}
+
+fn parseMcpArgs(
+    allocator: Allocator,
+    args: *std.process.ArgIterator,
+) !Mcp {
+    var mcp: Mcp = .{};
+
+    while (args.next()) |opt| {
+        if (try parseCommonArg(allocator, opt, args, &mcp.common)) {
+            continue;
+        }
+
+        log.fatal(.mcp, "unknown argument", .{ .mode = "mcp", .arg = opt });
+        return error.UnkownOption;
+    }
+
+    return mcp;
+}
+
+fn parseFetchArgs(
+    allocator: Allocator,
+    args: *std.process.ArgIterator,
+) !Fetch {
+    var dump_mode: ?DumpFormat = null;
+    var with_base: bool = false;
+    var with_frames: bool = false;
+    var url: ?[:0]const u8 = null;
+    var common: Common = .{};
+    var strip: dump.Opts.Strip = .{};
+    var wait_ms: u32 = 5000;
+    var wait_until: WaitUntil = .load;
+
+    while (args.next()) |opt| {
+        if (std.mem.eql(u8, "--wait-ms", opt) or std.mem.eql(u8, "--wait_ms", opt)) {
+            const str = args.next() orelse {
+                log.fatal(.app, "missing argument value", .{ .arg = opt });
+                return error.InvalidArgument;
+            };
+            wait_ms = std.fmt.parseInt(u32, str, 10) catch |err| {
+                log.fatal(.app, "invalid argument value", .{ .arg = opt, .err = err });
+                return error.InvalidArgument;
+            };
+            continue;
+        }
+
+        if (std.mem.eql(u8, "--wait-until", opt) or std.mem.eql(u8, "--wait_until", opt)) {
+            const str = args.next() orelse {
+                log.fatal(.app, "missing argument value", .{ .arg = opt });
+                return error.InvalidArgument;
+            };
+            wait_until = std.meta.stringToEnum(WaitUntil, str) orelse {
+                log.fatal(.app, "invalid argument value", .{ .arg = opt, .val = str });
+                return error.InvalidArgument;
+            };
+            continue;
+        }
+
+        if (std.mem.eql(u8, "--dump", opt)) {
+            var peek_args = args.*;
+            if (peek_args.next()) |next_arg| {
+                if (std.meta.stringToEnum(DumpFormat, next_arg)) |mode| {
+                    dump_mode = mode;
+                    _ = args.next();
+                } else {
+                    dump_mode = .html;
+                }
+            } else {
+                dump_mode = .html;
+            }
+            continue;
+        }
+
+        if (std.mem.eql(u8, "--noscript", opt)) {
+            log.warn(.app, "deprecation warning", .{
+                .feature = "--noscript argument",
+                .hint = "use '--strip-mode js' instead",
+            });
+            strip.js = true;
+            continue;
+        }
+
+        if (std.mem.eql(u8, "--with-base", opt) or std.mem.eql(u8, "--with_base", opt)) {
+            with_base = true;
+            continue;
+        }
+
+        if (std.mem.eql(u8, "--with-frames", opt) or std.mem.eql(u8, "--with_frames", opt)) {
+            with_frames = true;
+            continue;
+        }
+
+        if (std.mem.eql(u8, "--strip-mode", opt) or std.mem.eql(u8, "--strip_mode", opt)) {
+            const str = args.next() orelse {
+                log.fatal(.app, "missing argument value", .{ .arg = opt });
+                return error.InvalidArgument;
+            };
+
+            var it = std.mem.splitScalar(u8, str, ',');
+            while (it.next()) |part| {
+                const trimmed = std.mem.trim(u8, part, &std.ascii.whitespace);
+                if (std.mem.eql(u8, trimmed, "js")) {
+                    strip.js = true;
+                } else if (std.mem.eql(u8, trimmed, "ui")) {
+                    strip.ui = true;
+                } else if (std.mem.eql(u8, trimmed, "css")) {
+                    strip.css = true;
+                } else if (std.mem.eql(u8, trimmed, "full")) {
+                    strip.js = true;
+                    strip.ui = true;
+                    strip.css = true;
+                } else {
+                    log.fatal(.app, "invalid option choice", .{ .arg = opt, .value = trimmed });
+                }
+            }
+            continue;
+        }
+
+        if (try parseCommonArg(allocator, opt, args, &common)) {
+            continue;
+        }
+
+        if (std.mem.startsWith(u8, opt, "--")) {
+            log.fatal(.app, "unknown argument", .{ .mode = "fetch", .arg = opt });
+            return error.UnkownOption;
+        }
+
+        if (url != null) {
+            log.fatal(.app, "duplicate fetch url", .{ .help = "only 1 URL can be specified" });
+            return error.TooManyURLs;
+        }
+        url = try allocator.dupeZ(u8, opt);
+    }
+
+    if (url == null) {
+        log.fatal(.app, "missing fetch url", .{ .help = "URL to fetch must be provided" });
+        return error.MissingURL;
+    }
+
+    return .{
+        .url = url.?,
+        .dump_mode = dump_mode,
+        .strip = strip,
+        .common = common,
+        .with_base = with_base,
+        .with_frames = with_frames,
+        .wait_ms = wait_ms,
+        .wait_until = wait_until,
+    };
+}
+
+fn parseCommonArg(
+    allocator: Allocator,
+    opt: []const u8,
+    args: *std.process.ArgIterator,
+    common: *Common,
+) !bool {
+    if (std.mem.eql(u8, "--insecure-disable-tls-host-verification", opt) or std.mem.eql(u8, "--insecure_disable_tls_host_verification", opt)) {
+        common.tls_verify_host = false;
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--obey-robots", opt) or std.mem.eql(u8, "--obey_robots", opt)) {
+        common.obey_robots = true;
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--http-proxy", opt) or std.mem.eql(u8, "--http_proxy", opt)) {
+        const str = args.next() orelse {
+            log.fatal(.app, "missing argument value", .{ .arg = opt });
+            return error.InvalidArgument;
+        };
+        common.http_proxy = try allocator.dupeZ(u8, str);
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--proxy-bearer-token", opt) or std.mem.eql(u8, "--proxy_bearer_token", opt)) {
+        const str = args.next() orelse {
+            log.fatal(.app, "missing argument value", .{ .arg = opt });
+            return error.InvalidArgument;
+        };
+        common.proxy_bearer_token = try allocator.dupeZ(u8, str);
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--http-max-concurrent", opt) or std.mem.eql(u8, "--http_max_concurrent", opt)) {
+        const str = args.next() orelse {
+            log.fatal(.app, "missing argument value", .{ .arg = opt });
+            return error.InvalidArgument;
+        };
+
+        common.http_max_concurrent = std.fmt.parseInt(u8, str, 10) catch |err| {
+            log.fatal(.app, "invalid argument value", .{ .arg = opt, .err = err });
+            return error.InvalidArgument;
+        };
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--http-max-host-open", opt) or std.mem.eql(u8, "--http_max_host_open", opt)) {
+        const str = args.next() orelse {
+            log.fatal(.app, "missing argument value", .{ .arg = opt });
+            return error.InvalidArgument;
+        };
+
+        common.http_max_host_open = std.fmt.parseInt(u8, str, 10) catch |err| {
+            log.fatal(.app, "invalid argument value", .{ .arg = opt, .err = err });
+            return error.InvalidArgument;
+        };
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--http-connect-timeout", opt) or std.mem.eql(u8, "--http_connect_timeout", opt)) {
+        const str = args.next() orelse {
+            log.fatal(.app, "missing argument value", .{ .arg = opt });
+            return error.InvalidArgument;
+        };
+
+        common.http_connect_timeout = std.fmt.parseInt(u31, str, 10) catch |err| {
+            log.fatal(.app, "invalid argument value", .{ .arg = opt, .err = err });
+            return error.InvalidArgument;
+        };
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--http-timeout", opt) or std.mem.eql(u8, "--http_timeout", opt)) {
+        const str = args.next() orelse {
+            log.fatal(.app, "missing argument value", .{ .arg = opt });
+            return error.InvalidArgument;
+        };
+
+        common.http_timeout = std.fmt.parseInt(u31, str, 10) catch |err| {
+            log.fatal(.app, "invalid argument value", .{ .arg = opt, .err = err });
+            return error.InvalidArgument;
+        };
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--http-max-response-size", opt) or std.mem.eql(u8, "--http_max_response_size", opt)) {
+        const str = args.next() orelse {
+            log.fatal(.app, "missing argument value", .{ .arg = opt });
+            return error.InvalidArgument;
+        };
+
+        common.http_max_response_size = std.fmt.parseInt(usize, str, 10) catch |err| {
+            log.fatal(.app, "invalid argument value", .{ .arg = opt, .err = err });
+            return error.InvalidArgument;
+        };
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--log-level", opt) or std.mem.eql(u8, "--log_level", opt)) {
+        const str = args.next() orelse {
+            log.fatal(.app, "missing argument value", .{ .arg = opt });
+            return error.InvalidArgument;
+        };
+
+        common.log_level = std.meta.stringToEnum(log.Level, str) orelse blk: {
+            if (std.mem.eql(u8, str, "error")) {
+                break :blk .err;
+            }
+            log.fatal(.app, "invalid option choice", .{ .arg = opt, .value = str });
+            return error.InvalidArgument;
+        };
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--log-format", opt) or std.mem.eql(u8, "--log_format", opt)) {
+        const str = args.next() orelse {
+            log.fatal(.app, "missing argument value", .{ .arg = opt });
+            return error.InvalidArgument;
+        };
+
+        common.log_format = std.meta.stringToEnum(log.Format, str) orelse {
+            log.fatal(.app, "invalid option choice", .{ .arg = opt, .value = str });
+            return error.InvalidArgument;
+        };
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--log-filter-scopes", opt) or std.mem.eql(u8, "--log_filter_scopes", opt)) {
+        if (builtin.mode != .Debug) {
+            log.fatal(.app, "experimental", .{ .help = "log scope filtering is only available in debug builds" });
+            return false;
+        }
+
+        const str = args.next() orelse {
+            // disables the default filters
+            common.log_filter_scopes = &.{};
+            return true;
+        };
+
+        var arr: std.ArrayList(log.Scope) = .empty;
+
+        var it = std.mem.splitScalar(u8, str, ',');
+        while (it.next()) |part| {
+            try arr.append(allocator, std.meta.stringToEnum(log.Scope, part) orelse {
+                log.fatal(.app, "invalid option choice", .{ .arg = opt, .value = part });
+                return false;
+            });
+        }
+        common.log_filter_scopes = arr.items;
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--user-agent-suffix", opt) or std.mem.eql(u8, "--user_agent_suffix", opt)) {
+        const str = args.next() orelse {
+            log.fatal(.app, "missing argument value", .{ .arg = opt });
+            return error.InvalidArgument;
+        };
+        for (str) |c| {
+            if (!std.ascii.isPrint(c)) {
+                log.fatal(.app, "not printable character", .{ .arg = opt });
+                return error.InvalidArgument;
+            }
+        }
+        common.user_agent_suffix = try allocator.dupe(u8, str);
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--web-bot-auth-key-file", opt) or std.mem.eql(u8, "--web_bot_auth_key_file", opt)) {
+        const str = args.next() orelse {
+            log.fatal(.app, "missing argument value", .{ .arg = opt });
+            return error.InvalidArgument;
+        };
+        common.web_bot_auth_key_file = try allocator.dupe(u8, str);
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--web-bot-auth-keyid", opt) or std.mem.eql(u8, "--web_bot_auth_keyid", opt)) {
+        const str = args.next() orelse {
+            log.fatal(.app, "missing argument value", .{ .arg = opt });
+            return error.InvalidArgument;
+        };
+        common.web_bot_auth_keyid = try allocator.dupe(u8, str);
+        return true;
+    }
+
+    if (std.mem.eql(u8, "--web-bot-auth-domain", opt) or std.mem.eql(u8, "--web_bot_auth_domain", opt)) {
+        const str = args.next() orelse {
+            log.fatal(.app, "missing argument value", .{ .arg = opt });
+            return error.InvalidArgument;
+        };
+        common.web_bot_auth_domain = try allocator.dupe(u8, str);
+        return true;
+    }
+
+    return false;
+}

src/Notification.zig

@@ -0,0 +1,419 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const lp = @import("lightpanda");
+
+const log = @import("log.zig");
+const Page = @import("browser/Page.zig");
+const Transfer = @import("browser/HttpClient.zig").Transfer;
+
+const Allocator = std.mem.Allocator;
+
+const List = std.DoublyLinkedList;
+
+// Allows code to register for and emit events.
+// Keeps two lists
+// 1 - for a given event type, a linked list of all the listeners
+// 2 - for a given listener, a list of all it's registration
+// The 2nd one is so that a listener can unregister all of it's listeners
+// (there's currently no need for a listener to unregister only 1 or more
+// specific listener).
+//
+// Scoping is important. Imagine we created a global singleton registry, and our
+// CDP code registers for the "network_bytes_sent" event, because it needs to
+// send messages to the client when this happens. Our HTTP client could then
+// emit a "network_bytes_sent" message. It would be easy, and it would work.
+// That is, it would work until multiple CDP clients connect, and because
+// everything's just one big global, events from one CDP session would be sent
+// to all CDP clients.
+//
+// To avoid this, one way or another, we need scoping. We could still have
+// a global registry but every "register" and every "emit" has some type of
+// "scope". This would have a run-time cost and still require some coordination
+// between components to share a common scope.
+//
+// Instead, the approach that we take is to have a notification instance per
+// CDP connection (BrowserContext). Each CDP connection has its own notification
+// that is shared across all Sessions (tabs) within that connection. This ensures
+// proper isolation between different CDP clients while allowing a single client
+// to receive events from all its tabs.
+const Notification = @This();
+// Every event type (which are hard-coded), has a list of Listeners.
+// When the event happens, we dispatch to those listener.
+event_listeners: EventListeners,
+
+// list of listeners for a specified receiver
+// @intFromPtr(receiver) -> [listener1, listener2, ...]
+// Used when `unregisterAll` is called.
+listeners: std.AutoHashMapUnmanaged(usize, std.ArrayList(*Listener)),
+
+allocator: Allocator,
+mem_pool: std.heap.MemoryPool(Listener),
+
+const EventListeners = struct {
+    page_remove: List = .{},
+    page_created: List = .{},
+    page_navigate: List = .{},
+    page_navigated: List = .{},
+    page_network_idle: List = .{},
+    page_network_almost_idle: List = .{},
+    page_frame_created: List = .{},
+    http_request_fail: List = .{},
+    http_request_start: List = .{},
+    http_request_intercept: List = .{},
+    http_request_done: List = .{},
+    http_request_auth_required: List = .{},
+    http_response_data: List = .{},
+    http_response_header_done: List = .{},
+};
+
+const Events = union(enum) {
+    page_remove: PageRemove,
+    page_created: *Page,
+    page_navigate: *const PageNavigate,
+    page_navigated: *const PageNavigated,
+    page_network_idle: *const PageNetworkIdle,
+    page_network_almost_idle: *const PageNetworkAlmostIdle,
+    page_frame_created: *const PageFrameCreated,
+    http_request_fail: *const RequestFail,
+    http_request_start: *const RequestStart,
+    http_request_intercept: *const RequestIntercept,
+    http_request_auth_required: *const RequestAuthRequired,
+    http_request_done: *const RequestDone,
+    http_response_data: *const ResponseData,
+    http_response_header_done: *const ResponseHeaderDone,
+};
+const EventType = std.meta.FieldEnum(Events);
+
+pub const PageRemove = struct {};
+
+pub const PageNavigate = struct {
+    req_id: u32,
+    frame_id: u32,
+    timestamp: u64,
+    url: [:0]const u8,
+    opts: Page.NavigateOpts,
+};
+
+pub const PageNavigated = struct {
+    req_id: u32,
+    frame_id: u32,
+    timestamp: u64,
+    url: [:0]const u8,
+    opts: Page.NavigatedOpts,
+};
+
+pub const PageNetworkIdle = struct {
+    req_id: u32,
+    frame_id: u32,
+    timestamp: u64,
+};
+
+pub const PageNetworkAlmostIdle = struct {
+    req_id: u32,
+    frame_id: u32,
+    timestamp: u64,
+};
+
+pub const PageFrameCreated = struct {
+    frame_id: u32,
+    parent_id: u32,
+    timestamp: u64,
+};
+
+pub const RequestStart = struct {
+    transfer: *Transfer,
+};
+
+pub const RequestIntercept = struct {
+    transfer: *Transfer,
+    wait_for_interception: *bool,
+};
+
+pub const RequestAuthRequired = struct {
+    transfer: *Transfer,
+    wait_for_interception: *bool,
+};
+
+pub const ResponseData = struct {
+    data: []const u8,
+    transfer: *Transfer,
+};
+
+pub const ResponseHeaderDone = struct {
+    transfer: *Transfer,
+};
+
+pub const RequestDone = struct {
+    transfer: *Transfer,
+};
+
+pub const RequestFail = struct {
+    transfer: *Transfer,
+    err: anyerror,
+};
+
+pub fn init(allocator: Allocator) !*Notification {
+    const notification = try allocator.create(Notification);
+    errdefer allocator.destroy(notification);
+
+    notification.* = .{
+        .listeners = .{},
+        .event_listeners = .{},
+        .allocator = allocator,
+        .mem_pool = std.heap.MemoryPool(Listener).init(allocator),
+    };
+
+    return notification;
+}
+
+pub fn deinit(self: *Notification) void {
+    const allocator = self.allocator;
+
+    var it = self.listeners.valueIterator();
+    while (it.next()) |listener| {
+        listener.deinit(allocator);
+    }
+    self.listeners.deinit(allocator);
+    self.mem_pool.deinit();
+    allocator.destroy(self);
+}
+
+pub fn register(self: *Notification, comptime event: EventType, receiver: anytype, func: EventFunc(event)) !void {
+    var list = &@field(self.event_listeners, @tagName(event));
+
+    var listener = try self.mem_pool.create();
+    errdefer self.mem_pool.destroy(listener);
+
+    listener.* = .{
+        .node = .{},
+        .list = list,
+        .receiver = receiver,
+        .event = event,
+        .func = @ptrCast(func),
+        .struct_name = @typeName(@typeInfo(@TypeOf(receiver)).pointer.child),
+    };
+
+    const allocator = self.allocator;
+    const gop = try self.listeners.getOrPut(allocator, @intFromPtr(receiver));
+    if (gop.found_existing == false) {
+        gop.value_ptr.* = .{};
+    }
+    try gop.value_ptr.append(allocator, listener);
+
+    // we don't add this until we've successfully added the entry to
+    // self.listeners
+    list.append(&listener.node);
+}
+
+pub fn unregister(self: *Notification, comptime event: EventType, receiver: anytype) void {
+    var listeners = self.listeners.getPtr(@intFromPtr(receiver)) orelse return;
+
+    var i: usize = 0;
+    while (i < listeners.items.len) {
+        const listener = listeners.items[i];
+        if (listener.event != event) {
+            i += 1;
+            continue;
+        }
+        listener.list.remove(&listener.node);
+        self.mem_pool.destroy(listener);
+        _ = listeners.swapRemove(i);
+    }
+
+    if (listeners.items.len == 0) {
+        listeners.deinit(self.allocator);
+        const removed = self.listeners.remove(@intFromPtr(receiver));
+        lp.assert(removed == true, "Notification.unregister", .{ .type = event });
+    }
+}
+
+pub fn unregisterAll(self: *Notification, receiver: *anyopaque) void {
+    var kv = self.listeners.fetchRemove(@intFromPtr(receiver)) orelse return;
+    for (kv.value.items) |listener| {
+        listener.list.remove(&listener.node);
+        self.mem_pool.destroy(listener);
+    }
+    kv.value.deinit(self.allocator);
+}
+
+pub fn dispatch(self: *Notification, comptime event: EventType, data: ArgType(event)) void {
+    if (self.listeners.count() == 0) {
+        return;
+    }
+    const list = &@field(self.event_listeners, @tagName(event));
+
+    var node = list.first;
+    while (node) |n| {
+        const listener: *Listener = @fieldParentPtr("node", n);
+        const func: EventFunc(event) = @ptrCast(@alignCast(listener.func));
+        func(listener.receiver, data) catch |err| {
+            log.err(.app, "dispatch error", .{
+                .err = err,
+                .event = event,
+                .source = "notification",
+                .listener = listener.struct_name,
+            });
+        };
+        node = n.next;
+    }
+}
+
+// Given an event type enum, returns the type of arg the event emits
+fn ArgType(comptime event: Notification.EventType) type {
+    inline for (std.meta.fields(Notification.Events)) |f| {
+        if (std.mem.eql(u8, f.name, @tagName(event))) {
+            return f.type;
+        }
+    }
+    unreachable;
+}
+
+// Given an event type enum, returns the listening function type
+fn EventFunc(comptime event: Notification.EventType) type {
+    return *const fn (*anyopaque, ArgType(event)) anyerror!void;
+}
+
+// A listener. This is 1 receiver, with its function, and the linked list
+// node that goes in the appropriate EventListeners list.
+const Listener = struct {
+    // the receiver of the event, i.e. the self parameter to `func`
+    receiver: *anyopaque,
+
+    // the function to call
+    func: *const anyopaque,
+
+    // For logging slightly better error
+    struct_name: []const u8,
+
+    event: Notification.EventType,
+
+    // intrusive linked list node
+    node: List.Node,
+
+    // The event list this listener belongs to.
+    // We need this in order to be able to remove the node from the list
+    list: *List,
+};
+
+const testing = std.testing;
+test "Notification" {
+    var notifier = try Notification.init(testing.allocator);
+    defer notifier.deinit();
+
+    // noop
+    notifier.dispatch(.page_navigate, &.{
+        .frame_id = 0,
+        .req_id = 1,
+        .timestamp = 4,
+        .url = undefined,
+        .opts = .{},
+    });
+
+    var tc = TestClient{};
+
+    try notifier.register(.page_navigate, &tc, TestClient.pageNavigate);
+    notifier.dispatch(.page_navigate, &.{
+        .frame_id = 0,
+        .req_id = 1,
+        .timestamp = 4,
+        .url = undefined,
+        .opts = .{},
+    });
+    try testing.expectEqual(4, tc.page_navigate);
+
+    notifier.unregisterAll(&tc);
+    notifier.dispatch(.page_navigate, &.{
+        .frame_id = 0,
+        .req_id = 1,
+        .timestamp = 10,
+        .url = undefined,
+        .opts = .{},
+    });
+    try testing.expectEqual(4, tc.page_navigate);
+
+    try notifier.register(.page_navigate, &tc, TestClient.pageNavigate);
+    try notifier.register(.page_navigated, &tc, TestClient.pageNavigated);
+    notifier.dispatch(.page_navigate, &.{
+        .frame_id = 0,
+        .req_id = 1,
+        .timestamp = 10,
+        .url = undefined,
+        .opts = .{},
+    });
+    notifier.dispatch(.page_navigated, &.{ .frame_id = 0, .req_id = 1, .timestamp = 6, .url = undefined, .opts = .{} });
+    try testing.expectEqual(14, tc.page_navigate);
+    try testing.expectEqual(6, tc.page_navigated);
+
+    notifier.unregisterAll(&tc);
+    notifier.dispatch(.page_navigate, &.{
+        .frame_id = 0,
+        .req_id = 1,
+        .timestamp = 100,
+        .url = undefined,
+        .opts = .{},
+    });
+    notifier.dispatch(.page_navigated, &.{ .frame_id = 0, .req_id = 1, .timestamp = 100, .url = undefined, .opts = .{} });
+    try testing.expectEqual(14, tc.page_navigate);
+    try testing.expectEqual(6, tc.page_navigated);
+
+    {
+        // unregister
+        try notifier.register(.page_navigate, &tc, TestClient.pageNavigate);
+        try notifier.register(.page_navigated, &tc, TestClient.pageNavigated);
+        notifier.dispatch(.page_navigate, &.{ .frame_id = 0, .req_id = 1, .timestamp = 100, .url = undefined, .opts = .{} });
+        notifier.dispatch(.page_navigated, &.{ .frame_id = 0, .req_id = 1, .timestamp = 1000, .url = undefined, .opts = .{} });
+        try testing.expectEqual(114, tc.page_navigate);
+        try testing.expectEqual(1006, tc.page_navigated);
+
+        notifier.unregister(.page_navigate, &tc);
+        notifier.dispatch(.page_navigate, &.{ .frame_id = 0, .req_id = 1, .timestamp = 100, .url = undefined, .opts = .{} });
+        notifier.dispatch(.page_navigated, &.{ .frame_id = 0, .req_id = 1, .timestamp = 1000, .url = undefined, .opts = .{} });
+        try testing.expectEqual(114, tc.page_navigate);
+        try testing.expectEqual(2006, tc.page_navigated);
+
+        notifier.unregister(.page_navigated, &tc);
+        notifier.dispatch(.page_navigate, &.{ .frame_id = 0, .req_id = 1, .timestamp = 100, .url = undefined, .opts = .{} });
+        notifier.dispatch(.page_navigated, &.{ .frame_id = 0, .req_id = 1, .timestamp = 1000, .url = undefined, .opts = .{} });
+        try testing.expectEqual(114, tc.page_navigate);
+        try testing.expectEqual(2006, tc.page_navigated);
+
+        // already unregistered, try anyways
+        notifier.unregister(.page_navigated, &tc);
+        notifier.dispatch(.page_navigate, &.{ .frame_id = 0, .req_id = 1, .timestamp = 100, .url = undefined, .opts = .{} });
+        notifier.dispatch(.page_navigated, &.{ .frame_id = 0, .req_id = 1, .timestamp = 1000, .url = undefined, .opts = .{} });
+        try testing.expectEqual(114, tc.page_navigate);
+        try testing.expectEqual(2006, tc.page_navigated);
+    }
+}
+
+const TestClient = struct {
+    page_navigate: u64 = 0,
+    page_navigated: u64 = 0,
+
+    fn pageNavigate(ptr: *anyopaque, data: *const Notification.PageNavigate) !void {
+        const self: *TestClient = @ptrCast(@alignCast(ptr));
+        self.page_navigate += data.timestamp;
+    }
+
+    fn pageNavigated(ptr: *anyopaque, data: *const Notification.PageNavigated) !void {
+        const self: *TestClient = @ptrCast(@alignCast(ptr));
+        self.page_navigated += data.timestamp;
+    }
+};

src/SemanticTree.zig

@@ -0,0 +1,563 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  See <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+
+const lp = @import("lightpanda");
+const log = @import("log.zig");
+const isAllWhitespace = @import("string.zig").isAllWhitespace;
+const Page = lp.Page;
+const interactive = @import("browser/interactive.zig");
+
+const CData = @import("browser/webapi/CData.zig");
+const Element = @import("browser/webapi/Element.zig");
+const Node = @import("browser/webapi/Node.zig");
+const AXNode = @import("cdp/AXNode.zig");
+const CDPNode = @import("cdp/Node.zig");
+
+const Self = @This();
+
+dom_node: *Node,
+registry: *CDPNode.Registry,
+page: *Page,
+arena: std.mem.Allocator,
+prune: bool = true,
+interactive_only: bool = false,
+max_depth: u32 = std.math.maxInt(u32) - 1,
+
+pub fn jsonStringify(self: @This(), jw: *std.json.Stringify) error{WriteFailed}!void {
+    var visitor = JsonVisitor{ .jw = jw, .tree = self };
+    var xpath_buffer: std.ArrayList(u8) = .{};
+    const listener_targets = interactive.buildListenerTargetMap(self.page, self.arena) catch |err| {
+        log.err(.app, "listener map failed", .{ .err = err });
+        return error.WriteFailed;
+    };
+    var visibility_cache: Element.VisibilityCache = .empty;
+    var pointer_events_cache: Element.PointerEventsCache = .empty;
+    var ctx: WalkContext = .{
+        .xpath_buffer = &xpath_buffer,
+        .listener_targets = listener_targets,
+        .visibility_cache = &visibility_cache,
+        .pointer_events_cache = &pointer_events_cache,
+    };
+    self.walk(&ctx, self.dom_node, null, &visitor, 1, 0) catch |err| {
+        log.err(.app, "semantic tree json dump failed", .{ .err = err });
+        return error.WriteFailed;
+    };
+}
+
+pub fn textStringify(self: @This(), writer: *std.Io.Writer) error{WriteFailed}!void {
+    var visitor = TextVisitor{ .writer = writer, .tree = self, .depth = 0 };
+    var xpath_buffer: std.ArrayList(u8) = .empty;
+    const listener_targets = interactive.buildListenerTargetMap(self.page, self.arena) catch |err| {
+        log.err(.app, "listener map failed", .{ .err = err });
+        return error.WriteFailed;
+    };
+    var visibility_cache: Element.VisibilityCache = .empty;
+    var pointer_events_cache: Element.PointerEventsCache = .empty;
+    var ctx: WalkContext = .{
+        .xpath_buffer = &xpath_buffer,
+        .listener_targets = listener_targets,
+        .visibility_cache = &visibility_cache,
+        .pointer_events_cache = &pointer_events_cache,
+    };
+    self.walk(&ctx, self.dom_node, null, &visitor, 1, 0) catch |err| {
+        log.err(.app, "semantic tree text dump failed", .{ .err = err });
+        return error.WriteFailed;
+    };
+}
+
+const OptionData = struct {
+    value: []const u8,
+    text: []const u8,
+    selected: bool,
+};
+
+const NodeData = struct {
+    id: CDPNode.Id,
+    axn: AXNode,
+    role: []const u8,
+    name: ?[]const u8,
+    value: ?[]const u8,
+    options: ?[]OptionData = null,
+    xpath: []const u8,
+    is_interactive: bool,
+    node_name: []const u8,
+};
+
+const WalkContext = struct {
+    xpath_buffer: *std.ArrayList(u8),
+    listener_targets: interactive.ListenerTargetMap,
+    visibility_cache: *Element.VisibilityCache,
+    pointer_events_cache: *Element.PointerEventsCache,
+};
+
+fn walk(
+    self: @This(),
+    ctx: *WalkContext,
+    node: *Node,
+    parent_name: ?[]const u8,
+    visitor: anytype,
+    index: usize,
+    current_depth: u32,
+) !void {
+    if (current_depth > self.max_depth) return;
+
+    // 1. Skip non-content nodes
+    if (node.is(Element)) |el| {
+        const tag = el.getTag();
+        if (tag.isMetadata() or tag == .svg) return;
+
+        // We handle options/optgroups natively inside their parents, skip them in the general walk
+        if (tag == .datalist or tag == .option or tag == .optgroup) return;
+
+        // Check visibility using the engine's checkVisibility which handles CSS display: none
+        if (!el.checkVisibilityCached(ctx.visibility_cache, self.page)) {
+            return;
+        }
+
+        if (el.is(Element.Html)) |html_el| {
+            if (html_el.getHidden()) return;
+        }
+    } else if (node.is(CData.Text)) |text_node| {
+        const text = text_node.getWholeText();
+        if (isAllWhitespace(text)) {
+            return;
+        }
+    } else if (node._type != .document and node._type != .document_fragment) {
+        return;
+    }
+
+    const cdp_node = try self.registry.register(node);
+    const axn = AXNode.fromNode(node);
+    const role = try axn.getRole();
+
+    var is_interactive = false;
+    var value: ?[]const u8 = null;
+    var options: ?[]OptionData = null;
+    var node_name: []const u8 = "text";
+
+    if (node.is(Element)) |el| {
+        node_name = el.getTagNameLower();
+
+        if (el.is(Element.Html.Input)) |input| {
+            value = input.getValue();
+            if (el.getAttributeSafe(comptime lp.String.wrap("list"))) |list_id| {
+                options = try extractDataListOptions(list_id, self.page, self.arena);
+            }
+        } else if (el.is(Element.Html.TextArea)) |textarea| {
+            value = textarea.getValue();
+        } else if (el.is(Element.Html.Select)) |select| {
+            value = select.getValue(self.page);
+            options = try extractSelectOptions(el.asNode(), self.page, self.arena);
+        }
+
+        if (el.is(Element.Html)) |html_el| {
+            if (interactive.classifyInteractivity(self.page, el, html_el, ctx.listener_targets, ctx.pointer_events_cache) != null) {
+                is_interactive = true;
+            }
+        }
+    } else if (node._type == .document or node._type == .document_fragment) {
+        node_name = "root";
+    }
+
+    const initial_xpath_len = ctx.xpath_buffer.items.len;
+    try appendXPathSegment(node, ctx.xpath_buffer.writer(self.arena), index);
+    const xpath = ctx.xpath_buffer.items;
+
+    var name = try axn.getName(self.page, self.arena);
+
+    const has_explicit_label = if (node.is(Element)) |el|
+        el.getAttributeSafe(.wrap("aria-label")) != null or el.getAttributeSafe(.wrap("title")) != null
+    else
+        false;
+
+    const structural = isStructuralRole(role);
+
+    // Filter out computed concatenated names for generic containers without explicit labels.
+    // This prevents token bloat and ensures their StaticText children aren't incorrectly pruned.
+    // We ignore interactivity because a generic wrapper with an event listener still shouldn't hoist all text.
+    if (name != null and structural and !has_explicit_label) {
+        name = null;
+    }
+
+    var should_visit = true;
+    if (self.interactive_only) {
+        var keep = false;
+        if (interactive.isInteractiveRole(role)) {
+            keep = true;
+        } else if (interactive.isContentRole(role)) {
+            if (name != null and name.?.len > 0) {
+                keep = true;
+            }
+        } else if (std.mem.eql(u8, role, "RootWebArea")) {
+            keep = true;
+        } else if (is_interactive) {
+            keep = true;
+        }
+        if (!keep) {
+            should_visit = false;
+        }
+    } else if (self.prune) {
+        if (structural and !is_interactive and !has_explicit_label) {
+            should_visit = false;
+        }
+
+        if (std.mem.eql(u8, role, "StaticText") and node._parent != null) {
+            if (parent_name != null and name != null and std.mem.indexOf(u8, parent_name.?, name.?) != null) {
+                should_visit = false;
+            }
+        }
+    }
+
+    var did_visit = false;
+    var should_walk_children = true;
+    var data: NodeData = .{
+        .id = cdp_node.id,
+        .axn = axn,
+        .role = role,
+        .name = name,
+        .value = value,
+        .options = options,
+        .xpath = xpath,
+        .is_interactive = is_interactive,
+        .node_name = node_name,
+    };
+
+    if (should_visit) {
+        should_walk_children = try visitor.visit(node, &data);
+        did_visit = true; // Always true if should_visit was true, because visit() executed and opened structures
+    } else {
+        // If we skip the node, we must NOT tell the visitor to close it later
+        did_visit = false;
+    }
+
+    if (should_walk_children) {
+        // If we are printing this node normally OR skipping it and unrolling its children,
+        // we walk the children iterator.
+        var it = node.childrenIterator();
+        var tag_counts = std.StringArrayHashMap(usize).init(self.arena);
+        while (it.next()) |child| {
+            var tag: []const u8 = "text()";
+            if (child.is(Element)) |el| {
+                tag = el.getTagNameLower();
+            }
+
+            const gop = try tag_counts.getOrPut(tag);
+            if (!gop.found_existing) {
+                gop.value_ptr.* = 0;
+            }
+            gop.value_ptr.* += 1;
+
+            try self.walk(ctx, child, name, visitor, gop.value_ptr.*, current_depth + 1);
+        }
+    }
+
+    if (did_visit) {
+        try visitor.leave();
+    }
+
+    ctx.xpath_buffer.shrinkRetainingCapacity(initial_xpath_len);
+}
+
+fn extractSelectOptions(node: *Node, page: *Page, arena: std.mem.Allocator) ![]OptionData {
+    var options: std.ArrayList(OptionData) = .empty;
+    var it = node.childrenIterator();
+    while (it.next()) |child| {
+        if (child.is(Element)) |el| {
+            if (el.getTag() == .option) {
+                if (el.is(Element.Html.Option)) |opt| {
+                    const text = opt.getText(page);
+                    const value = opt.getValue(page);
+                    const selected = opt.getSelected();
+                    try options.append(arena, .{ .text = text, .value = value, .selected = selected });
+                }
+            } else if (el.getTag() == .optgroup) {
+                var group_it = child.childrenIterator();
+                while (group_it.next()) |group_child| {
+                    if (group_child.is(Element.Html.Option)) |opt| {
+                        const text = opt.getText(page);
+                        const value = opt.getValue(page);
+                        const selected = opt.getSelected();
+                        try options.append(arena, .{ .text = text, .value = value, .selected = selected });
+                    }
+                }
+            }
+        }
+    }
+    return options.toOwnedSlice(arena);
+}
+
+fn extractDataListOptions(list_id: []const u8, page: *Page, arena: std.mem.Allocator) !?[]OptionData {
+    if (page.document.getElementById(list_id, page)) |referenced_el| {
+        if (referenced_el.getTag() == .datalist) {
+            return try extractSelectOptions(referenced_el.asNode(), page, arena);
+        }
+    }
+    return null;
+}
+
+fn appendXPathSegment(node: *Node, writer: anytype, index: usize) !void {
+    if (node.is(Element)) |el| {
+        const tag = el.getTagNameLower();
+        try std.fmt.format(writer, "/{s}[{d}]", .{ tag, index });
+    } else if (node.is(CData.Text)) |_| {
+        try std.fmt.format(writer, "/text()[{d}]", .{index});
+    }
+}
+
+const JsonVisitor = struct {
+    jw: *std.json.Stringify,
+    tree: Self,
+
+    pub fn visit(self: *JsonVisitor, node: *Node, data: *NodeData) !bool {
+        try self.jw.beginObject();
+
+        try self.jw.objectField("nodeId");
+        try self.jw.write(try std.fmt.allocPrint(self.tree.arena, "{d}", .{data.id}));
+
+        try self.jw.objectField("backendDOMNodeId");
+        try self.jw.write(data.id);
+
+        try self.jw.objectField("nodeName");
+        try self.jw.write(data.node_name);
+
+        try self.jw.objectField("xpath");
+        try self.jw.write(data.xpath);
+
+        if (node.is(Element)) |el| {
+            try self.jw.objectField("nodeType");
+            try self.jw.write(1);
+
+            try self.jw.objectField("isInteractive");
+            try self.jw.write(data.is_interactive);
+
+            try self.jw.objectField("role");
+            try self.jw.write(data.role);
+
+            if (data.name) |name| {
+                if (name.len > 0) {
+                    try self.jw.objectField("name");
+                    try self.jw.write(name);
+                }
+            }
+
+            if (data.value) |value| {
+                try self.jw.objectField("value");
+                try self.jw.write(value);
+            }
+
+            if (el._attributes) |attrs| {
+                try self.jw.objectField("attributes");
+                try self.jw.beginObject();
+                var iter = attrs.iterator();
+                while (iter.next()) |attr| {
+                    try self.jw.objectField(attr._name.str());
+                    try self.jw.write(attr._value.str());
+                }
+                try self.jw.endObject();
+            }
+
+            if (data.options) |options| {
+                try self.jw.objectField("options");
+                try self.jw.beginArray();
+                for (options) |opt| {
+                    try self.jw.beginObject();
+                    try self.jw.objectField("value");
+                    try self.jw.write(opt.value);
+                    try self.jw.objectField("text");
+                    try self.jw.write(opt.text);
+                    try self.jw.objectField("selected");
+                    try self.jw.write(opt.selected);
+                    try self.jw.endObject();
+                }
+                try self.jw.endArray();
+            }
+        } else if (node.is(CData.Text)) |text_node| {
+            try self.jw.objectField("nodeType");
+            try self.jw.write(3);
+            try self.jw.objectField("nodeValue");
+            try self.jw.write(text_node.getWholeText());
+        } else {
+            try self.jw.objectField("nodeType");
+            try self.jw.write(9);
+        }
+
+        try self.jw.objectField("children");
+        try self.jw.beginArray();
+
+        if (data.options != null) {
+            // Signal to not walk children, as we handled them natively
+            return false;
+        }
+
+        return true;
+    }
+
+    pub fn leave(self: *JsonVisitor) !void {
+        try self.jw.endArray();
+        try self.jw.endObject();
+    }
+};
+
+fn isStructuralRole(role: []const u8) bool {
+    const structural_roles = std.StaticStringMap(void).initComptime(.{
+        .{ "none", {} },
+        .{ "generic", {} },
+        .{ "InlineTextBox", {} },
+        .{ "banner", {} },
+        .{ "navigation", {} },
+        .{ "main", {} },
+        .{ "list", {} },
+        .{ "listitem", {} },
+        .{ "table", {} },
+        .{ "rowgroup", {} },
+        .{ "row", {} },
+        .{ "cell", {} },
+        .{ "region", {} },
+    });
+    return structural_roles.has(role);
+}
+
+const TextVisitor = struct {
+    writer: *std.Io.Writer,
+    tree: Self,
+    depth: usize,
+
+    pub fn visit(self: *TextVisitor, node: *Node, data: *NodeData) !bool {
+        for (0..self.depth) |_| {
+            try self.writer.writeByte(' ');
+        }
+
+        var name_to_print: ?[]const u8 = null;
+        if (data.name) |n| {
+            if (n.len > 0) {
+                name_to_print = n;
+            }
+        } else if (node.is(CData.Text)) |text_node| {
+            const trimmed = std.mem.trim(u8, text_node.getWholeText(), " \t\r\n");
+            if (trimmed.len > 0) {
+                name_to_print = trimmed;
+            }
+        }
+
+        const is_text_only = std.mem.eql(u8, data.role, "StaticText") or std.mem.eql(u8, data.role, "none") or std.mem.eql(u8, data.role, "generic");
+
+        try self.writer.print("{d}", .{data.id});
+        if (!is_text_only) {
+            try self.writer.print(" {s}", .{data.role});
+        }
+        if (name_to_print) |n| {
+            try self.writer.print(" '{s}'", .{n});
+        }
+
+        if (data.value) |v| {
+            if (v.len > 0) {
+                try self.writer.print(" value='{s}'", .{v});
+            }
+        }
+
+        if (data.options) |options| {
+            try self.writer.writeAll(" options=[");
+            for (options, 0..) |opt, i| {
+                if (i > 0) try self.writer.writeAll(",");
+                try self.writer.print("'{s}'", .{opt.value});
+                if (opt.selected) {
+                    try self.writer.writeAll("*");
+                }
+            }
+            try self.writer.writeAll("]\n");
+            self.depth += 1;
+            return false; // Native handling complete, do not walk children
+        }
+
+        try self.writer.writeByte('\n');
+        self.depth += 1;
+
+        // If this is a leaf-like semantic node and we already have a name,
+        // skip children to avoid redundant StaticText or noise.
+        const is_leaf_semantic = std.mem.eql(u8, data.role, "link") or
+            std.mem.eql(u8, data.role, "button") or
+            std.mem.eql(u8, data.role, "heading") or
+            std.mem.eql(u8, data.role, "code");
+        if (is_leaf_semantic and data.name != null and data.name.?.len > 0) {
+            return false;
+        }
+
+        return true;
+    }
+
+    pub fn leave(self: *TextVisitor) !void {
+        if (self.depth > 0) {
+            self.depth -= 1;
+        }
+    }
+};
+
+const testing = @import("testing.zig");
+
+test "SemanticTree backendDOMNodeId" {
+    var registry: CDPNode.Registry = .init(testing.allocator);
+    defer registry.deinit();
+
+    var page = try testing.pageTest("cdp/registry1.html");
+    defer testing.reset();
+    defer page._session.removePage();
+
+    const st: Self = .{
+        .dom_node = page.window._document.asNode(),
+        .registry = &registry,
+        .page = page,
+        .arena = testing.arena_allocator,
+        .prune = false,
+        .interactive_only = false,
+        .max_depth = std.math.maxInt(u32) - 1,
+    };
+
+    const json_str = try std.json.Stringify.valueAlloc(testing.allocator, st, .{});
+    defer testing.allocator.free(json_str);
+
+    try testing.expect(std.mem.indexOf(u8, json_str, "\"backendDOMNodeId\":") != null);
+}
+
+test "SemanticTree max_depth" {
+    var registry: CDPNode.Registry = .init(testing.allocator);
+    defer registry.deinit();
+
+    var page = try testing.pageTest("cdp/registry1.html");
+    defer testing.reset();
+    defer page._session.removePage();
+
+    const st: Self = .{
+        .dom_node = page.window._document.asNode(),
+        .registry = &registry,
+        .page = page,
+        .arena = testing.arena_allocator,
+        .prune = false,
+        .interactive_only = false,
+        .max_depth = 1,
+    };
+
+    var aw: std.Io.Writer.Allocating = .init(testing.allocator);
+    defer aw.deinit();
+
+    try st.textStringify(&aw.writer);
+    const text_str = aw.written();
+
+    try testing.expect(std.mem.indexOf(u8, text_str, "other") == null);
+}

src/Server.zig

@@ -0,0 +1,945 @@
+// Copyright (C) 2023-2025 Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const lp = @import("lightpanda");
+const net = std.net;
+const posix = std.posix;
+
+const Allocator = std.mem.Allocator;
+const ArenaAllocator = std.heap.ArenaAllocator;
+
+const log = @import("log.zig");
+const App = @import("App.zig");
+const Config = @import("Config.zig");
+const CDP = @import("cdp/cdp.zig").CDP;
+const Net = @import("network/websocket.zig");
+const HttpClient = @import("browser/HttpClient.zig");
+
+const Server = @This();
+
+app: *App,
+allocator: Allocator,
+json_version_response: []const u8,
+
+// Thread management
+active_threads: std.atomic.Value(u32) = .init(0),
+clients: std.ArrayList(*Client) = .{},
+client_mutex: std.Thread.Mutex = .{},
+clients_pool: std.heap.MemoryPool(Client),
+
+pub fn init(app: *App, address: net.Address) !*Server {
+    const allocator = app.allocator;
+    const json_version_response = try buildJSONVersionResponse(app);
+    errdefer allocator.free(json_version_response);
+
+    const self = try allocator.create(Server);
+    errdefer allocator.destroy(self);
+
+    self.* = .{
+        .app = app,
+        .allocator = allocator,
+        .json_version_response = json_version_response,
+        .clients_pool = std.heap.MemoryPool(Client).init(allocator),
+    };
+
+    try self.app.network.bind(address, self, onAccept);
+    log.info(.app, "server running", .{ .address = address });
+
+    return self;
+}
+
+pub fn shutdown(self: *Server) void {
+    self.client_mutex.lock();
+    defer self.client_mutex.unlock();
+
+    for (self.clients.items) |client| {
+        client.stop();
+    }
+}
+
+pub fn deinit(self: *Server) void {
+    self.shutdown();
+    self.joinThreads();
+    self.clients.deinit(self.allocator);
+    self.clients_pool.deinit();
+    self.allocator.free(self.json_version_response);
+    self.allocator.destroy(self);
+}
+
+fn onAccept(ctx: *anyopaque, socket: posix.socket_t) void {
+    const self: *Server = @ptrCast(@alignCast(ctx));
+    const timeout_ms: u32 = @intCast(self.app.config.cdpTimeout());
+    self.spawnWorker(socket, timeout_ms) catch |err| {
+        log.err(.app, "CDP spawn", .{ .err = err });
+        posix.close(socket);
+    };
+}
+
+fn handleConnection(self: *Server, socket: posix.socket_t, timeout_ms: u32) void {
+    defer posix.close(socket);
+
+    // Client is HUGE (> 512KB) because it has a large read buffer.
+    // V8 crashes if this is on the stack (likely related to its size).
+    const client = self.getClient() catch |err| {
+        log.err(.app, "CDP client create", .{ .err = err });
+        return;
+    };
+    defer self.releaseClient(client);
+
+    client.* = Client.init(
+        socket,
+        self.allocator,
+        self.app,
+        self.json_version_response,
+        timeout_ms,
+    ) catch |err| {
+        log.err(.app, "CDP client init", .{ .err = err });
+        return;
+    };
+    defer client.deinit();
+
+    self.registerClient(client);
+    defer self.unregisterClient(client);
+
+    // Check shutdown after registering to avoid missing the stop signal.
+    // If deinit() already iterated over clients, this client won't receive stop()
+    // and would block joinThreads() indefinitely.
+    if (self.app.shutdown()) {
+        return;
+    }
+
+    client.start();
+}
+
+fn getClient(self: *Server) !*Client {
+    self.client_mutex.lock();
+    defer self.client_mutex.unlock();
+    return self.clients_pool.create();
+}
+
+fn releaseClient(self: *Server, client: *Client) void {
+    self.client_mutex.lock();
+    defer self.client_mutex.unlock();
+    self.clients_pool.destroy(client);
+}
+
+fn registerClient(self: *Server, client: *Client) void {
+    self.client_mutex.lock();
+    defer self.client_mutex.unlock();
+    self.clients.append(self.allocator, client) catch {};
+}
+
+fn unregisterClient(self: *Server, client: *Client) void {
+    self.client_mutex.lock();
+    defer self.client_mutex.unlock();
+    for (self.clients.items, 0..) |c, i| {
+        if (c == client) {
+            _ = self.clients.swapRemove(i);
+            break;
+        }
+    }
+}
+
+fn spawnWorker(self: *Server, socket: posix.socket_t, timeout_ms: u32) !void {
+    if (self.app.shutdown()) {
+        return error.ShuttingDown;
+    }
+
+    // Atomically increment active_threads only if below max_connections.
+    // Uses CAS loop to avoid race between checking the limit and incrementing.
+    //
+    // cmpxchgWeak may fail for two reasons:
+    // 1. Another thread changed the value (increment or decrement)
+    // 2. Spurious failure on some architectures (e.g. ARM)
+    //
+    // We use Weak instead of Strong because we need a retry loop anyway:
+    // if CAS fails because a thread finished (counter decreased), we should
+    // retry rather than return an error - there may now be room for a new connection.
+    //
+    // On failure, cmpxchgWeak returns the actual value, which we reuse to avoid
+    // an extra load on the next iteration.
+    const max_connections = self.app.config.maxConnections();
+    var current = self.active_threads.load(.monotonic);
+    while (current < max_connections) {
+        current = self.active_threads.cmpxchgWeak(current, current + 1, .monotonic, .monotonic) orelse break;
+    } else {
+        return error.MaxThreadsReached;
+    }
+    errdefer _ = self.active_threads.fetchSub(1, .monotonic);
+
+    const thread = try std.Thread.spawn(.{}, runWorker, .{ self, socket, timeout_ms });
+    thread.detach();
+}
+
+fn runWorker(self: *Server, socket: posix.socket_t, timeout_ms: u32) void {
+    defer _ = self.active_threads.fetchSub(1, .monotonic);
+    handleConnection(self, socket, timeout_ms);
+}
+
+fn joinThreads(self: *Server) void {
+    while (self.active_threads.load(.monotonic) > 0) {
+        std.Thread.sleep(10 * std.time.ns_per_ms);
+    }
+}
+
+// Handle exactly one TCP connection.
+pub const Client = struct {
+    // The client is initially serving HTTP requests but, under normal circumstances
+    // should eventually be upgraded to a websocket connections
+    mode: union(enum) {
+        http: void,
+        cdp: CDP,
+    },
+
+    allocator: Allocator,
+    app: *App,
+    http: *HttpClient,
+    ws: Net.WsConnection,
+
+    fn init(
+        socket: posix.socket_t,
+        allocator: Allocator,
+        app: *App,
+        json_version_response: []const u8,
+        timeout_ms: u32,
+    ) !Client {
+        var ws = try Net.WsConnection.init(socket, allocator, json_version_response, timeout_ms);
+        errdefer ws.deinit();
+
+        if (log.enabled(.app, .info)) {
+            const client_address = ws.getAddress() catch null;
+            log.info(.app, "client connected", .{ .ip = client_address });
+        }
+
+        const http = try HttpClient.init(allocator, &app.network);
+        errdefer http.deinit();
+
+        return .{
+            .allocator = allocator,
+            .app = app,
+            .http = http,
+            .ws = ws,
+            .mode = .{ .http = {} },
+        };
+    }
+
+    fn stop(self: *Client) void {
+        switch (self.mode) {
+            .http => {},
+            .cdp => |*cdp| {
+                cdp.browser.env.terminate();
+                self.ws.sendClose();
+            },
+        }
+        self.ws.shutdown();
+    }
+
+    fn deinit(self: *Client) void {
+        switch (self.mode) {
+            .cdp => |*cdp| cdp.deinit(),
+            .http => {},
+        }
+        self.ws.deinit();
+        self.http.deinit();
+    }
+
+    fn start(self: *Client) void {
+        const http = self.http;
+        http.cdp_client = .{
+            .socket = self.ws.socket,
+            .ctx = self,
+            .blocking_read_start = Client.blockingReadStart,
+            .blocking_read = Client.blockingRead,
+            .blocking_read_end = Client.blockingReadStop,
+        };
+        defer http.cdp_client = null;
+
+        self.httpLoop(http) catch |err| {
+            log.err(.app, "CDP client loop", .{ .err = err });
+        };
+    }
+
+    fn httpLoop(self: *Client, http: *HttpClient) !void {
+        lp.assert(self.mode == .http, "Client.httpLoop invalid mode", .{});
+
+        while (true) {
+            const status = http.tick(self.ws.timeout_ms) catch |err| {
+                log.err(.app, "http tick", .{ .err = err });
+                return;
+            };
+            if (status != .cdp_socket) {
+                log.info(.app, "CDP timeout", .{});
+                return;
+            }
+
+            if (self.readSocket() == false) {
+                return;
+            }
+
+            if (self.mode == .cdp) {
+                break;
+            }
+        }
+
+        var cdp = &self.mode.cdp;
+        var last_message = milliTimestamp(.monotonic);
+        var ms_remaining = self.ws.timeout_ms;
+
+        while (true) {
+            const result = cdp.pageWait(ms_remaining) catch |wait_err| switch (wait_err) {
+                error.NoPage => {
+                    const status = http.tick(ms_remaining) catch |err| {
+                        log.err(.app, "http tick", .{ .err = err });
+                        return;
+                    };
+                    if (status != .cdp_socket) {
+                        log.info(.app, "CDP timeout", .{});
+                        return;
+                    }
+                    if (self.readSocket() == false) {
+                        return;
+                    }
+                    last_message = milliTimestamp(.monotonic);
+                    ms_remaining = self.ws.timeout_ms;
+                    continue;
+                },
+                else => return wait_err,
+            };
+
+            switch (result) {
+                .cdp_socket => {
+                    if (self.readSocket() == false) {
+                        return;
+                    }
+                    last_message = milliTimestamp(.monotonic);
+                    ms_remaining = self.ws.timeout_ms;
+                },
+                .done => {
+                    const now = milliTimestamp(.monotonic);
+                    const elapsed = now - last_message;
+                    if (elapsed >= ms_remaining) {
+                        log.info(.app, "CDP timeout", .{});
+                        return;
+                    }
+                    ms_remaining -= @intCast(elapsed);
+                    last_message = now;
+                },
+            }
+        }
+    }
+
+    fn blockingReadStart(ctx: *anyopaque) bool {
+        const self: *Client = @ptrCast(@alignCast(ctx));
+        self.ws.setBlocking(true) catch |err| {
+            log.warn(.app, "CDP blockingReadStart", .{ .err = err });
+            return false;
+        };
+        return true;
+    }
+
+    fn blockingRead(ctx: *anyopaque) bool {
+        const self: *Client = @ptrCast(@alignCast(ctx));
+        return self.readSocket();
+    }
+
+    fn blockingReadStop(ctx: *anyopaque) bool {
+        const self: *Client = @ptrCast(@alignCast(ctx));
+        self.ws.setBlocking(false) catch |err| {
+            log.warn(.app, "CDP blockingReadStop", .{ .err = err });
+            return false;
+        };
+        return true;
+    }
+
+    fn readSocket(self: *Client) bool {
+        const n = self.ws.read() catch |err| {
+            log.warn(.app, "CDP read", .{ .err = err });
+            return false;
+        };
+
+        if (n == 0) {
+            log.info(.app, "CDP disconnect", .{});
+            return false;
+        }
+
+        return self.processData() catch false;
+    }
+
+    fn processData(self: *Client) !bool {
+        switch (self.mode) {
+            .cdp => |*cdp| return self.processWebsocketMessage(cdp),
+            .http => return self.processHTTPRequest(),
+        }
+    }
+
+    fn processHTTPRequest(self: *Client) !bool {
+        lp.assert(self.ws.reader.pos == 0, "Client.HTTP pos", .{ .pos = self.ws.reader.pos });
+        const request = self.ws.reader.buf[0..self.ws.reader.len];
+
+        if (request.len > Config.CDP_MAX_HTTP_REQUEST_SIZE) {
+            self.writeHTTPErrorResponse(413, "Request too large");
+            return error.RequestTooLarge;
+        }
+
+        // we're only expecting [body-less] GET requests.
+        if (std.mem.endsWith(u8, request, "\r\n\r\n") == false) {
+            // we need more data, put any more data here
+            return true;
+        }
+
+        // the next incoming data can go to the front of our buffer
+        defer self.ws.reader.len = 0;
+        return self.handleHTTPRequest(request) catch |err| {
+            switch (err) {
+                error.NotFound => self.writeHTTPErrorResponse(404, "Not found"),
+                error.InvalidRequest => self.writeHTTPErrorResponse(400, "Invalid request"),
+                error.InvalidProtocol => self.writeHTTPErrorResponse(400, "Invalid HTTP protocol"),
+                error.MissingHeaders => self.writeHTTPErrorResponse(400, "Missing required header"),
+                error.InvalidUpgradeHeader => self.writeHTTPErrorResponse(400, "Unsupported upgrade type"),
+                error.InvalidVersionHeader => self.writeHTTPErrorResponse(400, "Invalid websocket version"),
+                error.InvalidConnectionHeader => self.writeHTTPErrorResponse(400, "Invalid connection header"),
+                else => {
+                    log.err(.app, "server 500", .{ .err = err, .req = request[0..@min(100, request.len)] });
+                    self.writeHTTPErrorResponse(500, "Internal Server Error");
+                },
+            }
+            return err;
+        };
+    }
+
+    fn handleHTTPRequest(self: *Client, request: []u8) !bool {
+        if (request.len < 18) {
+            // 18 is [generously] the smallest acceptable HTTP request
+            return error.InvalidRequest;
+        }
+
+        if (std.mem.eql(u8, request[0..4], "GET ") == false) {
+            return error.NotFound;
+        }
+
+        const url_end = std.mem.indexOfScalarPos(u8, request, 4, ' ') orelse {
+            return error.InvalidRequest;
+        };
+
+        const url = request[4..url_end];
+
+        if (std.mem.eql(u8, url, "/")) {
+            try self.upgradeConnection(request);
+            return true;
+        }
+
+        if (std.mem.eql(u8, url, "/json/version") or std.mem.eql(u8, url, "/json/version/")) {
+            try self.ws.send(self.ws.json_version_response);
+            // Chromedp (a Go driver) does an http request to /json/version
+            // then to / (websocket upgrade) using a different connection.
+            // Since we only allow 1 connection at a time, the 2nd one (the
+            // websocket upgrade) blocks until the first one times out.
+            // We can avoid that by closing the connection. json_version_response
+            // has a Connection: Close header too.
+            self.ws.shutdown();
+            return false;
+        }
+
+        return error.NotFound;
+    }
+
+    fn upgradeConnection(self: *Client, request: []u8) !void {
+        try self.ws.upgrade(request);
+        self.mode = .{ .cdp = try CDP.init(self.app, self.http, self) };
+    }
+
+    fn writeHTTPErrorResponse(self: *Client, comptime status: u16, comptime body: []const u8) void {
+        self.ws.sendHttpError(status, body);
+    }
+
+    fn processWebsocketMessage(self: *Client, cdp: *CDP) !bool {
+        return self.ws.processMessages(cdp);
+    }
+
+    pub fn sendAllocator(self: *Client) Allocator {
+        return self.ws.send_arena.allocator();
+    }
+
+    pub fn sendJSON(self: *Client, message: anytype, opts: std.json.Stringify.Options) !void {
+        return self.ws.sendJSON(message, opts);
+    }
+
+    pub fn sendJSONRaw(self: *Client, buf: std.ArrayList(u8)) !void {
+        return self.ws.sendJSONRaw(buf);
+    }
+};
+
+// Utils
+// --------
+
+fn buildJSONVersionResponse(
+    app: *const App,
+) ![]const u8 {
+    const port = app.config.port();
+    const host = app.config.advertiseHost();
+    if (std.mem.eql(u8, host, "0.0.0.0")) {
+        log.info(.cdp, "unreachable advertised host", .{
+            .message = "when --host is set to 0.0.0.0 consider setting --advertise-host to a reachable address",
+        });
+    }
+    const body_format = "{{\"webSocketDebuggerUrl\": \"ws://{s}:{d}/\"}}";
+    const body_len = std.fmt.count(body_format, .{ host, port });
+
+    // We send a Connection: Close (and actually close the connection)
+    // because chromedp (Go driver) sends a request to /json/version and then
+    // does an upgrade request, on a different connection. Since we only allow
+    // 1 connection at a time, the upgrade connection doesn't proceed until we
+    // timeout the /json/version. So, instead of waiting for that, we just
+    // always close HTTP requests.
+    const response_format =
+        "HTTP/1.1 200 OK\r\n" ++
+        "Content-Length: {d}\r\n" ++
+        "Connection: Close\r\n" ++
+        "Content-Type: application/json; charset=UTF-8\r\n\r\n" ++
+        body_format;
+    return try std.fmt.allocPrint(app.allocator, response_format, .{ body_len, host, port });
+}
+
+pub const timestamp = @import("datetime.zig").timestamp;
+pub const milliTimestamp = @import("datetime.zig").milliTimestamp;
+
+const testing = @import("testing.zig");
+test "server: buildJSONVersionResponse" {
+    const res = try buildJSONVersionResponse(testing.test_app);
+    defer testing.test_app.allocator.free(res);
+
+    try testing.expectEqual("HTTP/1.1 200 OK\r\n" ++
+        "Content-Length: 48\r\n" ++
+        "Connection: Close\r\n" ++
+        "Content-Type: application/json; charset=UTF-8\r\n\r\n" ++
+        "{\"webSocketDebuggerUrl\": \"ws://127.0.0.1:9222/\"}", res);
+}
+
+test "Client: http invalid request" {
+    var c = try createTestClient();
+    defer c.deinit();
+
+    const res = try c.httpRequest("GET /over/9000 HTTP/1.1\r\n" ++ "Header: " ++ ("a" ** 4100) ++ "\r\n\r\n");
+    try testing.expectEqual("HTTP/1.1 413 \r\n" ++
+        "Connection: Close\r\n" ++
+        "Content-Length: 17\r\n\r\n" ++
+        "Request too large", res);
+}
+
+test "Client: http invalid handshake" {
+    try assertHTTPError(
+        400,
+        "Invalid request",
+        "\r\n\r\n",
+    );
+
+    try assertHTTPError(
+        404,
+        "Not found",
+        "GET /over/9000 HTTP/1.1\r\n\r\n",
+    );
+
+    try assertHTTPError(
+        404,
+        "Not found",
+        "POST / HTTP/1.1\r\n\r\n",
+    );
+
+    try assertHTTPError(
+        400,
+        "Invalid HTTP protocol",
+        "GET / HTTP/1.0\r\n\r\n",
+    );
+
+    try assertHTTPError(
+        400,
+        "Missing required header",
+        "GET / HTTP/1.1\r\n\r\n",
+    );
+
+    try assertHTTPError(
+        400,
+        "Missing required header",
+        "GET / HTTP/1.1\r\nConnection:  upgrade\r\n\r\n",
+    );
+
+    try assertHTTPError(
+        400,
+        "Missing required header",
+        "GET / HTTP/1.1\r\nConnection: upgrade\r\nUpgrade: websocket\r\n\r\n",
+    );
+
+    try assertHTTPError(
+        400,
+        "Missing required header",
+        "GET / HTTP/1.1\r\nConnection: upgrade\r\nUpgrade: websocket\r\nsec-websocket-version:13\r\n\r\n",
+    );
+}
+
+test "Client: http valid handshake" {
+    var c = try createTestClient();
+    defer c.deinit();
+
+    const request =
+        "GET /   HTTP/1.1\r\n" ++
+        "Connection: upgrade\r\n" ++
+        "Upgrade: websocket\r\n" ++
+        "sec-websocket-version:13\r\n" ++
+        "sec-websocket-key: this is my key\r\n" ++
+        "Custom:  Header-Value\r\n\r\n";
+
+    const res = try c.httpRequest(request);
+    try testing.expectEqual("HTTP/1.1 101 Switching Protocols\r\n" ++
+        "Upgrade: websocket\r\n" ++
+        "Connection: upgrade\r\n" ++
+        "Sec-Websocket-Accept: flzHu2DevQ2dSCSVqKSii5e9C2o=\r\n\r\n", res);
+}
+
+test "Client: read invalid websocket message" {
+    // 131 = 128 (fin) | 3  where 3 isn't a valid type
+    try assertWebSocketError(
+        1002,
+        &.{ 131, 128, 'm', 'a', 's', 'k' },
+    );
+
+    for ([_]u8{ 16, 32, 64 }) |rsv| {
+        // none of the reserve flags should be set
+        try assertWebSocketError(
+            1002,
+            &.{ rsv, 128, 'm', 'a', 's', 'k' },
+        );
+
+        // as a bitmask
+        try assertWebSocketError(
+            1002,
+            &.{ rsv + 4, 128, 'm', 'a', 's', 'k' },
+        );
+    }
+
+    // client->server messages must be masked
+    try assertWebSocketError(
+        1002,
+        &.{ 129, 1, 'a' },
+    );
+
+    // control types (ping/ping/close) can't be > 125 bytes
+    for ([_]u8{ 136, 137, 138 }) |op| {
+        try assertWebSocketError(
+            1002,
+            &.{ op, 254, 1, 1 },
+        );
+    }
+
+    // length of message is 0000 0810, i.e: 1024 * 512 + 265
+    try assertWebSocketError(1009, &.{ 129, 255, 0, 0, 0, 0, 0, 8, 1, 0, 'm', 'a', 's', 'k' });
+
+    // continuation type message must come after a normal message
+    // even when not a fin frame
+    try assertWebSocketError(
+        1002,
+        &.{ 0, 129, 'm', 'a', 's', 'k', 'd' },
+    );
+
+    // continuation type message must come after a normal message
+    // even as a fin frame
+    try assertWebSocketError(
+        1002,
+        &.{ 128, 129, 'm', 'a', 's', 'k', 'd' },
+    );
+
+    // text (non-fin) - text (non-fin)
+    try assertWebSocketError(
+        1002,
+        &.{ 1, 129, 'm', 'a', 's', 'k', 'd', 1, 128, 'k', 's', 'a', 'm' },
+    );
+
+    // text (non-fin) - text (fin) should always been continuation after non-fin
+    try assertWebSocketError(
+        1002,
+        &.{ 1, 129, 'm', 'a', 's', 'k', 'd', 129, 128, 'k', 's', 'a', 'm' },
+    );
+
+    // close must be fin
+    try assertWebSocketError(
+        1002,
+        &.{
+            8, 129, 'm', 'a', 's', 'k', 'd',
+        },
+    );
+
+    // ping must be fin
+    try assertWebSocketError(
+        1002,
+        &.{
+            9, 129, 'm', 'a', 's', 'k', 'd',
+        },
+    );
+
+    // pong must be fin
+    try assertWebSocketError(
+        1002,
+        &.{
+            10, 129, 'm', 'a', 's', 'k', 'd',
+        },
+    );
+}
+
+test "Client: ping reply" {
+    try assertWebSocketMessage(
+        // fin | pong, len
+        &.{ 138, 0 },
+
+        // fin | ping, masked | len, 4-byte mask
+        &.{ 137, 128, 0, 0, 0, 0 },
+    );
+
+    try assertWebSocketMessage(
+        // fin | pong, len, payload
+        &.{ 138, 5, 100, 96, 97, 109, 104 },
+
+        // fin | ping, masked | len, 4-byte mask, 5 byte payload
+        &.{ 137, 133, 0, 5, 7, 10, 100, 101, 102, 103, 104 },
+    );
+}
+
+test "Client: close message" {
+    try assertWebSocketMessage(
+        // fin | close, len, close code (normal)
+        &.{ 136, 2, 3, 232 },
+
+        // fin | close, masked | len, 4-byte mask
+        &.{ 136, 128, 0, 0, 0, 0 },
+    );
+}
+
+test "server: 404" {
+    var c = try createTestClient();
+    defer c.deinit();
+
+    const res = try c.httpRequest("GET /unknown HTTP/1.1\r\n\r\n");
+    try testing.expectEqual("HTTP/1.1 404 \r\n" ++
+        "Connection: Close\r\n" ++
+        "Content-Length: 9\r\n\r\n" ++
+        "Not found", res);
+}
+
+test "server: get /json/version" {
+    const expected_response =
+        "HTTP/1.1 200 OK\r\n" ++
+        "Content-Length: 48\r\n" ++
+        "Connection: Close\r\n" ++
+        "Content-Type: application/json; charset=UTF-8\r\n\r\n" ++
+        "{\"webSocketDebuggerUrl\": \"ws://127.0.0.1:9222/\"}";
+
+    {
+        // twice on the same connection
+        var c = try createTestClient();
+        defer c.deinit();
+
+        const res1 = try c.httpRequest("GET /json/version HTTP/1.1\r\n\r\n");
+        try testing.expectEqual(expected_response, res1);
+    }
+
+    {
+        // again on a new connection
+        var c = try createTestClient();
+        defer c.deinit();
+
+        const res1 = try c.httpRequest("GET /json/version HTTP/1.1\r\n\r\n");
+        try testing.expectEqual(expected_response, res1);
+    }
+}
+
+fn assertHTTPError(
+    comptime expected_status: u16,
+    comptime expected_body: []const u8,
+    input: []const u8,
+) !void {
+    var c = try createTestClient();
+    defer c.deinit();
+
+    const res = try c.httpRequest(input);
+    const expected_response = std.fmt.comptimePrint(
+        "HTTP/1.1 {d} \r\nConnection: Close\r\nContent-Length: {d}\r\n\r\n{s}",
+        .{ expected_status, expected_body.len, expected_body },
+    );
+
+    try testing.expectEqual(expected_response, res);
+}
+
+fn assertWebSocketError(close_code: u16, input: []const u8) !void {
+    var c = try createTestClient();
+    defer c.deinit();
+
+    try c.handshake();
+    try c.stream.writeAll(input);
+
+    const msg = try c.readWebsocketMessage() orelse return error.NoMessage;
+    defer if (msg.cleanup_fragment) {
+        c.reader.cleanup();
+    };
+
+    try testing.expectEqual(.close, msg.type);
+    try testing.expectEqual(2, msg.data.len);
+    try testing.expectEqual(close_code, std.mem.readInt(u16, msg.data[0..2], .big));
+}
+
+fn assertWebSocketMessage(expected: []const u8, input: []const u8) !void {
+    var c = try createTestClient();
+    defer c.deinit();
+
+    try c.handshake();
+    try c.stream.writeAll(input);
+
+    const msg = try c.readWebsocketMessage() orelse return error.NoMessage;
+    defer if (msg.cleanup_fragment) {
+        c.reader.cleanup();
+    };
+
+    const actual = c.reader.buf[0 .. msg.data.len + 2];
+    try testing.expectEqualSlices(u8, expected, actual);
+}
+
+const MockCDP = struct {
+    messages: std.ArrayList([]const u8) = .{},
+
+    allocator: Allocator = testing.allocator,
+
+    fn init(_: Allocator, client: anytype) MockCDP {
+        _ = client;
+        return .{};
+    }
+
+    fn deinit(self: *MockCDP) void {
+        const allocator = self.allocator;
+        for (self.messages.items) |msg| {
+            allocator.free(msg);
+        }
+        self.messages.deinit(allocator);
+    }
+
+    fn handleMessage(self: *MockCDP, message: []const u8) bool {
+        const owned = self.allocator.dupe(u8, message) catch unreachable;
+        self.messages.append(self.allocator, owned) catch unreachable;
+        return true;
+    }
+};
+
+fn createTestClient() !TestClient {
+    const address = std.net.Address.initIp4([_]u8{ 127, 0, 0, 1 }, 9583);
+    const stream = try std.net.tcpConnectToAddress(address);
+
+    const timeout = std.mem.toBytes(posix.timeval{
+        .sec = 2,
+        .usec = 0,
+    });
+    try posix.setsockopt(stream.handle, posix.SOL.SOCKET, posix.SO.RCVTIMEO, &timeout);
+    try posix.setsockopt(stream.handle, posix.SOL.SOCKET, posix.SO.SNDTIMEO, &timeout);
+    return .{
+        .stream = stream,
+        .reader = .{
+            .allocator = testing.allocator,
+            .buf = try testing.allocator.alloc(u8, 1024 * 16),
+        },
+    };
+}
+
+const TestClient = struct {
+    stream: std.net.Stream,
+    buf: [1024]u8 = undefined,
+    reader: Net.Reader(false),
+
+    fn deinit(self: *TestClient) void {
+        self.stream.close();
+        self.reader.deinit();
+    }
+
+    fn httpRequest(self: *TestClient, req: []const u8) ![]const u8 {
+        try self.stream.writeAll(req);
+
+        var pos: usize = 0;
+        var total_length: ?usize = null;
+        while (true) {
+            pos += try self.stream.read(self.buf[pos..]);
+            if (pos == 0) {
+                return error.NoMoreData;
+            }
+            const response = self.buf[0..pos];
+            if (total_length == null) {
+                const header_end = std.mem.indexOf(u8, response, "\r\n\r\n") orelse continue;
+                const header = response[0 .. header_end + 4];
+
+                const cl = blk: {
+                    const cl_header = "Content-Length: ";
+                    const start = (std.mem.indexOf(u8, header, cl_header) orelse {
+                        break :blk 0;
+                    }) + cl_header.len;
+
+                    const end = std.mem.indexOfScalarPos(u8, header, start, '\r') orelse {
+                        return error.InvalidContentLength;
+                    };
+
+                    break :blk std.fmt.parseInt(usize, header[start..end], 10) catch {
+                        return error.InvalidContentLength;
+                    };
+                };
+
+                total_length = cl + header.len;
+            }
+
+            if (total_length) |tl| {
+                if (pos == tl) {
+                    return response;
+                }
+                if (pos > tl) {
+                    return error.DataExceedsContentLength;
+                }
+            }
+        }
+    }
+
+    fn handshake(self: *TestClient) !void {
+        const request =
+            "GET /   HTTP/1.1\r\n" ++
+            "Connection: upgrade\r\n" ++
+            "Upgrade: websocket\r\n" ++
+            "sec-websocket-version:13\r\n" ++
+            "sec-websocket-key: this is my key\r\n" ++
+            "Custom:  Header-Value\r\n\r\n";
+
+        const res = try self.httpRequest(request);
+        try testing.expectEqual("HTTP/1.1 101 Switching Protocols\r\n" ++
+            "Upgrade: websocket\r\n" ++
+            "Connection: upgrade\r\n" ++
+            "Sec-Websocket-Accept: flzHu2DevQ2dSCSVqKSii5e9C2o=\r\n\r\n", res);
+    }
+
+    fn readWebsocketMessage(self: *TestClient) !?Net.Message {
+        while (true) {
+            const n = try self.stream.read(self.reader.readBuf());
+            if (n == 0) {
+                return error.Closed;
+            }
+            self.reader.len += n;
+            if (try self.reader.next()) |msg| {
+                return msg;
+            }
+        }
+    }
+};

src/Sighandler.zig

@@ -0,0 +1,107 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+//! This structure processes operating system signals (SIGINT, SIGTERM)
+//! and runs callbacks to clean up the system gracefully.
+//!
+//! The structure does not clear the memory allocated in the arena,
+//! clear the entire arena when exiting the program.
+const std = @import("std");
+const assert = std.debug.assert;
+const Allocator = std.mem.Allocator;
+const lp = @import("lightpanda");
+
+const log = lp.log;
+
+const SigHandler = @This();
+
+arena: Allocator,
+
+sigset: std.posix.sigset_t = undefined,
+handle_thread: ?std.Thread = null,
+
+attempt: u32 = 0,
+listeners: std.ArrayList(Listener) = .empty,
+
+pub const Listener = struct {
+    args: []const u8,
+    start: *const fn (context: *const anyopaque) void,
+};
+
+pub fn install(self: *SigHandler) !void {
+    // Block SIGINT and SIGTERM for the current thread and all created from it
+    self.sigset = std.posix.sigemptyset();
+    std.posix.sigaddset(&self.sigset, std.posix.SIG.INT);
+    std.posix.sigaddset(&self.sigset, std.posix.SIG.TERM);
+    std.posix.sigaddset(&self.sigset, std.posix.SIG.QUIT);
+    std.posix.sigprocmask(std.posix.SIG.BLOCK, &self.sigset, null);
+
+    self.handle_thread = try std.Thread.spawn(.{ .allocator = self.arena }, SigHandler.sighandle, .{self});
+    self.handle_thread.?.detach();
+}
+
+pub fn on(self: *SigHandler, func: anytype, args: std.meta.ArgsTuple(@TypeOf(func))) !void {
+    assert(@typeInfo(@TypeOf(func)).@"fn".return_type.? == void);
+
+    const Args = @TypeOf(args);
+    const TypeErased = struct {
+        fn start(context: *const anyopaque) void {
+            const args_casted: *const Args = @ptrCast(@alignCast(context));
+            @call(.auto, func, args_casted.*);
+        }
+    };
+
+    const buffer = try self.arena.alignedAlloc(u8, .of(Args), @sizeOf(Args));
+    errdefer self.arena.free(buffer);
+
+    const bytes: []const u8 = @ptrCast((&args)[0..1]);
+    @memcpy(buffer, bytes);
+
+    try self.listeners.append(self.arena, .{
+        .args = buffer,
+        .start = TypeErased.start,
+    });
+}
+
+fn sighandle(self: *SigHandler) noreturn {
+    while (true) {
+        var sig: c_int = 0;
+
+        const rc = std.c.sigwait(&self.sigset, &sig);
+        if (rc != 0) {
+            log.err(.app, "Unable to process signal {}", .{rc});
+            std.process.exit(1);
+        }
+
+        switch (sig) {
+            std.posix.SIG.INT, std.posix.SIG.TERM => {
+                if (self.attempt > 1) {
+                    std.process.exit(1);
+                }
+                self.attempt += 1;
+
+                log.info(.app, "Received termination signal...", .{});
+                for (self.listeners.items) |*item| {
+                    item.start(item.args.ptr);
+                }
+                continue;
+            },
+            else => continue,
+        }
+    }
+}

src/TestHTTPServer.zig

@@ -0,0 +1,154 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const URL = @import("browser/URL.zig");
+
+const TestHTTPServer = @This();
+
+shutdown: std.atomic.Value(bool),
+listener: ?std.net.Server,
+handler: Handler,
+
+const Handler = *const fn (req: *std.http.Server.Request) anyerror!void;
+
+pub fn init(handler: Handler) TestHTTPServer {
+    return .{
+        .shutdown = .init(true),
+        .listener = null,
+        .handler = handler,
+    };
+}
+
+pub fn deinit(self: *TestHTTPServer) void {
+    self.listener = null;
+}
+
+pub fn stop(self: *TestHTTPServer) void {
+    self.shutdown.store(true, .release);
+    if (self.listener) |*listener| {
+        switch (@import("builtin").target.os.tag) {
+            .linux => std.posix.shutdown(listener.stream.handle, .recv) catch {},
+            else => std.posix.close(listener.stream.handle),
+        }
+    }
+}
+
+pub fn run(self: *TestHTTPServer, wg: *std.Thread.WaitGroup) !void {
+    const address = try std.net.Address.parseIp("127.0.0.1", 9582);
+
+    self.listener = try address.listen(.{ .reuse_address = true });
+    var listener = &self.listener.?;
+    self.shutdown.store(false, .release);
+
+    wg.finish();
+
+    while (true) {
+        const conn = listener.accept() catch |err| {
+            if (self.shutdown.load(.acquire) or err == error.SocketNotListening) {
+                return;
+            }
+            return err;
+        };
+        const thrd = try std.Thread.spawn(.{}, handleConnection, .{ self, conn });
+        thrd.detach();
+    }
+}
+
+fn handleConnection(self: *TestHTTPServer, conn: std.net.Server.Connection) !void {
+    defer conn.stream.close();
+
+    var req_buf: [2048]u8 = undefined;
+    var conn_reader = conn.stream.reader(&req_buf);
+    var conn_writer = conn.stream.writer(&req_buf);
+
+    var http_server = std.http.Server.init(conn_reader.interface(), &conn_writer.interface);
+
+    while (true) {
+        var req = http_server.receiveHead() catch |err| switch (err) {
+            error.ReadFailed => continue,
+            error.HttpConnectionClosing => continue,
+            else => {
+                std.debug.print("Test HTTP Server error: {}\n", .{err});
+                return err;
+            },
+        };
+
+        self.handler(&req) catch |err| {
+            std.debug.print("test http error '{s}': {}\n", .{ req.head.target, err });
+            try req.respond("server error", .{ .status = .internal_server_error });
+            return;
+        };
+    }
+}
+
+pub fn sendFile(req: *std.http.Server.Request, file_path: []const u8) !void {
+    var url_buf: [1024]u8 = undefined;
+    var fba = std.heap.FixedBufferAllocator.init(&url_buf);
+    const unescaped_file_path = try URL.unescape(fba.allocator(), file_path);
+    var file = std.fs.cwd().openFile(unescaped_file_path, .{}) catch |err| switch (err) {
+        error.FileNotFound => return req.respond("server error", .{ .status = .not_found }),
+        else => return err,
+    };
+    defer file.close();
+
+    const stat = try file.stat();
+    var send_buffer: [4096]u8 = undefined;
+
+    var res = try req.respondStreaming(&send_buffer, .{
+        .content_length = stat.size,
+        .respond_options = .{
+            .extra_headers = &.{
+                .{ .name = "content-type", .value = getContentType(file_path) },
+            },
+        },
+    });
+
+    var read_buffer: [4096]u8 = undefined;
+    var reader = file.reader(&read_buffer);
+    _ = try res.writer.sendFileAll(&reader, .unlimited);
+    try res.writer.flush();
+    try res.end();
+}
+
+fn getContentType(file_path: []const u8) []const u8 {
+    if (std.mem.endsWith(u8, file_path, ".js")) {
+        return "application/json";
+    }
+
+    if (std.mem.endsWith(u8, file_path, ".html")) {
+        return "text/html";
+    }
+
+    if (std.mem.endsWith(u8, file_path, ".htm")) {
+        return "text/html";
+    }
+
+    if (std.mem.endsWith(u8, file_path, ".xml")) {
+        // some wpt tests do this
+        return "text/xml";
+    }
+
+    if (std.mem.endsWith(u8, file_path, ".mjs")) {
+        // mjs are ECMAScript modules
+        return "application/json";
+    }
+
+    std.debug.print("TestHTTPServer asked to serve an unknown file type: {s}\n", .{file_path});
+    return "text/html";
+}

src/async/stream.zig

@@ -1,133 +0,0 @@
-// Copyright (C) 2023-2024  Lightpanda (Selecy SAS)
-//
-// Francis Bouvier <francis@lightpanda.io>
-// Pierre Tachoire <pierre@lightpanda.io>
-//
-// This program is free software: you can redistribute it and/or modify
-// it under the terms of the GNU Affero General Public License as
-// published by the Free Software Foundation, either version 3 of the
-// License, or (at your option) any later version.
-//
-// This program is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// GNU Affero General Public License for more details.
-//
-// You should have received a copy of the GNU Affero General Public License
-// along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-const std = @import("std");
-const builtin = @import("builtin");
-const posix = std.posix;
-const io = std.io;
-const assert = std.debug.assert;
-
-const tcp = @import("tcp.zig");
-
-pub const Stream = struct {
-    alloc: std.mem.Allocator,
-    conn: *tcp.Conn,
-
-    handle: posix.socket_t,
-
-    pub fn close(self: Stream) void {
-        posix.close(self.handle);
-        self.alloc.destroy(self.conn);
-    }
-
-    pub const ReadError = posix.ReadError;
-    pub const WriteError = posix.WriteError;
-
-    pub const Reader = io.Reader(Stream, ReadError, read);
-    pub const Writer = io.Writer(Stream, WriteError, write);
-
-    pub fn reader(self: Stream) Reader {
-        return .{ .context = self };
-    }
-
-    pub fn writer(self: Stream) Writer {
-        return .{ .context = self };
-    }
-
-    pub fn read(self: Stream, buffer: []u8) ReadError!usize {
-        return self.conn.receive(self.handle, buffer) catch |err| switch (err) {
-            else => return error.Unexpected,
-        };
-    }
-
-    pub fn readv(s: Stream, iovecs: []const posix.iovec) ReadError!usize {
-        return posix.readv(s.handle, iovecs);
-    }
-
-    /// Returns the number of bytes read. If the number read is smaller than
-    /// `buffer.len`, it means the stream reached the end. Reaching the end of
-    /// a stream is not an error condition.
-    pub fn readAll(s: Stream, buffer: []u8) ReadError!usize {
-        return readAtLeast(s, buffer, buffer.len);
-    }
-
-    /// Returns the number of bytes read, calling the underlying read function
-    /// the minimal number of times until the buffer has at least `len` bytes
-    /// filled. If the number read is less than `len` it means the stream
-    /// reached the end. Reaching the end of the stream is not an error
-    /// condition.
-    pub fn readAtLeast(s: Stream, buffer: []u8, len: usize) ReadError!usize {
-        assert(len <= buffer.len);
-        var index: usize = 0;
-        while (index < len) {
-            const amt = try s.read(buffer[index..]);
-            if (amt == 0) break;
-            index += amt;
-        }
-        return index;
-    }
-
-    /// TODO in evented I/O mode, this implementation incorrectly uses the event loop's
-    /// file system thread instead of non-blocking. It needs to be reworked to properly
-    /// use non-blocking I/O.
-    pub fn write(self: Stream, buffer: []const u8) WriteError!usize {
-        return self.conn.send(self.handle, buffer) catch |err| switch (err) {
-            error.AccessDenied => error.AccessDenied,
-            error.WouldBlock => error.WouldBlock,
-            error.ConnectionResetByPeer => error.ConnectionResetByPeer,
-            error.MessageTooBig => error.FileTooBig,
-            error.BrokenPipe => error.BrokenPipe,
-            else => return error.Unexpected,
-        };
-    }
-
-    pub fn writeAll(self: Stream, bytes: []const u8) WriteError!void {
-        var index: usize = 0;
-        while (index < bytes.len) {
-            index += try self.write(bytes[index..]);
-        }
-    }
-
-    /// See https://github.com/ziglang/zig/issues/7699
-    /// See equivalent function: `std.fs.File.writev`.
-    pub fn writev(self: Stream, iovecs: []const posix.iovec_const) WriteError!usize {
-        if (iovecs.len == 0) return 0;
-        const first_buffer = iovecs[0].iov_base[0..iovecs[0].iov_len];
-        return try self.write(first_buffer);
-    }
-
-    /// The `iovecs` parameter is mutable because this function needs to mutate the fields in
-    /// order to handle partial writes from the underlying OS layer.
-    /// See https://github.com/ziglang/zig/issues/7699
-    /// See equivalent function: `std.fs.File.writevAll`.
-    pub fn writevAll(self: Stream, iovecs: []posix.iovec_const) WriteError!void {
-        if (iovecs.len == 0) return;
-
-        var i: usize = 0;
-        while (true) {
-            var amt = try self.writev(iovecs[i..]);
-            while (amt >= iovecs[i].iov_len) {
-                amt -= iovecs[i].iov_len;
-                i += 1;
-                if (i >= iovecs.len) return;
-            }
-            iovecs[i].iov_base += amt;
-            iovecs[i].iov_len -= amt;
-        }
-    }
-};

src/async/tcp.zig

@@ -1,112 +0,0 @@
-// Copyright (C) 2023-2024  Lightpanda (Selecy SAS)
-//
-// Francis Bouvier <francis@lightpanda.io>
-// Pierre Tachoire <pierre@lightpanda.io>
-//
-// This program is free software: you can redistribute it and/or modify
-// it under the terms of the GNU Affero General Public License as
-// published by the Free Software Foundation, either version 3 of the
-// License, or (at your option) any later version.
-//
-// This program is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// GNU Affero General Public License for more details.
-//
-// You should have received a copy of the GNU Affero General Public License
-// along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-const std = @import("std");
-const net = std.net;
-const Stream = @import("stream.zig").Stream;
-const Loop = @import("jsruntime").Loop;
-const NetworkImpl = Loop.Network(Conn.Command);
-
-// Conn is a TCP connection using jsruntime Loop async I/O.
-// connect, send and receive are blocking, but use async I/O in the background.
-// Client doesn't own the socket used for the connection, the caller is
-// responsible for closing it.
-pub const Conn = struct {
-    const Command = struct {
-        impl: NetworkImpl,
-
-        done: bool = false,
-        err: ?anyerror = null,
-        ln: usize = 0,
-
-        fn ok(self: *Command, err: ?anyerror, ln: usize) void {
-            self.err = err;
-            self.ln = ln;
-            self.done = true;
-        }
-
-        fn wait(self: *Command) !usize {
-            while (!self.done) try self.impl.tick();
-
-            if (self.err) |err| return err;
-            return self.ln;
-        }
-        pub fn onConnect(self: *Command, err: ?anyerror) void {
-            self.ok(err, 0);
-        }
-        pub fn onSend(self: *Command, ln: usize, err: ?anyerror) void {
-            self.ok(err, ln);
-        }
-        pub fn onReceive(self: *Command, ln: usize, err: ?anyerror) void {
-            self.ok(err, ln);
-        }
-    };
-
-    loop: *Loop,
-
-    pub fn connect(self: *Conn, socket: std.posix.socket_t, address: std.net.Address) !void {
-        var cmd = Command{ .impl = NetworkImpl.init(self.loop) };
-        cmd.impl.connect(&cmd, socket, address);
-        _ = try cmd.wait();
-    }
-
-    pub fn send(self: *Conn, socket: std.posix.socket_t, buffer: []const u8) !usize {
-        var cmd = Command{ .impl = NetworkImpl.init(self.loop) };
-        cmd.impl.send(&cmd, socket, buffer);
-        return try cmd.wait();
-    }
-
-    pub fn receive(self: *Conn, socket: std.posix.socket_t, buffer: []u8) !usize {
-        var cmd = Command{ .impl = NetworkImpl.init(self.loop) };
-        cmd.impl.receive(&cmd, socket, buffer);
-        return try cmd.wait();
-    }
-};
-
-pub fn tcpConnectToHost(alloc: std.mem.Allocator, loop: *Loop, name: []const u8, port: u16) !Stream {
-    // TODO async resolve
-    const list = try net.getAddressList(alloc, name, port);
-    defer list.deinit();
-
-    if (list.addrs.len == 0) return error.UnknownHostName;
-
-    for (list.addrs) |addr| {
-        return tcpConnectToAddress(alloc, loop, addr) catch |err| switch (err) {
-            error.ConnectionRefused => {
-                continue;
-            },
-            else => return err,
-        };
-    }
-    return std.posix.ConnectError.ConnectionRefused;
-}
-
-pub fn tcpConnectToAddress(alloc: std.mem.Allocator, loop: *Loop, addr: net.Address) !Stream {
-    const sockfd = try std.posix.socket(addr.any.family, std.posix.SOCK.STREAM, std.posix.IPPROTO.TCP);
-    errdefer std.posix.close(sockfd);
-
-    var conn = try alloc.create(Conn);
-    conn.* = Conn{ .loop = loop };
-    try conn.connect(sockfd, addr);
-
-    return Stream{
-        .alloc = alloc,
-        .conn = conn,
-        .handle = sockfd,
-    };
-}

src/async/test.zig

@@ -1,189 +0,0 @@
-// Copyright (C) 2023-2024  Lightpanda (Selecy SAS)
-//
-// Francis Bouvier <francis@lightpanda.io>
-// Pierre Tachoire <pierre@lightpanda.io>
-//
-// This program is free software: you can redistribute it and/or modify
-// it under the terms of the GNU Affero General Public License as
-// published by the Free Software Foundation, either version 3 of the
-// License, or (at your option) any later version.
-//
-// This program is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// GNU Affero General Public License for more details.
-//
-// You should have received a copy of the GNU Affero General Public License
-// along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-const std = @import("std");
-const http = std.http;
-const Client = @import("Client.zig");
-const Request = @import("Client.zig").Request;
-
-pub const Loop = @import("jsruntime").Loop;
-
-const url = "https://w3.org";
-
-test "blocking mode fetch API" {
-    const alloc = std.testing.allocator;
-
-    var loop = try Loop.init(alloc);
-    defer loop.deinit();
-
-    var client: Client = .{
-        .allocator = alloc,
-        .loop = &loop,
-    };
-    defer client.deinit();
-
-    // force client's CA cert scan from system.
-    try client.ca_bundle.rescan(client.allocator);
-
-    const res = try client.fetch(.{
-        .location = .{ .uri = try std.Uri.parse(url) },
-    });
-
-    try std.testing.expect(res.status == .ok);
-}
-
-test "blocking mode open/send/wait API" {
-    const alloc = std.testing.allocator;
-
-    var loop = try Loop.init(alloc);
-    defer loop.deinit();
-
-    var client: Client = .{
-        .allocator = alloc,
-        .loop = &loop,
-    };
-    defer client.deinit();
-
-    // force client's CA cert scan from system.
-    try client.ca_bundle.rescan(client.allocator);
-
-    var buf: [2014]u8 = undefined;
-    var req = try client.open(.GET, try std.Uri.parse(url), .{
-        .server_header_buffer = &buf,
-    });
-    defer req.deinit();
-
-    try req.send();
-    try req.finish();
-    try req.wait();
-
-    try std.testing.expect(req.response.status == .ok);
-}
-
-// Example how to write an async http client using the modified standard client.
-const AsyncClient = struct {
-    cli: Client,
-
-    const YieldImpl = Loop.Yield(AsyncRequest);
-    const AsyncRequest = struct {
-        const State = enum { new, open, send, finish, wait, done };
-
-        cli: *Client,
-        uri: std.Uri,
-
-        req: ?Request = undefined,
-        state: State = .new,
-
-        impl: YieldImpl,
-        err: ?anyerror = null,
-
-        buf: [2014]u8 = undefined,
-
-        pub fn deinit(self: *AsyncRequest) void {
-            if (self.req) |*r| r.deinit();
-        }
-
-        pub fn fetch(self: *AsyncRequest) void {
-            self.state = .new;
-            return self.impl.yield(self);
-        }
-
-        fn onerr(self: *AsyncRequest, err: anyerror) void {
-            self.state = .done;
-            self.err = err;
-        }
-
-        pub fn onYield(self: *AsyncRequest, err: ?anyerror) void {
-            if (err) |e| return self.onerr(e);
-
-            switch (self.state) {
-                .new => {
-                    self.state = .open;
-                    self.req = self.cli.open(.GET, self.uri, .{
-                        .server_header_buffer = &self.buf,
-                    }) catch |e| return self.onerr(e);
-                },
-                .open => {
-                    self.state = .send;
-                    self.req.?.send() catch |e| return self.onerr(e);
-                },
-                .send => {
-                    self.state = .finish;
-                    self.req.?.finish() catch |e| return self.onerr(e);
-                },
-                .finish => {
-                    self.state = .wait;
-                    self.req.?.wait() catch |e| return self.onerr(e);
-                },
-                .wait => {
-                    self.state = .done;
-                    return;
-                },
-                .done => return,
-            }
-
-            return self.impl.yield(self);
-        }
-
-        pub fn wait(self: *AsyncRequest) !void {
-            while (self.state != .done) try self.impl.tick();
-            if (self.err) |err| return err;
-        }
-    };
-
-    pub fn init(alloc: std.mem.Allocator, loop: *Loop) AsyncClient {
-        return .{
-            .cli = .{
-                .allocator = alloc,
-                .loop = loop,
-            },
-        };
-    }
-
-    pub fn deinit(self: *AsyncClient) void {
-        self.cli.deinit();
-    }
-
-    pub fn createRequest(self: *AsyncClient, uri: std.Uri) !AsyncRequest {
-        return .{
-            .impl = YieldImpl.init(self.cli.loop),
-            .cli = &self.cli,
-            .uri = uri,
-        };
-    }
-};
-
-test "non blocking client" {
-    const alloc = std.testing.allocator;
-
-    var loop = try Loop.init(alloc);
-    defer loop.deinit();
-
-    var client = AsyncClient.init(alloc, &loop);
-    defer client.deinit();
-
-    var reqs: [3]AsyncClient.AsyncRequest = undefined;
-    for (0..reqs.len) |i| {
-        reqs[i] = try client.createRequest(try std.Uri.parse(url));
-        reqs[i].fetch();
-    }
-    for (0..reqs.len) |i| {
-        try reqs[i].wait();
-        reqs[i].deinit();
-    }
-}

src/browser/Browser.zig

@@ -0,0 +1,122 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+
+const Allocator = std.mem.Allocator;
+const ArenaAllocator = std.heap.ArenaAllocator;
+
+const js = @import("js/js.zig");
+const log = @import("../log.zig");
+const App = @import("../App.zig");
+const HttpClient = @import("HttpClient.zig");
+
+const ArenaPool = App.ArenaPool;
+
+const IS_DEBUG = @import("builtin").mode == .Debug;
+
+const Session = @import("Session.zig");
+const Notification = @import("../Notification.zig");
+
+// Browser is an instance of the browser.
+// You can create multiple browser instances.
+// A browser contains only one session.
+const Browser = @This();
+
+env: js.Env,
+app: *App,
+session: ?Session,
+allocator: Allocator,
+arena_pool: *ArenaPool,
+http_client: *HttpClient,
+
+const InitOpts = struct {
+    env: js.Env.InitOpts = .{},
+    http_client: *HttpClient,
+};
+
+pub fn init(app: *App, opts: InitOpts) !Browser {
+    const allocator = app.allocator;
+
+    var env = try js.Env.init(app, opts.env);
+    errdefer env.deinit();
+
+    return .{
+        .app = app,
+        .env = env,
+        .session = null,
+        .allocator = allocator,
+        .arena_pool = &app.arena_pool,
+        .http_client = opts.http_client,
+    };
+}
+
+pub fn deinit(self: *Browser) void {
+    self.closeSession();
+    self.env.deinit();
+}
+
+pub fn newSession(self: *Browser, notification: *Notification) !*Session {
+    self.closeSession();
+    self.session = @as(Session, undefined);
+    const session = &self.session.?;
+    try Session.init(session, self, notification);
+    return session;
+}
+
+pub fn closeSession(self: *Browser) void {
+    if (self.session) |*session| {
+        session.deinit();
+        self.session = null;
+        self.env.memoryPressureNotification(.critical);
+    }
+}
+
+pub fn runMicrotasks(self: *Browser) void {
+    self.env.runMicrotasks();
+}
+
+pub fn runMacrotasks(self: *Browser) !void {
+    const env = &self.env;
+
+    try self.env.runMacrotasks();
+    env.pumpMessageLoop();
+
+    // either of the above could have queued more microtasks
+    env.runMicrotasks();
+}
+
+pub fn hasBackgroundTasks(self: *Browser) bool {
+    return self.env.hasBackgroundTasks();
+}
+
+pub fn waitForBackgroundTasks(self: *Browser) void {
+    self.env.waitForBackgroundTasks();
+}
+
+pub fn msToNextMacrotask(self: *Browser) ?u64 {
+    return self.env.msToNextMacrotask();
+}
+
+pub fn msTo(self: *Browser) bool {
+    return self.env.hasBackgroundTasks();
+}
+
+pub fn runIdleTasks(self: *const Browser) void {
+    self.env.runIdleTasks();
+}

src/browser/EventManager.zig

@@ -0,0 +1,943 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const builtin = @import("builtin");
+
+const log = @import("../log.zig");
+const String = @import("../string.zig").String;
+
+const js = @import("js/js.zig");
+const Page = @import("Page.zig");
+
+const Node = @import("webapi/Node.zig");
+const Event = @import("webapi/Event.zig");
+const EventTarget = @import("webapi/EventTarget.zig");
+const Element = @import("webapi/Element.zig");
+
+const Allocator = std.mem.Allocator;
+
+const IS_DEBUG = builtin.mode == .Debug;
+
+const EventKey = struct {
+    event_target: usize,
+    type_string: String,
+};
+
+const EventKeyContext = struct {
+    pub fn hash(_: @This(), key: EventKey) u64 {
+        var hasher = std.hash.Wyhash.init(0);
+        hasher.update(std.mem.asBytes(&key.event_target));
+        hasher.update(key.type_string.str());
+        return hasher.final();
+    }
+
+    pub fn eql(_: @This(), a: EventKey, b: EventKey) bool {
+        return a.event_target == b.event_target and a.type_string.eql(b.type_string);
+    }
+};
+
+pub const EventManager = @This();
+
+page: *Page,
+arena: Allocator,
+// Used as an optimization in Page._documentIsComplete. If we know there are no
+// 'load' listeners in the document, we can skip dispatching the per-resource
+// 'load' event (e.g. amazon product page has no listener and ~350 resources)
+has_dom_load_listener: bool,
+listener_pool: std.heap.MemoryPool(Listener),
+ignore_list: std.ArrayList(*Listener),
+list_pool: std.heap.MemoryPool(std.DoublyLinkedList),
+lookup: std.HashMapUnmanaged(
+    EventKey,
+    *std.DoublyLinkedList,
+    EventKeyContext,
+    std.hash_map.default_max_load_percentage,
+),
+dispatch_depth: usize,
+deferred_removals: std.ArrayList(struct { list: *std.DoublyLinkedList, listener: *Listener }),
+
+pub fn init(arena: Allocator, page: *Page) EventManager {
+    return .{
+        .page = page,
+        .lookup = .{},
+        .arena = arena,
+        .ignore_list = .{},
+        .list_pool = .init(arena),
+        .listener_pool = .init(arena),
+        .dispatch_depth = 0,
+        .deferred_removals = .{},
+        .has_dom_load_listener = false,
+    };
+}
+
+pub const RegisterOptions = struct {
+    once: bool = false,
+    capture: bool = false,
+    passive: bool = false,
+    signal: ?*@import("webapi/AbortSignal.zig") = null,
+};
+
+pub const Callback = union(enum) {
+    function: js.Function,
+    object: js.Object,
+};
+
+pub fn register(self: *EventManager, target: *EventTarget, typ: []const u8, callback: Callback, opts: RegisterOptions) !void {
+    if (comptime IS_DEBUG) {
+        log.debug(.event, "eventManager.register", .{ .type = typ, .capture = opts.capture, .once = opts.once, .target = target.toString() });
+    }
+
+    // If a signal is provided and already aborted, don't register the listener
+    if (opts.signal) |signal| {
+        if (signal.getAborted()) {
+            return;
+        }
+    }
+
+    // Allocate the type string we'll use in both listener and key
+    const type_string = try String.init(self.arena, typ, .{});
+
+    if (type_string.eql(comptime .wrap("load")) and target._type == .node) {
+        self.has_dom_load_listener = true;
+    }
+
+    const gop = try self.lookup.getOrPut(self.arena, .{
+        .type_string = type_string,
+        .event_target = @intFromPtr(target),
+    });
+    if (gop.found_existing) {
+        // check for duplicate callbacks already registered
+        var node = gop.value_ptr.*.first;
+        while (node) |n| {
+            const listener: *Listener = @alignCast(@fieldParentPtr("node", n));
+            const is_duplicate = switch (callback) {
+                .object => |obj| listener.function.eqlObject(obj),
+                .function => |func| listener.function.eqlFunction(func),
+            };
+            if (is_duplicate and listener.capture == opts.capture) {
+                return;
+            }
+            node = n.next;
+        }
+    } else {
+        gop.value_ptr.* = try self.list_pool.create();
+        gop.value_ptr.*.* = .{};
+    }
+
+    const func = switch (callback) {
+        .function => |f| Function{ .value = try f.persist() },
+        .object => |o| Function{ .object = try o.persist() },
+    };
+
+    const listener = try self.listener_pool.create();
+    listener.* = .{
+        .node = .{},
+        .once = opts.once,
+        .capture = opts.capture,
+        .passive = opts.passive,
+        .function = func,
+        .signal = opts.signal,
+        .typ = type_string,
+    };
+    // append the listener to the list of listeners for this target
+    gop.value_ptr.*.append(&listener.node);
+
+    // Track load listeners for script execution ignore list
+    if (type_string.eql(comptime .wrap("load"))) {
+        try self.ignore_list.append(self.arena, listener);
+    }
+}
+
+pub fn remove(self: *EventManager, target: *EventTarget, typ: []const u8, callback: Callback, use_capture: bool) void {
+    const list = self.lookup.get(.{
+        .type_string = .wrap(typ),
+        .event_target = @intFromPtr(target),
+    }) orelse return;
+    if (findListener(list, callback, use_capture)) |listener| {
+        self.removeListener(list, listener);
+    }
+}
+
+pub fn clearIgnoreList(self: *EventManager) void {
+    self.ignore_list.clearRetainingCapacity();
+}
+
+// Dispatching can be recursive from the compiler's point of view, so we need to
+// give it an explicit error set so that other parts of the code can use and
+// inferred error.
+const DispatchError = error{
+    OutOfMemory,
+    StringTooLarge,
+    JSExecCallback,
+    CompilationError,
+    ExecutionError,
+    JsException,
+};
+
+pub const DispatchOpts = struct {
+    // A "load" event triggered by a script (in ScriptManager) should not trigger
+    // a "load" listener added within that script. Therefore, any "load" listener
+    // that we add go into an ignore list until after the script finishes executing.
+    // The ignore list is only checked when apply_ignore  == true, which is only
+    // set by the ScriptManager when raising the script's "load" event.
+    apply_ignore: bool = false,
+};
+
+pub fn dispatch(self: *EventManager, target: *EventTarget, event: *Event) DispatchError!void {
+    return self.dispatchOpts(target, event, .{});
+}
+
+pub fn dispatchOpts(self: *EventManager, target: *EventTarget, event: *Event, comptime opts: DispatchOpts) DispatchError!void {
+    event.acquireRef();
+    defer event.deinit(false, self.page._session);
+
+    if (comptime IS_DEBUG) {
+        log.debug(.event, "eventManager.dispatch", .{ .type = event._type_string.str(), .bubbles = event._bubbles });
+    }
+
+    switch (target._type) {
+        .node => |node| try self.dispatchNode(node, event, opts),
+        else => try self.dispatchDirect(target, event, null, .{ .context = "dispatch" }),
+    }
+}
+
+// There are a lot of events that can be attached via addEventListener or as
+// a property, like the XHR events, or window.onload. You might think that the
+// property is just a shortcut for calling addEventListener, but they are distinct.
+// An event set via property cannot be removed by removeEventListener. If you
+// set both the property and add a listener, they both execute.
+const DispatchDirectOptions = struct {
+    context: []const u8,
+    inject_target: bool = true,
+};
+
+// Direct dispatch for non-DOM targets (Window, XHR, AbortSignal) or DOM nodes with
+// property handlers. No propagation - just calls the handler and registered listeners.
+// Handler can be: null, ?js.Function.Global, ?js.Function.Temp, or js.Function
+pub fn dispatchDirect(self: *EventManager, target: *EventTarget, event: *Event, handler: anytype, comptime opts: DispatchDirectOptions) !void {
+    const page = self.page;
+
+    // Set window.event to the currently dispatching event (WHATWG spec)
+    const window = page.window;
+    const prev_event = window._current_event;
+    window._current_event = event;
+    defer window._current_event = prev_event;
+
+    event.acquireRef();
+    defer event.deinit(false, page._session);
+
+    if (comptime IS_DEBUG) {
+        log.debug(.event, "dispatchDirect", .{ .type = event._type_string, .context = opts.context });
+    }
+
+    if (comptime opts.inject_target) {
+        event._target = target;
+        event._dispatch_target = target; // Store original target for composedPath()
+    }
+
+    var was_dispatched = false;
+
+    var ls: js.Local.Scope = undefined;
+    page.js.localScope(&ls);
+    defer {
+        ls.local.runMicrotasks();
+        ls.deinit();
+    }
+
+    if (getFunction(handler, &ls.local)) |func| {
+        event._current_target = target;
+        if (func.callWithThis(void, target, .{event})) {
+            was_dispatched = true;
+        } else |err| {
+            // a non-JS error
+            log.warn(.event, opts.context, .{ .err = err });
+        }
+    }
+
+    // listeners reigstered via addEventListener
+    const list = self.lookup.get(.{
+        .event_target = @intFromPtr(target),
+        .type_string = event._type_string,
+    }) orelse return;
+
+    // This is a slightly simplified version of what you'll find in dispatchPhase
+    // It is simpler because, for direct dispatching, we know there's no ancestors
+    // and only the single target phase.
+
+    // Track dispatch depth for deferred removal
+    self.dispatch_depth += 1;
+    defer {
+        const dispatch_depth = self.dispatch_depth;
+        // Only destroy deferred listeners when we exit the outermost dispatch
+        if (dispatch_depth == 1) {
+            for (self.deferred_removals.items) |removal| {
+                removal.list.remove(&removal.listener.node);
+                self.listener_pool.destroy(removal.listener);
+            }
+            self.deferred_removals.clearRetainingCapacity();
+        } else {
+            self.dispatch_depth = dispatch_depth - 1;
+        }
+    }
+
+    // Use the last listener in the list as sentinel - listeners added during dispatch will be after it
+    const last_node = list.last orelse return;
+    const last_listener: *Listener = @alignCast(@fieldParentPtr("node", last_node));
+
+    // Iterate through the list, stopping after we've encountered the last_listener
+    var node = list.first;
+    var is_done = false;
+    while (node) |n| {
+        if (is_done) {
+            break;
+        }
+
+        const listener: *Listener = @alignCast(@fieldParentPtr("node", n));
+        is_done = (listener == last_listener);
+        node = n.next;
+
+        // Skip removed listeners
+        if (listener.removed) {
+            continue;
+        }
+
+        // If the listener has an aborted signal, remove it and skip
+        if (listener.signal) |signal| {
+            if (signal.getAborted()) {
+                self.removeListener(list, listener);
+                continue;
+            }
+        }
+
+        // Remove "once" listeners BEFORE calling them so nested dispatches don't see them
+        if (listener.once) {
+            self.removeListener(list, listener);
+        }
+
+        was_dispatched = true;
+        event._current_target = target;
+
+        switch (listener.function) {
+            .value => |value| try ls.toLocal(value).callWithThis(void, target, .{event}),
+            .string => |string| {
+                const str = try page.call_arena.dupeZ(u8, string.str());
+                try ls.local.eval(str, null);
+            },
+            .object => |obj_global| {
+                const obj = ls.toLocal(obj_global);
+                if (try obj.getFunction("handleEvent")) |handleEvent| {
+                    try handleEvent.callWithThis(void, obj, .{event});
+                }
+            },
+        }
+
+        if (event._stop_immediate_propagation) {
+            return;
+        }
+    }
+}
+
+fn getFunction(handler: anytype, local: *const js.Local) ?js.Function {
+    const T = @TypeOf(handler);
+    const ti = @typeInfo(T);
+
+    if (ti == .null) {
+        return null;
+    }
+    if (ti == .optional) {
+        return getFunction(handler orelse return null, local);
+    }
+    return switch (T) {
+        js.Function => handler,
+        js.Function.Temp => local.toLocal(handler),
+        js.Function.Global => local.toLocal(handler),
+        else => @compileError("handler must be null or \\??js.Function(\\.(Temp|Global))?"),
+    };
+}
+
+/// Check if there are any listeners for a direct dispatch (non-DOM target).
+/// Use this to avoid creating an event when there are no listeners.
+pub fn hasDirectListeners(self: *EventManager, target: *EventTarget, typ: []const u8, handler: anytype) bool {
+    if (hasHandler(handler)) {
+        return true;
+    }
+    return self.lookup.get(.{
+        .event_target = @intFromPtr(target),
+        .type_string = .wrap(typ),
+    }) != null;
+}
+
+fn hasHandler(handler: anytype) bool {
+    const ti = @typeInfo(@TypeOf(handler));
+    if (ti == .null) {
+        return false;
+    }
+    if (ti == .optional) {
+        return handler != null;
+    }
+    return true;
+}
+
+fn dispatchNode(self: *EventManager, target: *Node, event: *Event, comptime opts: DispatchOpts) !void {
+    const ShadowRoot = @import("webapi/ShadowRoot.zig");
+
+    {
+        const et = target.asEventTarget();
+        event._target = et;
+        event._dispatch_target = et; // Store original target for composedPath()
+    }
+
+    const page = self.page;
+
+    // Set window.event to the currently dispatching event (WHATWG spec)
+    const window = page.window;
+    const prev_event = window._current_event;
+    window._current_event = event;
+    defer window._current_event = prev_event;
+
+    var was_handled = false;
+
+    // Create a single scope for all event handlers in this dispatch.
+    // This ensures function handles passed to queueMicrotask remain valid
+    // throughout the entire dispatch, preventing crashes when microtasks run.
+    var ls: js.Local.Scope = undefined;
+    page.js.localScope(&ls);
+    defer {
+        if (was_handled) {
+            ls.local.runMicrotasks();
+        }
+        ls.deinit();
+    }
+
+    const activation_state = ActivationState.create(event, target, page);
+
+    // Defer runs even on early return - ensures event phase is reset
+    // and default actions execute (unless prevented)
+    defer {
+        event._event_phase = .none;
+        event._stop_propagation = false;
+        event._stop_immediate_propagation = false;
+        // Handle checkbox/radio activation rollback or commit
+        if (activation_state) |state| {
+            state.restore(event, page);
+        }
+
+        // Execute default action if not prevented
+        if (event._prevent_default) {
+            // can't return in a defer (╯°□°)╯︵ ┻━┻
+        } else if (event._type_string.eql(comptime .wrap("click"))) {
+            page.handleClick(target) catch |err| {
+                log.warn(.event, "page.click", .{ .err = err });
+            };
+        } else if (event._type_string.eql(comptime .wrap("keydown"))) {
+            page.handleKeydown(target, event) catch |err| {
+                log.warn(.event, "page.keydown", .{ .err = err });
+            };
+        }
+    }
+
+    var path_len: usize = 0;
+    var path_buffer: [128]*EventTarget = undefined;
+
+    var node: ?*Node = target;
+    while (node) |n| {
+        if (path_len >= path_buffer.len) break;
+        path_buffer[path_len] = n.asEventTarget();
+        path_len += 1;
+
+        // Check if this node is a shadow root
+        if (n.is(ShadowRoot)) |shadow| {
+            event._needs_retargeting = true;
+
+            // If event is not composed, stop at shadow boundary
+            if (!event._composed) {
+                break;
+            }
+
+            // Otherwise, jump to the shadow host and continue
+            node = shadow._host.asNode();
+            continue;
+        }
+
+        node = n._parent;
+    }
+
+    // Even though the window isn't part of the DOM, most events propagate
+    // through it in the capture phase (unless we stopped at a shadow boundary)
+    // The only explicit exception is "load"
+    if (event._type_string.eql(comptime .wrap("load")) == false) {
+        if (path_len < path_buffer.len) {
+            path_buffer[path_len] = page.window.asEventTarget();
+            path_len += 1;
+        }
+    }
+
+    const path = path_buffer[0..path_len];
+
+    // Phase 1: Capturing phase (root → target, excluding target)
+    // This happens for all events, regardless of bubbling
+    event._event_phase = .capturing_phase;
+    var i: usize = path_len;
+    while (i > 1) {
+        i -= 1;
+        if (event._stop_propagation) return;
+        const current_target = path[i];
+        if (self.lookup.get(.{
+            .event_target = @intFromPtr(current_target),
+            .type_string = event._type_string,
+        })) |list| {
+            try self.dispatchPhase(list, current_target, event, &was_handled, &ls.local, comptime .init(true, opts));
+        }
+    }
+
+    // Phase 2: At target
+    if (event._stop_propagation) return;
+    event._event_phase = .at_target;
+    const target_et = target.asEventTarget();
+
+    blk: {
+        // Get inline handler (e.g., onclick property) for this target
+        if (self.getInlineHandler(target_et, event)) |inline_handler| {
+            was_handled = true;
+            event._current_target = target_et;
+
+            try ls.toLocal(inline_handler).callWithThis(void, target_et, .{event});
+
+            if (event._stop_propagation) {
+                return;
+            }
+
+            if (event._stop_immediate_propagation) {
+                break :blk;
+            }
+        }
+
+        if (self.lookup.get(.{
+            .type_string = event._type_string,
+            .event_target = @intFromPtr(target_et),
+        })) |list| {
+            try self.dispatchPhase(list, target_et, event, &was_handled, &ls.local, comptime .init(null, opts));
+            if (event._stop_propagation) {
+                return;
+            }
+        }
+    }
+
+    // Phase 3: Bubbling phase (target → root, excluding target)
+    // This only happens if the event bubbles
+    if (event._bubbles) {
+        event._event_phase = .bubbling_phase;
+        for (path[1..]) |current_target| {
+            if (event._stop_propagation) break;
+            if (self.lookup.get(.{
+                .type_string = event._type_string,
+                .event_target = @intFromPtr(current_target),
+            })) |list| {
+                try self.dispatchPhase(list, current_target, event, &was_handled, &ls.local, comptime .init(false, opts));
+            }
+        }
+    }
+}
+
+const DispatchPhaseOpts = struct {
+    capture_only: ?bool = null,
+    apply_ignore: bool = false,
+
+    fn init(capture_only: ?bool, opts: DispatchOpts) DispatchPhaseOpts {
+        return .{
+            .capture_only = capture_only,
+            .apply_ignore = opts.apply_ignore,
+        };
+    }
+};
+
+fn dispatchPhase(self: *EventManager, list: *std.DoublyLinkedList, current_target: *EventTarget, event: *Event, was_handled: *bool, local: *const js.Local, comptime opts: DispatchPhaseOpts) !void {
+    const page = self.page;
+
+    // Track dispatch depth for deferred removal
+    self.dispatch_depth += 1;
+    defer {
+        const dispatch_depth = self.dispatch_depth;
+        // Only destroy deferred listeners when we exit the outermost dispatch
+        if (dispatch_depth == 1) {
+            for (self.deferred_removals.items) |removal| {
+                removal.list.remove(&removal.listener.node);
+                self.listener_pool.destroy(removal.listener);
+            }
+            self.deferred_removals.clearRetainingCapacity();
+        } else {
+            self.dispatch_depth = dispatch_depth - 1;
+        }
+    }
+
+    // Use the last listener in the list as sentinel - listeners added during dispatch will be after it
+    const last_node = list.last orelse return;
+    const last_listener: *Listener = @alignCast(@fieldParentPtr("node", last_node));
+
+    // Iterate through the list, stopping after we've encountered the last_listener
+    var node = list.first;
+    var is_done = false;
+    node_loop: while (node) |n| {
+        if (is_done) {
+            break;
+        }
+
+        const listener: *Listener = @alignCast(@fieldParentPtr("node", n));
+        is_done = (listener == last_listener);
+        node = n.next;
+
+        // Skip non-matching listeners
+        if (comptime opts.capture_only) |capture| {
+            if (listener.capture != capture) {
+                continue;
+            }
+        }
+
+        // Skip removed listeners
+        if (listener.removed) {
+            continue;
+        }
+
+        // If the listener has an aborted signal, remove it and skip
+        if (listener.signal) |signal| {
+            if (signal.getAborted()) {
+                self.removeListener(list, listener);
+                continue;
+            }
+        }
+
+        if (comptime opts.apply_ignore) {
+            for (self.ignore_list.items) |ignored| {
+                if (ignored == listener) {
+                    continue :node_loop;
+                }
+            }
+        }
+
+        // Remove "once" listeners BEFORE calling them so nested dispatches don't see them
+        if (listener.once) {
+            self.removeListener(list, listener);
+        }
+
+        was_handled.* = true;
+        event._current_target = current_target;
+
+        // Compute adjusted target for shadow DOM retargeting (only if needed)
+        const original_target = event._target;
+        if (event._needs_retargeting) {
+            event._target = getAdjustedTarget(original_target, current_target);
+        }
+
+        switch (listener.function) {
+            .value => |value| try local.toLocal(value).callWithThis(void, current_target, .{event}),
+            .string => |string| {
+                const str = try page.call_arena.dupeZ(u8, string.str());
+                try local.eval(str, null);
+            },
+            .object => |obj_global| {
+                const obj = local.toLocal(obj_global);
+                if (try obj.getFunction("handleEvent")) |handleEvent| {
+                    try handleEvent.callWithThis(void, obj, .{event});
+                }
+            },
+        }
+
+        // Restore original target (only if we changed it)
+        if (event._needs_retargeting) {
+            event._target = original_target;
+        }
+
+        if (event._stop_immediate_propagation) {
+            return;
+        }
+    }
+}
+
+fn getInlineHandler(self: *EventManager, target: *EventTarget, event: *Event) ?js.Function.Global {
+    const global_event_handlers = @import("webapi/global_event_handlers.zig");
+    const handler_type = global_event_handlers.fromEventType(event._type_string.str()) orelse return null;
+
+    // Look up the inline handler for this target
+    const html_element = switch (target._type) {
+        .node => |n| n.is(Element.Html) orelse return null,
+        else => return null,
+    };
+
+    return html_element.getAttributeFunction(handler_type, self.page) catch |err| {
+        log.warn(.event, "inline html callback", .{ .type = handler_type, .err = err });
+        return null;
+    };
+}
+
+fn removeListener(self: *EventManager, list: *std.DoublyLinkedList, listener: *Listener) void {
+    // If we're in a dispatch, defer removal to avoid invalidating iteration
+    if (self.dispatch_depth > 0) {
+        listener.removed = true;
+        self.deferred_removals.append(self.arena, .{ .list = list, .listener = listener }) catch unreachable;
+    } else {
+        // Outside dispatch, remove immediately
+        list.remove(&listener.node);
+        self.listener_pool.destroy(listener);
+    }
+}
+
+fn findListener(list: *const std.DoublyLinkedList, callback: Callback, capture: bool) ?*Listener {
+    var node = list.first;
+    while (node) |n| {
+        node = n.next;
+        const listener: *Listener = @alignCast(@fieldParentPtr("node", n));
+        const matches = switch (callback) {
+            .object => |obj| listener.function.eqlObject(obj),
+            .function => |func| listener.function.eqlFunction(func),
+        };
+        if (!matches) {
+            continue;
+        }
+        if (listener.capture != capture) {
+            continue;
+        }
+        return listener;
+    }
+    return null;
+}
+
+const Listener = struct {
+    typ: String,
+    once: bool,
+    capture: bool,
+    passive: bool,
+    function: Function,
+    signal: ?*@import("webapi/AbortSignal.zig") = null,
+    node: std.DoublyLinkedList.Node,
+    removed: bool = false,
+};
+
+const Function = union(enum) {
+    value: js.Function.Global,
+    string: String,
+    object: js.Object.Global,
+
+    fn eqlFunction(self: Function, func: js.Function) bool {
+        return switch (self) {
+            .value => |v| v.isEqual(func),
+            else => false,
+        };
+    }
+
+    fn eqlObject(self: Function, obj: js.Object) bool {
+        return switch (self) {
+            .object => |o| return o.isEqual(obj),
+            else => false,
+        };
+    }
+};
+
+// Computes the adjusted target for shadow DOM event retargeting
+// Returns the lowest shadow-including ancestor of original_target that is
+// also an ancestor-or-self of current_target
+fn getAdjustedTarget(original_target: ?*EventTarget, current_target: *EventTarget) ?*EventTarget {
+    const ShadowRoot = @import("webapi/ShadowRoot.zig");
+
+    const orig_node = switch ((original_target orelse return null)._type) {
+        .node => |n| n,
+        else => return original_target,
+    };
+    const curr_node = switch (current_target._type) {
+        .node => |n| n,
+        else => return original_target,
+    };
+
+    // Walk up from original target, checking if we can reach current target
+    var node: ?*Node = orig_node;
+    while (node) |n| {
+        // Check if current_target is an ancestor of n (or n itself)
+        if (isAncestorOrSelf(curr_node, n)) {
+            return n.asEventTarget();
+        }
+
+        // Cross shadow boundary if needed
+        if (n.is(ShadowRoot)) |shadow| {
+            node = shadow._host.asNode();
+            continue;
+        }
+
+        node = n._parent;
+    }
+
+    return original_target;
+}
+
+// Check if ancestor is an ancestor of (or the same as) node
+// WITHOUT crossing shadow boundaries (just regular DOM tree)
+fn isAncestorOrSelf(ancestor: *Node, node: *Node) bool {
+    if (ancestor == node) {
+        return true;
+    }
+
+    var current: ?*Node = node._parent;
+    while (current) |n| {
+        if (n == ancestor) {
+            return true;
+        }
+        current = n._parent;
+    }
+
+    return false;
+}
+
+// Handles the default action for clicking on input checked/radio. Maybe this
+// could be generalized if needed, but I'm not sure. This wasn't obvious to me
+// but when an input is clicked, it's important to think about both the intent
+// and the actual result. Imagine you have an unchecked checkbox. When clicked,
+// the checkbox immediately becomes checked, and event handlers see this "checked"
+// intent. But a listener can preventDefault() in which case the check we did at
+// the start will be undone.
+// This is a bit more complicated for radio buttons, as the checking/unchecking
+// and the rollback can impact a different radio input. So if you "check" a radio
+// the intent is that it becomes checked and whatever was checked before becomes
+// unchecked, so that if you have to rollback (because of a preventDefault())
+// then both inputs have to revert to their original values.
+const ActivationState = struct {
+    old_checked: bool,
+    input: *Element.Html.Input,
+    previously_checked_radio: ?*Input,
+
+    const Input = Element.Html.Input;
+
+    fn create(event: *const Event, target: *Node, page: *Page) ?ActivationState {
+        if (event._type_string.eql(comptime .wrap("click")) == false) {
+            return null;
+        }
+
+        const input = target.is(Element.Html.Input) orelse return null;
+        if (input._input_type != .checkbox and input._input_type != .radio) {
+            return null;
+        }
+
+        const old_checked = input._checked;
+        var previously_checked_radio: ?*Element.Html.Input = null;
+
+        // For radio buttons, find the currently checked radio in the group
+        if (input._input_type == .radio and !old_checked) {
+            previously_checked_radio = try findCheckedRadioInGroup(input, page);
+        }
+
+        // Toggle checkbox or check radio (which unchecks others in group)
+        const new_checked = if (input._input_type == .checkbox) !old_checked else true;
+        try input.setChecked(new_checked, page);
+
+        return .{
+            .input = input,
+            .old_checked = old_checked,
+            .previously_checked_radio = previously_checked_radio,
+        };
+    }
+
+    fn restore(self: *const ActivationState, event: *const Event, page: *Page) void {
+        const input = self.input;
+        if (event._prevent_default) {
+            // Rollback: restore previous state
+            input._checked = self.old_checked;
+            input._checked_dirty = true;
+            if (self.previously_checked_radio) |prev_radio| {
+                prev_radio._checked = true;
+                prev_radio._checked_dirty = true;
+            }
+            return;
+        }
+
+        // Commit: fire input and change events only if state actually changed
+        // and the element is connected to a document (detached elements don't fire).
+        // For checkboxes, state always changes. For radios, only if was unchecked.
+        const state_changed = (input._input_type == .checkbox) or !self.old_checked;
+        if (state_changed and input.asElement().asNode().isConnected()) {
+            fireEvent(page, input, "input") catch |err| {
+                log.warn(.event, "input event", .{ .err = err });
+            };
+            fireEvent(page, input, "change") catch |err| {
+                log.warn(.event, "change event", .{ .err = err });
+            };
+        }
+    }
+
+    fn findCheckedRadioInGroup(input: *Input, page: *Page) !?*Input {
+        const elem = input.asElement();
+
+        const name = elem.getAttributeSafe(comptime .wrap("name")) orelse return null;
+        if (name.len == 0) {
+            return null;
+        }
+
+        const form = input.getForm(page);
+
+        // Walk from the root of the tree containing this element
+        // This handles both document-attached and orphaned elements
+        const root = elem.asNode().getRootNode(null);
+
+        const TreeWalker = @import("webapi/TreeWalker.zig");
+        var walker = TreeWalker.Full.init(root, .{});
+
+        while (walker.next()) |node| {
+            const other_element = node.is(Element) orelse continue;
+            const other_input = other_element.is(Input) orelse continue;
+
+            if (other_input._input_type != .radio) {
+                continue;
+            }
+
+            // Skip the input we're checking from
+            if (other_input == input) {
+                continue;
+            }
+
+            const other_name = other_element.getAttributeSafe(comptime .wrap("name")) orelse continue;
+            if (!std.mem.eql(u8, name, other_name)) {
+                continue;
+            }
+
+            // Check if same form context
+            const other_form = other_input.getForm(page);
+            if (form) |f| {
+                const of = other_form orelse continue;
+                if (f != of) {
+                    continue; // Different forms
+                }
+            } else if (other_form != null) {
+                continue; // form is null but other has a form
+            }
+
+            if (other_input._checked) {
+                return other_input;
+            }
+        }
+
+        return null;
+    }
+
+    // Fire input or change event
+    fn fireEvent(page: *Page, input: *Input, comptime typ: []const u8) !void {
+        const event = try Event.initTrusted(comptime .wrap(typ), .{
+            .bubbles = true,
+            .cancelable = false,
+        }, page);
+
+        const target = input.asElement().asEventTarget();
+        try page._event_manager.dispatch(target, event);
+    }
+};

src/browser/Factory.zig

@@ -0,0 +1,462 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const builtin = @import("builtin");
+const reflect = @import("reflect.zig");
+
+const log = @import("../log.zig");
+const String = @import("../string.zig").String;
+
+const SlabAllocator = @import("../slab.zig").SlabAllocator;
+
+const Page = @import("Page.zig");
+const Node = @import("webapi/Node.zig");
+const Event = @import("webapi/Event.zig");
+const UIEvent = @import("webapi/event/UIEvent.zig");
+const MouseEvent = @import("webapi/event/MouseEvent.zig");
+const Element = @import("webapi/Element.zig");
+const Document = @import("webapi/Document.zig");
+const EventTarget = @import("webapi/EventTarget.zig");
+const XMLHttpRequestEventTarget = @import("webapi/net/XMLHttpRequestEventTarget.zig");
+const Blob = @import("webapi/Blob.zig");
+const AbstractRange = @import("webapi/AbstractRange.zig");
+
+const Allocator = std.mem.Allocator;
+
+const IS_DEBUG = builtin.mode == .Debug;
+const assert = std.debug.assert;
+
+// Shared across all frames of a Page.
+const Factory = @This();
+
+_arena: Allocator,
+_slab: SlabAllocator,
+
+pub fn init(arena: Allocator) Factory {
+    return .{
+        ._arena = arena,
+        ._slab = SlabAllocator.init(arena, 128),
+    };
+}
+
+// this is a root object
+pub fn eventTarget(self: *Factory, child: anytype) !*@TypeOf(child) {
+    return self.eventTargetWithAllocator(self._slab.allocator(), child);
+}
+
+pub fn eventTargetWithAllocator(_: *const Factory, allocator: Allocator, child: anytype) !*@TypeOf(child) {
+    const chain = try PrototypeChain(
+        &.{ EventTarget, @TypeOf(child) },
+    ).allocate(allocator);
+
+    const event_ptr = chain.get(0);
+    event_ptr.* = .{
+        ._type = unionInit(EventTarget.Type, chain.get(1)),
+    };
+    chain.setLeaf(1, child);
+
+    return chain.get(1);
+}
+
+pub fn standaloneEventTarget(self: *Factory, child: anytype) !*EventTarget {
+    const allocator = self._slab.allocator();
+    const et = try allocator.create(EventTarget);
+    et.* = .{ ._type = unionInit(EventTarget.Type, child) };
+    return et;
+}
+
+// this is a root object
+pub fn event(_: *const Factory, arena: Allocator, typ: String, child: anytype) !*@TypeOf(child) {
+    const chain = try PrototypeChain(
+        &.{ Event, @TypeOf(child) },
+    ).allocate(arena);
+
+    // Special case: Event has a _type_string field, so we need manual setup
+    const event_ptr = chain.get(0);
+    event_ptr.* = try eventInit(arena, typ, chain.get(1));
+    chain.setLeaf(1, child);
+
+    return chain.get(1);
+}
+
+pub fn uiEvent(_: *const Factory, arena: Allocator, typ: String, child: anytype) !*@TypeOf(child) {
+    const chain = try PrototypeChain(
+        &.{ Event, UIEvent, @TypeOf(child) },
+    ).allocate(arena);
+
+    // Special case: Event has a _type_string field, so we need manual setup
+    const event_ptr = chain.get(0);
+    event_ptr.* = try eventInit(arena, typ, chain.get(1));
+    chain.setMiddle(1, UIEvent.Type);
+    chain.setLeaf(2, child);
+
+    return chain.get(2);
+}
+
+pub fn mouseEvent(_: *const Factory, arena: Allocator, typ: String, mouse: MouseEvent, child: anytype) !*@TypeOf(child) {
+    const chain = try PrototypeChain(
+        &.{ Event, UIEvent, MouseEvent, @TypeOf(child) },
+    ).allocate(arena);
+
+    // Special case: Event has a _type_string field, so we need manual setup
+    const event_ptr = chain.get(0);
+    event_ptr.* = try eventInit(arena, typ, chain.get(1));
+    chain.setMiddle(1, UIEvent.Type);
+
+    // Set MouseEvent with all its fields
+    const mouse_ptr = chain.get(2);
+    mouse_ptr.* = mouse;
+    mouse_ptr._proto = chain.get(1);
+    mouse_ptr._type = unionInit(MouseEvent.Type, chain.get(3));
+
+    chain.setLeaf(3, child);
+
+    return chain.get(3);
+}
+
+fn PrototypeChain(comptime types: []const type) type {
+    return struct {
+        const Self = @This();
+        memory: []u8,
+
+        fn totalSize() usize {
+            var size: usize = 0;
+            for (types) |T| {
+                size = std.mem.alignForward(usize, size, @alignOf(T));
+                size += @sizeOf(T);
+            }
+            return size;
+        }
+
+        fn maxAlign() std.mem.Alignment {
+            var alignment: std.mem.Alignment = .@"1";
+
+            for (types) |T| {
+                alignment = std.mem.Alignment.max(alignment, std.mem.Alignment.of(T));
+            }
+
+            return alignment;
+        }
+
+        fn getType(comptime index: usize) type {
+            return types[index];
+        }
+
+        fn allocate(allocator: std.mem.Allocator) !Self {
+            const size = comptime Self.totalSize();
+            const alignment = comptime Self.maxAlign();
+
+            const memory = try allocator.alignedAlloc(u8, alignment, size);
+            return .{ .memory = memory };
+        }
+
+        fn get(self: *const Self, comptime index: usize) *getType(index) {
+            var offset: usize = 0;
+            inline for (types, 0..) |T, i| {
+                offset = std.mem.alignForward(usize, offset, @alignOf(T));
+
+                if (i == index) {
+                    return @as(*T, @ptrCast(@alignCast(self.memory.ptr + offset)));
+                }
+                offset += @sizeOf(T);
+            }
+            unreachable;
+        }
+
+        fn set(self: *const Self, comptime index: usize, value: getType(index)) void {
+            const ptr = self.get(index);
+            ptr.* = value;
+        }
+
+        fn setRoot(self: *const Self, comptime T: type) void {
+            const ptr = self.get(0);
+            ptr.* = .{ ._type = unionInit(T, self.get(1)) };
+        }
+
+        fn setMiddle(self: *const Self, comptime index: usize, comptime T: type) void {
+            assert(index >= 1);
+            assert(index < types.len);
+
+            const ptr = self.get(index);
+            ptr.* = .{ ._proto = self.get(index - 1), ._type = unionInit(T, self.get(index + 1)) };
+        }
+
+        fn setMiddleWithValue(self: *const Self, comptime index: usize, comptime T: type, value: anytype) void {
+            assert(index >= 1);
+
+            const ptr = self.get(index);
+            ptr.* = .{ ._proto = self.get(index - 1), ._type = unionInit(T, value) };
+        }
+
+        fn setLeaf(self: *const Self, comptime index: usize, value: anytype) void {
+            assert(index >= 1);
+
+            const ptr = self.get(index);
+            ptr.* = value;
+            ptr._proto = self.get(index - 1);
+        }
+    };
+}
+
+fn AutoPrototypeChain(comptime types: []const type) type {
+    return struct {
+        fn create(allocator: std.mem.Allocator, leaf_value: anytype) !*@TypeOf(leaf_value) {
+            const chain = try PrototypeChain(types).allocate(allocator);
+
+            const RootType = types[0];
+            chain.setRoot(RootType.Type);
+
+            inline for (1..types.len - 1) |i| {
+                const MiddleType = types[i];
+                chain.setMiddle(i, MiddleType.Type);
+            }
+
+            chain.setLeaf(types.len - 1, leaf_value);
+            return chain.get(types.len - 1);
+        }
+    };
+}
+
+fn eventInit(arena: Allocator, typ: String, value: anytype) !Event {
+    // Round to 2ms for privacy (browsers do this)
+    const raw_timestamp = @import("../datetime.zig").milliTimestamp(.monotonic);
+    const time_stamp = (raw_timestamp / 2) * 2;
+
+    return .{
+        ._rc = 0,
+        ._arena = arena,
+        ._type = unionInit(Event.Type, value),
+        ._type_string = typ,
+        ._time_stamp = time_stamp,
+    };
+}
+
+pub fn blob(_: *const Factory, arena: Allocator, child: anytype) !*@TypeOf(child) {
+    // Special case: Blob has slice and mime fields, so we need manual setup
+    const chain = try PrototypeChain(
+        &.{ Blob, @TypeOf(child) },
+    ).allocate(arena);
+
+    const blob_ptr = chain.get(0);
+    blob_ptr.* = .{
+        ._arena = arena,
+        ._type = unionInit(Blob.Type, chain.get(1)),
+        ._slice = "",
+        ._mime = "",
+    };
+    chain.setLeaf(1, child);
+
+    return chain.get(1);
+}
+
+pub fn abstractRange(_: *const Factory, arena: Allocator, child: anytype, page: *Page) !*@TypeOf(child) {
+    const chain = try PrototypeChain(&.{ AbstractRange, @TypeOf(child) }).allocate(arena);
+
+    const doc = page.document.asNode();
+    const abstract_range = chain.get(0);
+    abstract_range.* = AbstractRange{
+        ._rc = 0,
+        ._arena = arena,
+        ._page_id = page.id,
+        ._type = unionInit(AbstractRange.Type, chain.get(1)),
+        ._end_offset = 0,
+        ._start_offset = 0,
+        ._end_container = doc,
+        ._start_container = doc,
+    };
+    chain.setLeaf(1, child);
+    page._live_ranges.append(&abstract_range._range_link);
+    return chain.get(1);
+}
+
+pub fn node(self: *Factory, child: anytype) !*@TypeOf(child) {
+    const allocator = self._slab.allocator();
+    return try AutoPrototypeChain(
+        &.{ EventTarget, Node, @TypeOf(child) },
+    ).create(allocator, child);
+}
+
+pub fn document(self: *Factory, child: anytype) !*@TypeOf(child) {
+    const allocator = self._slab.allocator();
+    return try AutoPrototypeChain(
+        &.{ EventTarget, Node, Document, @TypeOf(child) },
+    ).create(allocator, child);
+}
+
+pub fn documentFragment(self: *Factory, child: anytype) !*@TypeOf(child) {
+    const allocator = self._slab.allocator();
+    return try AutoPrototypeChain(
+        &.{ EventTarget, Node, Node.DocumentFragment, @TypeOf(child) },
+    ).create(allocator, child);
+}
+
+pub fn element(self: *Factory, child: anytype) !*@TypeOf(child) {
+    const allocator = self._slab.allocator();
+    return try AutoPrototypeChain(
+        &.{ EventTarget, Node, Element, @TypeOf(child) },
+    ).create(allocator, child);
+}
+
+pub fn htmlElement(self: *Factory, child: anytype) !*@TypeOf(child) {
+    const allocator = self._slab.allocator();
+    return try AutoPrototypeChain(
+        &.{ EventTarget, Node, Element, Element.Html, @TypeOf(child) },
+    ).create(allocator, child);
+}
+
+pub fn htmlMediaElement(self: *Factory, child: anytype) !*@TypeOf(child) {
+    const allocator = self._slab.allocator();
+    return try AutoPrototypeChain(
+        &.{ EventTarget, Node, Element, Element.Html, Element.Html.Media, @TypeOf(child) },
+    ).create(allocator, child);
+}
+
+pub fn svgElement(self: *Factory, tag_name: []const u8, child: anytype) !*@TypeOf(child) {
+    const allocator = self._slab.allocator();
+    const ChildT = @TypeOf(child);
+
+    if (ChildT == Element.Svg) {
+        return self.element(child);
+    }
+
+    const chain = try PrototypeChain(
+        &.{ EventTarget, Node, Element, Element.Svg, ChildT },
+    ).allocate(allocator);
+
+    chain.setRoot(EventTarget.Type);
+    chain.setMiddle(1, Node.Type);
+    chain.setMiddle(2, Element.Type);
+
+    // will never allocate, can't fail
+    const tag_name_str = String.init(self._arena, tag_name, .{}) catch unreachable;
+
+    // Manually set Element.Svg with the tag_name
+    chain.set(3, .{
+        ._proto = chain.get(2),
+        ._tag_name = tag_name_str,
+        ._type = unionInit(Element.Svg.Type, chain.get(4)),
+    });
+
+    chain.setLeaf(4, child);
+    return chain.get(4);
+}
+
+pub fn xhrEventTarget(_: *const Factory, allocator: Allocator, child: anytype) !*@TypeOf(child) {
+    return try AutoPrototypeChain(
+        &.{ EventTarget, XMLHttpRequestEventTarget, @TypeOf(child) },
+    ).create(allocator, child);
+}
+
+pub fn textTrackCue(self: *Factory, child: anytype) !*@TypeOf(child) {
+    const allocator = self._slab.allocator();
+    const TextTrackCue = @import("webapi/media/TextTrackCue.zig");
+
+    return try AutoPrototypeChain(
+        &.{ EventTarget, TextTrackCue, @TypeOf(child) },
+    ).create(allocator, child);
+}
+
+pub fn destroy(self: *Factory, value: anytype) void {
+    const S = reflect.Struct(@TypeOf(value));
+
+    if (comptime IS_DEBUG) {
+        // We should always destroy from the leaf down.
+        if (@hasDecl(S, "_prototype_root")) {
+            // A Event{._type == .generic} (or any other similar types)
+            // _should_ be destoyed directly. The _type = .generic is a pseudo
+            // child
+            if (S != Event or value._type != .generic) {
+                log.fatal(.bug, "factory.destroy.event", .{ .type = @typeName(S) });
+                unreachable;
+            }
+        }
+    }
+
+    if (comptime @hasField(S, "_proto")) {
+        self.destroyChain(value, 0, std.mem.Alignment.@"1");
+    } else {
+        self.destroyStandalone(value);
+    }
+}
+
+pub fn destroyStandalone(self: *Factory, value: anytype) void {
+    const allocator = self._slab.allocator();
+    allocator.destroy(value);
+}
+
+fn destroyChain(
+    self: *Factory,
+    value: anytype,
+    old_size: usize,
+    old_align: std.mem.Alignment,
+) void {
+    const S = reflect.Struct(@TypeOf(value));
+    const allocator = self._slab.allocator();
+
+    // aligns the old size to the alignment of this element
+    const current_size = std.mem.alignForward(usize, old_size, @alignOf(S));
+    const new_size = current_size + @sizeOf(S);
+    const new_align = std.mem.Alignment.max(old_align, std.mem.Alignment.of(S));
+
+    if (@hasField(S, "_proto")) {
+        self.destroyChain(value._proto, new_size, new_align);
+    } else {
+        // no proto so this is the head of the chain.
+        // we use this as the ptr to the start of the chain.
+        // and we have summed up the length.
+        assert(@hasDecl(S, "_prototype_root"));
+
+        const memory_ptr: [*]u8 = @ptrCast(@constCast(value));
+        const len = std.mem.alignForward(usize, new_size, new_align.toByteUnits());
+        allocator.rawFree(memory_ptr[0..len], new_align, @returnAddress());
+    }
+}
+
+pub fn createT(self: *Factory, comptime T: type) !*T {
+    const allocator = self._slab.allocator();
+    return try allocator.create(T);
+}
+
+pub fn create(self: *Factory, value: anytype) !*@TypeOf(value) {
+    const ptr = try self.createT(@TypeOf(value));
+    ptr.* = value;
+    return ptr;
+}
+
+fn unionInit(comptime T: type, value: anytype) T {
+    const V = @TypeOf(value);
+    const field_name = comptime unionFieldName(T, V);
+    return @unionInit(T, field_name, value);
+}
+
+// There can be friction between comptime and runtime. Comptime has to
+// account for all possible types, even if some runtime flow makes certain
+// cases impossible. At runtime, we always call `unionFieldName` with the
+// correct struct or pointer type. But at comptime time, `unionFieldName`
+// is called with both variants (S and *S). So we use reflect.Struct().
+// This only works because we never have a union with a field S and another
+// field *S.
+fn unionFieldName(comptime T: type, comptime V: type) []const u8 {
+    inline for (@typeInfo(T).@"union".fields) |field| {
+        if (reflect.Struct(field.type) == reflect.Struct(V)) {
+            return field.name;
+        }
+    }
+    @compileError(@typeName(V) ++ " is not a valid type for " ++ @typeName(T) ++ ".type");
+}

src/browser/Mime.zig

@@ -0,0 +1,782 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+
+const Mime = @This();
+content_type: ContentType,
+params: []const u8 = "",
+// IANA defines max. charset value length as 40.
+// We keep 41 for null-termination since HTML parser expects in this format.
+charset: [41]u8 = default_charset,
+charset_len: usize = default_charset_len,
+is_default_charset: bool = true,
+
+/// String "UTF-8" continued by null characters.
+const default_charset = .{ 'U', 'T', 'F', '-', '8' } ++ .{0} ** 36;
+const default_charset_len = 5;
+
+/// Mime with unknown Content-Type, empty params and empty charset.
+pub const unknown = Mime{ .content_type = .{ .unknown = {} } };
+
+pub const ContentTypeEnum = enum {
+    text_xml,
+    text_html,
+    text_javascript,
+    text_plain,
+    text_css,
+    image_jpeg,
+    image_gif,
+    image_png,
+    image_webp,
+    application_json,
+    unknown,
+    other,
+};
+
+pub const ContentType = union(ContentTypeEnum) {
+    text_xml: void,
+    text_html: void,
+    text_javascript: void,
+    text_plain: void,
+    text_css: void,
+    image_jpeg: void,
+    image_gif: void,
+    image_png: void,
+    image_webp: void,
+    application_json: void,
+    unknown: void,
+    other: struct { type: []const u8, sub_type: []const u8 },
+};
+
+pub fn contentTypeString(mime: *const Mime) []const u8 {
+    return switch (mime.content_type) {
+        .text_xml => "text/xml",
+        .text_html => "text/html",
+        .text_javascript => "application/javascript",
+        .text_plain => "text/plain",
+        .text_css => "text/css",
+        .image_jpeg => "image/jpeg",
+        .image_png => "image/png",
+        .image_gif => "image/gif",
+        .image_webp => "image/webp",
+        .application_json => "application/json",
+        else => "",
+    };
+}
+
+/// Returns the null-terminated charset value.
+pub fn charsetStringZ(mime: *const Mime) [:0]const u8 {
+    return mime.charset[0..mime.charset_len :0];
+}
+
+pub fn charsetString(mime: *const Mime) []const u8 {
+    return mime.charset[0..mime.charset_len];
+}
+
+/// Removes quotes of value if quotes are given.
+///
+/// Currently we don't validate the charset.
+/// See section 2.3 Naming Requirements:
+/// https://datatracker.ietf.org/doc/rfc2978/
+fn parseCharset(value: []const u8) error{ CharsetTooBig, Invalid }![]const u8 {
+    // Cannot be larger than 40.
+    // https://datatracker.ietf.org/doc/rfc2978/
+    if (value.len > 40) return error.CharsetTooBig;
+
+    // If the first char is a quote, look for a pair.
+    if (value[0] == '"') {
+        if (value.len < 3 or value[value.len - 1] != '"') {
+            return error.Invalid;
+        }
+
+        return value[1 .. value.len - 1];
+    }
+
+    // No quotes.
+    return value;
+}
+
+pub fn parse(input: []u8) !Mime {
+    if (input.len > 255) {
+        return error.TooBig;
+    }
+
+    // Zig's trim API is broken. The return type is always `[]const u8`,
+    // even if the input type is `[]u8`. @constCast is safe here.
+    var normalized = @constCast(std.mem.trim(u8, input, &std.ascii.whitespace));
+    _ = std.ascii.lowerString(normalized, normalized);
+
+    const content_type, const type_len = try parseContentType(normalized);
+    if (type_len >= normalized.len) {
+        return .{ .content_type = content_type };
+    }
+
+    const params = trimLeft(normalized[type_len..]);
+
+    var charset: [41]u8 = default_charset;
+    var charset_len: usize = default_charset_len;
+    var has_explicit_charset = false;
+
+    var it = std.mem.splitScalar(u8, params, ';');
+    while (it.next()) |attr| {
+        const i = std.mem.indexOfScalarPos(u8, attr, 0, '=') orelse continue;
+        const name = trimLeft(attr[0..i]);
+
+        const value = trimRight(attr[i + 1 ..]);
+        if (value.len == 0) {
+            continue;
+        }
+
+        const attribute_name = std.meta.stringToEnum(enum {
+            charset,
+        }, name) orelse continue;
+
+        switch (attribute_name) {
+            .charset => {
+                if (value.len == 0) {
+                    break;
+                }
+
+                const attribute_value = parseCharset(value) catch continue;
+                @memcpy(charset[0..attribute_value.len], attribute_value);
+                // Null-terminate right after attribute value.
+                charset[attribute_value.len] = 0;
+                charset_len = attribute_value.len;
+                has_explicit_charset = true;
+            },
+        }
+    }
+
+    return .{
+        .params = params,
+        .charset = charset,
+        .charset_len = charset_len,
+        .content_type = content_type,
+        .is_default_charset = !has_explicit_charset,
+    };
+}
+
+/// Prescan the first 1024 bytes of an HTML document for a charset declaration.
+/// Looks for `<meta charset="X">` and `<meta http-equiv="Content-Type" content="...;charset=X">`.
+/// Returns the charset value or null if none found.
+/// See: https://www.w3.org/International/questions/qa-html-encoding-declarations
+pub fn prescanCharset(html: []const u8) ?[]const u8 {
+    const limit = @min(html.len, 1024);
+    const data = html[0..limit];
+
+    // Scan for <meta tags
+    var pos: usize = 0;
+    while (pos < data.len) {
+        // Find next '<'
+        pos = std.mem.indexOfScalarPos(u8, data, pos, '<') orelse return null;
+        pos += 1;
+        if (pos >= data.len) return null;
+
+        // Check for "meta" (case-insensitive)
+        if (pos + 4 >= data.len) return null;
+        var tag_buf: [4]u8 = undefined;
+        _ = std.ascii.lowerString(&tag_buf, data[pos..][0..4]);
+        if (!std.mem.eql(u8, &tag_buf, "meta")) {
+            continue;
+        }
+        pos += 4;
+
+        // Must be followed by whitespace or end of tag
+        if (pos >= data.len) return null;
+        if (data[pos] != ' ' and data[pos] != '\t' and data[pos] != '\n' and
+            data[pos] != '\r' and data[pos] != '/')
+        {
+            continue;
+        }
+
+        // Scan attributes within this meta tag
+        const tag_end = std.mem.indexOfScalarPos(u8, data, pos, '>') orelse return null;
+        const attrs = data[pos..tag_end];
+
+        // Look for charset= attribute directly
+        if (findAttrValue(attrs, "charset")) |charset| {
+            if (charset.len > 0 and charset.len <= 40) return charset;
+        }
+
+        // Look for http-equiv="content-type" with content="...;charset=X"
+        if (findAttrValue(attrs, "http-equiv")) |he| {
+            if (std.ascii.eqlIgnoreCase(he, "content-type")) {
+                if (findAttrValue(attrs, "content")) |content| {
+                    if (extractCharsetFromContentType(content)) |charset| {
+                        return charset;
+                    }
+                }
+            }
+        }
+
+        pos = tag_end + 1;
+    }
+    return null;
+}
+
+fn findAttrValue(attrs: []const u8, name: []const u8) ?[]const u8 {
+    var pos: usize = 0;
+    while (pos < attrs.len) {
+        // Skip whitespace
+        while (pos < attrs.len and (attrs[pos] == ' ' or attrs[pos] == '\t' or
+            attrs[pos] == '\n' or attrs[pos] == '\r'))
+        {
+            pos += 1;
+        }
+        if (pos >= attrs.len) return null;
+
+        // Read attribute name
+        const attr_start = pos;
+        while (pos < attrs.len and attrs[pos] != '=' and attrs[pos] != ' ' and
+            attrs[pos] != '\t' and attrs[pos] != '>' and attrs[pos] != '/')
+        {
+            pos += 1;
+        }
+        const attr_name = attrs[attr_start..pos];
+
+        // Skip whitespace around =
+        while (pos < attrs.len and (attrs[pos] == ' ' or attrs[pos] == '\t')) pos += 1;
+        if (pos >= attrs.len or attrs[pos] != '=') {
+            // No '=' found - skip this token. Advance at least one byte to avoid infinite loop.
+            if (pos == attr_start) pos += 1;
+            continue;
+        }
+        pos += 1; // skip '='
+        while (pos < attrs.len and (attrs[pos] == ' ' or attrs[pos] == '\t')) pos += 1;
+        if (pos >= attrs.len) return null;
+
+        // Read attribute value
+        const value = blk: {
+            if (attrs[pos] == '"' or attrs[pos] == '\'') {
+                const quote = attrs[pos];
+                pos += 1;
+                const val_start = pos;
+                while (pos < attrs.len and attrs[pos] != quote) pos += 1;
+                const val = attrs[val_start..pos];
+                if (pos < attrs.len) pos += 1; // skip closing quote
+                break :blk val;
+            } else {
+                const val_start = pos;
+                while (pos < attrs.len and attrs[pos] != ' ' and attrs[pos] != '\t' and
+                    attrs[pos] != '>' and attrs[pos] != '/')
+                {
+                    pos += 1;
+                }
+                break :blk attrs[val_start..pos];
+            }
+        };
+
+        if (std.ascii.eqlIgnoreCase(attr_name, name)) return value;
+    }
+    return null;
+}
+
+fn extractCharsetFromContentType(content: []const u8) ?[]const u8 {
+    var it = std.mem.splitScalar(u8, content, ';');
+    while (it.next()) |part| {
+        const trimmed = std.mem.trimLeft(u8, part, &.{ ' ', '\t' });
+        if (trimmed.len > 8 and std.ascii.eqlIgnoreCase(trimmed[0..8], "charset=")) {
+            const val = std.mem.trim(u8, trimmed[8..], &.{ ' ', '\t', '"', '\'' });
+            if (val.len > 0 and val.len <= 40) return val;
+        }
+    }
+    return null;
+}
+
+pub fn sniff(body: []const u8) ?Mime {
+    // 0x0C is form feed
+    const content = std.mem.trimLeft(u8, body, &.{ ' ', '\t', '\n', '\r', 0x0C });
+    if (content.len == 0) {
+        return null;
+    }
+
+    if (content[0] != '<') {
+        if (std.mem.startsWith(u8, content, &.{ 0xEF, 0xBB, 0xBF })) {
+            // UTF-8 BOM
+            return .{
+                .content_type = .{ .text_plain = {} },
+                .charset = default_charset,
+                .charset_len = default_charset_len,
+                .is_default_charset = false,
+            };
+        }
+        if (std.mem.startsWith(u8, content, &.{ 0xFE, 0xFF })) {
+            // UTF-16 big-endian BOM
+            return .{
+                .content_type = .{ .text_plain = {} },
+                .charset = .{ 'U', 'T', 'F', '-', '1', '6', 'B', 'E' } ++ .{0} ** 33,
+                .charset_len = 8,
+                .is_default_charset = false,
+            };
+        }
+        if (std.mem.startsWith(u8, content, &.{ 0xFF, 0xFE })) {
+            // UTF-16 little-endian BOM
+            return .{
+                .content_type = .{ .text_plain = {} },
+                .charset = .{ 'U', 'T', 'F', '-', '1', '6', 'L', 'E' } ++ .{0} ** 33,
+                .charset_len = 8,
+                .is_default_charset = false,
+            };
+        }
+        return null;
+    }
+
+    // The longest prefix we have is "<!DOCTYPE HTML ", 15 bytes. If we're
+    // here, we already know content[0] == '<', so we can skip that. So 14
+    // bytes.
+
+    // +1 because we don't need the leading '<'
+    var buf: [14]u8 = undefined;
+
+    const stripped = content[1..];
+    const prefix_len = @min(stripped.len, buf.len);
+    const prefix = std.ascii.lowerString(&buf, stripped[0..prefix_len]);
+
+    // we already know it starts with a <
+    const known_prefixes = [_]struct { []const u8, ContentType }{
+        .{ "!doctype html", .{ .text_html = {} } },
+        .{ "html", .{ .text_html = {} } },
+        .{ "script", .{ .text_html = {} } },
+        .{ "iframe", .{ .text_html = {} } },
+        .{ "h1", .{ .text_html = {} } },
+        .{ "div", .{ .text_html = {} } },
+        .{ "font", .{ .text_html = {} } },
+        .{ "table", .{ .text_html = {} } },
+        .{ "a", .{ .text_html = {} } },
+        .{ "style", .{ .text_html = {} } },
+        .{ "title", .{ .text_html = {} } },
+        .{ "b", .{ .text_html = {} } },
+        .{ "body", .{ .text_html = {} } },
+        .{ "br", .{ .text_html = {} } },
+        .{ "p", .{ .text_html = {} } },
+        .{ "!--", .{ .text_html = {} } },
+        .{ "xml", .{ .text_xml = {} } },
+    };
+    inline for (known_prefixes) |kp| {
+        const known_prefix = kp.@"0";
+        if (std.mem.startsWith(u8, prefix, known_prefix) and prefix.len > known_prefix.len) {
+            const next = prefix[known_prefix.len];
+            // a "tag-terminating-byte"
+            if (next == ' ' or next == '>') {
+                return .{ .content_type = kp.@"1" };
+            }
+        }
+    }
+
+    return null;
+}
+
+pub fn isHTML(self: *const Mime) bool {
+    return self.content_type == .text_html;
+}
+
+pub fn isText(mime: *const Mime) bool {
+    return switch (mime.content_type) {
+        .text_xml, .text_html, .text_javascript, .text_plain, .text_css => true,
+        .application_json => true,
+        else => false,
+    };
+}
+
+// we expect value to be lowercase
+fn parseContentType(value: []const u8) !struct { ContentType, usize } {
+    const end = std.mem.indexOfScalarPos(u8, value, 0, ';') orelse value.len;
+    const type_name = trimRight(value[0..end]);
+    const attribute_start = end + 1;
+
+    if (std.meta.stringToEnum(enum {
+        @"text/xml",
+        @"text/html",
+        @"text/css",
+        @"text/plain",
+
+        @"text/javascript",
+        @"application/javascript",
+        @"application/x-javascript",
+
+        @"image/jpeg",
+        @"image/png",
+        @"image/gif",
+        @"image/webp",
+
+        @"application/json",
+    }, type_name)) |known_type| {
+        const ct: ContentType = switch (known_type) {
+            .@"text/xml" => .{ .text_xml = {} },
+            .@"text/html" => .{ .text_html = {} },
+            .@"text/javascript", .@"application/javascript", .@"application/x-javascript" => .{ .text_javascript = {} },
+            .@"text/plain" => .{ .text_plain = {} },
+            .@"text/css" => .{ .text_css = {} },
+            .@"image/jpeg" => .{ .image_jpeg = {} },
+            .@"image/png" => .{ .image_png = {} },
+            .@"image/gif" => .{ .image_gif = {} },
+            .@"image/webp" => .{ .image_webp = {} },
+            .@"application/json" => .{ .application_json = {} },
+        };
+        return .{ ct, attribute_start };
+    }
+
+    const separator = std.mem.indexOfScalarPos(u8, type_name, 0, '/') orelse return error.Invalid;
+
+    const main_type = value[0..separator];
+    const sub_type = trimRight(value[separator + 1 .. end]);
+
+    if (main_type.len == 0 or validType(main_type) == false) {
+        return error.Invalid;
+    }
+    if (sub_type.len == 0 or validType(sub_type) == false) {
+        return error.Invalid;
+    }
+
+    return .{ .{ .other = .{
+        .type = main_type,
+        .sub_type = sub_type,
+    } }, attribute_start };
+}
+
+const VALID_CODEPOINTS = blk: {
+    var v: [256]bool = undefined;
+    for (0..256) |i| {
+        v[i] = std.ascii.isAlphanumeric(i);
+    }
+    for ("!#$%&\\*+-.^'_`|~") |b| {
+        v[b] = true;
+    }
+    break :blk v;
+};
+
+fn validType(value: []const u8) bool {
+    for (value) |b| {
+        if (VALID_CODEPOINTS[b] == false) {
+            return false;
+        }
+    }
+    return true;
+}
+
+fn trimLeft(s: []const u8) []const u8 {
+    return std.mem.trimLeft(u8, s, &std.ascii.whitespace);
+}
+
+fn trimRight(s: []const u8) []const u8 {
+    return std.mem.trimRight(u8, s, &std.ascii.whitespace);
+}
+
+const testing = @import("../testing.zig");
+test "Mime: invalid" {
+    defer testing.reset();
+
+    const invalids = [_][]const u8{
+        "",
+        "text",
+        "text /html",
+        "text/ html",
+        "text / html",
+        "text/html other",
+    };
+
+    for (invalids) |invalid| {
+        const mutable_input = try testing.arena_allocator.dupe(u8, invalid);
+        try testing.expectError(error.Invalid, Mime.parse(mutable_input));
+    }
+}
+
+test "Mime: malformed parameters are ignored" {
+    defer testing.reset();
+
+    // These should all parse successfully as text/html with malformed params ignored
+    const valid_with_malformed_params = [_][]const u8{
+        "text/html; x",
+        "text/html; x=",
+        "text/html; x=  ",
+        "text/html; = ",
+        "text/html;=",
+        "text/html; charset=\"\"",
+        "text/html; charset=\"",
+        "text/html; charset=\"\\",
+        "text/html;\"",
+    };
+
+    for (valid_with_malformed_params) |input| {
+        const mutable_input = try testing.arena_allocator.dupe(u8, input);
+        const mime = try Mime.parse(mutable_input);
+        try testing.expectEqual(.text_html, std.meta.activeTag(mime.content_type));
+    }
+}
+
+test "Mime: parse common" {
+    defer testing.reset();
+
+    try expect(.{ .content_type = .{ .text_xml = {} } }, "text/xml");
+    try expect(.{ .content_type = .{ .text_html = {} } }, "text/html");
+    try expect(.{ .content_type = .{ .text_plain = {} } }, "text/plain");
+
+    try expect(.{ .content_type = .{ .text_xml = {} } }, "text/xml;");
+    try expect(.{ .content_type = .{ .text_html = {} } }, "text/html;");
+    try expect(.{ .content_type = .{ .text_plain = {} } }, "text/plain;");
+
+    try expect(.{ .content_type = .{ .text_xml = {} } }, "  \ttext/xml");
+    try expect(.{ .content_type = .{ .text_html = {} } }, "text/html   ");
+    try expect(.{ .content_type = .{ .text_plain = {} } }, "text/plain \t\t");
+
+    try expect(.{ .content_type = .{ .text_xml = {} } }, "TEXT/xml");
+    try expect(.{ .content_type = .{ .text_html = {} } }, "text/Html");
+    try expect(.{ .content_type = .{ .text_plain = {} } }, "TEXT/PLAIN");
+
+    try expect(.{ .content_type = .{ .text_xml = {} } }, " TeXT/xml");
+    try expect(.{ .content_type = .{ .text_html = {} } }, "teXt/HtML  ;");
+    try expect(.{ .content_type = .{ .text_plain = {} } }, "tExT/PlAiN;");
+
+    try expect(.{ .content_type = .{ .text_javascript = {} } }, "text/javascript");
+    try expect(.{ .content_type = .{ .text_javascript = {} } }, "Application/JavaScript");
+    try expect(.{ .content_type = .{ .text_javascript = {} } }, "application/x-javascript");
+
+    try expect(.{ .content_type = .{ .application_json = {} } }, "application/json");
+    try expect(.{ .content_type = .{ .text_css = {} } }, "text/css");
+
+    try expect(.{ .content_type = .{ .image_jpeg = {} } }, "image/jpeg");
+    try expect(.{ .content_type = .{ .image_png = {} } }, "image/png");
+    try expect(.{ .content_type = .{ .image_gif = {} } }, "image/gif");
+    try expect(.{ .content_type = .{ .image_webp = {} } }, "image/webp");
+}
+
+test "Mime: parse uncommon" {
+    defer testing.reset();
+
+    const text_csv = Expectation{
+        .content_type = .{ .other = .{ .type = "text", .sub_type = "csv" } },
+    };
+    try expect(text_csv, "text/csv");
+    try expect(text_csv, "text/csv;");
+    try expect(text_csv, "  text/csv\t  ");
+    try expect(text_csv, "  text/csv\t  ;");
+
+    try expect(
+        .{ .content_type = .{ .other = .{ .type = "text", .sub_type = "csv" } } },
+        "Text/CSV",
+    );
+}
+
+test "Mime: parse charset" {
+    defer testing.reset();
+
+    try expect(.{
+        .content_type = .{ .text_xml = {} },
+        .charset = "utf-8",
+        .params = "charset=utf-8",
+    }, "text/xml; charset=utf-8");
+
+    try expect(.{
+        .content_type = .{ .text_xml = {} },
+        .charset = "utf-8",
+        .params = "charset=\"utf-8\"",
+    }, "text/xml;charset=\"UTF-8\"");
+
+    try expect(.{
+        .content_type = .{ .text_html = {} },
+        .charset = "iso-8859-1",
+        .params = "charset=\"iso-8859-1\"",
+    }, "text/html; charset=\"iso-8859-1\"");
+
+    try expect(.{
+        .content_type = .{ .text_html = {} },
+        .charset = "iso-8859-1",
+        .params = "charset=\"iso-8859-1\"",
+    }, "text/html; charset=\"ISO-8859-1\"");
+
+    try expect(.{
+        .content_type = .{ .text_xml = {} },
+        .charset = "custom-non-standard-charset-value",
+        .params = "charset=\"custom-non-standard-charset-value\"",
+    }, "text/xml;charset=\"custom-non-standard-charset-value\"");
+
+    try expect(.{
+        .content_type = .{ .text_html = {} },
+        .charset = "UTF-8",
+        .params = "x=\"",
+    }, "text/html;x=\"");
+}
+
+test "Mime: isHTML" {
+    defer testing.reset();
+
+    const assert = struct {
+        fn assert(expected: bool, input: []const u8) !void {
+            const mutable_input = try testing.arena_allocator.dupe(u8, input);
+            var mime = try Mime.parse(mutable_input);
+            try testing.expectEqual(expected, mime.isHTML());
+        }
+    }.assert;
+    try assert(true, "text/html");
+    try assert(true, "text/html;");
+    try assert(true, "text/html; charset=utf-8");
+    try assert(false, "text/htm"); // htm not html
+    try assert(false, "text/plain");
+    try assert(false, "over/9000");
+}
+
+test "Mime: sniff" {
+    try testing.expectEqual(null, Mime.sniff(""));
+    try testing.expectEqual(null, Mime.sniff("<htm"));
+    try testing.expectEqual(null, Mime.sniff("<html!"));
+    try testing.expectEqual(null, Mime.sniff("<a_"));
+    try testing.expectEqual(null, Mime.sniff("<!doctype html"));
+    try testing.expectEqual(null, Mime.sniff("<!doctype  html>"));
+    try testing.expectEqual(null, Mime.sniff("\n  <!doctype  html>"));
+    try testing.expectEqual(null, Mime.sniff("\n \t <font/>"));
+
+    const expectHTML = struct {
+        fn expect(input: []const u8) !void {
+            try testing.expectEqual(.text_html, std.meta.activeTag(Mime.sniff(input).?.content_type));
+        }
+    }.expect;
+
+    try expectHTML("<!doctype html ");
+    try expectHTML("\n  \t    <!DOCTYPE HTML ");
+
+    try expectHTML("<html ");
+    try expectHTML("\n  \t    <HtmL> even more stufff");
+
+    try expectHTML("<script>");
+    try expectHTML("\n  \t    <SCRIpt >alert(document.cookies)</script>");
+
+    try expectHTML("<iframe>");
+    try expectHTML(" \t    <ifRAME >");
+
+    try expectHTML("<h1>");
+    try expectHTML("  <H1>");
+
+    try expectHTML("<div>");
+    try expectHTML("\n\r\r  <DiV>");
+
+    try expectHTML("<font>");
+    try expectHTML("  <fonT>");
+
+    try expectHTML("<table>");
+    try expectHTML("\t\t<TAblE>");
+
+    try expectHTML("<a>");
+    try expectHTML("\n\n<A>");
+
+    try expectHTML("<style>");
+    try expectHTML("    \n\t <STyLE>");
+
+    try expectHTML("<title>");
+    try expectHTML("    \n\t <TITLE>");
+
+    try expectHTML("<b>");
+    try expectHTML("    \n\t <B>");
+
+    try expectHTML("<body>");
+    try expectHTML("    \n\t <BODY>");
+
+    try expectHTML("<br>");
+    try expectHTML("    \n\t <BR>");
+
+    try expectHTML("<p>");
+    try expectHTML("    \n\t <P>");
+
+    try expectHTML("<!-->");
+    try expectHTML("    \n\t <!-->");
+
+    {
+        const mime = Mime.sniff(&.{ 0xEF, 0xBB, 0xBF }).?;
+        try testing.expectEqual(.text_plain, std.meta.activeTag(mime.content_type));
+        try testing.expectEqual("UTF-8", mime.charsetString());
+    }
+
+    {
+        const mime = Mime.sniff(&.{ 0xFE, 0xFF }).?;
+        try testing.expectEqual(.text_plain, std.meta.activeTag(mime.content_type));
+        try testing.expectEqual("UTF-16BE", mime.charsetString());
+    }
+
+    {
+        const mime = Mime.sniff(&.{ 0xFF, 0xFE }).?;
+        try testing.expectEqual(.text_plain, std.meta.activeTag(mime.content_type));
+        try testing.expectEqual("UTF-16LE", mime.charsetString());
+    }
+}
+
+const Expectation = struct {
+    content_type: Mime.ContentType,
+    params: []const u8 = "",
+    charset: ?[]const u8 = null,
+};
+
+fn expect(expected: Expectation, input: []const u8) !void {
+    const mutable_input = try testing.arena_allocator.dupe(u8, input);
+
+    const actual = try Mime.parse(mutable_input);
+    try testing.expectEqual(
+        std.meta.activeTag(expected.content_type),
+        std.meta.activeTag(actual.content_type),
+    );
+
+    switch (expected.content_type) {
+        .other => |e| {
+            const a = actual.content_type.other;
+            try testing.expectEqual(e.type, a.type);
+            try testing.expectEqual(e.sub_type, a.sub_type);
+        },
+        else => {}, // already asserted above
+    }
+
+    try testing.expectEqual(expected.params, actual.params);
+
+    if (expected.charset) |ec| {
+        // We remove the null characters for testing purposes here.
+        try testing.expectEqual(ec, actual.charsetString());
+    } else {
+        const m: Mime = .unknown;
+        try testing.expectEqual(m.charsetStringZ(), actual.charsetStringZ());
+    }
+}
+
+test "Mime: prescanCharset" {
+    // <meta charset="X">
+    try testing.expectEqual("utf-8", Mime.prescanCharset("<html><head><meta charset=\"utf-8\">").?);
+    try testing.expectEqual("iso-8859-1", Mime.prescanCharset("<html><head><meta charset=\"iso-8859-1\">").?);
+    try testing.expectEqual("shift_jis", Mime.prescanCharset("<meta charset='shift_jis'>").?);
+
+    // Case-insensitive tag matching
+    try testing.expectEqual("utf-8", Mime.prescanCharset("<META charset=\"utf-8\">").?);
+    try testing.expectEqual("utf-8", Mime.prescanCharset("<Meta charset=\"utf-8\">").?);
+
+    // <meta http-equiv="Content-Type" content="text/html; charset=X">
+    try testing.expectEqual(
+        "iso-8859-1",
+        Mime.prescanCharset("<meta http-equiv=\"Content-Type\" content=\"text/html; charset=iso-8859-1\">").?,
+    );
+
+    // No charset found
+    try testing.expectEqual(null, Mime.prescanCharset("<html><head><title>Test</title>"));
+    try testing.expectEqual(null, Mime.prescanCharset(""));
+    try testing.expectEqual(null, Mime.prescanCharset("no html here"));
+
+    // Self-closing meta without charset must not loop forever
+    try testing.expectEqual(null, Mime.prescanCharset("<meta foo=\"bar\"/>"));
+
+    // Charset after 1024 bytes should not be found
+    var long_html: [1100]u8 = undefined;
+    @memset(&long_html, ' ');
+    const suffix = "<meta charset=\"windows-1252\">";
+    @memcpy(long_html[1050 .. 1050 + suffix.len], suffix);
+    try testing.expectEqual(null, Mime.prescanCharset(&long_html));
+}

src/browser/Runner.zig

@@ -0,0 +1,241 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const lp = @import("lightpanda");
+const builtin = @import("builtin");
+
+const log = @import("../log.zig");
+const App = @import("../App.zig");
+
+const Page = @import("Page.zig");
+const Session = @import("Session.zig");
+const Browser = @import("Browser.zig");
+const Factory = @import("Factory.zig");
+const HttpClient = @import("HttpClient.zig");
+
+const IS_DEBUG = builtin.mode == .Debug;
+
+const Runner = @This();
+
+page: *Page,
+session: *Session,
+http_client: *HttpClient,
+
+pub const Opts = struct {};
+
+pub fn init(session: *Session, _: Opts) !Runner {
+    const page = &(session.page orelse return error.NoPage);
+
+    return .{
+        .page = page,
+        .session = session,
+        .http_client = session.browser.http_client,
+    };
+}
+
+pub const WaitOpts = struct {
+    ms: u32,
+    until: lp.Config.WaitUntil = .done,
+};
+pub fn wait(self: *Runner, opts: WaitOpts) !void {
+    _ = try self._wait(false, opts);
+}
+
+pub const CDPWaitResult = enum {
+    done,
+    cdp_socket,
+};
+pub fn waitCDP(self: *Runner, opts: WaitOpts) !CDPWaitResult {
+    return self._wait(true, opts);
+}
+
+fn _wait(self: *Runner, comptime is_cdp: bool, opts: WaitOpts) !CDPWaitResult {
+    var timer = try std.time.Timer.start();
+    var ms_remaining = opts.ms;
+
+    const tick_opts = TickOpts{
+        .ms = 200,
+        .until = opts.until,
+    };
+    while (true) {
+        const tick_result = self._tick(is_cdp, tick_opts) catch |err| {
+            switch (err) {
+                error.JsError => {}, // already logged (with hopefully more context)
+                else => log.err(.browser, "session wait", .{
+                    .err = err,
+                    .url = self.page.url,
+                }),
+            }
+            return err;
+        };
+
+        const next_ms = switch (tick_result) {
+            .ok => |next_ms| next_ms,
+            .done => return .done,
+            .cdp_socket => if (comptime is_cdp) return .cdp_socket else unreachable,
+        };
+
+        const ms_elapsed = timer.lap() / 1_000_000;
+        if (ms_elapsed >= ms_remaining) {
+            return .done;
+        }
+        ms_remaining -= @intCast(ms_elapsed);
+        if (next_ms > 0) {
+            std.Thread.sleep(std.time.ns_per_ms * next_ms);
+        }
+    }
+}
+
+pub const TickOpts = struct {
+    ms: u32,
+    until: lp.Config.WaitUntil = .done,
+};
+
+pub const TickResult = union(enum) {
+    done,
+    ok: u32,
+};
+pub fn tick(self: *Runner, opts: TickOpts) !TickResult {
+    return switch (try self._tick(false, opts)) {
+        .ok => |ms| .{ .ok = ms },
+        .done => .done,
+        .cdp_socket => unreachable,
+    };
+}
+
+pub const CDPTickResult = union(enum) {
+    done,
+    cdp_socket,
+    ok: u32,
+};
+pub fn tickCDP(self: *Runner, opts: TickOpts) !CDPTickResult {
+    return self._tick(true, opts);
+}
+
+fn _tick(self: *Runner, comptime is_cdp: bool, opts: TickOpts) !CDPTickResult {
+    const page = self.page;
+    const http_client = self.http_client;
+
+    switch (page._parse_state) {
+        .pre, .raw, .text, .image => {
+            // The main page hasn't started/finished navigating.
+            // There's no JS to run, and no reason to run the scheduler.
+            if (http_client.active == 0 and (comptime is_cdp) == false) {
+                // haven't started navigating, I guess.
+                return .done;
+            }
+
+            // Either we have active http connections, or we're in CDP
+            // mode with an extra socket. Either way, we're waiting
+            // for http traffic
+            const http_result = try http_client.tick(@intCast(opts.ms));
+            if ((comptime is_cdp) and http_result == .cdp_socket) {
+                return .cdp_socket;
+            }
+            return .{ .ok = 0 };
+        },
+        .html, .complete => {
+            const session = self.session;
+            if (session.queued_navigation.items.len != 0) {
+                try session.processQueuedNavigation();
+                self.page = &session.page.?; // might have changed
+                return .{ .ok = 0 };
+            }
+            const browser = session.browser;
+
+            // The HTML page was parsed. We now either have JS scripts to
+            // download, or scheduled tasks to execute, or both.
+
+            // scheduler.run could trigger new http transfers, so do not
+            // store http_client.active BEFORE this call and then use
+            // it AFTER.
+            try browser.runMacrotasks();
+
+            // Each call to this runs scheduled load events.
+            try page.dispatchLoad();
+
+            const http_active = http_client.active;
+            const total_network_activity = http_active + http_client.intercepted;
+            if (page._notified_network_almost_idle.check(total_network_activity <= 2)) {
+                page.notifyNetworkAlmostIdle();
+            }
+            if (page._notified_network_idle.check(total_network_activity == 0)) {
+                page.notifyNetworkIdle();
+            }
+
+            if (http_active == 0 and (comptime is_cdp == false)) {
+                // we don't need to consider http_client.intercepted here
+                // because is_cdp is true, and that can only be
+                // the case when interception isn't possible.
+                if (comptime IS_DEBUG) {
+                    std.debug.assert(http_client.intercepted == 0);
+                }
+
+                if (browser.hasBackgroundTasks()) {
+                    // _we_ have nothing to run, but v8 is working on
+                    // background tasks. We'll wait for them.
+                    browser.waitForBackgroundTasks();
+                }
+
+                switch (opts.until) {
+                    .done => {},
+                    .domcontentloaded => if (page._load_state == .load or page._load_state == .complete) {
+                        return .done;
+                    },
+                    .load => if (page._load_state == .complete) {
+                        return .done;
+                    },
+                    .networkidle => if (page._notified_network_idle == .done) {
+                        return .done;
+                    },
+                }
+
+                // We never advertise a wait time of more than 20, there can
+                // always be new background tasks to run.
+                if (browser.msToNextMacrotask()) |ms_to_next_task| {
+                    return .{ .ok = @min(ms_to_next_task, 20) };
+                }
+                return .done;
+            }
+
+            // We're here because we either have active HTTP
+            // connections, or is_cdp == false (aka, there's
+            // an cdp_socket registered with the http client).
+            // We should continue to run tasks, so we minimize how long
+            // we'll poll for network I/O.
+            var ms_to_wait = @min(opts.ms, browser.msToNextMacrotask() orelse 200);
+            if (ms_to_wait > 10 and browser.hasBackgroundTasks()) {
+                // if we have background tasks, we don't want to wait too
+                // long for a message from the client. We want to go back
+                // to the top of the loop and run macrotasks.
+                ms_to_wait = 10;
+            }
+            const http_result = try http_client.tick(@intCast(@min(opts.ms, ms_to_wait)));
+            if ((comptime is_cdp) and http_result == .cdp_socket) {
+                return .cdp_socket;
+            }
+            return .{ .ok = 0 };
+        },
+        .err => |err| {
+            page._parse_state = .{ .raw_done = @errorName(err) };
+            return err;
+        },
+        .raw_done => return .done,
+    }
+}

src/browser/Session.zig

@@ -0,0 +1,491 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const lp = @import("lightpanda");
+const builtin = @import("builtin");
+
+const log = @import("../log.zig");
+const App = @import("../App.zig");
+
+const js = @import("js/js.zig");
+const v8 = js.v8;
+const storage = @import("webapi/storage/storage.zig");
+const Navigation = @import("webapi/navigation/Navigation.zig");
+const History = @import("webapi/History.zig");
+
+const Page = @import("Page.zig");
+pub const Runner = @import("Runner.zig");
+const Browser = @import("Browser.zig");
+const Factory = @import("Factory.zig");
+const Notification = @import("../Notification.zig");
+const QueuedNavigation = Page.QueuedNavigation;
+
+const Allocator = std.mem.Allocator;
+const ArenaPool = App.ArenaPool;
+const IS_DEBUG = builtin.mode == .Debug;
+
+// You can create successively multiple pages for a session, but you must
+// deinit a page before running another one. It manages two distinct lifetimes.
+//
+// The first is the lifetime of the Session itself, where pages are created and
+// removed, but share the same cookie jar and navigation history (etc...)
+//
+// The second is as a container the data needed by the full page hierarchy, i.e. \
+// the root page and all of its frames (and all of their frames.)
+const Session = @This();
+
+// These are the fields that remain intact for the duration of the Session
+browser: *Browser,
+arena: Allocator,
+history: History,
+navigation: Navigation,
+storage_shed: storage.Shed,
+notification: *Notification,
+cookie_jar: storage.Cookie.Jar,
+
+// These are the fields that get reset whenever the Session's page (the root) is reset.
+factory: Factory,
+
+page_arena: Allocator,
+
+// Origin map for same-origin context sharing. Scoped to the root page lifetime.
+origins: std.StringHashMapUnmanaged(*js.Origin) = .empty,
+
+// Identity tracking for the main world. All main world contexts share this,
+// ensuring object identity works across same-origin frames.
+identity: js.Identity = .{},
+
+// Shared resources for all pages in this session.
+// These live for the duration of the page tree (root + frames).
+arena_pool: *ArenaPool,
+
+page: ?Page,
+
+// Double buffer so that, as we process one list of queued navigations, new entries
+// are added to the separate buffer. This ensures that we don't end up with
+// endless navigation loops AND that we don't invalidate the list while iterating
+// if a new entry gets appended
+queued_navigation_1: std.ArrayList(*Page),
+queued_navigation_2: std.ArrayList(*Page),
+// pointer to either queued_navigation_1 or queued_navigation_2
+queued_navigation: *std.ArrayList(*Page),
+
+// Temporary buffer for about:blank navigations during processing.
+// We process async navigations first (safe from re-entrance), then sync
+// about:blank navigations (which may add to queued_navigation).
+queued_queued_navigation: std.ArrayList(*Page),
+
+page_id_gen: u32 = 0,
+frame_id_gen: u32 = 0,
+
+pub fn init(self: *Session, browser: *Browser, notification: *Notification) !void {
+    const allocator = browser.app.allocator;
+    const arena_pool = browser.arena_pool;
+
+    const arena = try arena_pool.acquire(.{ .debug = "Session" });
+    errdefer arena_pool.release(arena);
+
+    const page_arena = try arena_pool.acquire(.{ .debug = "Session.page_arena" });
+    errdefer arena_pool.release(page_arena);
+
+    self.* = .{
+        .page = null,
+        .arena = arena,
+        .arena_pool = arena_pool,
+        .page_arena = page_arena,
+        .factory = Factory.init(page_arena),
+        .history = .{},
+        // The prototype (EventTarget) for Navigation is created when a Page is created.
+        .navigation = .{ ._proto = undefined },
+        .storage_shed = .{},
+        .browser = browser,
+        .queued_navigation = undefined,
+        .queued_navigation_1 = .{},
+        .queued_navigation_2 = .{},
+        .queued_queued_navigation = .{},
+        .notification = notification,
+        .cookie_jar = storage.Cookie.Jar.init(allocator),
+    };
+    self.queued_navigation = &self.queued_navigation_1;
+}
+
+pub fn deinit(self: *Session) void {
+    if (self.page != null) {
+        self.removePage();
+    }
+    self.cookie_jar.deinit();
+
+    self.storage_shed.deinit(self.browser.app.allocator);
+    self.arena_pool.release(self.page_arena);
+    self.arena_pool.release(self.arena);
+}
+
+// NOTE: the caller is not the owner of the returned value,
+// the pointer on Page is just returned as a convenience
+pub fn createPage(self: *Session) !*Page {
+    lp.assert(self.page == null, "Session.createPage - page not null", .{});
+
+    self.page = @as(Page, undefined);
+    const page = &self.page.?;
+    try Page.init(page, self.nextFrameId(), self, null);
+
+    // Creates a new NavigationEventTarget for this page.
+    try self.navigation.onNewPage(page);
+
+    if (comptime IS_DEBUG) {
+        log.debug(.browser, "create page", .{});
+    }
+    // start JS env
+    // Inform CDP the main page has been created such that additional context for other Worlds can be created as well
+    self.notification.dispatch(.page_created, page);
+
+    return page;
+}
+
+pub fn removePage(self: *Session) void {
+    // Inform CDP the page is going to be removed, allowing other worlds to remove themselves before the main one
+    self.notification.dispatch(.page_remove, .{});
+    lp.assert(self.page != null, "Session.removePage - page is null", .{});
+
+    self.page.?.deinit(false);
+    self.page = null;
+
+    self.navigation.onRemovePage();
+    self.resetPageResources();
+
+    if (comptime IS_DEBUG) {
+        log.debug(.browser, "remove page", .{});
+    }
+}
+
+pub const GetArenaOpts = struct {
+    debug: []const u8,
+};
+
+pub fn getArena(self: *Session, opts: GetArenaOpts) !Allocator {
+    return self.arena_pool.acquire(.{ .debug = opts.debug });
+}
+
+pub fn releaseArena(self: *Session, allocator: Allocator) void {
+    self.arena_pool.release(allocator);
+}
+
+pub fn getOrCreateOrigin(self: *Session, key_: ?[]const u8) !*js.Origin {
+    const key = key_ orelse {
+        var opaque_origin: [36]u8 = undefined;
+        @import("../id.zig").uuidv4(&opaque_origin);
+        // Origin.init will dupe opaque_origin. It's fine that this doesn't
+        // get added to self.origins. In fact, it further isolates it. When the
+        // context is freed, it'll call session.releaseOrigin which will free it.
+        return js.Origin.init(self.browser.app, self.browser.env.isolate, &opaque_origin);
+    };
+
+    const gop = try self.origins.getOrPut(self.arena, key);
+    if (gop.found_existing) {
+        const origin = gop.value_ptr.*;
+        origin.rc += 1;
+        return origin;
+    }
+
+    errdefer _ = self.origins.remove(key);
+
+    const origin = try js.Origin.init(self.browser.app, self.browser.env.isolate, key);
+    gop.key_ptr.* = origin.key;
+    gop.value_ptr.* = origin;
+    return origin;
+}
+
+pub fn releaseOrigin(self: *Session, origin: *js.Origin) void {
+    const rc = origin.rc;
+    if (rc == 1) {
+        _ = self.origins.remove(origin.key);
+        origin.deinit(self.browser.app);
+    } else {
+        origin.rc = rc - 1;
+    }
+}
+
+/// Reset page_arena and factory for a clean slate.
+/// Called when root page is removed.
+fn resetPageResources(self: *Session) void {
+    self.identity.deinit();
+    self.identity = .{};
+
+    if (comptime IS_DEBUG) {
+        std.debug.assert(self.origins.count() == 0);
+    }
+    // Defensive cleanup in case origins leaked
+    {
+        const app = self.browser.app;
+        var it = self.origins.valueIterator();
+        while (it.next()) |value| {
+            value.*.deinit(app);
+        }
+        self.origins = .empty;
+    }
+
+    self.frame_id_gen = 0;
+    self.arena_pool.reset(self.page_arena, 64 * 1024);
+    self.factory = Factory.init(self.page_arena);
+}
+
+pub fn replacePage(self: *Session) !*Page {
+    if (comptime IS_DEBUG) {
+        log.debug(.browser, "replace page", .{});
+    }
+
+    lp.assert(self.page != null, "Session.replacePage null page", .{});
+    lp.assert(self.page.?.parent == null, "Session.replacePage with parent", .{});
+
+    var current = self.page.?;
+    const frame_id = current._frame_id;
+    current.deinit(true);
+
+    self.resetPageResources();
+    self.browser.env.memoryPressureNotification(.moderate);
+
+    self.page = @as(Page, undefined);
+    const page = &self.page.?;
+    try Page.init(page, frame_id, self, null);
+    return page;
+}
+
+pub fn currentPage(self: *Session) ?*Page {
+    return &(self.page orelse return null);
+}
+
+pub fn findPageByFrameId(self: *Session, frame_id: u32) ?*Page {
+    const page = self.currentPage() orelse return null;
+    return findPageBy(page, "_frame_id", frame_id);
+}
+
+pub fn findPageById(self: *Session, id: u32) ?*Page {
+    const page = self.currentPage() orelse return null;
+    return findPageBy(page, "id", id);
+}
+
+fn findPageBy(page: *Page, comptime field: []const u8, id: u32) ?*Page {
+    if (@field(page, field) == id) return page;
+    for (page.frames.items) |f| {
+        if (findPageBy(f, field, id)) |found| {
+            return found;
+        }
+    }
+    return null;
+}
+
+pub fn runner(self: *Session, opts: Runner.Opts) !Runner {
+    return Runner.init(self, opts);
+}
+
+pub fn scheduleNavigation(self: *Session, page: *Page) !void {
+    const list = self.queued_navigation;
+
+    // Check if page is already queued
+    for (list.items) |existing| {
+        if (existing == page) {
+            // Already queued
+            return;
+        }
+    }
+
+    return list.append(self.arena, page);
+}
+
+pub fn processQueuedNavigation(self: *Session) !void {
+    const navigations = self.queued_navigation;
+    if (self.queued_navigation == &self.queued_navigation_1) {
+        self.queued_navigation = &self.queued_navigation_2;
+    } else {
+        self.queued_navigation = &self.queued_navigation_1;
+    }
+
+    if (self.page.?._queued_navigation != null) {
+        // This is both an optimization and a simplification of sorts. If the
+        // root page is navigating, then we don't need to process any other
+        // navigation. Also, the navigation for the root page and for a frame
+        // is different enough that have two distinct code blocks is, imo,
+        // better. Yes, there will be duplication.
+        navigations.clearRetainingCapacity();
+        return self.processRootQueuedNavigation();
+    }
+
+    const about_blank_queue = &self.queued_queued_navigation;
+    defer about_blank_queue.clearRetainingCapacity();
+
+    // First pass: process async navigations (non-about:blank)
+    for (navigations.items) |page| {
+        const qn = page._queued_navigation.?;
+
+        if (qn.is_about_blank) {
+            // Defer about:blank to second pass
+            try about_blank_queue.append(self.arena, page);
+            continue;
+        }
+
+        self.processFrameNavigation(page, qn) catch |err| {
+            log.warn(.page, "frame navigation", .{ .url = qn.url, .err = err });
+        };
+    }
+
+    navigations.clearRetainingCapacity();
+
+    // Second pass: process synchronous navigations (about:blank)
+    // These may trigger new navigations which go into queued_navigation
+    for (about_blank_queue.items) |page| {
+        const qn = page._queued_navigation.?;
+        try self.processFrameNavigation(page, qn);
+    }
+
+    // Safety: Remove any about:blank navigations that were queued during
+    // processing to prevent infinite loops. New navigations have been queued
+    // in the other buffer.
+    const new_navigations = self.queued_navigation;
+    var i: usize = 0;
+    while (i < new_navigations.items.len) {
+        const page = new_navigations.items[i];
+        if (page._queued_navigation) |qn| {
+            if (qn.is_about_blank) {
+                log.warn(.page, "recursive about blank", .{});
+                _ = self.queued_navigation.swapRemove(i);
+                continue;
+            }
+        }
+        i += 1;
+    }
+}
+
+fn processFrameNavigation(self: *Session, page: *Page, qn: *QueuedNavigation) !void {
+    lp.assert(page.parent != null, "root queued navigation", .{});
+
+    const iframe = page.iframe.?;
+    const parent = page.parent.?;
+
+    page._queued_navigation = null;
+    defer self.releaseArena(qn.arena);
+
+    errdefer iframe._window = null;
+
+    const parent_notified = page._parent_notified;
+    if (parent_notified) {
+        // we already notified the parent that we had loaded
+        parent._pending_loads += 1;
+    }
+
+    const frame_id = page._frame_id;
+    page.deinit(true);
+    page.* = undefined;
+
+    try Page.init(page, frame_id, self, parent);
+    errdefer {
+        for (parent.frames.items, 0..) |frame, i| {
+            if (frame == page) {
+                parent.frames_sorted = false;
+                _ = parent.frames.swapRemove(i);
+                break;
+            }
+        }
+        if (parent_notified) {
+            parent._pending_loads -= 1;
+        }
+        page.deinit(true);
+    }
+
+    page.iframe = iframe;
+    iframe._window = page.window;
+
+    page.navigate(qn.url, qn.opts) catch |err| {
+        log.err(.browser, "queued frame navigation error", .{ .err = err });
+        return err;
+    };
+}
+
+fn processRootQueuedNavigation(self: *Session) !void {
+    const current_page = &self.page.?;
+    const frame_id = current_page._frame_id;
+
+    // create a copy before the page is cleared
+    const qn = current_page._queued_navigation.?;
+    current_page._queued_navigation = null;
+
+    defer self.arena_pool.release(qn.arena);
+
+    self.removePage();
+
+    self.page = @as(Page, undefined);
+    const new_page = &self.page.?;
+    try Page.init(new_page, frame_id, self, null);
+
+    // Creates a new NavigationEventTarget for this page.
+    try self.navigation.onNewPage(new_page);
+
+    // start JS env
+    // Inform CDP the main page has been created such that additional context for other Worlds can be created as well
+    self.notification.dispatch(.page_created, new_page);
+
+    new_page.navigate(qn.url, qn.opts) catch |err| {
+        log.err(.browser, "queued navigation error", .{ .err = err });
+        return err;
+    };
+}
+
+pub fn nextFrameId(self: *Session) u32 {
+    const id = self.frame_id_gen +% 1;
+    self.frame_id_gen = id;
+    return id;
+}
+
+pub fn nextPageId(self: *Session) u32 {
+    const id = self.page_id_gen +% 1;
+    self.page_id_gen = id;
+    return id;
+}
+
+// A type that has a finalizer can have its finalizer called one of two ways.
+// The first is from V8 via the WeakCallback we give to weakRef. But that isn't
+// guaranteed to fire, so we track this in finalizer_callbacks and call them on
+// page reset.
+pub const FinalizerCallback = struct {
+    arena: Allocator,
+    session: *Session,
+    ptr: *anyopaque,
+    global: v8.Global,
+    identity: *js.Identity,
+    zig_finalizer: *const fn (ptr: *anyopaque, session: *Session) void,
+
+    pub fn deinit(self: *FinalizerCallback) void {
+        self.zig_finalizer(self.ptr, self.session);
+        self.session.releaseArena(self.arena);
+    }
+
+    /// Release this item from the identity tracking maps (called after finalizer runs from V8)
+    pub fn releaseIdentity(self: *FinalizerCallback) void {
+        const session = self.session;
+        const id = @intFromPtr(self.ptr);
+
+        if (self.identity.identity_map.fetchRemove(id)) |kv| {
+            var global = kv.value;
+            v8.v8__Global__Reset(&global);
+        }
+
+        _ = self.identity.finalizer_callbacks.remove(id);
+
+        session.releaseArena(self.arena);
+    }
+};

src/browser/StyleManager.zig

@@ -0,0 +1,855 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+
+const log = @import("../log.zig");
+const String = @import("../string.zig").String;
+
+const Page = @import("Page.zig");
+
+const CssParser = @import("css/Parser.zig");
+const Element = @import("webapi/Element.zig");
+
+const Selector = @import("webapi/selector/Selector.zig");
+const SelectorParser = @import("webapi/selector/Parser.zig");
+const SelectorList = @import("webapi/selector/List.zig");
+
+const CSSStyleRule = @import("webapi/css/CSSStyleRule.zig");
+const CSSStyleSheet = @import("webapi/css/CSSStyleSheet.zig");
+const CSSStyleProperties = @import("webapi/css/CSSStyleProperties.zig");
+const CSSStyleProperty = @import("webapi/css/CSSStyleDeclaration.zig").Property;
+
+const Allocator = std.mem.Allocator;
+
+pub const VisibilityCache = std.AutoHashMapUnmanaged(*Element, bool);
+pub const PointerEventsCache = std.AutoHashMapUnmanaged(*Element, bool);
+
+// Tracks visibility-relevant CSS rules from <style> elements.
+// Rules are bucketed by their rightmost selector part for fast lookup.
+const StyleManager = @This();
+
+const Tag = Element.Tag;
+const RuleList = std.MultiArrayList(VisibilityRule);
+
+page: *Page,
+
+arena: Allocator,
+
+// Bucketed rules for fast lookup - keyed by rightmost selector part
+id_rules: std.StringHashMapUnmanaged(RuleList) = .empty,
+class_rules: std.StringHashMapUnmanaged(RuleList) = .empty,
+tag_rules: std.AutoHashMapUnmanaged(Tag, RuleList) = .empty,
+other_rules: RuleList = .empty, // universal, attribute, pseudo-class endings
+
+// Document order counter for tie-breaking equal specificity
+next_doc_order: u32 = 0,
+
+// When true, rules need to be rebuilt
+dirty: bool = false,
+
+pub fn init(page: *Page) !StyleManager {
+    return .{
+        .page = page,
+        .arena = try page.getArena(.{ .debug = "StyleManager" }),
+    };
+}
+
+pub fn deinit(self: *StyleManager) void {
+    self.page.releaseArena(self.arena);
+}
+
+fn parseSheet(self: *StyleManager, sheet: *CSSStyleSheet) !void {
+    if (sheet._css_rules) |css_rules| {
+        for (css_rules._rules.items) |rule| {
+            const style_rule = rule.is(CSSStyleRule) orelse continue;
+            try self.addRule(style_rule);
+        }
+        return;
+    }
+
+    const owner_node = sheet.getOwnerNode() orelse return;
+    if (owner_node.is(Element.Html.Style)) |style| {
+        const text = try style.asNode().getTextContentAlloc(self.arena);
+        var it = CssParser.parseStylesheet(text);
+        while (it.next()) |parsed_rule| {
+            try self.addRawRule(parsed_rule.selector, parsed_rule.block);
+        }
+    }
+}
+
+fn addRawRule(self: *StyleManager, selector_text: []const u8, block_text: []const u8) !void {
+    if (selector_text.len == 0) return;
+
+    var props = VisibilityProperties{};
+    var it = CssParser.parseDeclarationsList(block_text);
+    while (it.next()) |decl| {
+        const name = decl.name;
+        const val = decl.value;
+        if (std.ascii.eqlIgnoreCase(name, "display")) {
+            props.display_none = std.ascii.eqlIgnoreCase(val, "none");
+        } else if (std.ascii.eqlIgnoreCase(name, "visibility")) {
+            props.visibility_hidden = std.ascii.eqlIgnoreCase(val, "hidden") or std.ascii.eqlIgnoreCase(val, "collapse");
+        } else if (std.ascii.eqlIgnoreCase(name, "opacity")) {
+            props.opacity_zero = std.ascii.eqlIgnoreCase(val, "0");
+        } else if (std.ascii.eqlIgnoreCase(name, "pointer-events")) {
+            props.pointer_events_none = std.ascii.eqlIgnoreCase(val, "none");
+        }
+    }
+
+    if (!props.isRelevant()) return;
+
+    const selectors = SelectorParser.parseList(self.arena, selector_text, self.page) catch return;
+    for (selectors) |selector| {
+        const rightmost = if (selector.segments.len > 0) selector.segments[selector.segments.len - 1].compound else selector.first;
+        const bucket_key = getBucketKey(rightmost) orelse continue;
+        const rule = VisibilityRule{
+            .props = props,
+            .selector = selector,
+            .priority = (@as(u64, computeSpecificity(selector)) << 32) | @as(u64, self.next_doc_order),
+        };
+        self.next_doc_order += 1;
+
+        switch (bucket_key) {
+            .id => |id| {
+                const gop = try self.id_rules.getOrPut(self.arena, id);
+                if (!gop.found_existing) gop.value_ptr.* = .{};
+                try gop.value_ptr.append(self.arena, rule);
+            },
+            .class => |class| {
+                const gop = try self.class_rules.getOrPut(self.arena, class);
+                if (!gop.found_existing) gop.value_ptr.* = .{};
+                try gop.value_ptr.append(self.arena, rule);
+            },
+            .tag => |tag| {
+                const gop = try self.tag_rules.getOrPut(self.arena, tag);
+                if (!gop.found_existing) gop.value_ptr.* = .{};
+                try gop.value_ptr.append(self.arena, rule);
+            },
+            .other => {
+                try self.other_rules.append(self.arena, rule);
+            },
+        }
+    }
+}
+
+pub fn sheetRemoved(self: *StyleManager) void {
+    self.dirty = true;
+}
+
+pub fn sheetModified(self: *StyleManager) void {
+    self.dirty = true;
+}
+
+/// Rebuilds the rule list from all document stylesheets.
+/// Called lazily when dirty flag is set and rules are needed.
+fn rebuildIfDirty(self: *StyleManager) !void {
+    if (!self.dirty) {
+        return;
+    }
+
+    self.dirty = false;
+    errdefer self.dirty = true;
+    const id_rules_count = self.id_rules.count();
+    const class_rules_count = self.class_rules.count();
+    const tag_rules_count = self.tag_rules.count();
+    const other_rules_count = self.other_rules.len;
+
+    self.page._session.arena_pool.resetRetain(self.arena);
+
+    self.next_doc_order = 0;
+
+    self.id_rules = .empty;
+    try self.id_rules.ensureTotalCapacity(self.arena, id_rules_count);
+
+    self.class_rules = .empty;
+    try self.class_rules.ensureTotalCapacity(self.arena, class_rules_count);
+
+    self.tag_rules = .empty;
+    try self.tag_rules.ensureTotalCapacity(self.arena, tag_rules_count);
+
+    self.other_rules = .{};
+    try self.other_rules.ensureTotalCapacity(self.arena, other_rules_count);
+
+    const sheets = self.page.document._style_sheets orelse return;
+    for (sheets._sheets.items) |sheet| {
+        self.parseSheet(sheet) catch |err| {
+            log.err(.browser, "StyleManager parseSheet", .{ .err = err });
+            return err;
+        };
+    }
+}
+
+// Check if an element is hidden based on options.
+// By default only checks display:none.
+// Walks up the tree to check ancestors.
+pub fn isHidden(self: *StyleManager, el: *Element, cache: ?*VisibilityCache, options: CheckVisibilityOptions) bool {
+    self.rebuildIfDirty() catch return false;
+
+    var current: ?*Element = el;
+
+    while (current) |elem| {
+        // Check cache first (only when checking all properties for caching consistency)
+        if (cache) |c| {
+            if (c.get(elem)) |hidden| {
+                if (hidden) {
+                    return true;
+                }
+                current = elem.parentElement();
+                continue;
+            }
+        }
+
+        const hidden = self.isElementHidden(elem, options);
+
+        // Store in cache
+        if (cache) |c| {
+            c.put(self.page.call_arena, elem, hidden) catch {};
+        }
+
+        if (hidden) {
+            return true;
+        }
+        current = elem.parentElement();
+    }
+
+    return false;
+}
+
+/// Check if a single element (not ancestors) is hidden.
+fn isElementHidden(self: *StyleManager, el: *Element, options: CheckVisibilityOptions) bool {
+    // Track best match per property (value + priority)
+    // Initialize priority to INLINE_PRIORITY for properties we don't care about - this makes
+    // the loop naturally skip them since no stylesheet rule can have priority >= INLINE_PRIORITY
+    var display_none: ?bool = null;
+    var display_priority: u64 = 0;
+
+    var visibility_hidden: ?bool = null;
+    var visibility_priority: u64 = 0;
+
+    var opacity_zero: ?bool = null;
+    var opacity_priority: u64 = 0;
+
+    // Check inline styles FIRST - they use INLINE_PRIORITY so no stylesheet can beat them
+    if (getInlineStyleProperty(el, comptime .wrap("display"), self.page)) |property| {
+        if (property._value.eql(comptime .wrap("none"))) {
+            return true; // Early exit for hiding value
+        }
+        display_none = false;
+        display_priority = INLINE_PRIORITY;
+    }
+
+    if (options.check_visibility) {
+        if (getInlineStyleProperty(el, comptime .wrap("visibility"), self.page)) |property| {
+            if (property._value.eql(comptime .wrap("hidden")) or property._value.eql(comptime .wrap("collapse"))) {
+                return true;
+            }
+            visibility_hidden = false;
+            visibility_priority = INLINE_PRIORITY;
+        }
+    } else {
+        // This can't be beat. Setting this means that, when checking rules
+        // we no longer have to check if options.check_visibility is enabled.
+        // We can just compare the priority.
+        visibility_priority = INLINE_PRIORITY;
+    }
+
+    if (options.check_opacity) {
+        if (getInlineStyleProperty(el, comptime .wrap("opacity"), self.page)) |property| {
+            if (property._value.eql(comptime .wrap("0"))) {
+                return true;
+            }
+            opacity_zero = false;
+            opacity_priority = INLINE_PRIORITY;
+        }
+    } else {
+        opacity_priority = INLINE_PRIORITY;
+    }
+
+    if (display_priority == INLINE_PRIORITY and visibility_priority == INLINE_PRIORITY and opacity_priority == INLINE_PRIORITY) {
+        return false;
+    }
+
+    // Helper to check a single rule
+    const Ctx = struct {
+        display_none: *?bool,
+        display_priority: *u64,
+        visibility_hidden: *?bool,
+        visibility_priority: *u64,
+        opacity_zero: *?bool,
+        opacity_priority: *u64,
+        el: *Element,
+        page: *Page,
+
+        fn checkRules(ctx: @This(), rules: *const RuleList) void {
+            if (ctx.display_priority.* == INLINE_PRIORITY and
+                ctx.visibility_priority.* == INLINE_PRIORITY and
+                ctx.opacity_priority.* == INLINE_PRIORITY)
+            {
+                return;
+            }
+
+            const priorities = rules.items(.priority);
+            const props_list = rules.items(.props);
+            const selectors = rules.items(.selector);
+
+            for (priorities, props_list, selectors) |p, props, selector| {
+                // Fast skip using packed u64 priority
+                if (p <= ctx.display_priority.* and p <= ctx.visibility_priority.* and p <= ctx.opacity_priority.*) {
+                    continue;
+                }
+
+                // Logic for property dominance
+                const dominated = (props.display_none == null or p <= ctx.display_priority.*) and
+                    (props.visibility_hidden == null or p <= ctx.visibility_priority.*) and
+                    (props.opacity_zero == null or p <= ctx.opacity_priority.*);
+
+                if (dominated) continue;
+
+                if (matchesSelector(ctx.el, selector, ctx.page)) {
+                    // Update best priorities
+                    if (props.display_none != null and p > ctx.display_priority.*) {
+                        ctx.display_none.* = props.display_none;
+                        ctx.display_priority.* = p;
+                    }
+                    if (props.visibility_hidden != null and p > ctx.visibility_priority.*) {
+                        ctx.visibility_hidden.* = props.visibility_hidden;
+                        ctx.visibility_priority.* = p;
+                    }
+                    if (props.opacity_zero != null and p > ctx.opacity_priority.*) {
+                        ctx.opacity_zero.* = props.opacity_zero;
+                        ctx.opacity_priority.* = p;
+                    }
+                }
+            }
+        }
+    };
+    const ctx = Ctx{
+        .display_none = &display_none,
+        .display_priority = &display_priority,
+        .visibility_hidden = &visibility_hidden,
+        .visibility_priority = &visibility_priority,
+        .opacity_zero = &opacity_zero,
+        .opacity_priority = &opacity_priority,
+        .el = el,
+        .page = self.page,
+    };
+
+    if (el.getAttributeSafe(comptime .wrap("id"))) |id| {
+        if (self.id_rules.get(id)) |rules| {
+            ctx.checkRules(&rules);
+        }
+    }
+
+    if (el.getAttributeSafe(comptime .wrap("class"))) |class_attr| {
+        var it = std.mem.tokenizeAny(u8, class_attr, &std.ascii.whitespace);
+        while (it.next()) |class| {
+            if (self.class_rules.get(class)) |rules| {
+                ctx.checkRules(&rules);
+            }
+        }
+    }
+
+    if (self.tag_rules.get(el.getTag())) |rules| {
+        ctx.checkRules(&rules);
+    }
+
+    ctx.checkRules(&self.other_rules);
+
+    return (display_none orelse false) or (visibility_hidden orelse false) or (opacity_zero orelse false);
+}
+
+/// Check if an element has pointer-events:none.
+/// Checks inline style first - if set, skips stylesheet lookup.
+/// Walks up the tree to check ancestors.
+pub fn hasPointerEventsNone(self: *StyleManager, el: *Element, cache: ?*PointerEventsCache) bool {
+    self.rebuildIfDirty() catch return false;
+
+    var current: ?*Element = el;
+
+    while (current) |elem| {
+        // Check cache first
+        if (cache) |c| {
+            if (c.get(elem)) |pe_none| {
+                if (pe_none) return true;
+                current = elem.parentElement();
+                continue;
+            }
+        }
+
+        const pe_none = self.elementHasPointerEventsNone(elem);
+
+        if (cache) |c| {
+            c.put(self.page.call_arena, elem, pe_none) catch {};
+        }
+
+        if (pe_none) {
+            return true;
+        }
+        current = elem.parentElement();
+    }
+
+    return false;
+}
+
+/// Check if a single element (not ancestors) has pointer-events:none.
+fn elementHasPointerEventsNone(self: *StyleManager, el: *Element) bool {
+    const page = self.page;
+
+    // Check inline style first
+    if (getInlineStyleProperty(el, .wrap("pointer-events"), page)) |property| {
+        if (property._value.eql(comptime .wrap("none"))) {
+            return true;
+        }
+        return false;
+    }
+
+    var result: ?bool = null;
+    var best_priority: u64 = 0;
+
+    // Helper to check a single rule
+    const checkRules = struct {
+        fn check(rules: *const RuleList, res: *?bool, current_priority: *u64, elem: *Element, p: *Page) void {
+            if (current_priority.* == INLINE_PRIORITY) return;
+
+            const priorities = rules.items(.priority);
+            const props_list = rules.items(.props);
+            const selectors = rules.items(.selector);
+
+            for (priorities, props_list, selectors) |priority, props, selector| {
+                if (priority <= current_priority.*) continue;
+                if (props.pointer_events_none == null) continue;
+
+                if (matchesSelector(elem, selector, p)) {
+                    res.* = props.pointer_events_none;
+                    current_priority.* = priority;
+                }
+            }
+        }
+    }.check;
+
+    if (el.getAttributeSafe(comptime .wrap("id"))) |id| {
+        if (self.id_rules.get(id)) |rules| {
+            checkRules(&rules, &result, &best_priority, el, page);
+        }
+    }
+
+    if (el.getAttributeSafe(comptime .wrap("class"))) |class_attr| {
+        var it = std.mem.tokenizeAny(u8, class_attr, &std.ascii.whitespace);
+        while (it.next()) |class| {
+            if (self.class_rules.get(class)) |rules| {
+                checkRules(&rules, &result, &best_priority, el, page);
+            }
+        }
+    }
+
+    if (self.tag_rules.get(el.getTag())) |rules| {
+        checkRules(&rules, &result, &best_priority, el, page);
+    }
+
+    checkRules(&self.other_rules, &result, &best_priority, el, page);
+
+    return result orelse false;
+}
+
+// Extracts visibility-relevant rules from a CSS rule.
+// Creates one VisibilityRule per selector (not per selector list) so each has correct specificity.
+// Buckets rules by their rightmost selector part for fast lookup.
+fn addRule(self: *StyleManager, style_rule: *CSSStyleRule) !void {
+    const selector_text = style_rule._selector_text;
+    if (selector_text.len == 0) {
+        return;
+    }
+
+    // Check if the rule has visibility-relevant properties
+    const style = style_rule._style orelse return;
+    const props = extractVisibilityProperties(style);
+    if (!props.isRelevant()) {
+        return;
+    }
+
+    // Parse the selector list
+    const selectors = SelectorParser.parseList(self.arena, selector_text, self.page) catch return;
+    if (selectors.len == 0) {
+        return;
+    }
+
+    // Create one rule per selector - each has its own specificity
+    // e.g., "#id, .class { display: none }" becomes two rules with different specificities
+    for (selectors) |selector| {
+        // Get the rightmost compound (last segment, or first if no segments)
+        const rightmost = if (selector.segments.len > 0)
+            selector.segments[selector.segments.len - 1].compound
+        else
+            selector.first;
+
+        // Find the bucketing key from rightmost compound
+        const bucket_key = getBucketKey(rightmost) orelse continue; // skip if dynamic pseudo-class
+
+        const rule = VisibilityRule{
+            .props = props,
+            .selector = selector,
+            .priority = (@as(u64, computeSpecificity(selector)) << 32) | @as(u64, self.next_doc_order),
+        };
+        self.next_doc_order += 1;
+
+        // Add to appropriate bucket
+        switch (bucket_key) {
+            .id => |id| {
+                const gop = try self.id_rules.getOrPut(self.arena, id);
+                if (!gop.found_existing) gop.value_ptr.* = .{};
+                try gop.value_ptr.append(self.arena, rule);
+            },
+            .class => |class| {
+                const gop = try self.class_rules.getOrPut(self.arena, class);
+                if (!gop.found_existing) gop.value_ptr.* = .{};
+                try gop.value_ptr.append(self.arena, rule);
+            },
+            .tag => |tag| {
+                const gop = try self.tag_rules.getOrPut(self.arena, tag);
+                if (!gop.found_existing) gop.value_ptr.* = .{};
+                try gop.value_ptr.append(self.arena, rule);
+            },
+            .other => {
+                try self.other_rules.append(self.arena, rule);
+            },
+        }
+    }
+}
+
+const BucketKey = union(enum) {
+    id: []const u8,
+    class: []const u8,
+    tag: Tag,
+    other,
+};
+
+/// Returns the best bucket key for a compound selector, or null if it contains
+/// a dynamic pseudo-class we should skip (hover, active, focus, etc.)
+/// Priority: id > class > tag > other
+fn getBucketKey(compound: Selector.Compound) ?BucketKey {
+    var best_key: BucketKey = .other;
+
+    for (compound.parts) |part| {
+        switch (part) {
+            .id => |id| {
+                best_key = .{ .id = id };
+            },
+            .class => |class| {
+                if (best_key != .id) {
+                    best_key = .{ .class = class };
+                }
+            },
+            .tag => |tag| {
+                if (best_key == .other) {
+                    best_key = .{ .tag = tag };
+                }
+            },
+            .tag_name => {
+                // Custom tag - put in other bucket (can't efficiently look up)
+                // Keep current best_key if we have something better
+            },
+            .pseudo_class => |pc| {
+                // Skip dynamic pseudo-classes - they depend on interaction state
+                switch (pc) {
+                    .hover, .active, .focus, .focus_within, .focus_visible, .visited, .target => {
+                        return null; // Skip this selector entirely
+                    },
+                    else => {},
+                }
+            },
+            .universal, .attribute => {},
+        }
+    }
+
+    return best_key;
+}
+
+/// Extracts visibility-relevant properties from a style declaration.
+fn extractVisibilityProperties(style: *CSSStyleProperties) VisibilityProperties {
+    var props = VisibilityProperties{};
+    const decl = style.asCSSStyleDeclaration();
+
+    if (decl.findProperty(comptime .wrap("display"))) |property| {
+        props.display_none = property._value.eql(comptime .wrap("none"));
+    }
+
+    if (decl.findProperty(comptime .wrap("visibility"))) |property| {
+        props.visibility_hidden = property._value.eql(comptime .wrap("hidden")) or property._value.eql(comptime .wrap("collapse"));
+    }
+
+    if (decl.findProperty(comptime .wrap("opacity"))) |property| {
+        props.opacity_zero = property._value.eql(comptime .wrap("0"));
+    }
+
+    if (decl.findProperty(.wrap("pointer-events"))) |property| {
+        props.pointer_events_none = property._value.eql(comptime .wrap("none"));
+    }
+
+    return props;
+}
+
+// Computes CSS specificity for a selector.
+// Returns packed value: (id_count << 20) | (class_count << 10) | element_count
+pub fn computeSpecificity(selector: Selector.Selector) u32 {
+    var ids: u32 = 0;
+    var classes: u32 = 0; // includes classes, attributes, pseudo-classes
+    var elements: u32 = 0; // includes elements, pseudo-elements
+
+    // Count specificity for first compound
+    countCompoundSpecificity(selector.first, &ids, &classes, &elements);
+
+    // Count specificity for subsequent segments
+    for (selector.segments) |segment| {
+        countCompoundSpecificity(segment.compound, &ids, &classes, &elements);
+    }
+
+    // Pack into single u32: (ids << 20) | (classes << 10) | elements
+    // This gives us 10 bits each, supporting up to 1023 of each type
+    return (@as(u32, @min(ids, 1023)) << 20) | (@as(u32, @min(classes, 1023)) << 10) | @min(elements, 1023);
+}
+
+fn countCompoundSpecificity(compound: Selector.Compound, ids: *u32, classes: *u32, elements: *u32) void {
+    for (compound.parts) |part| {
+        switch (part) {
+            .id => ids.* += 1,
+            .class => classes.* += 1,
+            .tag, .tag_name => elements.* += 1,
+            .universal => {}, // zero specificity
+            .attribute => classes.* += 1,
+            .pseudo_class => |pc| {
+                switch (pc) {
+                    // :where() has zero specificity
+                    .where => {},
+                    // :not(), :is(), :has() take specificity of their most specific argument
+                    .not, .is, .has => |nested| {
+                        var max_nested: u32 = 0;
+                        for (nested) |nested_sel| {
+                            const spec = computeSpecificity(nested_sel);
+                            if (spec > max_nested) max_nested = spec;
+                        }
+                        // Unpack and add to our counts
+                        ids.* += (max_nested >> 20) & 0x3FF;
+                        classes.* += (max_nested >> 10) & 0x3FF;
+                        elements.* += max_nested & 0x3FF;
+                    },
+                    // All other pseudo-classes count as class-level specificity
+                    else => classes.* += 1,
+                }
+            },
+        }
+    }
+}
+
+fn matchesSelector(el: *Element, selector: Selector.Selector, page: *Page) bool {
+    const node = el.asNode();
+    return SelectorList.matches(node, selector, node, page);
+}
+
+const VisibilityProperties = struct {
+    display_none: ?bool = null,
+    visibility_hidden: ?bool = null,
+    opacity_zero: ?bool = null,
+    pointer_events_none: ?bool = null,
+
+    // returne true if any field in VisibilityProperties is not null
+    fn isRelevant(self: VisibilityProperties) bool {
+        return self.display_none != null or
+            self.visibility_hidden != null or
+            self.opacity_zero != null or
+            self.pointer_events_none != null;
+    }
+};
+
+const VisibilityRule = struct {
+    selector: Selector.Selector, // Single selector, not a list
+    props: VisibilityProperties,
+
+    // Packed priority: (specificity << 32) | doc_order
+    priority: u64,
+};
+
+const CheckVisibilityOptions = struct {
+    check_opacity: bool = false,
+    check_visibility: bool = false,
+};
+
+// Inline styles always win over stylesheets - use max u64 as sentinel
+const INLINE_PRIORITY: u64 = std.math.maxInt(u64);
+
+fn getInlineStyleProperty(el: *Element, property_name: String, page: *Page) ?*CSSStyleProperty {
+    const style = el.getOrCreateStyle(page) catch |err| {
+        log.err(.browser, "StyleManager getOrCreateStyle", .{ .err = err });
+        return null;
+    };
+    return style.asCSSStyleDeclaration().findProperty(property_name);
+}
+
+const testing = @import("../testing.zig");
+test "StyleManager: computeSpecificity: element selector" {
+    // div -> (0, 0, 1)
+    const selector = Selector.Selector{
+        .first = .{ .parts = &.{.{ .tag = .div }} },
+        .segments = &.{},
+    };
+    try testing.expectEqual(1, computeSpecificity(selector));
+}
+
+test "StyleManager: computeSpecificity: class selector" {
+    // .foo -> (0, 1, 0)
+    const selector = Selector.Selector{
+        .first = .{ .parts = &.{.{ .class = "foo" }} },
+        .segments = &.{},
+    };
+    try testing.expectEqual(1 << 10, computeSpecificity(selector));
+}
+
+test "StyleManager: computeSpecificity: id selector" {
+    // #bar -> (1, 0, 0)
+    const selector = Selector.Selector{
+        .first = .{ .parts = &.{.{ .id = "bar" }} },
+        .segments = &.{},
+    };
+    try testing.expectEqual(1 << 20, computeSpecificity(selector));
+}
+
+test "StyleManager: computeSpecificity: combined selector" {
+    // div.foo#bar -> (1, 1, 1)
+    const selector = Selector.Selector{
+        .first = .{ .parts = &.{
+            .{ .tag = .div },
+            .{ .class = "foo" },
+            .{ .id = "bar" },
+        } },
+        .segments = &.{},
+    };
+    try testing.expectEqual((1 << 20) | (1 << 10) | 1, computeSpecificity(selector));
+}
+
+test "StyleManager: computeSpecificity: universal selector" {
+    // * -> (0, 0, 0)
+    const selector = Selector.Selector{
+        .first = .{ .parts = &.{.universal} },
+        .segments = &.{},
+    };
+    try testing.expectEqual(0, computeSpecificity(selector));
+}
+
+test "StyleManager: computeSpecificity: multiple classes" {
+    // .a.b.c -> (0, 3, 0)
+    const selector = Selector.Selector{
+        .first = .{ .parts = &.{
+            .{ .class = "a" },
+            .{ .class = "b" },
+            .{ .class = "c" },
+        } },
+        .segments = &.{},
+    };
+    try testing.expectEqual(3 << 10, computeSpecificity(selector));
+}
+
+test "StyleManager: computeSpecificity: descendant combinator" {
+    // div span -> (0, 0, 2)
+    const selector = Selector.Selector{
+        .first = .{ .parts = &.{.{ .tag = .div }} },
+        .segments = &.{
+            .{ .combinator = .descendant, .compound = .{ .parts = &.{.{ .tag = .span }} } },
+        },
+    };
+    try testing.expectEqual(2, computeSpecificity(selector));
+}
+
+test "StyleManager: computeSpecificity: :where() has zero specificity" {
+    // :where(.foo) -> (0, 0, 0) regardless of what's inside
+    const inner_selector = Selector.Selector{
+        .first = .{ .parts = &.{.{ .class = "foo" }} },
+        .segments = &.{},
+    };
+    const selector = Selector.Selector{
+        .first = .{ .parts = &.{
+            .{ .pseudo_class = .{ .where = &.{inner_selector} } },
+        } },
+        .segments = &.{},
+    };
+    try testing.expectEqual(0, computeSpecificity(selector));
+}
+
+test "StyleManager: computeSpecificity: :not() takes inner specificity" {
+    // :not(.foo) -> (0, 1, 0) - takes specificity of .foo
+    const inner_selector = Selector.Selector{
+        .first = .{ .parts = &.{.{ .class = "foo" }} },
+        .segments = &.{},
+    };
+    const selector = Selector.Selector{
+        .first = .{ .parts = &.{
+            .{ .pseudo_class = .{ .not = &.{inner_selector} } },
+        } },
+        .segments = &.{},
+    };
+    try testing.expectEqual(1 << 10, computeSpecificity(selector));
+}
+
+test "StyleManager: computeSpecificity: :is() takes most specific inner" {
+    // :is(.foo, #bar) -> (1, 0, 0) - takes the most specific (#bar)
+    const class_selector = Selector.Selector{
+        .first = .{ .parts = &.{.{ .class = "foo" }} },
+        .segments = &.{},
+    };
+    const id_selector = Selector.Selector{
+        .first = .{ .parts = &.{.{ .id = "bar" }} },
+        .segments = &.{},
+    };
+    const selector = Selector.Selector{
+        .first = .{ .parts = &.{
+            .{ .pseudo_class = .{ .is = &.{ class_selector, id_selector } } },
+        } },
+        .segments = &.{},
+    };
+    try testing.expectEqual(1 << 20, computeSpecificity(selector));
+}
+
+test "StyleManager: computeSpecificity: pseudo-class (general)" {
+    // :hover -> (0, 1, 0) - pseudo-classes count as class-level
+    const selector = Selector.Selector{
+        .first = .{ .parts = &.{
+            .{ .pseudo_class = .hover },
+        } },
+        .segments = &.{},
+    };
+    try testing.expectEqual(1 << 10, computeSpecificity(selector));
+}
+
+test "StyleManager: document order tie-breaking" {
+    // When specificity is equal, higher doc_order (later in document) wins
+    const beats = struct {
+        fn f(spec: u32, doc_order: u32, best_spec: u32, best_doc_order: u32) bool {
+            return spec > best_spec or (spec == best_spec and doc_order > best_doc_order);
+        }
+    }.f;
+
+    // Higher specificity always wins regardless of doc_order
+    try testing.expect(beats(2, 0, 1, 10));
+    try testing.expect(!beats(1, 10, 2, 0));
+
+    // Equal specificity: higher doc_order wins
+    try testing.expect(beats(1, 5, 1, 3)); // doc_order 5 > 3
+    try testing.expect(!beats(1, 3, 1, 5)); // doc_order 3 < 5
+
+    // Equal specificity and doc_order: no win
+    try testing.expect(!beats(1, 5, 1, 5));
+}

src/browser/actions.zig

@@ -0,0 +1,137 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const lp = @import("../lightpanda.zig");
+const DOMNode = @import("webapi/Node.zig");
+const Element = @import("webapi/Element.zig");
+const Event = @import("webapi/Event.zig");
+const MouseEvent = @import("webapi/event/MouseEvent.zig");
+const Page = @import("Page.zig");
+const Session = @import("Session.zig");
+const Selector = @import("webapi/selector/Selector.zig");
+
+pub fn click(node: *DOMNode, page: *Page) !void {
+    const el = node.is(Element) orelse return error.InvalidNodeType;
+
+    const mouse_event: *MouseEvent = try .initTrusted(comptime .wrap("click"), .{
+        .bubbles = true,
+        .cancelable = true,
+        .composed = true,
+        .clientX = 0,
+        .clientY = 0,
+    }, page);
+
+    page._event_manager.dispatch(el.asEventTarget(), mouse_event.asEvent()) catch |err| {
+        lp.log.err(.app, "click failed", .{ .err = err });
+        return error.ActionFailed;
+    };
+}
+
+pub fn fill(node: *DOMNode, text: []const u8, page: *Page) !void {
+    const el = node.is(Element) orelse return error.InvalidNodeType;
+
+    if (el.is(Element.Html.Input)) |input| {
+        input.setValue(text, page) catch |err| {
+            lp.log.err(.app, "fill input failed", .{ .err = err });
+            return error.ActionFailed;
+        };
+    } else if (el.is(Element.Html.TextArea)) |textarea| {
+        textarea.setValue(text, page) catch |err| {
+            lp.log.err(.app, "fill textarea failed", .{ .err = err });
+            return error.ActionFailed;
+        };
+    } else if (el.is(Element.Html.Select)) |select| {
+        select.setValue(text, page) catch |err| {
+            lp.log.err(.app, "fill select failed", .{ .err = err });
+            return error.ActionFailed;
+        };
+    } else {
+        return error.InvalidNodeType;
+    }
+
+    const input_evt: *Event = try .initTrusted(comptime .wrap("input"), .{ .bubbles = true }, page);
+    page._event_manager.dispatch(el.asEventTarget(), input_evt) catch |err| {
+        lp.log.err(.app, "dispatch input event failed", .{ .err = err });
+    };
+
+    const change_evt: *Event = try .initTrusted(comptime .wrap("change"), .{ .bubbles = true }, page);
+    page._event_manager.dispatch(el.asEventTarget(), change_evt) catch |err| {
+        lp.log.err(.app, "dispatch change event failed", .{ .err = err });
+    };
+}
+
+pub fn scroll(node: ?*DOMNode, x: ?i32, y: ?i32, page: *Page) !void {
+    if (node) |n| {
+        const el = n.is(Element) orelse return error.InvalidNodeType;
+
+        if (x) |val| {
+            el.setScrollLeft(val, page) catch |err| {
+                lp.log.err(.app, "setScrollLeft failed", .{ .err = err });
+                return error.ActionFailed;
+            };
+        }
+        if (y) |val| {
+            el.setScrollTop(val, page) catch |err| {
+                lp.log.err(.app, "setScrollTop failed", .{ .err = err });
+                return error.ActionFailed;
+            };
+        }
+
+        const scroll_evt: *Event = try .initTrusted(comptime .wrap("scroll"), .{ .bubbles = true }, page);
+        page._event_manager.dispatch(el.asEventTarget(), scroll_evt) catch |err| {
+            lp.log.err(.app, "dispatch scroll event failed", .{ .err = err });
+        };
+    } else {
+        page.window.scrollTo(.{ .x = x orelse 0 }, y, page) catch |err| {
+            lp.log.err(.app, "scroll failed", .{ .err = err });
+            return error.ActionFailed;
+        };
+    }
+}
+
+pub fn waitForSelector(selector: [:0]const u8, timeout_ms: u32, session: *Session) !*DOMNode {
+    var timer = try std.time.Timer.start();
+    var runner = try session.runner(.{});
+    try runner.wait(.{ .ms = timeout_ms, .until = .load });
+
+    while (true) {
+        const page = runner.page;
+        const element = Selector.querySelector(page.document.asNode(), selector, page) catch {
+            return error.InvalidSelector;
+        };
+
+        if (element) |el| {
+            return el.asNode();
+        }
+
+        const elapsed: u32 = @intCast(timer.read() / std.time.ns_per_ms);
+        if (elapsed >= timeout_ms) {
+            return error.Timeout;
+        }
+        switch (try runner.tick(.{ .ms = timeout_ms - elapsed })) {
+            .done => return error.Timeout,
+            .ok => |recommended_sleep_ms| {
+                if (recommended_sleep_ms > 0) {
+                    // guanrateed to be <= 20ms
+                    std.Thread.sleep(std.time.ns_per_ms * recommended_sleep_ms);
+                }
+            },
+        }
+    }
+}

src/browser/browser.zig

@@ -1,560 +0,0 @@
-// Copyright (C) 2023-2024  Lightpanda (Selecy SAS)
-//
-// Francis Bouvier <francis@lightpanda.io>
-// Pierre Tachoire <pierre@lightpanda.io>
-//
-// This program is free software: you can redistribute it and/or modify
-// it under the terms of the GNU Affero General Public License as
-// published by the Free Software Foundation, either version 3 of the
-// License, or (at your option) any later version.
-//
-// This program is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// GNU Affero General Public License for more details.
-//
-// You should have received a copy of the GNU Affero General Public License
-// along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-const std = @import("std");
-const builtin = @import("builtin");
-
-const Types = @import("root").Types;
-
-const parser = @import("netsurf");
-const Loader = @import("loader.zig").Loader;
-const Dump = @import("dump.zig");
-const Mime = @import("mime.zig");
-
-const jsruntime = @import("jsruntime");
-const Loop = jsruntime.Loop;
-const Env = jsruntime.Env;
-
-const apiweb = @import("../apiweb.zig");
-
-const Window = @import("../html/window.zig").Window;
-const Walker = @import("../dom/walker.zig").WalkerDepthFirst;
-
-const storage = @import("../storage/storage.zig");
-
-const FetchResult = std.http.Client.FetchResult;
-
-const UserContext = @import("../user_context.zig").UserContext;
-const HttpClient = @import("../async/Client.zig");
-
-const log = std.log.scoped(.browser);
-
-// Browser is an instance of the browser.
-// You can create multiple browser instances.
-// A browser contains only one session.
-// TODO allow multiple sessions per browser.
-pub const Browser = struct {
-    session: *Session,
-
-    pub fn init(alloc: std.mem.Allocator, vm: jsruntime.VM) !Browser {
-        // We want to ensure the caller initialised a VM, but the browser
-        // doesn't use it directly...
-        _ = vm;
-
-        return Browser{
-            .session = try Session.init(alloc, "about:blank"),
-        };
-    }
-
-    pub fn deinit(self: *Browser) void {
-        self.session.deinit();
-    }
-
-    pub fn currentSession(self: *Browser) *Session {
-        return self.session;
-    }
-};
-
-// Session is like a browser's tab.
-// It owns the js env and the loader for all the pages of the session.
-// You can create successively multiple pages for a session, but you must
-// deinit a page before running another one.
-pub const Session = struct {
-    // allocator used to init the arena.
-    alloc: std.mem.Allocator,
-
-    // The arena is used only to bound the js env init b/c it leaks memory.
-    // see https://github.com/lightpanda-io/jsruntime-lib/issues/181
-    //
-    // The arena is initialised with self.alloc allocator.
-    // all others Session deps use directly self.alloc and not the arena.
-    arena: std.heap.ArenaAllocator,
-
-    uri: []const u8,
-
-    // TODO handle proxy
-    loader: Loader,
-    env: Env = undefined,
-    loop: Loop,
-    window: Window,
-    // TODO move the shed to the browser?
-    storageShed: storage.Shed,
-    page: ?*Page = null,
-    httpClient: HttpClient,
-
-    jstypes: [Types.len]usize = undefined,
-
-    fn init(alloc: std.mem.Allocator, uri: []const u8) !*Session {
-        var self = try alloc.create(Session);
-        self.* = Session{
-            .uri = uri,
-            .alloc = alloc,
-            .arena = std.heap.ArenaAllocator.init(alloc),
-            .window = Window.create(null),
-            .loader = Loader.init(alloc),
-            .loop = try Loop.init(alloc),
-            .storageShed = storage.Shed.init(alloc),
-            .httpClient = undefined,
-        };
-
-        self.env = try Env.init(self.arena.allocator(), &self.loop, null);
-        self.httpClient = .{ .allocator = alloc, .loop = &self.loop };
-        try self.env.load(&self.jstypes);
-
-        return self;
-    }
-
-    fn deinit(self: *Session) void {
-        if (self.page) |page| page.end();
-
-        self.env.deinit();
-        self.arena.deinit();
-
-        self.loader.deinit();
-        self.loop.deinit();
-        self.storageShed.deinit();
-        self.httpClient.deinit();
-        self.alloc.destroy(self);
-    }
-
-    pub fn createPage(self: *Session) !Page {
-        return Page.init(self.alloc, self);
-    }
-};
-
-// Page navigates to an url.
-// You can navigates multiple urls with the same page, but you have to call
-// end() to stop the previous navigation before starting a new one.
-// The page handle all its memory in an arena allocator. The arena is reseted
-// when end() is called.
-pub const Page = struct {
-    arena: std.heap.ArenaAllocator,
-    session: *Session,
-    doc: ?*parser.Document = null,
-
-    // handle url
-    rawuri: ?[]const u8 = null,
-    uri: std.Uri = undefined,
-    origin: ?[]const u8 = null,
-
-    raw_data: ?[]const u8 = null,
-
-    fn init(
-        alloc: std.mem.Allocator,
-        session: *Session,
-    ) !Page {
-        if (session.page != null) return error.SessionPageExists;
-        var page = Page{
-            .arena = std.heap.ArenaAllocator.init(alloc),
-            .session = session,
-        };
-        session.page = &page;
-        return page;
-    }
-
-    // reset js env and mem arena.
-    pub fn end(self: *Page) void {
-        self.session.env.stop();
-        // TODO unload document: https://html.spec.whatwg.org/#unloading-documents
-
-        // clear netsurf memory arena.
-        parser.deinit();
-
-        _ = self.arena.reset(.free_all);
-    }
-
-    pub fn deinit(self: *Page) void {
-        self.arena.deinit();
-        self.session.page = null;
-    }
-
-    // dump writes the page content into the given file.
-    pub fn dump(self: *Page, out: std.fs.File) !void {
-
-        // if no HTML document pointer available, dump the data content only.
-        if (self.doc == null) {
-            // no data loaded, nothing to do.
-            if (self.raw_data == null) return;
-            return try out.writeAll(self.raw_data.?);
-        }
-
-        // if the page has a pointer to a document, dumps the HTML.
-        try Dump.writeHTML(self.doc.?, out);
-    }
-
-    pub fn wait(self: *Page) !void {
-        const alloc = self.arena.allocator();
-        var res = try self.session.env.waitTryCatch(alloc);
-        defer res.deinit(alloc);
-
-        if (res.success) {
-            log.debug("wait: {s}", .{res.result});
-        } else {
-            if (builtin.mode == .Debug and res.stack != null) {
-                log.info("wait: {s}", .{res.stack.?});
-            } else {
-                log.info("wait: {s}", .{res.result});
-            }
-        }
-
-        return;
-    }
-
-    // spec reference: https://html.spec.whatwg.org/#document-lifecycle
-    pub fn navigate(self: *Page, uri: []const u8) !void {
-        const alloc = self.arena.allocator();
-
-        log.debug("starting GET {s}", .{uri});
-
-        // own the url
-        if (self.rawuri) |prev| alloc.free(prev);
-        self.rawuri = try alloc.dupe(u8, uri);
-        self.uri = std.Uri.parse(self.rawuri.?) catch try std.Uri.parseAfterScheme("", self.rawuri.?);
-
-        // prepare origin value.
-        var buf = std.ArrayList(u8).init(alloc);
-        defer buf.deinit();
-        try self.uri.writeToStream(.{
-            .scheme = true,
-            .authority = true,
-        }, buf.writer());
-        self.origin = try buf.toOwnedSlice();
-
-        // TODO handle fragment in url.
-
-        // load the data
-        var resp = try self.session.loader.get(alloc, self.uri);
-        defer resp.deinit();
-
-        const req = resp.req;
-
-        log.info("GET {any} {d}", .{ self.uri, req.response.status });
-
-        // TODO handle redirection
-        if (req.response.status != .ok) {
-            log.debug("{?} {d} {s}", .{
-                req.response.version,
-                req.response.status,
-                req.response.reason,
-                // TODO log headers
-            });
-            return error.BadStatusCode;
-        }
-
-        // TODO handle charset
-        // https://html.spec.whatwg.org/#content-type
-        var it = req.response.iterateHeaders();
-        var ct: ?[]const u8 = null;
-        while (true) {
-            const h = it.next() orelse break;
-            if (std.ascii.eqlIgnoreCase(h.name, "Content-Type")) {
-                ct = try alloc.dupe(u8, h.value);
-            }
-        }
-        if (ct == null) {
-            // no content type in HTTP headers.
-            // TODO try to sniff mime type from the body.
-            log.info("no content-type HTTP header", .{});
-            return;
-        }
-        defer alloc.free(ct.?);
-
-        log.debug("header content-type: {s}", .{ct.?});
-        const mime = try Mime.parse(ct.?);
-        if (mime.eql(Mime.HTML)) {
-            try self.loadHTMLDoc(req.reader(), mime.charset orelse "utf-8");
-        } else {
-            log.info("non-HTML document: {s}", .{ct.?});
-
-            // save the body into the page.
-            self.raw_data = try req.reader().readAllAlloc(alloc, 16 * 1024 * 1024);
-        }
-    }
-
-    // https://html.spec.whatwg.org/#read-html
-    fn loadHTMLDoc(self: *Page, reader: anytype, charset: []const u8) !void {
-        const alloc = self.arena.allocator();
-
-        // start netsurf memory arena.
-        try parser.init();
-
-        log.debug("parse html with charset {s}", .{charset});
-
-        const ccharset = try alloc.dupeZ(u8, charset);
-        defer alloc.free(ccharset);
-
-        const html_doc = try parser.documentHTMLParse(reader, ccharset);
-        const doc = parser.documentHTMLToDocument(html_doc);
-
-        // save a document's pointer in the page.
-        self.doc = doc;
-
-        // TODO set document.readyState to interactive
-        // https://html.spec.whatwg.org/#reporting-document-loading-status
-
-        // inject the URL to the document including the fragment.
-        try parser.documentSetDocumentURI(doc, self.rawuri orelse "about:blank");
-
-        // TODO set the referrer to the document.
-
-        self.session.window.replaceDocument(html_doc);
-        self.session.window.setStorageShelf(
-            try self.session.storageShed.getOrPut(self.origin orelse "null"),
-        );
-
-        // https://html.spec.whatwg.org/#read-html
-
-        // start JS env
-        // TODO load the js env concurrently with the HTML parsing.
-        log.debug("start js env", .{});
-        try self.session.env.start(alloc);
-
-        // replace the user context document with the new one.
-        try self.session.env.setUserContext(.{
-            .document = html_doc,
-            .httpClient = &self.session.httpClient,
-        });
-
-        // add global objects
-        log.debug("setup global env", .{});
-        try self.session.env.bindGlobal(&self.session.window);
-
-        // browse the DOM tree to retrieve scripts
-        // TODO execute the synchronous scripts during the HTL parsing.
-        // TODO fetch the script resources concurrently but execute them in the
-        // declaration order for synchronous ones.
-
-        // sasync stores scripts which can be run asynchronously.
-        // for now they are just run after the non-async one in order to
-        // dispatch DOMContentLoaded the sooner as possible.
-        var sasync = std.ArrayList(*parser.Element).init(alloc);
-        defer sasync.deinit();
-
-        const root = parser.documentToNode(doc);
-        const walker = Walker{};
-        var next: ?*parser.Node = null;
-        while (true) {
-            next = try walker.get_next(root, next) orelse break;
-
-            // ignore non-elements nodes.
-            if (try parser.nodeType(next.?) != .element) {
-                continue;
-            }
-
-            const e = parser.nodeToElement(next.?);
-            const tag = try parser.elementHTMLGetTagType(@as(*parser.ElementHTML, @ptrCast(e)));
-
-            // ignore non-script tags
-            if (tag != .script) continue;
-
-            // ignore non-js script.
-            // > type
-            // > Attribute is not set (default), an empty string, or a JavaScript MIME
-            // > type indicates that the script is a "classic script", containing
-            // > JavaScript code.
-            // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attribute_is_not_set_default_an_empty_string_or_a_javascript_mime_type
-            const stype = try parser.elementGetAttribute(e, "type");
-            if (!isJS(stype)) {
-                continue;
-            }
-
-            // Ignore the defer attribute b/c we analyze all script
-            // after the document has been parsed.
-            // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer
-
-            // TODO use fetchpriority
-            // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#fetchpriority
-
-            // > async
-            // > For classic scripts, if the async attribute is present,
-            // > then the classic script will be fetched in parallel to
-            // > parsing and evaluated as soon as it is available.
-            // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#async
-            if (try parser.elementGetAttribute(e, "async") != null) {
-                try sasync.append(e);
-                continue;
-            }
-
-            // TODO handle for attribute
-            // TODO handle event attribute
-
-            // TODO defer
-            // > This Boolean attribute is set to indicate to a browser
-            // > that the script is meant to be executed after the
-            // > document has been parsed, but before firing
-            // > DOMContentLoaded.
-            // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer
-            // defer allow us to load a script w/o blocking the rest of
-            // evaluations.
-
-            // > Scripts without async, defer or type="module"
-            // > attributes, as well as inline scripts without the
-            // > type="module" attribute, are fetched and executed
-            // > immediately before the browser continues to parse the
-            // > page.
-            // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#notes
-            self.evalScript(e) catch |err| log.warn("evaljs: {any}", .{err});
-        }
-
-        // TODO wait for deferred scripts
-
-        // dispatch DOMContentLoaded before the transition to "complete",
-        // at the point where all subresources apart from async script elements
-        // have loaded.
-        // https://html.spec.whatwg.org/#reporting-document-loading-status
-        const evt = try parser.eventCreate();
-        defer parser.eventDestroy(evt);
-
-        try parser.eventInit(evt, "DOMContentLoaded", .{ .bubbles = true, .cancelable = true });
-        _ = try parser.eventTargetDispatchEvent(parser.toEventTarget(parser.DocumentHTML, html_doc), evt);
-
-        // eval async scripts.
-        for (sasync.items) |e| {
-            self.evalScript(e) catch |err| log.warn("evaljs: {any}", .{err});
-        }
-
-        // TODO wait for async scripts
-
-        // TODO set document.readyState to complete
-
-        // dispatch window.load event
-        const loadevt = try parser.eventCreate();
-        defer parser.eventDestroy(loadevt);
-
-        try parser.eventInit(loadevt, "load", .{});
-        _ = try parser.eventTargetDispatchEvent(
-            parser.toEventTarget(Window, &self.session.window),
-            loadevt,
-        );
-    }
-
-    // evalScript evaluates the src in priority.
-    // if no src is present, we evaluate the text source.
-    // https://html.spec.whatwg.org/multipage/scripting.html#script-processing-model
-    fn evalScript(self: *Page, e: *parser.Element) !void {
-        const alloc = self.arena.allocator();
-
-        // https://html.spec.whatwg.org/multipage/webappapis.html#fetch-a-classic-script
-        const opt_src = try parser.elementGetAttribute(e, "src");
-        if (opt_src) |src| {
-            log.debug("starting GET {s}", .{src});
-
-            self.fetchScript(src) catch |err| {
-                switch (err) {
-                    FetchError.BadStatusCode => return err,
-
-                    // TODO If el's result is null, then fire an event named error at
-                    // el, and return.
-                    FetchError.NoBody => return,
-
-                    FetchError.JsErr => {}, // nothing to do here.
-                    else => return err,
-                }
-            };
-
-            // TODO If el's from an external file is true, then fire an event
-            // named load at el.
-
-            return;
-        }
-
-        const opt_text = try parser.nodeTextContent(parser.elementToNode(e));
-        if (opt_text) |text| {
-            // TODO handle charset attribute
-            var res = try self.session.env.execTryCatch(alloc, text, "");
-            defer res.deinit(alloc);
-
-            if (res.success) {
-                log.debug("eval inline: {s}", .{res.result});
-            } else {
-                if (builtin.mode == .Debug and res.stack != null) {
-                    log.info("eval inline: {s}", .{res.stack.?});
-                } else {
-                    log.info("eval inline: {s}", .{res.result});
-                }
-            }
-
-            return;
-        }
-
-        // nothing has been loaded.
-        // TODO If el's result is null, then fire an event named error at
-        // el, and return.
-    }
-
-    const FetchError = error{
-        BadStatusCode,
-        NoBody,
-        JsErr,
-    };
-
-    // fetchScript senf a GET request to the src and execute the script
-    // received.
-    fn fetchScript(self: *Page, src: []const u8) !void {
-        const alloc = self.arena.allocator();
-
-        log.debug("starting fetch script {s}", .{src});
-
-        var buffer: [1024]u8 = undefined;
-        var b: []u8 = buffer[0..];
-        const u = try std.Uri.resolve_inplace(self.uri, src, &b);
-
-        var fetchres = try self.session.loader.get(alloc, u);
-        defer fetchres.deinit();
-
-        const resp = fetchres.req.response;
-
-        log.info("fech script {any}: {d}", .{ u, resp.status });
-
-        if (resp.status != .ok) return FetchError.BadStatusCode;
-
-        // TODO check content-type
-        const body = try fetchres.req.reader().readAllAlloc(alloc, 16 * 1024 * 1024);
-        defer alloc.free(body);
-
-        // check no body
-        if (body.len == 0) return FetchError.NoBody;
-
-        var res = try self.session.env.execTryCatch(alloc, body, src);
-        defer res.deinit(alloc);
-
-        if (res.success) {
-            log.debug("eval remote {s}: {s}", .{ src, res.result });
-        } else {
-            if (builtin.mode == .Debug and res.stack != null) {
-                log.info("eval remote {s}: {s}", .{ src, res.stack.? });
-            } else {
-                log.info("eval remote {s}: {s}", .{ src, res.result });
-            }
-            return FetchError.JsErr;
-        }
-    }
-
-    // > type
-    // > Attribute is not set (default), an empty string, or a JavaScript MIME
-    // > type indicates that the script is a "classic script", containing
-    // > JavaScript code.
-    // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attribute_is_not_set_default_an_empty_string_or_a_javascript_mime_type
-    fn isJS(stype: ?[]const u8) bool {
-        if (stype == null or stype.?.len == 0) return true;
-        if (std.mem.eql(u8, stype.?, "application/javascript")) return true;
-        if (!std.mem.eql(u8, stype.?, "module")) return true;
-
-        return false;
-    }
-};

src/browser/color.zig

@@ -0,0 +1,298 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const Io = std.Io;
+
+pub fn isHexColor(value: []const u8) bool {
+    if (value.len == 0) {
+        return false;
+    }
+
+    if (value[0] != '#') {
+        return false;
+    }
+
+    const hex_part = value[1..];
+    switch (hex_part.len) {
+        3, 4, 6, 8 => for (hex_part) |c| if (!std.ascii.isHex(c)) return false,
+        else => return false,
+    }
+
+    return true;
+}
+
+pub const RGBA = packed struct(u32) {
+    r: u8,
+    g: u8,
+    b: u8,
+    /// Opaque by default.
+    a: u8 = std.math.maxInt(u8),
+
+    pub const Named = struct {
+        // Basic colors (CSS Level 1)
+        pub const black: RGBA = .init(0, 0, 0, 1);
+        pub const silver: RGBA = .init(192, 192, 192, 1);
+        pub const gray: RGBA = .init(128, 128, 128, 1);
+        pub const white: RGBA = .init(255, 255, 255, 1);
+        pub const maroon: RGBA = .init(128, 0, 0, 1);
+        pub const red: RGBA = .init(255, 0, 0, 1);
+        pub const purple: RGBA = .init(128, 0, 128, 1);
+        pub const fuchsia: RGBA = .init(255, 0, 255, 1);
+        pub const green: RGBA = .init(0, 128, 0, 1);
+        pub const lime: RGBA = .init(0, 255, 0, 1);
+        pub const olive: RGBA = .init(128, 128, 0, 1);
+        pub const yellow: RGBA = .init(255, 255, 0, 1);
+        pub const navy: RGBA = .init(0, 0, 128, 1);
+        pub const blue: RGBA = .init(0, 0, 255, 1);
+        pub const teal: RGBA = .init(0, 128, 128, 1);
+        pub const aqua: RGBA = .init(0, 255, 255, 1);
+
+        // Extended colors (CSS Level 2+)
+        pub const aliceblue: RGBA = .init(240, 248, 255, 1);
+        pub const antiquewhite: RGBA = .init(250, 235, 215, 1);
+        pub const aquamarine: RGBA = .init(127, 255, 212, 1);
+        pub const azure: RGBA = .init(240, 255, 255, 1);
+        pub const beige: RGBA = .init(245, 245, 220, 1);
+        pub const bisque: RGBA = .init(255, 228, 196, 1);
+        pub const blanchedalmond: RGBA = .init(255, 235, 205, 1);
+        pub const blueviolet: RGBA = .init(138, 43, 226, 1);
+        pub const brown: RGBA = .init(165, 42, 42, 1);
+        pub const burlywood: RGBA = .init(222, 184, 135, 1);
+        pub const cadetblue: RGBA = .init(95, 158, 160, 1);
+        pub const chartreuse: RGBA = .init(127, 255, 0, 1);
+        pub const chocolate: RGBA = .init(210, 105, 30, 1);
+        pub const coral: RGBA = .init(255, 127, 80, 1);
+        pub const cornflowerblue: RGBA = .init(100, 149, 237, 1);
+        pub const cornsilk: RGBA = .init(255, 248, 220, 1);
+        pub const crimson: RGBA = .init(220, 20, 60, 1);
+        pub const cyan: RGBA = .init(0, 255, 255, 1); // Synonym of aqua
+        pub const darkblue: RGBA = .init(0, 0, 139, 1);
+        pub const darkcyan: RGBA = .init(0, 139, 139, 1);
+        pub const darkgoldenrod: RGBA = .init(184, 134, 11, 1);
+        pub const darkgray: RGBA = .init(169, 169, 169, 1);
+        pub const darkgreen: RGBA = .init(0, 100, 0, 1);
+        pub const darkgrey: RGBA = .init(169, 169, 169, 1); // Synonym of darkgray
+        pub const darkkhaki: RGBA = .init(189, 183, 107, 1);
+        pub const darkmagenta: RGBA = .init(139, 0, 139, 1);
+        pub const darkolivegreen: RGBA = .init(85, 107, 47, 1);
+        pub const darkorange: RGBA = .init(255, 140, 0, 1);
+        pub const darkorchid: RGBA = .init(153, 50, 204, 1);
+        pub const darkred: RGBA = .init(139, 0, 0, 1);
+        pub const darksalmon: RGBA = .init(233, 150, 122, 1);
+        pub const darkseagreen: RGBA = .init(143, 188, 143, 1);
+        pub const darkslateblue: RGBA = .init(72, 61, 139, 1);
+        pub const darkslategray: RGBA = .init(47, 79, 79, 1);
+        pub const darkslategrey: RGBA = .init(47, 79, 79, 1); // Synonym of darkslategray
+        pub const darkturquoise: RGBA = .init(0, 206, 209, 1);
+        pub const darkviolet: RGBA = .init(148, 0, 211, 1);
+        pub const deeppink: RGBA = .init(255, 20, 147, 1);
+        pub const deepskyblue: RGBA = .init(0, 191, 255, 1);
+        pub const dimgray: RGBA = .init(105, 105, 105, 1);
+        pub const dimgrey: RGBA = .init(105, 105, 105, 1); // Synonym of dimgray
+        pub const dodgerblue: RGBA = .init(30, 144, 255, 1);
+        pub const firebrick: RGBA = .init(178, 34, 34, 1);
+        pub const floralwhite: RGBA = .init(255, 250, 240, 1);
+        pub const forestgreen: RGBA = .init(34, 139, 34, 1);
+        pub const gainsboro: RGBA = .init(220, 220, 220, 1);
+        pub const ghostwhite: RGBA = .init(248, 248, 255, 1);
+        pub const gold: RGBA = .init(255, 215, 0, 1);
+        pub const goldenrod: RGBA = .init(218, 165, 32, 1);
+        pub const greenyellow: RGBA = .init(173, 255, 47, 1);
+        pub const grey: RGBA = .init(128, 128, 128, 1); // Synonym of gray
+        pub const honeydew: RGBA = .init(240, 255, 240, 1);
+        pub const hotpink: RGBA = .init(255, 105, 180, 1);
+        pub const indianred: RGBA = .init(205, 92, 92, 1);
+        pub const indigo: RGBA = .init(75, 0, 130, 1);
+        pub const ivory: RGBA = .init(255, 255, 240, 1);
+        pub const khaki: RGBA = .init(240, 230, 140, 1);
+        pub const lavender: RGBA = .init(230, 230, 250, 1);
+        pub const lavenderblush: RGBA = .init(255, 240, 245, 1);
+        pub const lawngreen: RGBA = .init(124, 252, 0, 1);
+        pub const lemonchiffon: RGBA = .init(255, 250, 205, 1);
+        pub const lightblue: RGBA = .init(173, 216, 230, 1);
+        pub const lightcoral: RGBA = .init(240, 128, 128, 1);
+        pub const lightcyan: RGBA = .init(224, 255, 255, 1);
+        pub const lightgoldenrodyellow: RGBA = .init(250, 250, 210, 1);
+        pub const lightgray: RGBA = .init(211, 211, 211, 1);
+        pub const lightgreen: RGBA = .init(144, 238, 144, 1);
+        pub const lightgrey: RGBA = .init(211, 211, 211, 1); // Synonym of lightgray
+        pub const lightpink: RGBA = .init(255, 182, 193, 1);
+        pub const lightsalmon: RGBA = .init(255, 160, 122, 1);
+        pub const lightseagreen: RGBA = .init(32, 178, 170, 1);
+        pub const lightskyblue: RGBA = .init(135, 206, 250, 1);
+        pub const lightslategray: RGBA = .init(119, 136, 153, 1);
+        pub const lightslategrey: RGBA = .init(119, 136, 153, 1); // Synonym of lightslategray
+        pub const lightsteelblue: RGBA = .init(176, 196, 222, 1);
+        pub const lightyellow: RGBA = .init(255, 255, 224, 1);
+        pub const limegreen: RGBA = .init(50, 205, 50, 1);
+        pub const linen: RGBA = .init(250, 240, 230, 1);
+        pub const magenta: RGBA = .init(255, 0, 255, 1); // Synonym of fuchsia
+        pub const mediumaquamarine: RGBA = .init(102, 205, 170, 1);
+        pub const mediumblue: RGBA = .init(0, 0, 205, 1);
+        pub const mediumorchid: RGBA = .init(186, 85, 211, 1);
+        pub const mediumpurple: RGBA = .init(147, 112, 219, 1);
+        pub const mediumseagreen: RGBA = .init(60, 179, 113, 1);
+        pub const mediumslateblue: RGBA = .init(123, 104, 238, 1);
+        pub const mediumspringgreen: RGBA = .init(0, 250, 154, 1);
+        pub const mediumturquoise: RGBA = .init(72, 209, 204, 1);
+        pub const mediumvioletred: RGBA = .init(199, 21, 133, 1);
+        pub const midnightblue: RGBA = .init(25, 25, 112, 1);
+        pub const mintcream: RGBA = .init(245, 255, 250, 1);
+        pub const mistyrose: RGBA = .init(255, 228, 225, 1);
+        pub const moccasin: RGBA = .init(255, 228, 181, 1);
+        pub const navajowhite: RGBA = .init(255, 222, 173, 1);
+        pub const oldlace: RGBA = .init(253, 245, 230, 1);
+        pub const olivedrab: RGBA = .init(107, 142, 35, 1);
+        pub const orange: RGBA = .init(255, 165, 0, 1);
+        pub const orangered: RGBA = .init(255, 69, 0, 1);
+        pub const orchid: RGBA = .init(218, 112, 214, 1);
+        pub const palegoldenrod: RGBA = .init(238, 232, 170, 1);
+        pub const palegreen: RGBA = .init(152, 251, 152, 1);
+        pub const paleturquoise: RGBA = .init(175, 238, 238, 1);
+        pub const palevioletred: RGBA = .init(219, 112, 147, 1);
+        pub const papayawhip: RGBA = .init(255, 239, 213, 1);
+        pub const peachpuff: RGBA = .init(255, 218, 185, 1);
+        pub const peru: RGBA = .init(205, 133, 63, 1);
+        pub const pink: RGBA = .init(255, 192, 203, 1);
+        pub const plum: RGBA = .init(221, 160, 221, 1);
+        pub const powderblue: RGBA = .init(176, 224, 230, 1);
+        pub const rebeccapurple: RGBA = .init(102, 51, 153, 1);
+        pub const rosybrown: RGBA = .init(188, 143, 143, 1);
+        pub const royalblue: RGBA = .init(65, 105, 225, 1);
+        pub const saddlebrown: RGBA = .init(139, 69, 19, 1);
+        pub const salmon: RGBA = .init(250, 128, 114, 1);
+        pub const sandybrown: RGBA = .init(244, 164, 96, 1);
+        pub const seagreen: RGBA = .init(46, 139, 87, 1);
+        pub const seashell: RGBA = .init(255, 245, 238, 1);
+        pub const sienna: RGBA = .init(160, 82, 45, 1);
+        pub const skyblue: RGBA = .init(135, 206, 235, 1);
+        pub const slateblue: RGBA = .init(106, 90, 205, 1);
+        pub const slategray: RGBA = .init(112, 128, 144, 1);
+        pub const slategrey: RGBA = .init(112, 128, 144, 1); // Synonym of slategray
+        pub const snow: RGBA = .init(255, 250, 250, 1);
+        pub const springgreen: RGBA = .init(0, 255, 127, 1);
+        pub const steelblue: RGBA = .init(70, 130, 180, 1);
+        pub const tan: RGBA = .init(210, 180, 140, 1);
+        pub const thistle: RGBA = .init(216, 191, 216, 1);
+        pub const tomato: RGBA = .init(255, 99, 71, 1);
+        pub const transparent: RGBA = .init(0, 0, 0, 0);
+        pub const turquoise: RGBA = .init(64, 224, 208, 1);
+        pub const violet: RGBA = .init(238, 130, 238, 1);
+        pub const wheat: RGBA = .init(245, 222, 179, 1);
+        pub const whitesmoke: RGBA = .init(245, 245, 245, 1);
+        pub const yellowgreen: RGBA = .init(154, 205, 50, 1);
+    };
+
+    pub fn init(r: u8, g: u8, b: u8, a: f32) RGBA {
+        const clamped = std.math.clamp(a, 0, 1);
+        return .{ .r = r, .g = g, .b = b, .a = @intFromFloat(clamped * 255) };
+    }
+
+    /// Finds a color by its name.
+    pub fn find(name: []const u8) ?RGBA {
+        const match = std.meta.stringToEnum(std.meta.DeclEnum(Named), name) orelse return null;
+
+        return switch (match) {
+            inline else => |comptime_enum| @field(Named, @tagName(comptime_enum)),
+        };
+    }
+
+    /// Parses the given color.
+    /// Currently we only parse hex colors and named colors; other variants
+    /// require CSS evaluation.
+    pub fn parse(input: []const u8) !RGBA {
+        if (!isHexColor(input)) {
+            // Try named colors.
+            return find(input) orelse return error.Invalid;
+        }
+
+        const slice = input[1..];
+        switch (slice.len) {
+            // This means the digit for a color is repeated.
+            // Given HEX is #f0c, its interpreted the same as #FF00CC.
+            3 => {
+                const r = try std.fmt.parseInt(u8, &.{ slice[0], slice[0] }, 16);
+                const g = try std.fmt.parseInt(u8, &.{ slice[1], slice[1] }, 16);
+                const b = try std.fmt.parseInt(u8, &.{ slice[2], slice[2] }, 16);
+                return .{ .r = r, .g = g, .b = b, .a = 255 };
+            },
+            4 => {
+                const r = try std.fmt.parseInt(u8, &.{ slice[0], slice[0] }, 16);
+                const g = try std.fmt.parseInt(u8, &.{ slice[1], slice[1] }, 16);
+                const b = try std.fmt.parseInt(u8, &.{ slice[2], slice[2] }, 16);
+                const a = try std.fmt.parseInt(u8, &.{ slice[3], slice[3] }, 16);
+                return .{ .r = r, .g = g, .b = b, .a = a };
+            },
+            // Regular HEX format.
+            6 => {
+                const r = try std.fmt.parseInt(u8, slice[0..2], 16);
+                const g = try std.fmt.parseInt(u8, slice[2..4], 16);
+                const b = try std.fmt.parseInt(u8, slice[4..6], 16);
+                return .{ .r = r, .g = g, .b = b, .a = 255 };
+            },
+            8 => {
+                const r = try std.fmt.parseInt(u8, slice[0..2], 16);
+                const g = try std.fmt.parseInt(u8, slice[2..4], 16);
+                const b = try std.fmt.parseInt(u8, slice[4..6], 16);
+                const a = try std.fmt.parseInt(u8, slice[6..8], 16);
+                return .{ .r = r, .g = g, .b = b, .a = a };
+            },
+            else => return error.Invalid,
+        }
+    }
+
+    /// By default, browsers prefer lowercase formatting.
+    const format_upper = false;
+
+    /// Formats the `Color` according to web expectations.
+    /// If color is opaque, HEX is preferred; RGBA otherwise.
+    pub fn format(self: *const RGBA, writer: *Io.Writer) Io.Writer.Error!void {
+        if (self.isOpaque()) {
+            // Convert RGB to HEX.
+            // https://gristle.tripod.com/hexconv.html
+            // Hexadecimal characters up to 15.
+            const char: []const u8 = "0123456789" ++ if (format_upper) "ABCDEF" else "abcdef";
+            // This variant always prefers 6 digit format, +1 is for hash char.
+            const buffer = [7]u8{
+                '#',
+                char[self.r >> 4],
+                char[self.r & 15],
+                char[self.g >> 4],
+                char[self.g & 15],
+                char[self.b >> 4],
+                char[self.b & 15],
+            };
+
+            return writer.writeAll(&buffer);
+        }
+
+        // Prefer RGBA format for everything else.
+        return writer.print("rgba({d}, {d}, {d}, {d:.2})", .{ self.r, self.g, self.b, self.normalizedAlpha() });
+    }
+
+    /// Returns true if `Color` is opaque.
+    pub inline fn isOpaque(self: *const RGBA) bool {
+        return self.a == std.math.maxInt(u8);
+    }
+
+    /// Returns the normalized alpha value.
+    pub inline fn normalizedAlpha(self: *const RGBA) f32 {
+        return @as(f32, @floatFromInt(self.a)) / 255;
+    }
+};

src/browser/css/Parser.zig

@@ -0,0 +1,483 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const Tokenizer = @import("Tokenizer.zig");
+
+pub const Declaration = struct {
+    name: []const u8,
+    value: []const u8,
+    important: bool,
+};
+
+const TokenSpan = struct {
+    token: Tokenizer.Token,
+    start: usize,
+    end: usize,
+};
+
+const TokenStream = struct {
+    tokenizer: Tokenizer,
+    peeked: ?TokenSpan = null,
+
+    fn init(input: []const u8) TokenStream {
+        return .{ .tokenizer = .{ .input = input } };
+    }
+
+    fn nextRaw(self: *TokenStream) ?TokenSpan {
+        const start = self.tokenizer.position;
+        const token = self.tokenizer.next() orelse return null;
+        const end = self.tokenizer.position;
+        return .{ .token = token, .start = start, .end = end };
+    }
+
+    fn next(self: *TokenStream) ?TokenSpan {
+        if (self.peeked) |token| {
+            self.peeked = null;
+            return token;
+        }
+        return self.nextRaw();
+    }
+
+    fn peek(self: *TokenStream) ?TokenSpan {
+        if (self.peeked == null) {
+            self.peeked = self.nextRaw();
+        }
+        return self.peeked;
+    }
+};
+
+pub fn parseDeclarationsList(input: []const u8) DeclarationsIterator {
+    return DeclarationsIterator.init(input);
+}
+
+pub const DeclarationsIterator = struct {
+    input: []const u8,
+    stream: TokenStream,
+
+    pub fn init(input: []const u8) DeclarationsIterator {
+        return .{
+            .input = input,
+            .stream = TokenStream.init(input),
+        };
+    }
+
+    pub fn next(self: *DeclarationsIterator) ?Declaration {
+        while (true) {
+            self.skipTriviaAndSemicolons();
+            const peeked = self.stream.peek() orelse return null;
+
+            switch (peeked.token) {
+                .at_keyword => {
+                    _ = self.stream.next();
+                    self.skipAtRule();
+                },
+                .ident => |name| {
+                    _ = self.stream.next();
+                    if (self.consumeDeclaration(name)) |declaration| {
+                        return declaration;
+                    }
+                },
+                else => {
+                    _ = self.stream.next();
+                    self.skipInvalidDeclaration();
+                },
+            }
+        }
+
+        return null;
+    }
+
+    fn consumeDeclaration(self: *DeclarationsIterator, name: []const u8) ?Declaration {
+        self.skipTrivia();
+
+        const colon = self.stream.next() orelse return null;
+        if (!isColon(colon.token)) {
+            self.skipInvalidDeclaration();
+            return null;
+        }
+
+        const value = self.consumeValue() orelse return null;
+        return .{
+            .name = name,
+            .value = value.value,
+            .important = value.important,
+        };
+    }
+
+    const ValueResult = struct {
+        value: []const u8,
+        important: bool,
+    };
+
+    fn consumeValue(self: *DeclarationsIterator) ?ValueResult {
+        self.skipTrivia();
+
+        var depth: usize = 0;
+        var start: ?usize = null;
+        var last_sig: ?TokenSpan = null;
+        var prev_sig: ?TokenSpan = null;
+
+        while (true) {
+            const peeked = self.stream.peek() orelse break;
+            if (isSemicolon(peeked.token) and depth == 0) {
+                _ = self.stream.next();
+                break;
+            }
+
+            const span = self.stream.next() orelse break;
+            if (isWhitespaceOrComment(span.token)) {
+                continue;
+            }
+
+            if (start == null) start = span.start;
+            prev_sig = last_sig;
+            last_sig = span;
+            updateDepth(span.token, &depth);
+        }
+
+        const value_start = start orelse return null;
+        const last = last_sig orelse return null;
+
+        var important = false;
+        var end_pos = last.end;
+
+        if (isImportantPair(prev_sig, last)) {
+            important = true;
+            const bang = prev_sig orelse return null;
+            if (value_start >= bang.start) return null;
+            end_pos = bang.start;
+        }
+
+        var value_slice = self.input[value_start..end_pos];
+        value_slice = std.mem.trim(u8, value_slice, &std.ascii.whitespace);
+        if (value_slice.len == 0) return null;
+
+        return .{ .value = value_slice, .important = important };
+    }
+
+    fn skipTrivia(self: *DeclarationsIterator) void {
+        while (self.stream.peek()) |peeked| {
+            if (!isWhitespaceOrComment(peeked.token)) break;
+            _ = self.stream.next();
+        }
+    }
+
+    fn skipTriviaAndSemicolons(self: *DeclarationsIterator) void {
+        while (self.stream.peek()) |peeked| {
+            if (isWhitespaceOrComment(peeked.token) or isSemicolon(peeked.token)) {
+                _ = self.stream.next();
+            } else {
+                break;
+            }
+        }
+    }
+
+    fn skipAtRule(self: *DeclarationsIterator) void {
+        var depth: usize = 0;
+        var saw_block = false;
+
+        while (true) {
+            const peeked = self.stream.peek() orelse return;
+            if (!saw_block and isSemicolon(peeked.token) and depth == 0) {
+                _ = self.stream.next();
+                return;
+            }
+
+            const span = self.stream.next() orelse return;
+            if (isWhitespaceOrComment(span.token)) continue;
+
+            if (isBlockStart(span.token)) {
+                depth += 1;
+                saw_block = true;
+            } else if (isBlockEnd(span.token)) {
+                if (depth > 0) depth -= 1;
+                if (saw_block and depth == 0) return;
+            }
+        }
+    }
+
+    fn skipInvalidDeclaration(self: *DeclarationsIterator) void {
+        var depth: usize = 0;
+
+        while (self.stream.peek()) |peeked| {
+            if (isSemicolon(peeked.token) and depth == 0) {
+                _ = self.stream.next();
+                return;
+            }
+
+            const span = self.stream.next() orelse return;
+            if (isWhitespaceOrComment(span.token)) continue;
+            updateDepth(span.token, &depth);
+        }
+    }
+};
+
+fn isWhitespaceOrComment(token: Tokenizer.Token) bool {
+    return switch (token) {
+        .white_space, .comment => true,
+        else => false,
+    };
+}
+
+fn isSemicolon(token: Tokenizer.Token) bool {
+    return switch (token) {
+        .semicolon => true,
+        else => false,
+    };
+}
+
+fn isColon(token: Tokenizer.Token) bool {
+    return switch (token) {
+        .colon => true,
+        else => false,
+    };
+}
+
+fn isBlockStart(token: Tokenizer.Token) bool {
+    return switch (token) {
+        .curly_bracket_block, .square_bracket_block, .parenthesis_block, .function => true,
+        else => false,
+    };
+}
+
+fn isBlockEnd(token: Tokenizer.Token) bool {
+    return switch (token) {
+        .close_curly_bracket, .close_parenthesis, .close_square_bracket => true,
+        else => false,
+    };
+}
+
+fn updateDepth(token: Tokenizer.Token, depth: *usize) void {
+    if (isBlockStart(token)) {
+        depth.* += 1;
+        return;
+    }
+
+    if (isBlockEnd(token)) {
+        if (depth.* > 0) depth.* -= 1;
+    }
+}
+
+fn isImportantPair(prev_sig: ?TokenSpan, last_sig: TokenSpan) bool {
+    if (!isIdentImportant(last_sig.token)) return false;
+    const prev = prev_sig orelse return false;
+    return isBang(prev.token);
+}
+
+fn isIdentImportant(token: Tokenizer.Token) bool {
+    return switch (token) {
+        .ident => |name| std.ascii.eqlIgnoreCase(name, "important"),
+        else => false,
+    };
+}
+
+fn isBang(token: Tokenizer.Token) bool {
+    return switch (token) {
+        .delim => |c| c == '!',
+        else => false,
+    };
+}
+
+pub const Rule = struct {
+    selector: []const u8,
+    block: []const u8,
+};
+
+pub fn parseStylesheet(input: []const u8) RulesIterator {
+    return RulesIterator.init(input);
+}
+
+pub const RulesIterator = struct {
+    input: []const u8,
+    stream: TokenStream,
+    has_skipped_at_rule: bool = false,
+
+    pub fn init(input: []const u8) RulesIterator {
+        return .{
+            .input = input,
+            .stream = TokenStream.init(input),
+        };
+    }
+
+    pub fn next(self: *RulesIterator) ?Rule {
+        var selector_start: ?usize = null;
+        var selector_end: ?usize = null;
+
+        while (true) {
+            const peeked = self.stream.peek() orelse return null;
+
+            if (peeked.token == .curly_bracket_block) {
+                if (selector_start == null) {
+                    self.skipBlock();
+                    continue;
+                }
+
+                const open_brace = self.stream.next() orelse return null;
+                const block_start = open_brace.end;
+                var block_end = block_start;
+
+                var depth: usize = 1;
+                while (true) {
+                    const span = self.stream.next() orelse {
+                        block_end = self.input.len;
+                        break;
+                    };
+                    if (span.token == .curly_bracket_block) {
+                        depth += 1;
+                    } else if (span.token == .close_curly_bracket) {
+                        depth -= 1;
+                        if (depth == 0) {
+                            block_end = span.start;
+                            break;
+                        }
+                    }
+                }
+
+                var selector = self.input[selector_start.?..selector_end.?];
+                selector = std.mem.trim(u8, selector, &std.ascii.whitespace);
+
+                return .{
+                    .selector = selector,
+                    .block = self.input[block_start..block_end],
+                };
+            }
+
+            if (peeked.token == .at_keyword) {
+                self.has_skipped_at_rule = true;
+                self.skipAtRule();
+                selector_start = null;
+                selector_end = null;
+                continue;
+            }
+
+            if (selector_start == null and (isWhitespaceOrComment(peeked.token) or isSemicolon(peeked.token))) {
+                _ = self.stream.next();
+                continue;
+            }
+
+            const span = self.stream.next() orelse return null;
+            if (!isWhitespaceOrComment(span.token)) {
+                if (selector_start == null) selector_start = span.start;
+                selector_end = span.end;
+            }
+        }
+    }
+
+    fn skipBlock(self: *RulesIterator) void {
+        const span = self.stream.next() orelse return;
+        if (span.token != .curly_bracket_block) return;
+
+        var depth: usize = 1;
+        while (true) {
+            const next_span = self.stream.next() orelse return;
+            if (next_span.token == .curly_bracket_block) {
+                depth += 1;
+            } else if (next_span.token == .close_curly_bracket) {
+                depth -= 1;
+                if (depth == 0) return;
+            }
+        }
+    }
+
+    fn skipAtRule(self: *RulesIterator) void {
+        _ = self.stream.next(); // consume @keyword
+        var depth: usize = 0;
+        var saw_block = false;
+
+        while (true) {
+            const peeked = self.stream.peek() orelse return;
+            if (!saw_block and isSemicolon(peeked.token) and depth == 0) {
+                _ = self.stream.next();
+                return;
+            }
+
+            const span = self.stream.next() orelse return;
+            if (isWhitespaceOrComment(span.token)) continue;
+
+            if (span.token == .curly_bracket_block) {
+                depth += 1;
+                saw_block = true;
+            } else if (span.token == .close_curly_bracket) {
+                if (depth > 0) depth -= 1;
+                if (saw_block and depth == 0) return;
+            }
+        }
+    }
+};
+
+const testing = std.testing;
+
+test "RulesIterator: single rule" {
+    var it = RulesIterator.init(".test { color: red; }");
+    const rule = it.next() orelse return error.MissingRule;
+    try testing.expectEqualStrings(".test", rule.selector);
+    try testing.expectEqualStrings(" color: red; ", rule.block);
+    try testing.expectEqual(@as(?Rule, null), it.next());
+}
+
+test "RulesIterator: multiple rules" {
+    var it = RulesIterator.init("h1 { margin: 0; } p { padding: 10px; }");
+
+    var rule = it.next() orelse return error.MissingRule;
+    try testing.expectEqualStrings("h1", rule.selector);
+    try testing.expectEqualStrings(" margin: 0; ", rule.block);
+
+    rule = it.next() orelse return error.MissingRule;
+    try testing.expectEqualStrings("p", rule.selector);
+    try testing.expectEqualStrings(" padding: 10px; ", rule.block);
+
+    try testing.expectEqual(@as(?Rule, null), it.next());
+}
+
+test "RulesIterator: skips at-rules without block" {
+    var it = RulesIterator.init("@import url('style.css'); .test { color: red; }");
+
+    const rule = it.next() orelse return error.MissingRule;
+    try testing.expectEqualStrings(".test", rule.selector);
+    try testing.expectEqualStrings(" color: red; ", rule.block);
+    try testing.expectEqual(@as(?Rule, null), it.next());
+}
+
+test "RulesIterator: skips at-rules with block" {
+    var it = RulesIterator.init("@media screen { .test { color: blue; } } .test2 { color: green; }");
+
+    const rule = it.next() orelse return error.MissingRule;
+    try testing.expectEqualStrings(".test2", rule.selector);
+    try testing.expectEqualStrings(" color: green; ", rule.block);
+    try testing.expectEqual(@as(?Rule, null), it.next());
+}
+
+test "RulesIterator: comments and whitespace" {
+    var it = RulesIterator.init("  /* comment */  .test  /* comment */ { /* comment */ color: red; } \n\t");
+
+    const rule = it.next() orelse return error.MissingRule;
+    try testing.expectEqualStrings(".test", rule.selector);
+    try testing.expectEqualStrings(" /* comment */ color: red; ", rule.block);
+    try testing.expectEqual(@as(?Rule, null), it.next());
+}
+
+test "RulesIterator: top-level semicolons" {
+    var it = RulesIterator.init("*{}; ; p{}");
+    var rule = it.next() orelse return error.MissingRule;
+    try testing.expectEqualStrings("*", rule.selector);
+
+    rule = it.next() orelse return error.MissingRule;
+    try testing.expectEqualStrings("p", rule.selector);
+    try testing.expectEqual(@as(?Rule, null), it.next());
+}

src/browser/css/Tokenizer.zig

@@ -0,0 +1,825 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+//! This file implements the tokenization step defined in the CSS Syntax Module Level 3 specification.
+//!
+//! The algorithm accepts a valid UTF-8 string and returns a stream of tokens.
+//! The tokenization step never fails, even for complete gibberish.
+//! Validity must then be checked by the parser.
+//!
+//! NOTE: The tokenizer is not thread-safe and does not own any memory, and does not check the validity of utf8.
+//!
+//! See spec for more info: https://drafts.csswg.org/css-syntax/#tokenization
+
+const std = @import("std");
+const builtin = @import("builtin");
+const assert = std.debug.assert;
+
+const Tokenizer = @This();
+
+pub const Token = union(enum) {
+    /// A `<ident-token>`
+    ident: []const u8,
+
+    /// A `<function-token>`
+    ///
+    /// The value (name) does not include the `(` marker.
+    function: []const u8,
+
+    /// A `<at-keyword-token>`
+    ///
+    /// The value does not include the `@` marker.
+    at_keyword: []const u8,
+
+    /// A `<hash-token>` with the type flag set to "id"
+    ///
+    /// The value does not include the `#` marker.
+    id_hash: []const u8, // Hash that is a valid ID selector.
+
+    /// A `<hash-token>` with the type flag set to "unrestricted"
+    ///
+    /// The value does not include the `#` marker.
+    unrestricted_hash: []const u8,
+
+    /// A `<string-token>`
+    ///
+    /// The value does not include the quotes.
+    string: []const u8,
+
+    /// A `<bad-string-token>`
+    ///
+    /// This token always indicates a parse error.
+    bad_string: []const u8,
+
+    /// A `<url-token>`
+    ///
+    /// The value does not include the `url(` `)` markers.  Note that `url( <string-token> )` is represented by a
+    /// `Function` token.
+    url: []const u8,
+
+    /// A `<bad-url-token>`
+    ///
+    /// This token always indicates a parse error.
+    bad_url: []const u8,
+
+    /// A `<delim-token>`
+    delim: u8,
+
+    /// A `<number-token>`
+    number: struct {
+        /// Whether the number had a `+` or `-` sign.
+        ///
+        /// This is used is some cases like the <An+B> micro syntax. (See the `parse_nth` function.)
+        has_sign: bool,
+
+        /// If the origin source did not include a fractional part, the value as an integer.
+        int_value: ?i32,
+
+        /// The value as a float
+        value: f32,
+    },
+
+    /// A `<percentage-token>`
+    percentage: struct {
+        /// Whether the number had a `+` or `-` sign.
+        has_sign: bool,
+
+        /// If the origin source did not include a fractional part, the value as an integer.
+        /// It is **not** divided by 100.
+        int_value: ?i32,
+
+        /// The value as a float, divided by 100 so that the nominal range is 0.0 to 1.0.
+        unit_value: f32,
+    },
+
+    /// A `<dimension-token>`
+    dimension: struct {
+        /// Whether the number had a `+` or `-` sign.
+        ///
+        /// This is used is some cases like the <An+B> micro syntax. (See the `parse_nth` function.)
+        has_sign: bool,
+
+        /// If the origin source did not include a fractional part, the value as an integer.
+        int_value: ?i32,
+
+        /// The value as a float
+        value: f32,
+
+        /// The unit, e.g. "px" in `12px`
+        unit: []const u8,
+    },
+
+    /// A `<unicode-range-token>`
+    unicode_range: struct { bgn: u32, end: i32 },
+
+    /// A `<whitespace-token>`
+    white_space: []const u8,
+
+    /// A `<!--` `<CDO-token>`
+    cdo,
+
+    /// A `-->` `<CDC-token>`
+    cdc,
+
+    /// A `:` `<colon-token>`
+    colon, // :
+
+    /// A `;` `<semicolon-token>`
+    semicolon, // ;
+
+    /// A `,` `<comma-token>`
+    comma, // ,
+
+    /// A `<[-token>`
+    square_bracket_block,
+
+    /// A `<]-token>`
+    ///
+    /// When obtained from one of the `Parser::next*` methods,
+    /// this token is always unmatched and indicates a parse error.
+    close_square_bracket,
+
+    /// A `<(-token>`
+    parenthesis_block,
+
+    /// A `<)-token>`
+    ///
+    /// When obtained from one of the `Parser::next*` methods,
+    /// this token is always unmatched and indicates a parse error.
+    close_parenthesis,
+
+    /// A `<{-token>`
+    curly_bracket_block,
+
+    /// A `<}-token>`
+    ///
+    /// When obtained from one of the `Parser::next*` methods,
+    /// this token is always unmatched and indicates a parse error.
+    close_curly_bracket,
+
+    /// A comment.
+    ///
+    /// The CSS Syntax spec does not generate tokens for comments,
+    /// But we do for simplicity of the interface.
+    ///
+    /// The value does not include the `/*` `*/` markers.
+    comment: []const u8,
+};
+
+input: []const u8,
+
+/// Counted in bytes, not code points. From 0.
+position: usize = 0,
+
+// If true, the input has at least `n` bytes left *after* the current one.
+// That is, `Lexer.byteAt(n)` will not panic.
+fn hasAtLeast(self: *const Tokenizer, n: usize) bool {
+    return self.position + n < self.input.len;
+}
+
+fn isEof(self: *const Tokenizer) bool {
+    return !self.hasAtLeast(0);
+}
+
+fn byteAt(self: *const Tokenizer, offset: usize) u8 {
+    return self.input[self.position + offset];
+}
+
+// Assumes non-EOF
+fn nextByteUnchecked(self: *const Tokenizer) u8 {
+    return self.byteAt(0);
+}
+
+fn nextByte(self: *const Tokenizer) ?u8 {
+    return if (self.isEof())
+        null
+    else
+        self.input[self.position];
+}
+
+fn startsWith(self: *const Tokenizer, needle: []const u8) bool {
+    return std.mem.startsWith(u8, self.input[self.position..], needle);
+}
+
+fn slice(self: *const Tokenizer, start: usize, end: usize) []const u8 {
+    return self.input[start..end];
+}
+
+fn sliceFrom(self: *const Tokenizer, start_pos: usize) []const u8 {
+    return self.slice(start_pos, self.position);
+}
+
+// Advance over N bytes in the input.  This function can advance
+// over ASCII bytes (excluding newlines), or UTF-8 sequence
+// leaders (excluding leaders for 4-byte sequences).
+fn advance(self: *Tokenizer, n: usize) void {
+    if (builtin.mode == .Debug) {
+        // Each byte must either be an ASCII byte or a sequence leader,
+        // but not a 4-byte leader; also newlines are rejected.
+        for (0..n) |i| {
+            const b = self.byteAt(i);
+            assert(b != '\r' and b != '\n' and b != '\x0C');
+            assert(b <= 0x7F or (b & 0xF0 != 0xF0 and b & 0xC0 != 0x80));
+        }
+    }
+    self.position += n;
+}
+
+fn hasNewlineAt(self: *const Tokenizer, offset: usize) bool {
+    if (!self.hasAtLeast(offset)) return false;
+
+    return switch (self.byteAt(offset)) {
+        '\n', '\r', '\x0C' => true,
+        else => false,
+    };
+}
+
+fn hasNonAsciiAt(self: *const Tokenizer, offset: usize) bool {
+    if (!self.hasAtLeast(offset)) return false;
+
+    const byte = self.byteAt(offset);
+    const len_utf8 = std.unicode.utf8ByteSequenceLength(byte) catch return false;
+
+    if (!self.hasAtLeast(offset + len_utf8 - 1)) return false;
+
+    const start = self.position + offset;
+    const bytes = self.slice(start, start + len_utf8);
+
+    const codepoint = std.unicode.utf8Decode(bytes) catch return false;
+
+    // https://drafts.csswg.org/css-syntax/#non-ascii-ident-code-point
+    return switch (codepoint) {
+        '\u{00B7}', '\u{200C}', '\u{200D}', '\u{203F}', '\u{2040}' => true,
+        '\u{00C0}'...'\u{00D6}' => true,
+        '\u{00D8}'...'\u{00F6}' => true,
+        '\u{00F8}'...'\u{037D}' => true,
+        '\u{037F}'...'\u{1FFF}' => true,
+        '\u{2070}'...'\u{218F}' => true,
+        '\u{2C00}'...'\u{2FEF}' => true,
+        '\u{3001}'...'\u{D7FF}' => true,
+        '\u{F900}'...'\u{FDCF}' => true,
+        '\u{FDF0}'...'\u{FFFD}' => true,
+        else => codepoint >= '\u{10000}',
+    };
+}
+
+fn isIdentStart(self: *Tokenizer) bool {
+    if (self.isEof()) return false;
+
+    var b = self.nextByteUnchecked();
+    if (b == '-') {
+        b = if (self.hasAtLeast(1)) self.byteAt(1) else return false;
+    }
+
+    return switch (b) {
+        'a'...'z', 'A'...'Z', '_', 0x0 => true,
+        '\\' => !self.hasNewlineAt(1),
+        else => b > 0x7F, // not is ascii
+    };
+}
+
+fn consumeChar(self: *Tokenizer) void {
+    const byte = self.nextByteUnchecked();
+    const len_utf8 = std.unicode.utf8ByteSequenceLength(byte) catch 1;
+    self.position += len_utf8;
+}
+
+// Given that a newline has been seen, advance over the newline
+// and update the state.
+fn consumeNewline(self: *Tokenizer) void {
+    const byte = self.nextByteUnchecked();
+    assert(byte == '\r' or byte == '\n' or byte == '\x0C');
+
+    self.position += 1;
+    if (byte == '\r' and self.nextByte() == '\n') {
+        self.position += 1;
+    }
+}
+
+fn consumeWhiteSpace(self: *Tokenizer, newline: bool) Token {
+    const start_position = self.position;
+    if (newline) {
+        self.consumeNewline();
+    } else {
+        self.advance(1);
+    }
+    while (!self.isEof()) {
+        const b = self.nextByteUnchecked();
+        switch (b) {
+            ' ', '\t' => {
+                self.advance(1);
+            },
+            '\n', '\x0C', '\r' => {
+                self.consumeNewline();
+            },
+            else => break,
+        }
+    }
+    return .{ .white_space = self.sliceFrom(start_position) };
+}
+
+fn consumeComment(self: *Tokenizer) []const u8 {
+    self.advance(2); // consume "/*"
+    const start_position = self.position;
+    while (!self.isEof()) {
+        switch (self.nextByteUnchecked()) {
+            '*' => {
+                const end_position = self.position;
+                self.advance(1);
+                if (self.nextByte() == '/') {
+                    self.advance(1);
+                    return self.slice(start_position, end_position);
+                }
+            },
+            '\n', '\x0C', '\r' => {
+                self.consumeNewline();
+            },
+            0x0 => self.advance(1),
+            else => self.consumeChar(),
+        }
+    }
+    return self.sliceFrom(start_position);
+}
+
+fn byteToHexDigit(b: u8) ?u32 {
+    return switch (b) {
+        '0'...'9' => b - '0',
+        'a'...'f' => b - 'a' + 10,
+        'A'...'F' => b - 'A' + 10,
+        else => null,
+    };
+}
+
+fn byteToDecimalDigit(b: u8) ?u32 {
+    return if (std.ascii.isDigit(b)) b - '0' else null;
+}
+
+// (value, number of digits up to 6)
+fn consumeHexDigits(self: *Tokenizer) void {
+    var value: u32 = 0;
+    var digits: u32 = 0;
+
+    while (digits < 6 and !self.isEof()) {
+        if (byteToHexDigit(self.nextByteUnchecked())) |digit| {
+            value = value * 16 + digit;
+            digits += 1;
+            self.advance(1);
+        } else {
+            break;
+        }
+    }
+
+    _ = &value;
+}
+
+// Assumes that the U+005C REVERSE SOLIDUS (\) has already been consumed
+// and that the next input character has already been verified
+// to not be a newline.
+fn consumeEscape(self: *Tokenizer) void {
+    if (self.isEof())
+        return; // Escaped EOF
+
+    switch (self.nextByteUnchecked()) {
+        '0'...'9', 'A'...'F', 'a'...'f' => {
+            consumeHexDigits(self);
+
+            if (!self.isEof()) {
+                switch (self.nextByteUnchecked()) {
+                    ' ', '\t' => {
+                        self.advance(1);
+                    },
+                    '\n', '\x0C', '\r' => {
+                        self.consumeNewline();
+                    },
+                    else => {},
+                }
+            }
+        },
+        else => self.consumeChar(),
+    }
+}
+
+/// https://drafts.csswg.org/css-syntax/#consume-string-token
+fn consumeString(self: *Tokenizer, single_quote: bool) Token {
+    self.advance(1); // Skip the initial quote
+
+    // start_pos is at code point boundary, after " or '
+    const start_pos = self.position;
+
+    while (!self.isEof()) {
+        switch (self.nextByteUnchecked()) {
+            '"' => {
+                if (!single_quote) {
+                    const value = self.sliceFrom(start_pos);
+                    self.advance(1);
+                    return .{ .string = value };
+                }
+                self.advance(1);
+            },
+            '\'' => {
+                if (single_quote) {
+                    const value = self.sliceFrom(start_pos);
+                    self.advance(1);
+                    return .{ .string = value };
+                }
+                self.advance(1);
+            },
+            '\n', '\r', '\x0C' => {
+                return .{ .bad_string = self.sliceFrom(start_pos) };
+            },
+            '\\' => {
+                self.advance(1);
+                if (self.isEof())
+                    continue; // escaped EOF, do nothing.
+
+                switch (self.nextByteUnchecked()) {
+                    // Escaped newline
+                    '\n', '\x0C', '\r' => self.consumeNewline(),
+
+                    // Spec calls for replacing escape sequences with characters,
+                    // but this would require allocating a new string.
+                    // Therefore, we leave it as is and let the parser handle the escaping.
+                    else => self.consumeEscape(),
+                }
+            },
+            else => self.consumeChar(),
+        }
+    }
+
+    return .{ .string = self.sliceFrom(start_pos) };
+}
+
+fn consumeName(self: *Tokenizer) []const u8 {
+    // start_pos is the end of the previous token, therefore at a code point boundary
+    const start_pos = self.position;
+
+    while (!self.isEof()) {
+        switch (self.nextByteUnchecked()) {
+            'a'...'z', 'A'...'Z', '0'...'9', '_', '-' => self.advance(1),
+            '\\' => {
+                if (self.hasNewlineAt(1)) {
+                    break;
+                }
+
+                self.advance(1);
+                self.consumeEscape();
+            },
+            0x0 => self.advance(1),
+            '\x80'...'\xFF' => {
+                // Non-ASCII: advance over the complete UTF-8 code point in one step.
+                // Using consumeChar() instead of advance(1) ensures we never land on
+                // a continuation byte, which advance() asserts against.
+                self.consumeChar();
+            },
+            else => {
+                if (self.hasNonAsciiAt(0)) {
+                    self.consumeChar();
+                } else {
+                    break; // ASCII
+                }
+            },
+        }
+    }
+
+    return self.sliceFrom(start_pos);
+}
+
+fn consumeMark(self: *Tokenizer) Token {
+    const byte = self.nextByteUnchecked();
+    self.advance(1);
+    return switch (byte) {
+        ',' => .comma,
+        ':' => .colon,
+        ';' => .semicolon,
+        '(' => .parenthesis_block,
+        ')' => .close_parenthesis,
+        '{' => .curly_bracket_block,
+        '}' => .close_curly_bracket,
+        '[' => .square_bracket_block,
+        ']' => .close_square_bracket,
+        else => unreachable,
+    };
+}
+
+fn consumeNumeric(self: *Tokenizer) Token {
+    // Parse [+-]?\d*(\.\d+)?([eE][+-]?\d+)?
+    // But this is always called so that there is at least one digit in \d*(\.\d+)?
+
+    // Do all the math in f64 so that large numbers overflow to +/-inf
+    // and i32::{MIN, MAX} are within range.
+
+    var sign: f64 = 1.0;
+    var has_sign = false;
+    switch (self.nextByteUnchecked()) {
+        '+' => {
+            has_sign = true;
+        },
+        '-' => {
+            has_sign = true;
+            sign = -1.0;
+        },
+        else => {},
+    }
+    if (has_sign) {
+        self.advance(1);
+    }
+
+    var is_integer = true;
+    var integral_part: f64 = 0.0;
+    var fractional_part: f64 = 0.0;
+
+    while (!self.isEof()) {
+        if (byteToDecimalDigit(self.nextByteUnchecked())) |digit| {
+            integral_part = integral_part * 10.0 + @as(f64, @floatFromInt(digit));
+            self.advance(1);
+        } else {
+            break;
+        }
+    }
+
+    if (self.hasAtLeast(1) and self.nextByteUnchecked() == '.' and std.ascii.isDigit(self.byteAt(1))) {
+        is_integer = false;
+        self.advance(1); // Consume '.'
+
+        var factor: f64 = 0.1;
+        while (!self.isEof()) {
+            if (byteToDecimalDigit(self.nextByteUnchecked())) |digit| {
+                fractional_part += @as(f64, @floatFromInt(digit)) * factor;
+                factor *= 0.1;
+                self.advance(1);
+            } else {
+                break;
+            }
+        }
+    }
+
+    var value = sign * (integral_part + fractional_part);
+
+    blk: {
+        const e = self.nextByte() orelse break :blk;
+        if (e != 'e' and e != 'E') break :blk;
+
+        var mul: f64 = 1.0;
+
+        if (self.hasAtLeast(2) and (self.byteAt(1) == '+' or self.byteAt(1) == '-') and std.ascii.isDigit(self.byteAt(2))) {
+            mul = switch (self.byteAt(1)) {
+                '-' => -1.0,
+                '+' => 1.0,
+                else => unreachable,
+            };
+
+            self.advance(2);
+        } else if (self.hasAtLeast(2) and std.ascii.isDigit(self.byteAt(2))) {
+            self.advance(1);
+        } else {
+            break :blk;
+        }
+
+        is_integer = false;
+
+        var exponent: f64 = 0.0;
+        while (!self.isEof()) {
+            if (byteToDecimalDigit(self.nextByteUnchecked())) |digit| {
+                exponent = exponent * 10.0 + @as(f64, @floatFromInt(digit));
+                self.advance(1);
+            } else {
+                break;
+            }
+        }
+        value *= std.math.pow(f64, 10.0, mul * exponent);
+    }
+
+    const int_value: ?i32 = if (is_integer) blk: {
+        if (value >= std.math.maxInt(i32)) {
+            break :blk std.math.maxInt(i32);
+        }
+
+        if (value <= std.math.minInt(i32)) {
+            break :blk std.math.minInt(i32);
+        }
+
+        break :blk @as(i32, @intFromFloat(value));
+    } else null;
+
+    if (!self.isEof() and self.nextByteUnchecked() == '%') {
+        self.advance(1);
+
+        return .{ .percentage = .{
+            .has_sign = has_sign,
+            .int_value = int_value,
+            .unit_value = @as(f32, @floatCast(value / 100.0)),
+        } };
+    }
+
+    if (isIdentStart(self)) {
+        return .{ .dimension = .{
+            .has_sign = has_sign,
+            .int_value = int_value,
+            .value = @as(f32, @floatCast(value)),
+            .unit = consumeName(self),
+        } };
+    }
+
+    return .{ .number = .{
+        .has_sign = has_sign,
+        .int_value = int_value,
+        .value = @as(f32, @floatCast(value)),
+    } };
+}
+
+fn consumeUnquotedUrl(self: *Tokenizer) ?Token {
+    // TODO: true url parser
+    if (self.nextByte()) |it| {
+        return self.consumeString(it == '\'');
+    }
+
+    return null;
+}
+
+fn consumeIdentLike(self: *Tokenizer) Token {
+    const value = self.consumeName();
+
+    if (!self.isEof() and self.nextByteUnchecked() == '(') {
+        self.advance(1);
+
+        if (std.ascii.eqlIgnoreCase(value, "url")) {
+            if (self.consumeUnquotedUrl()) |result| {
+                return result;
+            }
+        }
+
+        return .{ .function = value };
+    }
+
+    return .{ .ident = value };
+}
+
+pub fn next(self: *Tokenizer) ?Token {
+    if (self.isEof()) {
+        return null;
+    }
+
+    const b = self.nextByteUnchecked();
+    return switch (b) {
+        // Consume comments
+        '/' => {
+            if (self.startsWith("/*")) {
+                return .{ .comment = self.consumeComment() };
+            } else {
+                self.advance(1);
+                return .{ .delim = '/' };
+            }
+        },
+
+        // Consume marks
+        '(', ')', '{', '}', '[', ']', ',', ':', ';' => {
+            return self.consumeMark();
+        },
+
+        // Consume as much whitespace as possible. Return a <whitespace-token>.
+        ' ', '\t' => self.consumeWhiteSpace(false),
+        '\n', '\x0C', '\r' => self.consumeWhiteSpace(true),
+
+        // Consume a string token and return it.
+        '"' => self.consumeString(false),
+        '\'' => self.consumeString(true),
+
+        '0'...'9' => self.consumeNumeric(),
+        'a'...'z', 'A'...'Z', '_', 0x0 => self.consumeIdentLike(),
+
+        '+' => {
+            if ((self.hasAtLeast(1) and std.ascii.isDigit(self.byteAt(1))) or
+                (self.hasAtLeast(2) and self.byteAt(1) == '.' and std.ascii.isDigit(self.byteAt(2))))
+            {
+                return self.consumeNumeric();
+            }
+            self.advance(1);
+            return .{ .delim = '+' };
+        },
+        '-' => {
+            if ((self.hasAtLeast(1) and std.ascii.isDigit(self.byteAt(1))) or
+                (self.hasAtLeast(2) and self.byteAt(1) == '.' and std.ascii.isDigit(self.byteAt(2))))
+            {
+                return self.consumeNumeric();
+            }
+
+            if (self.startsWith("-->")) {
+                self.advance(3);
+                return .cdc;
+            }
+
+            if (isIdentStart(self)) {
+                return self.consumeIdentLike();
+            }
+
+            self.advance(1);
+            return .{ .delim = '-' };
+        },
+        '.' => {
+            if (self.hasAtLeast(1) and std.ascii.isDigit(self.byteAt(1))) {
+                return self.consumeNumeric();
+            }
+            self.advance(1);
+            return .{ .delim = '.' };
+        },
+
+        // Consume hash token
+        '#' => {
+            self.advance(1);
+            if (self.isIdentStart()) {
+                return .{ .id_hash = self.consumeName() };
+            }
+            if (self.nextByte()) |it| {
+                switch (it) {
+                    // Any other valid case here already resulted in IDHash.
+                    '0'...'9', '-' => return .{ .unrestricted_hash = self.consumeName() },
+                    else => {},
+                }
+            }
+            return .{ .delim = '#' };
+        },
+
+        // Consume at-rules
+        '@' => {
+            self.advance(1);
+            return if (isIdentStart(self))
+                .{ .at_keyword = consumeName(self) }
+            else
+                .{ .delim = '@' };
+        },
+
+        '<' => {
+            if (self.startsWith("<!--")) {
+                self.advance(4);
+                return .cdo;
+            } else {
+                self.advance(1);
+                return .{ .delim = '<' };
+            }
+        },
+
+        '\\' => {
+            if (!self.hasNewlineAt(1)) {
+                return self.consumeIdentLike();
+            }
+
+            self.advance(1);
+            return .{ .delim = '\\' };
+        },
+
+        else => {
+            if (b > 0x7F) { // not is ascii
+                return self.consumeIdentLike();
+            }
+
+            self.advance(1);
+            return .{ .delim = b };
+        },
+    };
+}
+
+const testing = std.testing;
+
+fn expectTokensEqual(input: []const u8, tokens: []const Token) !void {
+    var lexer = Tokenizer{ .input = input };
+
+    var i: usize = 0;
+    while (lexer.next()) |token| : (i += 1) {
+        assert(i < tokens.len);
+        try testing.expectEqualDeep(tokens[i], token);
+    }
+
+    try testing.expectEqual(i, tokens.len);
+    try testing.expectEqualDeep(null, lexer.next());
+}
+
+test "smoke" {
+    try expectTokensEqual(
+        \\.lightpanda  {color:red;}
+    , &.{
+        .{ .delim = '.' },
+        .{ .ident = "lightpanda" },
+        .{ .white_space = "  " },
+        .curly_bracket_block,
+        .{ .ident = "color" },
+        .colon,
+        .{ .ident = "red" },
+        .semicolon,
+        .close_curly_bracket,
+    });
+}

src/browser/dump.zig

@@ -1,4 +1,4 @@
-// Copyright (C) 2023-2024  Lightpanda (Selecy SAS)
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
 //
 // Francis Bouvier <francis@lightpanda.io>
 // Pierre Tachoire <pierre@lightpanda.io>
@@ -17,116 +17,344 @@
 // along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 const std = @import("std");
-const File = std.fs.File;
+const Page = @import("Page.zig");
+const Node = @import("webapi/Node.zig");
+const Slot = @import("webapi/element/html/Slot.zig");
+const IFrame = @import("webapi/element/html/IFrame.zig");
 
-const parser = @import("netsurf");
-const Walker = @import("../dom/walker.zig").WalkerChildren;
+const IS_DEBUG = @import("builtin").mode == .Debug;
 
-// writer must be a std.io.Writer
-pub fn writeHTML(doc: *parser.Document, writer: anytype) !void {
-    try writer.writeAll("<!DOCTYPE html>\n");
-    try writeNode(parser.documentToNode(doc), writer);
-    try writer.writeAll("\n");
+pub const Opts = struct {
+    with_base: bool = false,
+    with_frames: bool = false,
+    strip: Opts.Strip = .{},
+    shadow: Opts.Shadow = .rendered,
+
+    pub const Strip = struct {
+        js: bool = false,
+        ui: bool = false,
+        css: bool = false,
+    };
+
+    pub const Shadow = enum {
+        // Skip shadow DOM entirely (innerHTML/outerHTML)
+        skip,
+
+        // Dump everyhting (like "view source")
+        complete,
+
+        // Resolve slot elements (like what actually gets rendered)
+        rendered,
+    };
+};
+
+pub fn root(doc: *Node.Document, opts: Opts, writer: *std.Io.Writer, page: *Page) !void {
+    if (doc.is(Node.Document.HTMLDocument)) |html_doc| {
+        blk: {
+            // Ideally we just render the doctype which is part of the document
+            if (doc.asNode().firstChild()) |first| {
+                if (first._type == .document_type) {
+                    break :blk;
+                }
+            }
+            // But if the doc has no child, or the first child isn't a doctype
+            // well force it.
+            try writer.writeAll("<!DOCTYPE html>");
+        }
+
+        if (opts.with_base) {
+            const parent = if (html_doc.getHead()) |head| head.asNode() else doc.asNode();
+            const base = try doc.createElement("base", null, page);
+            try base.setAttributeSafe(comptime .wrap("base"), .wrap(page.base()), page);
+            _ = try parent.insertBefore(base.asNode(), parent.firstChild(), page);
+        }
+    }
+
+    return deep(doc.asNode(), opts, writer, page);
 }
 
-// writer must be a std.io.Writer
-pub fn writeNode(root: *parser.Node, writer: anytype) !void {
-    const walker = Walker{};
-    var next: ?*parser.Node = null;
-    while (true) {
-        next = try walker.get_next(root, next) orelse break;
-        switch (try parser.nodeType(next.?)) {
-            .element => {
-                // open the tag
-                const tag = try parser.nodeLocalName(next.?);
-                try writer.writeAll("<");
-                try writer.writeAll(tag);
+pub fn deep(node: *Node, opts: Opts, writer: *std.Io.Writer, page: *Page) error{WriteFailed}!void {
+    return _deep(node, opts, false, writer, page);
+}
 
-                // write the attributes
-                const map = try parser.nodeGetAttributes(next.?);
-                const ln = try parser.namedNodeMapGetLength(map);
-                var i: u32 = 0;
-                while (i < ln) {
-                    const attr = try parser.namedNodeMapItem(map, i) orelse break;
-                    try writer.writeAll(" ");
-                    try writer.writeAll(try parser.attributeGetName(attr));
-                    try writer.writeAll("=\"");
-                    try writer.writeAll(try parser.attributeGetValue(attr) orelse "");
-                    try writer.writeAll("\"");
-                    i += 1;
-                }
-
-                try writer.writeAll(">");
-
-                // void elements can't have any content.
-                if (try isVoid(parser.nodeToElement(next.?))) continue;
-
-                // write the children
-                // TODO avoid recursion
-                try writeNode(next.?, writer);
-
-                // close the tag
-                try writer.writeAll("</");
-                try writer.writeAll(tag);
-                try writer.writeAll(">");
-            },
-            .text => {
-                const v = try parser.nodeValue(next.?) orelse continue;
-                try writer.writeAll(v);
-            },
-            .cdata_section => {
-                const v = try parser.nodeValue(next.?) orelse continue;
-                try writer.writeAll("<![CDATA[");
-                try writer.writeAll(v);
-                try writer.writeAll("]]>");
-            },
-            .comment => {
-                const v = try parser.nodeValue(next.?) orelse continue;
+fn _deep(node: *Node, opts: Opts, comptime force_slot: bool, writer: *std.Io.Writer, page: *Page) error{WriteFailed}!void {
+    switch (node._type) {
+        .cdata => |cd| {
+            if (node.is(Node.CData.Comment)) |_| {
                 try writer.writeAll("<!--");
-                try writer.writeAll(v);
+                try writer.writeAll(cd.getData().str());
                 try writer.writeAll("-->");
-            },
-            // TODO handle processing instruction dump
-            .processing_instruction => continue,
-            // document fragment is outside of the main document DOM, so we
-            // don't output it.
-            .document_fragment => continue,
-            // document will never be called, but required for completeness.
-            .document => continue,
-            // done globally instead, but required for completeness.
-            .document_type => continue,
-            // deprecated
-            .attribute => continue,
-            .entity_reference => continue,
-            .entity => continue,
-            .notation => continue,
-        }
+            } else if (node.is(Node.CData.ProcessingInstruction)) |pi| {
+                try writer.writeAll("<?");
+                try writer.writeAll(pi._target);
+                try writer.writeAll(" ");
+                try writer.writeAll(cd.getData().str());
+                try writer.writeAll("?>");
+            } else {
+                if (shouldEscapeText(node._parent)) {
+                    try writeEscapedText(cd.getData().str(), writer);
+                } else {
+                    try writer.writeAll(cd.getData().str());
+                }
+            }
+        },
+        .element => |el| {
+            if (shouldStripElement(el, opts)) {
+                return;
+            }
+
+            // When opts.shadow == .rendered, we normally skip any element with
+            // a slot attribute. Only the "active" element will get rendered into
+            // the <slot name="X">. However, the `deep` function is itself used
+            // to render that "active" content, so when we're trying to render
+            // it, we don't want to skip it.
+            if ((comptime force_slot == false) and opts.shadow == .rendered) {
+                if (el.getAttributeSafe(comptime .wrap("slot"))) |_| {
+                    // Skip - will be rendered by the Slot if it's the active container
+                    return;
+                }
+            }
+
+            try el.format(writer);
+
+            if (opts.shadow == .rendered) {
+                if (el.is(Slot)) |slot| {
+                    try dumpSlotContent(slot, opts, writer, page);
+                    return writer.writeAll("</slot>");
+                }
+            }
+            if (opts.shadow != .skip) {
+                if (page._element_shadow_roots.get(el)) |shadow| {
+                    try children(shadow.asNode(), opts, writer, page);
+                    // In rendered mode, light DOM is only shown through slots, not directly
+                    if (opts.shadow == .rendered) {
+                        // Skip rendering light DOM children
+                        if (!isVoidElement(el)) {
+                            try writer.writeAll("</");
+                            try writer.writeAll(el.getTagNameDump());
+                            try writer.writeByte('>');
+                        }
+                        return;
+                    }
+                }
+            }
+
+            if (opts.with_frames and el.is(IFrame) != null) {
+                const frame = el.as(IFrame);
+                if (frame.getContentDocument()) |doc| {
+                    // A frame's document should always ahave a page, but
+                    // I'm not willing to crash a release build on that assertion.
+                    if (comptime IS_DEBUG) {
+                        std.debug.assert(doc._page != null);
+                    }
+                    if (doc._page) |frame_page| {
+                        try writer.writeByte('\n');
+                        root(doc, opts, writer, frame_page) catch return error.WriteFailed;
+                        try writer.writeByte('\n');
+                    }
+                }
+            } else {
+                try children(node, opts, writer, page);
+            }
+
+            if (!isVoidElement(el)) {
+                try writer.writeAll("</");
+                try writer.writeAll(el.getTagNameDump());
+                try writer.writeByte('>');
+            }
+        },
+        .document => try children(node, opts, writer, page),
+        .document_type => |dt| {
+            try writer.writeAll("<!DOCTYPE ");
+            try writer.writeAll(dt.getName());
+
+            const public_id = dt.getPublicId();
+            const system_id = dt.getSystemId();
+            if (public_id.len != 0 and system_id.len != 0) {
+                try writer.writeAll(" PUBLIC \"");
+                try writeEscapedText(public_id, writer);
+                try writer.writeAll("\" \"");
+                try writeEscapedText(system_id, writer);
+                try writer.writeByte('"');
+            } else if (public_id.len != 0) {
+                try writer.writeAll(" PUBLIC \"");
+                try writeEscapedText(public_id, writer);
+                try writer.writeByte('"');
+            } else if (system_id.len != 0) {
+                try writer.writeAll(" SYSTEM \"");
+                try writeEscapedText(system_id, writer);
+                try writer.writeByte('"');
+            }
+            try writer.writeAll(">\n");
+        },
+        .document_fragment => try children(node, opts, writer, page),
+        .attribute => {
+            // Not called normally, but can be called via XMLSerializer.serializeToString
+            // in which case it should return an empty string
+            try writer.writeAll("");
+        },
     }
 }
 
-// area, base, br, col, embed, hr, img, input, link, meta, source, track, wbr
-// https://html.spec.whatwg.org/#void-elements
-fn isVoid(elem: *parser.Element) !bool {
-    const tag = try parser.elementHTMLGetTagType(@as(*parser.ElementHTML, @ptrCast(elem)));
-    return switch (tag) {
-        .area, .base, .br, .col, .embed, .hr, .img, .input, .link => true,
-        .meta, .source, .track, .wbr => true,
-        else => false,
+pub fn children(parent: *Node, opts: Opts, writer: *std.Io.Writer, page: *Page) !void {
+    var it = parent.childrenIterator();
+    while (it.next()) |child| {
+        try deep(child, opts, writer, page);
+    }
+}
+
+pub fn toJSON(node: *Node, writer: *std.json.Stringify) !void {
+    try writer.beginObject();
+
+    try writer.objectField("type");
+    switch (node.type) {
+        .cdata => {
+            try writer.write("cdata");
+        },
+        .document => {
+            try writer.write("document");
+        },
+        .document_type => {
+            try writer.write("document_type");
+        },
+        .element => |*el| {
+            try writer.write("element");
+            try writer.objectField("tag");
+            try writer.write(el.tagName());
+
+            try writer.objectField("attributes");
+            try writer.beginObject();
+            var it = el.attributeIterator();
+            while (it.next()) |attr| {
+                try writer.objectField(attr.name);
+                try writer.write(attr.value);
+            }
+            try writer.endObject();
+        },
+    }
+
+    try writer.objectField("children");
+    try writer.beginArray();
+    var it = node.childrenIterator();
+    while (it.next()) |child| {
+        try toJSON(child, writer);
+    }
+    try writer.endArray();
+    try writer.endObject();
+}
+
+fn dumpSlotContent(slot: *Slot, opts: Opts, writer: *std.Io.Writer, page: *Page) !void {
+    const assigned = slot.assignedNodes(null, page) catch return;
+
+    if (assigned.len > 0) {
+        for (assigned) |assigned_node| {
+            try _deep(assigned_node, opts, true, writer, page);
+        }
+    } else {
+        try children(slot.asNode(), opts, writer, page);
+    }
+}
+
+fn isVoidElement(el: *const Node.Element) bool {
+    return switch (el._type) {
+        .html => |html| switch (html._type) {
+            .br, .hr, .img, .input, .link, .meta => true,
+            else => false,
+        },
+        .svg => false,
     };
 }
 
-test "dump.writeHTML" {
-    const out = try std.fs.openFileAbsolute("/dev/null", .{ .mode = .write_only });
-    defer out.close();
+fn shouldStripElement(el: *const Node.Element, opts: Opts) bool {
+    const tag_name = el.getTagNameDump();
 
-    const file = try std.fs.cwd().openFile("test.html", .{});
-    defer file.close();
+    if (opts.strip.js) {
+        if (std.mem.eql(u8, tag_name, "script")) return true;
+        if (std.mem.eql(u8, tag_name, "noscript")) return true;
 
-    const doc_html = try parser.documentHTMLParse(file.reader(), "UTF-8");
-    // ignore close error
-    defer parser.documentHTMLClose(doc_html) catch {};
+        if (std.mem.eql(u8, tag_name, "link")) {
+            if (el.getAttributeSafe(comptime .wrap("as"))) |as| {
+                if (std.mem.eql(u8, as, "script")) return true;
+            }
+            if (el.getAttributeSafe(comptime .wrap("rel"))) |rel| {
+                if (std.mem.eql(u8, rel, "modulepreload") or std.mem.eql(u8, rel, "preload")) {
+                    if (el.getAttributeSafe(comptime .wrap("as"))) |as| {
+                        if (std.mem.eql(u8, as, "script")) return true;
+                    }
+                }
+            }
+        }
+    }
 
-    const doc = parser.documentHTMLToDocument(doc_html);
+    if (opts.strip.css or opts.strip.ui) {
+        if (std.mem.eql(u8, tag_name, "style")) return true;
 
-    try writeHTML(doc, out);
+        if (std.mem.eql(u8, tag_name, "link")) {
+            if (el.getAttributeSafe(comptime .wrap("rel"))) |rel| {
+                if (std.mem.eql(u8, rel, "stylesheet")) return true;
+            }
+        }
+    }
+
+    if (opts.strip.ui) {
+        if (std.mem.eql(u8, tag_name, "img")) return true;
+        if (std.mem.eql(u8, tag_name, "picture")) return true;
+        if (std.mem.eql(u8, tag_name, "video")) return true;
+        if (std.mem.eql(u8, tag_name, "audio")) return true;
+        if (std.mem.eql(u8, tag_name, "svg")) return true;
+        if (std.mem.eql(u8, tag_name, "canvas")) return true;
+        if (std.mem.eql(u8, tag_name, "iframe")) return true;
+    }
+
+    return false;
+}
+
+fn shouldEscapeText(node_: ?*Node) bool {
+    const node = node_ orelse return true;
+    if (node.is(Node.Element.Html.Script) != null) {
+        return false;
+    }
+    // When scripting is enabled, <noscript> is a raw text element per the HTML spec
+    // (https://html.spec.whatwg.org/multipage/parsing.html#serialising-html-fragments).
+    // Its text content must not be HTML-escaped during serialization.
+    if (node.is(Node.Element.Html.Generic)) |generic| {
+        if (generic._tag == .noscript) return false;
+    }
+    return true;
+}
+fn writeEscapedText(text: []const u8, writer: *std.Io.Writer) !void {
+    // Fast path: if no special characters, write directly
+    const first_special = std.mem.indexOfAnyPos(u8, text, 0, &.{ '&', '<', '>', 194 }) orelse {
+        return writer.writeAll(text);
+    };
+
+    try writer.writeAll(text[0..first_special]);
+    var remaining = try writeEscapedByte(text, first_special, writer);
+
+    while (std.mem.indexOfAnyPos(u8, remaining, 0, &.{ '&', '<', '>', 194 })) |offset| {
+        try writer.writeAll(remaining[0..offset]);
+        remaining = try writeEscapedByte(remaining, offset, writer);
+    }
+
+    if (remaining.len > 0) {
+        try writer.writeAll(remaining);
+    }
+}
+
+fn writeEscapedByte(input: []const u8, index: usize, writer: *std.Io.Writer) ![]const u8 {
+    switch (input[index]) {
+        '&' => try writer.writeAll("&amp;"),
+        '<' => try writer.writeAll("&lt;"),
+        '>' => try writer.writeAll("&gt;"),
+        194 => {
+            // non breaking space
+            if (input.len > index + 1 and input[index + 1] == 160) {
+                try writer.writeAll("&nbsp;");
+                return input[index + 2 ..];
+            }
+            try writer.writeByte(194);
+        },
+        else => unreachable,
+    }
+    return input[index + 1 ..];
 }

src/browser/forms.zig

@@ -0,0 +1,460 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+
+const Page = @import("Page.zig");
+const TreeWalker = @import("webapi/TreeWalker.zig");
+const Element = @import("webapi/Element.zig");
+const Node = @import("webapi/Node.zig");
+
+const Allocator = std.mem.Allocator;
+
+pub const SelectOption = struct {
+    value: []const u8,
+    text: []const u8,
+
+    pub fn jsonStringify(self: *const SelectOption, jw: anytype) !void {
+        try jw.beginObject();
+        try jw.objectField("value");
+        try jw.write(self.value);
+        try jw.objectField("text");
+        try jw.write(self.text);
+        try jw.endObject();
+    }
+};
+
+pub const FormField = struct {
+    backendNodeId: ?u32 = null,
+    node: *Node,
+    tag_name: []const u8,
+    name: ?[]const u8,
+    input_type: ?[]const u8,
+    required: bool,
+    disabled: bool,
+    value: ?[]const u8,
+    placeholder: ?[]const u8,
+    options: []SelectOption,
+
+    pub fn jsonStringify(self: *const FormField, jw: anytype) !void {
+        try jw.beginObject();
+
+        if (self.backendNodeId) |id| {
+            try jw.objectField("backendNodeId");
+            try jw.write(id);
+        }
+
+        try jw.objectField("tagName");
+        try jw.write(self.tag_name);
+
+        if (self.name) |v| {
+            try jw.objectField("name");
+            try jw.write(v);
+        }
+
+        if (self.input_type) |v| {
+            try jw.objectField("inputType");
+            try jw.write(v);
+        }
+
+        try jw.objectField("required");
+        try jw.write(self.required);
+
+        try jw.objectField("disabled");
+        try jw.write(self.disabled);
+
+        if (self.value) |v| {
+            try jw.objectField("value");
+            try jw.write(v);
+        }
+
+        if (self.placeholder) |v| {
+            try jw.objectField("placeholder");
+            try jw.write(v);
+        }
+
+        if (self.options.len > 0) {
+            try jw.objectField("options");
+            try jw.beginArray();
+            for (self.options) |opt| {
+                try opt.jsonStringify(jw);
+            }
+            try jw.endArray();
+        }
+
+        try jw.endObject();
+    }
+};
+
+pub const FormInfo = struct {
+    backendNodeId: ?u32 = null,
+    node: *Node,
+    action: ?[]const u8,
+    method: ?[]const u8,
+    fields: []FormField,
+
+    pub fn jsonStringify(self: *const FormInfo, jw: anytype) !void {
+        try jw.beginObject();
+
+        if (self.backendNodeId) |id| {
+            try jw.objectField("backendNodeId");
+            try jw.write(id);
+        }
+
+        if (self.action) |v| {
+            try jw.objectField("action");
+            try jw.write(v);
+        }
+
+        if (self.method) |v| {
+            try jw.objectField("method");
+            try jw.write(v);
+        }
+
+        try jw.objectField("fields");
+        try jw.beginArray();
+        for (self.fields) |field| {
+            try field.jsonStringify(jw);
+        }
+        try jw.endArray();
+
+        try jw.endObject();
+    }
+};
+
+/// Populate backendNodeId on each form and its fields by registering
+/// their nodes in the given registry. Works with both CDP and MCP registries.
+pub fn registerNodes(forms_data: []FormInfo, registry: anytype) !void {
+    for (forms_data) |*form| {
+        const form_registered = try registry.register(form.node);
+        form.backendNodeId = form_registered.id;
+        for (form.fields) |*field| {
+            const field_registered = try registry.register(field.node);
+            field.backendNodeId = field_registered.id;
+        }
+    }
+}
+
+/// Collect all forms and their fields under `root`.
+/// Uses Form.getElements() to include fields outside the <form> that
+/// reference it via the form="id" attribute, matching browser behavior.
+/// `arena` must be an arena allocator — returned slices borrow its memory.
+pub fn collectForms(
+    arena: Allocator,
+    root: *Node,
+    page: *Page,
+) ![]FormInfo {
+    var forms: std.ArrayList(FormInfo) = .empty;
+
+    var tw = TreeWalker.Full.init(root, .{});
+    while (tw.next()) |node| {
+        const form = node.is(Element.Html.Form) orelse continue;
+        const el = form.asElement();
+
+        const fields = try collectFormFields(arena, form, page);
+        if (fields.len == 0) continue;
+
+        const action_attr = el.getAttributeSafe(comptime .wrap("action"));
+        const method_str = form.getMethod();
+
+        try forms.append(arena, .{
+            .node = node,
+            .action = if (action_attr) |a| if (a.len > 0) a else null else null,
+            .method = method_str,
+            .fields = fields,
+        });
+    }
+
+    return forms.items;
+}
+
+fn collectFormFields(
+    arena: Allocator,
+    form: *Element.Html.Form,
+    page: *Page,
+) ![]FormField {
+    var fields: std.ArrayList(FormField) = .empty;
+
+    var elements = try form.getElements(page);
+    var it = try elements.iterator();
+    while (it.next()) |el| {
+        const node = el.asNode();
+
+        const is_disabled = el.isDisabled();
+
+        if (el.is(Element.Html.Input)) |input| {
+            if (input._input_type == .hidden) continue;
+            if (input._input_type == .submit or input._input_type == .button or input._input_type == .image) continue;
+
+            try fields.append(arena, .{
+                .node = node,
+                .tag_name = "input",
+                .name = el.getAttributeSafe(comptime .wrap("name")),
+                .input_type = input._input_type.toString(),
+                .required = el.getAttributeSafe(comptime .wrap("required")) != null,
+                .disabled = is_disabled,
+                .value = input.getValue(),
+                .placeholder = el.getAttributeSafe(comptime .wrap("placeholder")),
+                .options = &.{},
+            });
+            continue;
+        }
+
+        if (el.is(Element.Html.TextArea)) |textarea| {
+            try fields.append(arena, .{
+                .node = node,
+                .tag_name = "textarea",
+                .name = el.getAttributeSafe(comptime .wrap("name")),
+                .input_type = null,
+                .required = el.getAttributeSafe(comptime .wrap("required")) != null,
+                .disabled = is_disabled,
+                .value = textarea.getValue(),
+                .placeholder = el.getAttributeSafe(comptime .wrap("placeholder")),
+                .options = &.{},
+            });
+            continue;
+        }
+
+        if (el.is(Element.Html.Select)) |select| {
+            const options = try collectSelectOptions(arena, node, page);
+
+            try fields.append(arena, .{
+                .node = node,
+                .tag_name = "select",
+                .name = el.getAttributeSafe(comptime .wrap("name")),
+                .input_type = null,
+                .required = el.getAttributeSafe(comptime .wrap("required")) != null,
+                .disabled = is_disabled,
+                .value = select.getValue(page),
+                .placeholder = null,
+                .options = options,
+            });
+            continue;
+        }
+
+        // Button elements from getElements() - skip (not fillable)
+    }
+
+    return fields.items;
+}
+
+fn collectSelectOptions(
+    arena: Allocator,
+    select_node: *Node,
+    page: *Page,
+) ![]SelectOption {
+    var options: std.ArrayList(SelectOption) = .empty;
+    const Option = Element.Html.Option;
+
+    var tw = TreeWalker.Full.init(select_node, .{});
+    while (tw.next()) |node| {
+        const el = node.is(Element) orelse continue;
+        const option = el.is(Option) orelse continue;
+
+        try options.append(arena, .{
+            .value = option.getValue(page),
+            .text = option.getText(page),
+        });
+    }
+
+    return options.items;
+}
+
+const testing = @import("../testing.zig");
+
+fn testForms(html: []const u8) ![]FormInfo {
+    const page = try testing.test_session.createPage();
+
+    const doc = page.window._document;
+    const div = try doc.createElement("div", null, page);
+    try page.parseHtmlAsChildren(div.asNode(), html);
+
+    return collectForms(page.call_arena, div.asNode(), page);
+}
+
+test "browser.forms: login form" {
+    defer testing.reset();
+    defer testing.test_session.removePage();
+    const forms = try testForms(
+        \\<form action="/login" method="POST">
+        \\  <input type="email" name="email" required placeholder="Email">
+        \\  <input type="password" name="password" required>
+        \\  <input type="submit" value="Log In">
+        \\</form>
+    );
+    try testing.expectEqual(1, forms.len);
+    try testing.expectEqual("/login", forms[0].action.?);
+    try testing.expectEqual("post", forms[0].method.?);
+    try testing.expectEqual(2, forms[0].fields.len);
+    try testing.expectEqual("email", forms[0].fields[0].name.?);
+    try testing.expectEqual("email", forms[0].fields[0].input_type.?);
+    try testing.expect(forms[0].fields[0].required);
+    try testing.expect(!forms[0].fields[0].disabled);
+    try testing.expectEqual("password", forms[0].fields[1].name.?);
+}
+
+test "browser.forms: form with select" {
+    defer testing.reset();
+    defer testing.test_session.removePage();
+    const forms = try testForms(
+        \\<form>
+        \\  <select name="color">
+        \\    <option value="red">Red</option>
+        \\    <option value="blue">Blue</option>
+        \\  </select>
+        \\</form>
+    );
+    try testing.expectEqual(1, forms.len);
+    try testing.expectEqual(1, forms[0].fields.len);
+    try testing.expectEqual("select", forms[0].fields[0].tag_name);
+    try testing.expectEqual(2, forms[0].fields[0].options.len);
+    try testing.expectEqual("red", forms[0].fields[0].options[0].value);
+    try testing.expectEqual("Red", forms[0].fields[0].options[0].text);
+}
+
+test "browser.forms: form with textarea" {
+    defer testing.reset();
+    defer testing.test_session.removePage();
+    const forms = try testForms(
+        \\<form method="POST">
+        \\  <textarea name="message" placeholder="Your message"></textarea>
+        \\</form>
+    );
+    try testing.expectEqual(1, forms.len);
+    try testing.expectEqual(1, forms[0].fields.len);
+    try testing.expectEqual("textarea", forms[0].fields[0].tag_name);
+    try testing.expectEqual("Your message", forms[0].fields[0].placeholder.?);
+}
+
+test "browser.forms: empty form skipped" {
+    defer testing.reset();
+    defer testing.test_session.removePage();
+    const forms = try testForms(
+        \\<form action="/empty">
+        \\  <p>No fields here</p>
+        \\</form>
+    );
+    try testing.expectEqual(0, forms.len);
+}
+
+test "browser.forms: hidden inputs excluded" {
+    defer testing.reset();
+    defer testing.test_session.removePage();
+    const forms = try testForms(
+        \\<form>
+        \\  <input type="hidden" name="csrf" value="token123">
+        \\  <input type="text" name="username">
+        \\</form>
+    );
+    try testing.expectEqual(1, forms.len);
+    try testing.expectEqual(1, forms[0].fields.len);
+    try testing.expectEqual("username", forms[0].fields[0].name.?);
+}
+
+test "browser.forms: multiple forms" {
+    defer testing.reset();
+    defer testing.test_session.removePage();
+    const forms = try testForms(
+        \\<form action="/search" method="GET">
+        \\  <input type="text" name="q" placeholder="Search">
+        \\</form>
+        \\<form action="/login" method="POST">
+        \\  <input type="email" name="email">
+        \\  <input type="password" name="pass">
+        \\</form>
+    );
+    try testing.expectEqual(2, forms.len);
+    try testing.expectEqual(1, forms[0].fields.len);
+    try testing.expectEqual(2, forms[1].fields.len);
+}
+
+test "browser.forms: disabled fields flagged" {
+    defer testing.reset();
+    defer testing.test_session.removePage();
+    const forms = try testForms(
+        \\<form>
+        \\  <input type="text" name="enabled_field">
+        \\  <input type="text" name="disabled_field" disabled>
+        \\</form>
+    );
+    try testing.expectEqual(1, forms.len);
+    try testing.expectEqual(2, forms[0].fields.len);
+    try testing.expect(!forms[0].fields[0].disabled);
+    try testing.expect(forms[0].fields[1].disabled);
+}
+
+test "browser.forms: disabled fieldset" {
+    defer testing.reset();
+    defer testing.test_session.removePage();
+    const forms = try testForms(
+        \\<form>
+        \\  <fieldset disabled>
+        \\    <input type="text" name="in_disabled_fieldset">
+        \\  </fieldset>
+        \\  <input type="text" name="outside_fieldset">
+        \\</form>
+    );
+    try testing.expectEqual(1, forms.len);
+    try testing.expectEqual(2, forms[0].fields.len);
+    try testing.expect(forms[0].fields[0].disabled);
+    try testing.expect(!forms[0].fields[1].disabled);
+}
+
+test "browser.forms: external field via form attribute" {
+    defer testing.reset();
+    defer testing.test_session.removePage();
+    const forms = try testForms(
+        \\<input type="text" name="external" form="myform">
+        \\<form id="myform" action="/submit">
+        \\  <input type="text" name="internal">
+        \\</form>
+    );
+    try testing.expectEqual(1, forms.len);
+    try testing.expectEqual(2, forms[0].fields.len);
+}
+
+test "browser.forms: checkbox and radio return value attribute" {
+    defer testing.reset();
+    defer testing.test_session.removePage();
+    const forms = try testForms(
+        \\<form>
+        \\  <input type="checkbox" name="agree" value="yes" checked>
+        \\  <input type="radio" name="color" value="red">
+        \\</form>
+    );
+    try testing.expectEqual(1, forms.len);
+    try testing.expectEqual(2, forms[0].fields.len);
+    try testing.expectEqual("checkbox", forms[0].fields[0].input_type.?);
+    try testing.expectEqual("yes", forms[0].fields[0].value.?);
+    try testing.expectEqual("radio", forms[0].fields[1].input_type.?);
+    try testing.expectEqual("red", forms[0].fields[1].value.?);
+}
+
+test "browser.forms: form without action or method" {
+    defer testing.reset();
+    defer testing.test_session.removePage();
+    const forms = try testForms(
+        \\<form>
+        \\  <input type="text" name="q">
+        \\</form>
+    );
+    try testing.expectEqual(1, forms.len);
+    try testing.expectEqual(null, forms[0].action);
+    try testing.expectEqual("get", forms[0].method.?);
+    try testing.expectEqual(1, forms[0].fields.len);
+}

src/browser/interactive.zig

@@ -0,0 +1,562 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+
+const Page = @import("Page.zig");
+const URL = @import("URL.zig");
+const TreeWalker = @import("webapi/TreeWalker.zig");
+const Element = @import("webapi/Element.zig");
+const Node = @import("webapi/Node.zig");
+const EventTarget = @import("webapi/EventTarget.zig");
+
+const Allocator = std.mem.Allocator;
+
+pub const InteractivityType = enum {
+    native,
+    aria,
+    contenteditable,
+    listener,
+    focusable,
+};
+
+pub const InteractiveElement = struct {
+    node: *Node,
+    tag_name: []const u8,
+    role: ?[]const u8,
+    name: ?[]const u8,
+    interactivity_type: InteractivityType,
+    listener_types: []const []const u8,
+    disabled: bool,
+    tab_index: i32,
+    id: ?[]const u8,
+    class: ?[]const u8,
+    href: ?[]const u8,
+    input_type: ?[]const u8,
+    value: ?[]const u8,
+    element_name: ?[]const u8,
+    placeholder: ?[]const u8,
+
+    pub fn jsonStringify(self: *const InteractiveElement, jw: anytype) !void {
+        try jw.beginObject();
+
+        try jw.objectField("tagName");
+        try jw.write(self.tag_name);
+
+        try jw.objectField("role");
+        try jw.write(self.role);
+
+        try jw.objectField("name");
+        try jw.write(self.name);
+
+        try jw.objectField("type");
+        try jw.write(@tagName(self.interactivity_type));
+
+        if (self.listener_types.len > 0) {
+            try jw.objectField("listeners");
+            try jw.beginArray();
+            for (self.listener_types) |lt| {
+                try jw.write(lt);
+            }
+            try jw.endArray();
+        }
+
+        if (self.disabled) {
+            try jw.objectField("disabled");
+            try jw.write(true);
+        }
+
+        try jw.objectField("tabIndex");
+        try jw.write(self.tab_index);
+
+        if (self.id) |v| {
+            try jw.objectField("id");
+            try jw.write(v);
+        }
+
+        if (self.class) |v| {
+            try jw.objectField("class");
+            try jw.write(v);
+        }
+
+        if (self.href) |v| {
+            try jw.objectField("href");
+            try jw.write(v);
+        }
+
+        if (self.input_type) |v| {
+            try jw.objectField("inputType");
+            try jw.write(v);
+        }
+
+        if (self.value) |v| {
+            try jw.objectField("value");
+            try jw.write(v);
+        }
+
+        if (self.element_name) |v| {
+            try jw.objectField("elementName");
+            try jw.write(v);
+        }
+
+        if (self.placeholder) |v| {
+            try jw.objectField("placeholder");
+            try jw.write(v);
+        }
+
+        try jw.endObject();
+    }
+};
+
+/// Collect all interactive elements under `root`.
+pub fn collectInteractiveElements(
+    root: *Node,
+    arena: Allocator,
+    page: *Page,
+) ![]InteractiveElement {
+    // Pre-build a map of event_target pointer → event type names,
+    // so classify and getListenerTypes are both O(1) per element.
+    const listener_targets = try buildListenerTargetMap(page, arena);
+
+    var css_cache: Element.PointerEventsCache = .empty;
+
+    var results: std.ArrayList(InteractiveElement) = .empty;
+
+    var tw = TreeWalker.Full.init(root, .{});
+    while (tw.next()) |node| {
+        const el = node.is(Element) orelse continue;
+        const html_el = el.is(Element.Html) orelse continue;
+
+        // Skip non-visual elements that are never user-interactive.
+        switch (el.getTag()) {
+            .script, .style, .link, .meta, .head, .noscript, .template => continue,
+            else => {},
+        }
+
+        const itype = classifyInteractivity(page, el, html_el, listener_targets, &css_cache) orelse continue;
+
+        const listener_types = getListenerTypes(
+            el.asEventTarget(),
+            listener_targets,
+        );
+
+        try results.append(arena, .{
+            .node = node,
+            .tag_name = el.getTagNameLower(),
+            .role = getRole(el),
+            .name = try getAccessibleName(el, arena),
+            .interactivity_type = itype,
+            .listener_types = listener_types,
+            .disabled = el.isDisabled(),
+            .tab_index = html_el.getTabIndex(),
+            .id = el.getAttributeSafe(comptime .wrap("id")),
+            .class = el.getAttributeSafe(comptime .wrap("class")),
+            .href = if (el.getAttributeSafe(comptime .wrap("href"))) |href|
+                URL.resolve(arena, page.base(), href, .{ .encode = true }) catch href
+            else
+                null,
+            .input_type = getInputType(el),
+            .value = getInputValue(el),
+            .element_name = el.getAttributeSafe(comptime .wrap("name")),
+            .placeholder = el.getAttributeSafe(comptime .wrap("placeholder")),
+        });
+    }
+
+    return results.items;
+}
+
+pub const ListenerTargetMap = std.AutoHashMapUnmanaged(usize, std.ArrayList([]const u8));
+
+/// Pre-build a map from event_target pointer → list of event type names.
+/// This lets both classifyInteractivity (O(1) "has any?") and
+/// getListenerTypes (O(1) "which ones?") avoid re-iterating per element.
+pub fn buildListenerTargetMap(page: *Page, arena: Allocator) !ListenerTargetMap {
+    var map = ListenerTargetMap{};
+
+    // addEventListener registrations
+    var it = page._event_manager.lookup.iterator();
+    while (it.next()) |entry| {
+        const list = entry.value_ptr.*;
+        if (list.first != null) {
+            const gop = try map.getOrPut(arena, entry.key_ptr.event_target);
+            if (!gop.found_existing) gop.value_ptr.* = .empty;
+            try gop.value_ptr.append(arena, entry.key_ptr.type_string.str());
+        }
+    }
+
+    // Inline handlers (onclick, onmousedown, etc.)
+    var attr_it = page._event_target_attr_listeners.iterator();
+    while (attr_it.next()) |entry| {
+        const gop = try map.getOrPut(arena, @intFromPtr(entry.key_ptr.target));
+        if (!gop.found_existing) gop.value_ptr.* = .empty;
+        // Strip "on" prefix to get the event type name.
+        try gop.value_ptr.append(arena, @tagName(entry.key_ptr.handler)[2..]);
+    }
+
+    return map;
+}
+
+pub fn classifyInteractivity(
+    page: *Page,
+    el: *Element,
+    html_el: *Element.Html,
+    listener_targets: ListenerTargetMap,
+    cache: ?*Element.PointerEventsCache,
+) ?InteractivityType {
+    if (el.hasPointerEventsNone(cache, page)) return null;
+
+    // 1. Native interactive by tag
+    switch (el.getTag()) {
+        .button, .summary, .details, .select, .textarea => return .native,
+        .anchor, .area => {
+            if (el.getAttributeSafe(comptime .wrap("href")) != null) return .native;
+        },
+        .input => {
+            if (el.is(Element.Html.Input)) |input| {
+                if (input._input_type != .hidden) return .native;
+            }
+        },
+        else => {},
+    }
+
+    // 2. ARIA interactive role
+    if (el.getAttributeSafe(comptime .wrap("role"))) |role| {
+        if (isInteractiveRole(role)) return .aria;
+    }
+
+    // 3. contenteditable (15 bytes, exceeds SSO limit for comptime)
+    if (el.getAttributeSafe(.wrap("contenteditable"))) |ce| {
+        if (ce.len == 0 or std.ascii.eqlIgnoreCase(ce, "true")) return .contenteditable;
+    }
+
+    // 4. Event listeners (addEventListener or inline handlers)
+    const et_ptr = @intFromPtr(html_el.asEventTarget());
+    if (listener_targets.get(et_ptr) != null) return .listener;
+
+    // 5. Explicitly focusable via tabindex.
+    // Only count elements with an EXPLICIT tabindex attribute,
+    // since getTabIndex() returns 0 for all interactive tags by default
+    // (including anchors without href and hidden inputs).
+    if (el.getAttributeSafe(comptime .wrap("tabindex"))) |_| {
+        if (html_el.getTabIndex() >= 0) return .focusable;
+    }
+
+    return null;
+}
+
+pub fn isInteractiveRole(role: []const u8) bool {
+    const MAX_LEN = "menuitemcheckbox".len;
+    if (role.len > MAX_LEN) return false;
+    var buf: [MAX_LEN]u8 = undefined;
+    const lowered = std.ascii.lowerString(&buf, role);
+    const interactive_roles = std.StaticStringMap(void).initComptime(.{
+        .{ "button", {} },
+        .{ "checkbox", {} },
+        .{ "combobox", {} },
+        .{ "iframe", {} },
+        .{ "link", {} },
+        .{ "listbox", {} },
+        .{ "menuitem", {} },
+        .{ "menuitemcheckbox", {} },
+        .{ "menuitemradio", {} },
+        .{ "option", {} },
+        .{ "radio", {} },
+        .{ "searchbox", {} },
+        .{ "slider", {} },
+        .{ "spinbutton", {} },
+        .{ "switch", {} },
+        .{ "tab", {} },
+        .{ "textbox", {} },
+        .{ "treeitem", {} },
+    });
+    return interactive_roles.has(lowered);
+}
+
+pub fn isContentRole(role: []const u8) bool {
+    const MAX_LEN = "columnheader".len;
+    if (role.len > MAX_LEN) return false;
+    var buf: [MAX_LEN]u8 = undefined;
+    const lowered = std.ascii.lowerString(&buf, role);
+    const content_roles = std.StaticStringMap(void).initComptime(.{
+        .{ "article", {} },
+        .{ "cell", {} },
+        .{ "columnheader", {} },
+        .{ "gridcell", {} },
+        .{ "heading", {} },
+        .{ "listitem", {} },
+        .{ "main", {} },
+        .{ "navigation", {} },
+        .{ "region", {} },
+        .{ "rowheader", {} },
+    });
+    return content_roles.has(lowered);
+}
+
+fn getRole(el: *Element) ?[]const u8 {
+    // Explicit role attribute takes precedence
+    if (el.getAttributeSafe(comptime .wrap("role"))) |role| return role;
+
+    // Implicit role from tag
+    return switch (el.getTag()) {
+        .button, .summary => "button",
+        .anchor, .area => if (el.getAttributeSafe(comptime .wrap("href")) != null) "link" else null,
+        .input => blk: {
+            if (el.is(Element.Html.Input)) |input| {
+                break :blk switch (input._input_type) {
+                    .text, .tel, .url, .email => "textbox",
+                    .checkbox => "checkbox",
+                    .radio => "radio",
+                    .button, .submit, .reset, .image => "button",
+                    .range => "slider",
+                    .number => "spinbutton",
+                    .search => "searchbox",
+                    else => null,
+                };
+            }
+            break :blk null;
+        },
+        .select => "combobox",
+        .textarea => "textbox",
+        .details => "group",
+        else => null,
+    };
+}
+
+fn getAccessibleName(el: *Element, arena: Allocator) !?[]const u8 {
+    // aria-label
+    if (el.getAttributeSafe(comptime .wrap("aria-label"))) |v| {
+        if (v.len > 0) return v;
+    }
+
+    // alt (for img, input[type=image])
+    if (el.getAttributeSafe(comptime .wrap("alt"))) |v| {
+        if (v.len > 0) return v;
+    }
+
+    // title
+    if (el.getAttributeSafe(comptime .wrap("title"))) |v| {
+        if (v.len > 0) return v;
+    }
+
+    // placeholder
+    if (el.getAttributeSafe(comptime .wrap("placeholder"))) |v| {
+        if (v.len > 0) return v;
+    }
+
+    // value (for buttons)
+    if (el.getTag() == .input) {
+        if (el.getAttributeSafe(comptime .wrap("value"))) |v| {
+            if (v.len > 0) return v;
+        }
+    }
+
+    // Text content (first non-empty text node, trimmed)
+    return try getTextContent(el.asNode(), arena);
+}
+
+fn getTextContent(node: *Node, arena: Allocator) !?[]const u8 {
+    var tw: TreeWalker.FullExcludeSelf = .init(node, .{});
+
+    var arr: std.ArrayList(u8) = .empty;
+    var single_chunk: ?[]const u8 = null;
+
+    while (tw.next()) |child| {
+        // Skip text inside script/style elements.
+        if (child.is(Element)) |el| {
+            switch (el.getTag()) {
+                .script, .style => {
+                    tw.skipChildren();
+                    continue;
+                },
+                else => {},
+            }
+        }
+        if (child.is(Node.CData)) |cdata| {
+            if (cdata.is(Node.CData.Text)) |text| {
+                const content = std.mem.trim(u8, text.getWholeText(), &std.ascii.whitespace);
+                if (content.len > 0) {
+                    if (single_chunk == null and arr.items.len == 0) {
+                        single_chunk = content;
+                    } else {
+                        if (single_chunk) |sc| {
+                            try arr.appendSlice(arena, sc);
+                            try arr.append(arena, ' ');
+                            single_chunk = null;
+                        }
+                        try arr.appendSlice(arena, content);
+                        try arr.append(arena, ' ');
+                    }
+                }
+            }
+        }
+    }
+
+    if (single_chunk) |sc| return sc;
+    if (arr.items.len == 0) return null;
+
+    // strip out trailing space
+    return arr.items[0 .. arr.items.len - 1];
+}
+
+fn getInputType(el: *Element) ?[]const u8 {
+    if (el.is(Element.Html.Input)) |input| {
+        return input._input_type.toString();
+    }
+    return null;
+}
+
+fn getInputValue(el: *Element) ?[]const u8 {
+    if (el.is(Element.Html.Input)) |input| {
+        return input.getValue();
+    }
+    return null;
+}
+
+/// Get all event listener types registered on this target.
+fn getListenerTypes(target: *EventTarget, listener_targets: ListenerTargetMap) []const []const u8 {
+    if (listener_targets.get(@intFromPtr(target))) |types| return types.items;
+    return &.{};
+}
+
+const testing = @import("../testing.zig");
+
+fn testInteractive(html: []const u8) ![]InteractiveElement {
+    const page = try testing.test_session.createPage();
+    defer testing.test_session.removePage();
+
+    const doc = page.window._document;
+    const div = try doc.createElement("div", null, page);
+    try page.parseHtmlAsChildren(div.asNode(), html);
+
+    return collectInteractiveElements(div.asNode(), page.call_arena, page);
+}
+
+test "browser.interactive: button" {
+    const elements = try testInteractive("<button>Click me</button>");
+    try testing.expectEqual(1, elements.len);
+    try testing.expectEqual("button", elements[0].tag_name);
+    try testing.expectEqual("button", elements[0].role.?);
+    try testing.expectEqual("Click me", elements[0].name.?);
+    try testing.expectEqual(InteractivityType.native, elements[0].interactivity_type);
+}
+
+test "browser.interactive: anchor with href" {
+    const elements = try testInteractive("<a href=\"/page\">Link</a>");
+    try testing.expectEqual(1, elements.len);
+    try testing.expectEqual("a", elements[0].tag_name);
+    try testing.expectEqual("link", elements[0].role.?);
+    try testing.expectEqual("Link", elements[0].name.?);
+}
+
+test "browser.interactive: anchor without href" {
+    const elements = try testInteractive("<a>Not a link</a>");
+    try testing.expectEqual(0, elements.len);
+}
+
+test "browser.interactive: input types" {
+    const elements = try testInteractive(
+        \\<input type="text" placeholder="Search">
+        \\<input type="hidden" name="csrf">
+    );
+    try testing.expectEqual(1, elements.len);
+    try testing.expectEqual("input", elements[0].tag_name);
+    try testing.expectEqual("text", elements[0].input_type.?);
+    try testing.expectEqual("Search", elements[0].placeholder.?);
+}
+
+test "browser.interactive: select and textarea" {
+    const elements = try testInteractive(
+        \\<select name="color"><option>Red</option></select>
+        \\<textarea name="msg"></textarea>
+    );
+    try testing.expectEqual(2, elements.len);
+    try testing.expectEqual("select", elements[0].tag_name);
+    try testing.expectEqual("textarea", elements[1].tag_name);
+}
+
+test "browser.interactive: aria role" {
+    const elements = try testInteractive("<div role=\"button\">Custom</div>");
+    try testing.expectEqual(1, elements.len);
+    try testing.expectEqual("div", elements[0].tag_name);
+    try testing.expectEqual("button", elements[0].role.?);
+    try testing.expectEqual(InteractivityType.aria, elements[0].interactivity_type);
+}
+
+test "browser.interactive: contenteditable" {
+    const elements = try testInteractive("<div contenteditable=\"true\">Edit me</div>");
+    try testing.expectEqual(1, elements.len);
+    try testing.expectEqual(InteractivityType.contenteditable, elements[0].interactivity_type);
+}
+
+test "browser.interactive: tabindex" {
+    const elements = try testInteractive("<div tabindex=\"0\">Focusable</div>");
+    try testing.expectEqual(1, elements.len);
+    try testing.expectEqual(InteractivityType.focusable, elements[0].interactivity_type);
+    try testing.expectEqual(@as(i32, 0), elements[0].tab_index);
+}
+
+test "browser.interactive: disabled" {
+    const elements = try testInteractive("<button disabled>Off</button>");
+    try testing.expectEqual(1, elements.len);
+    try testing.expect(elements[0].disabled);
+}
+
+test "browser.interactive: disabled by fieldset" {
+    const elements = try testInteractive(
+        \\<fieldset disabled>
+        \\  <button>Disabled</button>
+        \\  <legend><button>In legend</button></legend>
+        \\</fieldset>
+    );
+    try testing.expectEqual(2, elements.len);
+    // Button outside legend is disabled by fieldset
+    try testing.expect(elements[0].disabled);
+    // Button inside first legend is NOT disabled
+    try testing.expect(!elements[1].disabled);
+}
+
+test "browser.interactive: pointer-events none" {
+    const elements = try testInteractive("<button style=\"pointer-events: none;\">Click me</button>");
+    try testing.expectEqual(0, elements.len);
+}
+
+test "browser.interactive: non-interactive div" {
+    const elements = try testInteractive("<div>Just text</div>");
+    try testing.expectEqual(0, elements.len);
+}
+
+test "browser.interactive: details and summary" {
+    const elements = try testInteractive("<details><summary>More</summary><p>Content</p></details>");
+    try testing.expectEqual(2, elements.len);
+    try testing.expectEqual("details", elements[0].tag_name);
+    try testing.expectEqual("summary", elements[1].tag_name);
+}
+
+test "browser.interactive: mixed elements" {
+    const elements = try testInteractive(
+        \\<div>
+        \\  <a href="/home">Home</a>
+        \\  <p>Some text</p>
+        \\  <button id="btn1">Submit</button>
+        \\  <input type="email" placeholder="Email">
+        \\  <div>Not interactive</div>
+        \\  <div role="tab">Tab</div>
+        \\</div>
+    );
+    try testing.expectEqual(4, elements.len);
+}

src/browser/js/Array.zig

@@ -0,0 +1,66 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const js = @import("js.zig");
+const v8 = js.v8;
+
+const Array = @This();
+
+local: *const js.Local,
+handle: *const v8.Array,
+
+pub fn len(self: Array) usize {
+    return v8.v8__Array__Length(self.handle);
+}
+
+pub fn get(self: Array, index: u32) !js.Value {
+    const ctx = self.local.ctx;
+
+    const idx = js.Integer.init(ctx.isolate.handle, index);
+    const handle = v8.v8__Object__Get(@ptrCast(self.handle), self.local.handle, idx.handle) orelse {
+        return error.JsException;
+    };
+
+    return .{
+        .local = self.local,
+        .handle = handle,
+    };
+}
+
+pub fn set(self: Array, index: u32, value: anytype, comptime opts: js.Caller.CallOpts) !bool {
+    const js_value = try self.local.zigValueToJs(value, opts);
+
+    var out: v8.MaybeBool = undefined;
+    v8.v8__Object__SetAtIndex(@ptrCast(self.handle), self.local.handle, index, js_value.handle, &out);
+    return out.has_value;
+}
+
+pub fn toObject(self: Array) js.Object {
+    return .{
+        .local = self.local,
+        .handle = @ptrCast(self.handle),
+    };
+}
+
+pub fn toValue(self: Array) js.Value {
+    return .{
+        .local = self.local,
+        .handle = @ptrCast(self.handle),
+    };
+}

src/browser/js/BigInt.zig

@@ -0,0 +1,41 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const js = @import("js.zig");
+const v8 = js.v8;
+
+const BigInt = @This();
+
+handle: *const v8.Integer,
+
+pub fn init(isolate: *v8.Isolate, val: anytype) BigInt {
+    const handle = switch (@TypeOf(val)) {
+        i8, i16, i32, i64, isize => v8.v8__BigInt__New(isolate, val).?,
+        u8, u16, u32, u64, usize => v8.v8__BigInt__NewFromUnsigned(isolate, val).?,
+        else => |T| @compileError("cannot create v8::BigInt from: " ++ @typeName(T)),
+    };
+    return .{ .handle = handle };
+}
+
+pub fn getInt64(self: BigInt) i64 {
+    return v8.v8__BigInt__Int64Value(self.handle, null);
+}
+
+pub fn getUint64(self: BigInt) u64 {
+    return v8.v8__BigInt__Uint64Value(self.handle, null);
+}

src/browser/js/Caller.zig

@@ -0,0 +1,776 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const log = @import("../../log.zig");
+const string = @import("../../string.zig");
+
+const Page = @import("../Page.zig");
+
+const js = @import("js.zig");
+const Local = @import("Local.zig");
+const Context = @import("Context.zig");
+const TaggedOpaque = @import("TaggedOpaque.zig");
+
+const v8 = js.v8;
+const ArenaAllocator = std.heap.ArenaAllocator;
+
+const CALL_ARENA_RETAIN = 1024 * 16;
+const IS_DEBUG = @import("builtin").mode == .Debug;
+
+const Caller = @This();
+local: Local,
+prev_local: ?*const js.Local,
+prev_context: *Context,
+
+// Takes the raw v8 isolate and extracts the context from it.
+pub fn init(self: *Caller, v8_isolate: *v8.Isolate) void {
+    const ctx, const v8_context = Context.fromIsolate(.{ .handle = v8_isolate });
+    initWithContext(self, ctx, v8_context);
+}
+
+fn initWithContext(self: *Caller, ctx: *Context, v8_context: *const v8.Context) void {
+    ctx.call_depth += 1;
+    self.* = Caller{
+        .local = .{
+            .ctx = ctx,
+            .handle = v8_context,
+            .call_arena = ctx.call_arena,
+            .isolate = ctx.isolate,
+        },
+        .prev_local = ctx.local,
+        .prev_context = ctx.page.js,
+    };
+    ctx.page.js = ctx;
+    ctx.local = &self.local;
+}
+
+pub fn initFromHandle(self: *Caller, handle: ?*const v8.FunctionCallbackInfo) void {
+    const isolate = v8.v8__FunctionCallbackInfo__GetIsolate(handle).?;
+    self.init(isolate);
+}
+
+pub fn deinit(self: *Caller) void {
+    const ctx = self.local.ctx;
+    const call_depth = ctx.call_depth - 1;
+
+    // Because of callbacks, calls can be nested. Because of this, we
+    // can't clear the call_arena after _every_ call. Imagine we have
+    //    arr.forEach((i) => { console.log(i); }
+    //
+    // First we call forEach. Inside of our forEach call,
+    // we call console.log. If we reset the call_arena after this call,
+    // it'll reset it for the `forEach` call after, which might still
+    // need the data.
+    //
+    // Therefore, we keep a call_depth, and only reset the call_arena
+    // when a top-level (call_depth == 0) function ends.
+    if (call_depth == 0) {
+        const arena: *ArenaAllocator = @ptrCast(@alignCast(ctx.call_arena.ptr));
+        _ = arena.reset(.{ .retain_with_limit = CALL_ARENA_RETAIN });
+    }
+
+    ctx.call_depth = call_depth;
+    ctx.local = self.prev_local;
+    ctx.page.js = self.prev_context;
+}
+
+pub const CallOpts = struct {
+    dom_exception: bool = false,
+    null_as_undefined: bool = false,
+    as_typed_array: bool = false,
+};
+
+pub fn constructor(self: *Caller, comptime T: type, func: anytype, handle: *const v8.FunctionCallbackInfo, comptime opts: CallOpts) void {
+    const local = &self.local;
+
+    var hs: js.HandleScope = undefined;
+    hs.init(local.isolate);
+    defer hs.deinit();
+
+    const info = FunctionCallbackInfo{ .handle = handle };
+
+    if (!info.isConstructCall()) {
+        handleError(T, @TypeOf(func), local, error.InvalidArgument, info, opts);
+        return;
+    }
+
+    self._constructor(func, info) catch |err| {
+        handleError(T, @TypeOf(func), local, err, info, opts);
+    };
+}
+
+fn _constructor(self: *Caller, func: anytype, info: FunctionCallbackInfo) !void {
+    const F = @TypeOf(func);
+    const local = &self.local;
+    const args = try getArgs(F, 0, local, info);
+    const res = @call(.auto, func, args);
+
+    const ReturnType = @typeInfo(F).@"fn".return_type orelse {
+        @compileError(@typeName(F) ++ " has a constructor without a return type");
+    };
+
+    const new_this_handle = info.getThis();
+    var this = js.Object{ .local = local, .handle = new_this_handle };
+    if (@typeInfo(ReturnType) == .error_union) {
+        const non_error_res = res catch |err| return err;
+        this = try local.mapZigInstanceToJs(new_this_handle, non_error_res);
+    } else {
+        this = try local.mapZigInstanceToJs(new_this_handle, res);
+    }
+
+    // If we got back a different object (existing wrapper), copy the prototype
+    // from new object. (this happens when we're upgrading an CustomElement)
+    if (this.handle != new_this_handle) {
+        const prototype_handle = v8.v8__Object__GetPrototype(new_this_handle).?;
+        var out: v8.MaybeBool = undefined;
+        v8.v8__Object__SetPrototype(this.handle, self.local.handle, prototype_handle, &out);
+        if (comptime IS_DEBUG) {
+            std.debug.assert(out.has_value and out.value);
+        }
+    }
+
+    info.getReturnValue().set(this.handle);
+}
+
+pub fn getIndex(self: *Caller, comptime T: type, func: anytype, idx: u32, handle: *const v8.PropertyCallbackInfo, comptime opts: CallOpts) u8 {
+    const local = &self.local;
+
+    var hs: js.HandleScope = undefined;
+    hs.init(local.isolate);
+    defer hs.deinit();
+
+    const info = PropertyCallbackInfo{ .handle = handle };
+    return _getIndex(T, local, func, idx, info, opts) catch |err| {
+        handleError(T, @TypeOf(func), local, err, info, opts);
+        // not intercepted
+        return 0;
+    };
+}
+
+fn _getIndex(comptime T: type, local: *const Local, func: anytype, idx: u32, info: PropertyCallbackInfo, comptime opts: CallOpts) !u8 {
+    const F = @TypeOf(func);
+    var args: ParameterTypes(F) = undefined;
+    @field(args, "0") = try TaggedOpaque.fromJS(*T, info.getThis());
+    @field(args, "1") = idx;
+    if (@typeInfo(F).@"fn".params.len == 3) {
+        @field(args, "2") = local.ctx.page;
+    }
+    const ret = @call(.auto, func, args);
+    return handleIndexedReturn(T, F, true, local, ret, info, opts);
+}
+
+pub fn getNamedIndex(self: *Caller, comptime T: type, func: anytype, name: *const v8.Name, handle: *const v8.PropertyCallbackInfo, comptime opts: CallOpts) u8 {
+    const local = &self.local;
+
+    var hs: js.HandleScope = undefined;
+    hs.init(local.isolate);
+    defer hs.deinit();
+
+    const info = PropertyCallbackInfo{ .handle = handle };
+    return _getNamedIndex(T, local, func, name, info, opts) catch |err| {
+        handleError(T, @TypeOf(func), local, err, info, opts);
+        // not intercepted
+        return 0;
+    };
+}
+
+fn _getNamedIndex(comptime T: type, local: *const Local, func: anytype, name: *const v8.Name, info: PropertyCallbackInfo, comptime opts: CallOpts) !u8 {
+    const F = @TypeOf(func);
+    var args: ParameterTypes(F) = undefined;
+    @field(args, "0") = try TaggedOpaque.fromJS(*T, info.getThis());
+    @field(args, "1") = try nameToString(local, @TypeOf(args.@"1"), name);
+    if (@typeInfo(F).@"fn".params.len == 3) {
+        @field(args, "2") = local.ctx.page;
+    }
+    const ret = @call(.auto, func, args);
+    return handleIndexedReturn(T, F, true, local, ret, info, opts);
+}
+
+pub fn setNamedIndex(self: *Caller, comptime T: type, func: anytype, name: *const v8.Name, js_value: *const v8.Value, handle: *const v8.PropertyCallbackInfo, comptime opts: CallOpts) u8 {
+    const local = &self.local;
+
+    var hs: js.HandleScope = undefined;
+    hs.init(local.isolate);
+    defer hs.deinit();
+
+    const info = PropertyCallbackInfo{ .handle = handle };
+    return _setNamedIndex(T, local, func, name, .{ .local = &self.local, .handle = js_value }, info, opts) catch |err| {
+        handleError(T, @TypeOf(func), local, err, info, opts);
+        // not intercepted
+        return 0;
+    };
+}
+
+fn _setNamedIndex(comptime T: type, local: *const Local, func: anytype, name: *const v8.Name, js_value: js.Value, info: PropertyCallbackInfo, comptime opts: CallOpts) !u8 {
+    const F = @TypeOf(func);
+    var args: ParameterTypes(F) = undefined;
+    @field(args, "0") = try TaggedOpaque.fromJS(*T, info.getThis());
+    @field(args, "1") = try nameToString(local, @TypeOf(args.@"1"), name);
+    @field(args, "2") = try local.jsValueToZig(@TypeOf(@field(args, "2")), js_value);
+    if (@typeInfo(F).@"fn".params.len == 4) {
+        @field(args, "3") = local.ctx.page;
+    }
+    const ret = @call(.auto, func, args);
+    return handleIndexedReturn(T, F, false, local, ret, info, opts);
+}
+
+pub fn deleteNamedIndex(self: *Caller, comptime T: type, func: anytype, name: *const v8.Name, handle: *const v8.PropertyCallbackInfo, comptime opts: CallOpts) u8 {
+    const local = &self.local;
+
+    var hs: js.HandleScope = undefined;
+    hs.init(local.isolate);
+    defer hs.deinit();
+
+    const info = PropertyCallbackInfo{ .handle = handle };
+    return _deleteNamedIndex(T, local, func, name, info, opts) catch |err| {
+        handleError(T, @TypeOf(func), local, err, info, opts);
+        return 0;
+    };
+}
+
+fn _deleteNamedIndex(comptime T: type, local: *const Local, func: anytype, name: *const v8.Name, info: PropertyCallbackInfo, comptime opts: CallOpts) !u8 {
+    const F = @TypeOf(func);
+    var args: ParameterTypes(F) = undefined;
+    @field(args, "0") = try TaggedOpaque.fromJS(*T, info.getThis());
+    @field(args, "1") = try nameToString(local, @TypeOf(args.@"1"), name);
+    if (@typeInfo(F).@"fn".params.len == 3) {
+        @field(args, "2") = local.ctx.page;
+    }
+    const ret = @call(.auto, func, args);
+    return handleIndexedReturn(T, F, false, local, ret, info, opts);
+}
+
+pub fn getEnumerator(self: *Caller, comptime T: type, func: anytype, handle: *const v8.PropertyCallbackInfo, comptime opts: CallOpts) u8 {
+    const local = &self.local;
+
+    var hs: js.HandleScope = undefined;
+    hs.init(local.isolate);
+    defer hs.deinit();
+
+    const info = PropertyCallbackInfo{ .handle = handle };
+    return _getEnumerator(T, local, func, info, opts) catch |err| {
+        handleError(T, @TypeOf(func), local, err, info, opts);
+        // not intercepted
+        return 0;
+    };
+}
+
+fn _getEnumerator(comptime T: type, local: *const Local, func: anytype, info: PropertyCallbackInfo, comptime opts: CallOpts) !u8 {
+    const F = @TypeOf(func);
+    var args: ParameterTypes(F) = undefined;
+    @field(args, "0") = try TaggedOpaque.fromJS(*T, info.getThis());
+    if (@typeInfo(F).@"fn".params.len == 2) {
+        @field(args, "1") = local.ctx.page;
+    }
+    const ret = @call(.auto, func, args);
+    return handleIndexedReturn(T, F, true, local, ret, info, opts);
+}
+
+fn handleIndexedReturn(comptime T: type, comptime F: type, comptime with_value: bool, local: *const Local, ret: anytype, info: PropertyCallbackInfo, comptime opts: CallOpts) !u8 {
+    // need to unwrap this error immediately for when opts.null_as_undefined == true
+    // and we need to compare it to null;
+    const non_error_ret = switch (@typeInfo(@TypeOf(ret))) {
+        .error_union => |eu| blk: {
+            break :blk ret catch |err| {
+                // We can't compare err == error.NotHandled if error.NotHandled
+                // isn't part of the possible error set. So we first need to check
+                // if error.NotHandled is part of the error set.
+                if (isInErrorSet(error.NotHandled, eu.error_set)) {
+                    if (err == error.NotHandled) {
+                        // not intercepted
+                        return 0;
+                    }
+                }
+                handleError(T, F, local, err, info, opts);
+                // not intercepted
+                return 0;
+            };
+        },
+        else => ret,
+    };
+
+    if (comptime with_value) {
+        info.getReturnValue().set(try local.zigValueToJs(non_error_ret, opts));
+    }
+    // intercepted
+    return 1;
+}
+
+fn isInErrorSet(err: anyerror, comptime T: type) bool {
+    inline for (@typeInfo(T).error_set.?) |e| {
+        if (err == @field(anyerror, e.name)) return true;
+    }
+    return false;
+}
+
+fn nameToString(local: *const Local, comptime T: type, name: *const v8.Name) !T {
+    const handle = @as(*const v8.String, @ptrCast(name));
+    if (T == string.String) {
+        return js.String.toSSO(.{ .local = local, .handle = handle }, false);
+    }
+    if (T == string.Global) {
+        return js.String.toSSO(.{ .local = local, .handle = handle }, true);
+    }
+    return try js.String.toSlice(.{ .local = local, .handle = handle });
+}
+
+fn handleError(comptime T: type, comptime F: type, local: *const Local, err: anyerror, info: anytype, comptime opts: CallOpts) void {
+    const isolate = local.isolate;
+
+    if (comptime IS_DEBUG and @TypeOf(info) == FunctionCallbackInfo) {
+        if (log.enabled(.js, .debug)) {
+            const DOMException = @import("../webapi/DOMException.zig");
+            if (DOMException.fromError(err) == null) {
+                // This isn't a DOMException, let's log it
+                logFunctionCallError(local, @typeName(T), @typeName(F), err, info);
+            }
+        }
+    }
+
+    const js_err: *const v8.Value = switch (err) {
+        error.TryCatchRethrow => return,
+        error.InvalidArgument => isolate.createTypeError("invalid argument"),
+        error.TypeError => isolate.createTypeError(""),
+        error.OutOfMemory => isolate.createError("out of memory"),
+        error.IllegalConstructor => isolate.createError("Illegal Contructor"),
+        else => blk: {
+            if (comptime opts.dom_exception) {
+                const DOMException = @import("../webapi/DOMException.zig");
+                if (DOMException.fromError(err)) |ex| {
+                    const value = local.zigValueToJs(ex, .{}) catch break :blk isolate.createError("internal error");
+                    break :blk value.handle;
+                }
+            }
+            break :blk isolate.createError(@errorName(err));
+        },
+    };
+
+    const js_exception = isolate.throwException(js_err);
+    info.getReturnValue().setValueHandle(js_exception);
+}
+
+// This is extracted to speed up compilation. When left inlined in handleError,
+// this can add as much as 10 seconds of compilation time.
+fn logFunctionCallError(local: *const Local, type_name: []const u8, func: []const u8, err: anyerror, info: FunctionCallbackInfo) void {
+    const args_dump = serializeFunctionArgs(local, info) catch "failed to serialize args";
+    log.debug(.js, "function call error", .{
+        .type = type_name,
+        .func = func,
+        .err = err,
+        .args = args_dump,
+        .stack = local.stackTrace() catch |err1| @errorName(err1),
+    });
+}
+
+fn serializeFunctionArgs(local: *const Local, info: FunctionCallbackInfo) ![]const u8 {
+    var buf = std.Io.Writer.Allocating.init(local.call_arena);
+
+    const separator = log.separator();
+    for (0..info.length()) |i| {
+        try buf.writer.print("{s}{d} - ", .{ separator, i + 1 });
+        const js_value = info.getArg(@intCast(i), local);
+        try local.debugValue(js_value, &buf.writer);
+    }
+    return buf.written();
+}
+
+// Takes a function, and returns a tuple for its argument. Used when we
+// @call a function
+fn ParameterTypes(comptime F: type) type {
+    const params = @typeInfo(F).@"fn".params;
+    var fields: [params.len]std.builtin.Type.StructField = undefined;
+
+    inline for (params, 0..) |param, i| {
+        fields[i] = .{
+            .name = tupleFieldName(i),
+            .type = param.type.?,
+            .default_value_ptr = null,
+            .is_comptime = false,
+            .alignment = @alignOf(param.type.?),
+        };
+    }
+
+    return @Type(.{ .@"struct" = .{
+        .layout = .auto,
+        .decls = &.{},
+        .fields = &fields,
+        .is_tuple = true,
+    } });
+}
+
+fn tupleFieldName(comptime i: usize) [:0]const u8 {
+    return switch (i) {
+        0 => "0",
+        1 => "1",
+        2 => "2",
+        3 => "3",
+        4 => "4",
+        5 => "5",
+        6 => "6",
+        7 => "7",
+        8 => "8",
+        9 => "9",
+        else => std.fmt.comptimePrint("{d}", .{i}),
+    };
+}
+
+fn isPage(comptime T: type) bool {
+    return T == *Page or T == *const Page;
+}
+
+// These wrap the raw v8 C API to provide a cleaner interface.
+pub const FunctionCallbackInfo = struct {
+    handle: *const v8.FunctionCallbackInfo,
+
+    pub fn length(self: FunctionCallbackInfo) u32 {
+        return @intCast(v8.v8__FunctionCallbackInfo__Length(self.handle));
+    }
+
+    pub fn getArg(self: FunctionCallbackInfo, index: u32, local: *const js.Local) js.Value {
+        return .{ .local = local, .handle = v8.v8__FunctionCallbackInfo__INDEX(self.handle, @intCast(index)).? };
+    }
+
+    pub fn getData(self: FunctionCallbackInfo) ?*anyopaque {
+        const data = v8.v8__FunctionCallbackInfo__Data(self.handle) orelse return null;
+        return v8.v8__External__Value(@ptrCast(data));
+    }
+
+    pub fn getThis(self: FunctionCallbackInfo) *const v8.Object {
+        return v8.v8__FunctionCallbackInfo__This(self.handle).?;
+    }
+
+    pub fn getReturnValue(self: FunctionCallbackInfo) ReturnValue {
+        var rv: v8.ReturnValue = undefined;
+        v8.v8__FunctionCallbackInfo__GetReturnValue(self.handle, &rv);
+        return .{ .handle = rv };
+    }
+
+    fn isConstructCall(self: FunctionCallbackInfo) bool {
+        return v8.v8__FunctionCallbackInfo__IsConstructCall(self.handle);
+    }
+};
+
+pub const PropertyCallbackInfo = struct {
+    handle: *const v8.PropertyCallbackInfo,
+
+    pub fn getThis(self: PropertyCallbackInfo) *const v8.Object {
+        return v8.v8__PropertyCallbackInfo__This(self.handle).?;
+    }
+
+    pub fn getReturnValue(self: PropertyCallbackInfo) ReturnValue {
+        var rv: v8.ReturnValue = undefined;
+        v8.v8__PropertyCallbackInfo__GetReturnValue(self.handle, &rv);
+        return .{ .handle = rv };
+    }
+};
+
+const ReturnValue = struct {
+    handle: v8.ReturnValue,
+
+    pub fn set(self: ReturnValue, value: anytype) void {
+        const T = @TypeOf(value);
+        if (T == *const v8.Object) {
+            self.setValueHandle(@ptrCast(value));
+        } else if (T == *const v8.Value) {
+            self.setValueHandle(value);
+        } else if (T == js.Value) {
+            self.setValueHandle(value.handle);
+        } else {
+            @compileError("Unsupported type for ReturnValue.set: " ++ @typeName(T));
+        }
+    }
+
+    pub fn setValueHandle(self: ReturnValue, handle: *const v8.Value) void {
+        v8.v8__ReturnValue__Set(self.handle, handle);
+    }
+};
+
+pub const Function = struct {
+    pub const Opts = struct {
+        noop: bool = false,
+        static: bool = false,
+        dom_exception: bool = false,
+        as_typed_array: bool = false,
+        null_as_undefined: bool = false,
+        cache: ?Caching = null,
+        embedded_receiver: bool = false,
+
+        // We support two ways to cache a value directly into a v8::Object. The
+        // difference between the two is like the difference between a Map
+        // and a Struct.
+        // 1 - Using the object's internal fields. Think of this as
+        //     adding a field to the struct. It's fast, but the space is reserved
+        //     upfront for _every_ instance, whether we use it or not.
+        //
+        // 2 - Using the object's private state with a v8::Private key. Think of
+        //     this as a HashMap. It takes no memory if the cache isn't used
+        //     but has overhead when used.
+        //
+        // Consider `window.document`, (1) we have relatively few Window objects,
+        // (2) They all have a document and (3) The document is accessed _a lot_.
+        // An internal field makes sense.
+        //
+        // Consider `node.childNodes`, (1) we can have 20K+ node objects, (2)
+        // 95% of nodes will never have their .childNodes access by JavaScript.
+        // Private map lookup makes sense.
+        pub const Caching = union(enum) {
+            internal: u8,
+            private: []const u8,
+        };
+    };
+
+    pub fn call(comptime T: type, info_handle: *const v8.FunctionCallbackInfo, func: anytype, comptime opts: Opts) void {
+        const v8_isolate = v8.v8__FunctionCallbackInfo__GetIsolate(info_handle).?;
+        const ctx, const v8_context = Context.fromIsolate(.{ .handle = v8_isolate });
+        const info = FunctionCallbackInfo{ .handle = info_handle };
+
+        var hs: js.HandleScope = undefined;
+        hs.initWithIsolateHandle(v8_isolate);
+        defer hs.deinit();
+
+        var cache_state: CacheState = undefined;
+        if (comptime opts.cache) |cache| {
+            // This API is a bit weird. On
+            if (respondFromCache(cache, ctx, v8_context, info, &cache_state)) {
+                // Value was fetched from the cache and returned already
+                return;
+            } else {
+                // Cache miss: cache_state will have been populated
+            }
+        }
+
+        var caller: Caller = undefined;
+        caller.initWithContext(ctx, v8_context);
+        defer caller.deinit();
+
+        const js_value = _call(T, &caller.local, info, func, opts) catch |err| {
+            handleError(T, @TypeOf(func), &caller.local, err, info, .{
+                .dom_exception = opts.dom_exception,
+                .as_typed_array = opts.as_typed_array,
+                .null_as_undefined = opts.null_as_undefined,
+            });
+            return;
+        };
+
+        if (comptime opts.cache) |cache| {
+            cache_state.save(cache, js_value);
+        }
+    }
+
+    fn _call(comptime T: type, local: *const Local, info: FunctionCallbackInfo, func: anytype, comptime opts: Opts) !js.Value {
+        const F = @TypeOf(func);
+        var args: ParameterTypes(F) = undefined;
+        if (comptime opts.static) {
+            args = try getArgs(F, 0, local, info);
+        } else if (comptime opts.embedded_receiver) {
+            args = try getArgs(F, 1, local, info);
+            @field(args, "0") = @ptrCast(@alignCast(info.getData() orelse unreachable));
+        } else {
+            args = try getArgs(F, 1, local, info);
+            @field(args, "0") = try TaggedOpaque.fromJS(*T, info.getThis());
+        }
+        const res = @call(.auto, func, args);
+        const js_value = try local.zigValueToJs(res, .{
+            .dom_exception = opts.dom_exception,
+            .as_typed_array = opts.as_typed_array,
+            .null_as_undefined = opts.null_as_undefined,
+        });
+        info.getReturnValue().set(js_value);
+        return js_value;
+    }
+
+    // We can cache a value directly into the v8::Object so that our callback to fetch a property
+    // can be fast. Generally, think of it like this:
+    //   fn callback(handle: *const v8.FunctionCallbackInfo) callconv(.c) void {
+    //       const js_obj = info.getThis();
+    //       const cached_value = js_obj.getFromCache("Nodes.childNodes");
+    //       info.returnValue().set(cached_value);
+    //   }
+    //
+    // That above pseudocode snippet is largely what this respondFromCache is doing.
+    // But on miss, it's also setting the `cache_state` with all of the data it
+    // got checking the cache, so that, once we get the value from our Zig code,
+    // it's quick to store in the v8::Object for subsequent calls.
+    fn respondFromCache(comptime cache: Opts.Caching, ctx: *Context, v8_context: *const v8.Context, info: FunctionCallbackInfo, cache_state: *CacheState) bool {
+        const js_this = info.getThis();
+        const return_value = info.getReturnValue();
+
+        switch (cache) {
+            .internal => |idx| {
+                if (v8.v8__Object__GetInternalField(js_this, idx)) |cached| {
+                    // means we can't cache undefined, since we can't tell the
+                    // difference between "it isn't in the cache" and  "it's
+                    // in the cache with a valud of undefined"
+                    if (!v8.v8__Value__IsUndefined(cached)) {
+                        return_value.set(cached);
+                        return true;
+                    }
+                }
+
+                // store this so that we can quickly save the result into the cache
+                cache_state.* = .{
+                    .js_this = js_this,
+                    .v8_context = v8_context,
+                    .mode = .{ .internal = idx },
+                };
+            },
+            .private => |private_symbol| {
+                const global_handle = &@field(ctx.env.private_symbols, private_symbol).handle;
+                const private_key: *const v8.Private = v8.v8__Global__Get(global_handle, ctx.isolate.handle).?;
+                if (v8.v8__Object__GetPrivate(js_this, v8_context, private_key)) |cached| {
+                    // This means we can't cache "undefined", since we can't tell
+                    // the difference between a (a) undefined == not in the cache
+                    // and (b) undefined == the cache value.  If this becomes
+                    // important, we can check HasPrivate first. But that requires
+                    // calling HasPrivate then GetPrivate.
+                    if (!v8.v8__Value__IsUndefined(cached)) {
+                        return_value.set(cached);
+                        return true;
+                    }
+                }
+
+                // store this so that we can quickly save the result into the cache
+                cache_state.* = .{
+                    .js_this = js_this,
+                    .v8_context = v8_context,
+                    .mode = .{ .private = private_key },
+                };
+            },
+        }
+
+        // cache miss
+        return false;
+    }
+
+    const CacheState = struct {
+        js_this: *const v8.Object,
+        v8_context: *const v8.Context,
+        mode: union(enum) {
+            internal: u8,
+            private: *const v8.Private,
+        },
+
+        pub fn save(self: *const CacheState, comptime cache: Opts.Caching, js_value: js.Value) void {
+            if (comptime cache == .internal) {
+                v8.v8__Object__SetInternalField(self.js_this, self.mode.internal, js_value.handle);
+            } else {
+                var out: v8.MaybeBool = undefined;
+                v8.v8__Object__SetPrivate(self.js_this, self.v8_context, self.mode.private, js_value.handle, &out);
+            }
+        }
+    };
+};
+
+// If we call a method in javascript: cat.lives('nine');
+//
+// Then we'd expect a Zig function with 2 parameters: a self and the string.
+// In this case, offset == 1. Offset is always 1 for setters or methods.
+//
+// Offset is always 0 for constructors.
+//
+// For constructors, setters and methods, we can further increase offset + 1
+// if the first parameter is an instance of Page.
+//
+// Finally, if the JS function is called with _more_ parameters and
+// the last parameter in Zig is an array, we'll try to slurp the additional
+// parameters into the array.
+fn getArgs(comptime F: type, comptime offset: usize, local: *const Local, info: FunctionCallbackInfo) !ParameterTypes(F) {
+    var args: ParameterTypes(F) = undefined;
+
+    const params = @typeInfo(F).@"fn".params[offset..];
+    // Except for the constructor, the first parameter is always `self`
+    // This isn't something we'll bind from JS, so skip it.
+    const params_to_map = blk: {
+        if (params.len == 0) {
+            return args;
+        }
+
+        // If the last parameter is the Page, set it, and exclude it
+        // from our params slice, because we don't want to bind it to
+        // a JS argument
+        if (comptime isPage(params[params.len - 1].type.?)) {
+            @field(args, tupleFieldName(params.len - 1 + offset)) = local.ctx.page;
+            break :blk params[0 .. params.len - 1];
+        }
+
+        // we have neither a Page nor a JsObject. All params must be
+        // bound to a JavaScript value.
+        break :blk params;
+    };
+
+    if (params_to_map.len == 0) {
+        return args;
+    }
+
+    const js_parameter_count = info.length();
+    const last_js_parameter = params_to_map.len - 1;
+    var is_variadic = false;
+
+    {
+        // This is going to get complicated. If the last Zig parameter
+        // is a slice AND the corresponding javascript parameter is
+        // NOT an an array, then we'll treat it as a variadic.
+
+        const last_parameter_type = params_to_map[params_to_map.len - 1].type.?;
+        const last_parameter_type_info = @typeInfo(last_parameter_type);
+        if (last_parameter_type_info == .pointer and last_parameter_type_info.pointer.size == .slice) {
+            const slice_type = last_parameter_type_info.pointer.child;
+            const corresponding_js_value = info.getArg(@intCast(last_js_parameter), local);
+            if (slice_type == js.Value or (corresponding_js_value.isArray() == false and corresponding_js_value.isTypedArray() == false and slice_type != u8)) {
+                is_variadic = true;
+                if (js_parameter_count == 0) {
+                    @field(args, tupleFieldName(params_to_map.len + offset - 1)) = &.{};
+                } else if (js_parameter_count >= params_to_map.len) {
+                    const arr = try local.call_arena.alloc(last_parameter_type_info.pointer.child, js_parameter_count - params_to_map.len + 1);
+                    for (arr, last_js_parameter..) |*a, i| {
+                        a.* = try local.jsValueToZig(slice_type, info.getArg(@intCast(i), local));
+                    }
+                    @field(args, tupleFieldName(params_to_map.len + offset - 1)) = arr;
+                } else {
+                    @field(args, tupleFieldName(params_to_map.len + offset - 1)) = &.{};
+                }
+            }
+        }
+    }
+
+    inline for (params_to_map, 0..) |param, i| {
+        const field_index = comptime i + offset;
+        if (comptime i == params_to_map.len - 1) {
+            if (is_variadic) {
+                break;
+            }
+        }
+
+        if (comptime isPage(param.type.?)) {
+            @compileError("Page must be the last parameter (or 2nd last if there's a JsThis): " ++ @typeName(F));
+        } else if (i >= js_parameter_count) {
+            if (@typeInfo(param.type.?) != .optional) {
+                return error.InvalidArgument;
+            }
+            @field(args, tupleFieldName(field_index)) = null;
+        } else {
+            const js_val = info.getArg(@intCast(i), local);
+            @field(args, tupleFieldName(field_index)) = local.jsValueToZig(param.type.?, js_val) catch {
+                return error.InvalidArgument;
+            };
+        }
+    }
+
+    return args;
+}

src/browser/js/Env.zig

@@ -0,0 +1,570 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const js = @import("js.zig");
+const builtin = @import("builtin");
+
+const v8 = js.v8;
+
+const App = @import("../../App.zig");
+const log = @import("../../log.zig");
+
+const bridge = @import("bridge.zig");
+const Origin = @import("Origin.zig");
+const Context = @import("Context.zig");
+const Isolate = @import("Isolate.zig");
+const Platform = @import("Platform.zig");
+const Snapshot = @import("Snapshot.zig");
+const Inspector = @import("Inspector.zig");
+
+const Page = @import("../Page.zig");
+const Session = @import("../Session.zig");
+const Window = @import("../webapi/Window.zig");
+
+const JsApis = bridge.JsApis;
+const Allocator = std.mem.Allocator;
+const IS_DEBUG = builtin.mode == .Debug;
+
+fn initClassIds() void {
+    inline for (JsApis, 0..) |JsApi, i| {
+        JsApi.Meta.class_id = i;
+    }
+}
+
+var class_id_once = std.once(initClassIds);
+
+// The Env maps to a V8 isolate, which represents a isolated sandbox for
+// executing JavaScript. The Env is where we'll define our V8 <-> Zig bindings,
+// and it's where we'll start ExecutionWorlds, which actually execute JavaScript.
+// The `S` parameter is arbitrary state. When we start an ExecutionWorld, an instance
+// of S must be given. This instance is available to any Zig binding.
+// The `types` parameter is a tuple of Zig structures we want to bind to V8.
+const Env = @This();
+
+app: *App,
+
+allocator: Allocator,
+
+platform: *const Platform,
+
+// the global isolate
+isolate: js.Isolate,
+
+contexts: [64]*Context,
+context_count: usize,
+
+// just kept around because we need to free it on deinit
+isolate_params: *v8.CreateParams,
+
+context_id: usize,
+
+// Maps origin -> shared Origin contains, for v8 values shared across
+// same-origin Contexts. There's a mismatch here between our JS model and our
+// Browser model. Origins only live as long as the root page of a session exists.
+// It would be wrong/dangerous to re-use an Origin across root page navigations.
+
+// Global handles that need to be freed on deinit
+eternal_function_templates: []v8.Eternal,
+
+// Dynamic slice to avoid circular dependency on JsApis.len at comptime
+templates: []*const v8.FunctionTemplate,
+
+// Global template created once per isolate and reused across all contexts
+global_template: v8.Eternal,
+
+// Inspector associated with the Isolate. Exists when CDP is being used.
+inspector: ?*Inspector,
+
+// We can store data in a v8::Object's Private data bag. The keys are v8::Private
+// which an be created once per isolaet.
+private_symbols: PrivateSymbols,
+
+microtask_queues_are_running: bool,
+
+pub const InitOpts = struct {
+    with_inspector: bool = false,
+};
+
+pub fn init(app: *App, opts: InitOpts) !Env {
+    if (comptime IS_DEBUG) {
+        comptime {
+            // V8 requirement for any data using SetAlignedPointerInInternalField
+            const a = @alignOf(@import("TaggedOpaque.zig"));
+            std.debug.assert(a >= 2 and a % 2 == 0);
+        }
+    }
+
+    // Initialize class IDs once before any V8 work
+    class_id_once.call();
+
+    const allocator = app.allocator;
+    const snapshot = &app.snapshot;
+
+    var params = try allocator.create(v8.CreateParams);
+    errdefer allocator.destroy(params);
+    v8.v8__Isolate__CreateParams__CONSTRUCT(params);
+    params.snapshot_blob = @ptrCast(&snapshot.startup_data);
+
+    params.array_buffer_allocator = v8.v8__ArrayBuffer__Allocator__NewDefaultAllocator().?;
+    errdefer v8.v8__ArrayBuffer__Allocator__DELETE(params.array_buffer_allocator.?);
+
+    params.external_references = &snapshot.external_references;
+
+    var isolate = js.Isolate.init(params);
+    errdefer isolate.deinit();
+    const isolate_handle = isolate.handle;
+
+    v8.v8__Isolate__SetHostImportModuleDynamicallyCallback(isolate_handle, Context.dynamicModuleCallback);
+    v8.v8__Isolate__SetPromiseRejectCallback(isolate_handle, promiseRejectCallback);
+    v8.v8__Isolate__SetMicrotasksPolicy(isolate_handle, v8.kExplicit);
+    v8.v8__Isolate__SetFatalErrorHandler(isolate_handle, fatalCallback);
+    v8.v8__Isolate__SetOOMErrorHandler(isolate_handle, oomCallback);
+
+    isolate.enter();
+    errdefer isolate.exit();
+
+    v8.v8__Isolate__SetHostInitializeImportMetaObjectCallback(isolate_handle, Context.metaObjectCallback);
+
+    // Allocate arrays dynamically to avoid comptime dependency on JsApis.len
+    const eternal_function_templates = try allocator.alloc(v8.Eternal, JsApis.len);
+    errdefer allocator.free(eternal_function_templates);
+
+    const templates = try allocator.alloc(*const v8.FunctionTemplate, JsApis.len);
+    errdefer allocator.free(templates);
+
+    var global_eternal: v8.Eternal = undefined;
+    var private_symbols: PrivateSymbols = undefined;
+    {
+        var temp_scope: js.HandleScope = undefined;
+        temp_scope.init(isolate);
+        defer temp_scope.deinit();
+
+        inline for (JsApis, 0..) |_, i| {
+            const data = v8.v8__Isolate__GetDataFromSnapshotOnce(isolate_handle, snapshot.data_start + i);
+            const function_handle: *const v8.FunctionTemplate = @ptrCast(data);
+            // Make function template eternal
+            v8.v8__Eternal__New(isolate_handle, @ptrCast(function_handle), &eternal_function_templates[i]);
+
+            // Extract the local handle from the global for easy access
+            const eternal_ptr = v8.v8__Eternal__Get(&eternal_function_templates[i], isolate_handle);
+            templates[i] = @ptrCast(@alignCast(eternal_ptr.?));
+        }
+
+        // Create global template once per isolate
+        const js_global = v8.v8__FunctionTemplate__New__DEFAULT(isolate_handle);
+        const window_name = v8.v8__String__NewFromUtf8(isolate_handle, "Window", v8.kNormal, 6);
+        v8.v8__FunctionTemplate__SetClassName(js_global, window_name);
+
+        // Find Window in JsApis by name (avoids circular import)
+        const window_index = comptime bridge.JsApiLookup.getId(Window.JsApi);
+        v8.v8__FunctionTemplate__Inherit(js_global, templates[window_index]);
+
+        const global_template_local = v8.v8__FunctionTemplate__InstanceTemplate(js_global).?;
+        v8.v8__ObjectTemplate__SetNamedHandler(global_template_local, &.{
+            .getter = bridge.unknownWindowPropertyCallback,
+            .setter = null,
+            .query = null,
+            .deleter = null,
+            .enumerator = null,
+            .definer = null,
+            .descriptor = null,
+            .data = null,
+            .flags = v8.kOnlyInterceptStrings | v8.kNonMasking,
+        });
+        // I don't 100% understand this. We actually set this up in the snapshot,
+        // but for the global instance, it doesn't work. SetIndexedHandler and
+        // SetNamedHandler are set on the Instance template, and that's the key
+        // difference. The context has its own global instance, so we need to set
+        // these back up directly on it. There might be a better way to do this.
+        v8.v8__ObjectTemplate__SetIndexedHandler(global_template_local, &.{
+            .getter = Window.JsApi.index.getter,
+            .setter = null,
+            .query = null,
+            .deleter = null,
+            .enumerator = null,
+            .definer = null,
+            .descriptor = null,
+            .data = null,
+            .flags = 0,
+        });
+        v8.v8__Eternal__New(isolate_handle, @ptrCast(global_template_local), &global_eternal);
+        private_symbols = PrivateSymbols.init(isolate_handle);
+    }
+
+    var inspector: ?*js.Inspector = null;
+    if (opts.with_inspector) {
+        inspector = try Inspector.init(allocator, isolate_handle);
+    }
+
+    return .{
+        .app = app,
+        .context_id = 0,
+        .allocator = allocator,
+        .contexts = undefined,
+        .context_count = 0,
+        .isolate = isolate,
+        .platform = &app.platform,
+        .templates = templates,
+        .isolate_params = params,
+        .inspector = inspector,
+        .global_template = global_eternal,
+        .private_symbols = private_symbols,
+        .microtask_queues_are_running = false,
+        .eternal_function_templates = eternal_function_templates,
+    };
+}
+
+pub fn deinit(self: *Env) void {
+    if (comptime IS_DEBUG) {
+        std.debug.assert(self.context_count == 0);
+    }
+    for (self.contexts[0..self.context_count]) |ctx| {
+        ctx.deinit();
+    }
+
+    const app = self.app;
+    const allocator = app.allocator;
+
+    if (self.inspector) |i| {
+        i.deinit(allocator);
+    }
+
+    allocator.free(self.templates);
+    allocator.free(self.eternal_function_templates);
+    self.private_symbols.deinit();
+
+    self.isolate.exit();
+    self.isolate.deinit();
+    v8.v8__ArrayBuffer__Allocator__DELETE(self.isolate_params.array_buffer_allocator.?);
+    allocator.destroy(self.isolate_params);
+}
+
+pub const ContextParams = struct {
+    identity: *js.Identity,
+    identity_arena: Allocator,
+    call_arena: Allocator,
+    debug_name: []const u8 = "Context",
+};
+
+pub fn createContext(self: *Env, page: *Page, params: ContextParams) !*Context {
+    const context_arena = try self.app.arena_pool.acquire(.{ .debug = params.debug_name });
+    errdefer self.app.arena_pool.release(context_arena);
+
+    const isolate = self.isolate;
+    var hs: js.HandleScope = undefined;
+    hs.init(isolate);
+    defer hs.deinit();
+
+    // Create a per-context microtask queue for isolation
+    const microtask_queue = v8.v8__MicrotaskQueue__New(isolate.handle, v8.kExplicit).?;
+    errdefer v8.v8__MicrotaskQueue__DELETE(microtask_queue);
+
+    // Get the global template that was created once per isolate
+    const global_template: *const v8.ObjectTemplate = @ptrCast(@alignCast(v8.v8__Eternal__Get(&self.global_template, isolate.handle).?));
+    v8.v8__ObjectTemplate__SetInternalFieldCount(global_template, comptime Snapshot.countInternalFields(Window.JsApi));
+
+    const v8_context = v8.v8__Context__New__Config(isolate.handle, &.{
+        .global_template = global_template,
+        .global_object = null,
+        .microtask_queue = microtask_queue,
+    }).?;
+
+    // Create the v8::Context and wrap it in a v8::Global
+    var context_global: v8.Global = undefined;
+    v8.v8__Global__New(isolate.handle, v8_context, &context_global);
+
+    // get the global object for the context, this maps to our Window
+    const global_obj = v8.v8__Context__Global(v8_context).?;
+
+    {
+        // Store our TAO inside the internal field of the global object. This
+        // maps the v8::Object -> Zig instance. Almost all objects have this, and
+        // it gets setup automatically as objects are created, but the Window
+        // object already exists in v8 (it's the global) so we manually create
+        // the mapping here.
+        const tao = try context_arena.create(@import("TaggedOpaque.zig"));
+        tao.* = .{
+            .value = @ptrCast(page.window),
+            .prototype_chain = (&Window.JsApi.Meta.prototype_chain).ptr,
+            .prototype_len = @intCast(Window.JsApi.Meta.prototype_chain.len),
+            .subtype = .node, // this probably isn't right, but it's what we've been doing all along
+        };
+        v8.v8__Object__SetAlignedPointerInInternalField(global_obj, 0, tao);
+    }
+
+    const context_id = self.context_id;
+    self.context_id = context_id + 1;
+
+    const session = page._session;
+    const origin = try session.getOrCreateOrigin(null);
+    errdefer session.releaseOrigin(origin);
+
+    const context = try context_arena.create(Context);
+    context.* = .{
+        .env = self,
+        .page = page,
+        .origin = origin,
+        .id = context_id,
+        .session = session,
+        .isolate = isolate,
+        .arena = context_arena,
+        .handle = context_global,
+        .templates = self.templates,
+        .call_arena = params.call_arena,
+        .microtask_queue = microtask_queue,
+        .script_manager = &page._script_manager,
+        .scheduler = .init(context_arena),
+        .identity = params.identity,
+        .identity_arena = params.identity_arena,
+    };
+
+    {
+        // Multiple contexts can be created for the same Window (via CDP). We only
+        // need to register the first one.
+        const gop = try params.identity.identity_map.getOrPut(params.identity_arena, @intFromPtr(page.window));
+        if (gop.found_existing == false) {
+            // our window wrapped in a v8::Global
+            var global_global: v8.Global = undefined;
+            v8.v8__Global__New(isolate.handle, global_obj, &global_global);
+            gop.value_ptr.* = global_global;
+        }
+    }
+
+    // Store a pointer to our context inside the v8 context so that, given
+    // a v8 context, we can get our context out
+    v8.v8__Context__SetAlignedPointerInEmbedderData(v8_context, 1, @ptrCast(context));
+
+    const count = self.context_count;
+    if (count >= self.contexts.len) {
+        return error.TooManyContexts;
+    }
+    self.contexts[count] = context;
+    self.context_count = count + 1;
+
+    return context;
+}
+
+pub fn destroyContext(self: *Env, context: *Context) void {
+    for (self.contexts[0..self.context_count], 0..) |ctx, i| {
+        if (ctx == context) {
+            // Swap with last element and decrement count
+            self.context_count -= 1;
+            self.contexts[i] = self.contexts[self.context_count];
+            break;
+        }
+    } else {
+        if (comptime IS_DEBUG) {
+            @panic("Tried to remove unknown context");
+        }
+    }
+
+    const isolate = self.isolate;
+    if (self.inspector) |inspector| {
+        var hs: js.HandleScope = undefined;
+        hs.init(isolate);
+        defer hs.deinit();
+        inspector.contextDestroyed(@ptrCast(v8.v8__Global__Get(&context.handle, isolate.handle)));
+    }
+
+    context.deinit();
+}
+
+pub fn runMicrotasks(self: *Env) void {
+    if (self.microtask_queues_are_running == false) {
+        const v8_isolate = self.isolate.handle;
+
+        self.microtask_queues_are_running = true;
+        defer self.microtask_queues_are_running = false;
+
+        var i: usize = 0;
+        while (i < self.context_count) : (i += 1) {
+            const ctx = self.contexts[i];
+            v8.v8__MicrotaskQueue__PerformCheckpoint(ctx.microtask_queue, v8_isolate);
+        }
+    }
+}
+
+pub fn runMacrotasks(self: *Env) !void {
+    for (self.contexts[0..self.context_count]) |ctx| {
+        if (comptime builtin.is_test == false) {
+            // I hate this comptime check as much as you do. But we have tests
+            // which rely on short execution before shutdown. In real world, it's
+            // underterministic whether a timer will or won't run before the
+            // page shutsdown. But for tests, we need to run them to their end.
+            if (ctx.scheduler.hasReadyTasks() == false) {
+                continue;
+            }
+        }
+
+        var hs: js.HandleScope = undefined;
+        const entered = ctx.enter(&hs);
+        defer entered.exit();
+        try ctx.scheduler.run();
+    }
+}
+
+pub fn msToNextMacrotask(self: *Env) ?u64 {
+    var next_task: u64 = std.math.maxInt(u64);
+    for (self.contexts[0..self.context_count]) |ctx| {
+        const candidate = ctx.scheduler.msToNextHigh() orelse continue;
+        next_task = @min(candidate, next_task);
+    }
+    return if (next_task == std.math.maxInt(u64)) null else next_task;
+}
+
+pub fn pumpMessageLoop(self: *const Env) void {
+    var hs: v8.HandleScope = undefined;
+    v8.v8__HandleScope__CONSTRUCT(&hs, self.isolate.handle);
+    defer v8.v8__HandleScope__DESTRUCT(&hs);
+
+    const isolate = self.isolate.handle;
+    const platform = self.platform.handle;
+    while (v8.v8__Platform__PumpMessageLoop(platform, isolate, false)) {}
+}
+
+pub fn hasBackgroundTasks(self: *const Env) bool {
+    return v8.v8__Isolate__HasPendingBackgroundTasks(self.isolate.handle);
+}
+
+pub fn waitForBackgroundTasks(self: *Env) void {
+    var hs: v8.HandleScope = undefined;
+    v8.v8__HandleScope__CONSTRUCT(&hs, self.isolate.handle);
+    defer v8.v8__HandleScope__DESTRUCT(&hs);
+
+    const isolate = self.isolate.handle;
+    const platform = self.platform.handle;
+    while (v8.v8__Isolate__HasPendingBackgroundTasks(isolate)) {
+        _ = v8.v8__Platform__PumpMessageLoop(platform, isolate, true);
+        self.runMicrotasks();
+    }
+}
+
+pub fn runIdleTasks(self: *const Env) void {
+    v8.v8__Platform__RunIdleTasks(self.platform.handle, self.isolate.handle, 1);
+}
+
+// V8 doesn't immediately free memory associated with
+// a Context, it's managed by the garbage collector. We use the
+// `lowMemoryNotification` call on the isolate to encourage v8 to free
+// any contexts which have been freed.
+// This GC is very aggressive. Use memoryPressureNotification for less
+// aggressive GC passes.
+pub fn lowMemoryNotification(self: *Env) void {
+    var handle_scope: js.HandleScope = undefined;
+    handle_scope.init(self.isolate);
+    defer handle_scope.deinit();
+    self.isolate.lowMemoryNotification();
+}
+
+// V8 doesn't immediately free memory associated with
+// a Context, it's managed by the garbage collector. We use the
+// `memoryPressureNotification` call on the isolate to encourage v8 to free
+// any contexts which have been freed.
+// The level indicates the aggressivity of the GC required:
+// moderate speeds up incremental GC
+// critical runs one full GC
+// For a more aggressive GC, use lowMemoryNotification.
+pub fn memoryPressureNotification(self: *Env, level: Isolate.MemoryPressureLevel) void {
+    var handle_scope: js.HandleScope = undefined;
+    handle_scope.init(self.isolate);
+    defer handle_scope.deinit();
+    self.isolate.memoryPressureNotification(level);
+}
+
+pub fn dumpMemoryStats(self: *Env) void {
+    const stats = self.isolate.getHeapStatistics();
+    std.debug.print(
+        \\ Total Heap Size: {d}
+        \\ Total Heap Size Executable: {d}
+        \\ Total Physical Size: {d}
+        \\ Total Available Size: {d}
+        \\ Used Heap Size: {d}
+        \\ Heap Size Limit: {d}
+        \\ Malloced Memory: {d}
+        \\ External Memory: {d}
+        \\ Peak Malloced Memory: {d}
+        \\ Number Of Native Contexts: {d}
+        \\ Number Of Detached Contexts: {d}
+        \\ Total Global Handles Size: {d}
+        \\ Used Global Handles Size: {d}
+        \\ Zap Garbage: {any}
+        \\
+    , .{ stats.total_heap_size, stats.total_heap_size_executable, stats.total_physical_size, stats.total_available_size, stats.used_heap_size, stats.heap_size_limit, stats.malloced_memory, stats.external_memory, stats.peak_malloced_memory, stats.number_of_native_contexts, stats.number_of_detached_contexts, stats.total_global_handles_size, stats.used_global_handles_size, stats.does_zap_garbage });
+}
+
+pub fn terminate(self: *const Env) void {
+    v8.v8__Isolate__TerminateExecution(self.isolate.handle);
+}
+
+fn promiseRejectCallback(message_handle: v8.PromiseRejectMessage) callconv(.c) void {
+    const promise_event = v8.v8__PromiseRejectMessage__GetEvent(&message_handle);
+    if (promise_event != v8.kPromiseRejectWithNoHandler and promise_event != v8.kPromiseHandlerAddedAfterReject) {
+        return;
+    }
+
+    const promise_handle = v8.v8__PromiseRejectMessage__GetPromise(&message_handle).?;
+    const v8_isolate = v8.v8__Object__GetIsolate(@ptrCast(promise_handle)).?;
+    const isolate = js.Isolate{ .handle = v8_isolate };
+    const ctx, const v8_context = Context.fromIsolate(isolate);
+
+    const local = js.Local{
+        .ctx = ctx,
+        .isolate = isolate,
+        .handle = v8_context,
+        .call_arena = ctx.call_arena,
+    };
+
+    const page = ctx.page;
+    page.window.unhandledPromiseRejection(promise_event == v8.kPromiseRejectWithNoHandler, .{
+        .local = &local,
+        .handle = &message_handle,
+    }, page) catch |err| {
+        log.warn(.browser, "unhandled rejection handler", .{ .err = err });
+    };
+}
+
+fn fatalCallback(c_location: [*c]const u8, c_message: [*c]const u8) callconv(.c) void {
+    const location = std.mem.span(c_location);
+    const message = std.mem.span(c_message);
+    log.fatal(.app, "V8 fatal callback", .{ .location = location, .message = message });
+    @import("../../crash_handler.zig").crash("Fatal V8 Error", .{ .location = location, .message = message }, @returnAddress());
+}
+
+fn oomCallback(c_location: [*c]const u8, details: ?*const v8.OOMDetails) callconv(.c) void {
+    const location = std.mem.span(c_location);
+    const detail = if (details) |d| std.mem.span(d.detail) else "";
+    log.fatal(.app, "V8 OOM", .{ .location = location, .detail = detail });
+    @import("../../crash_handler.zig").crash("V8 OOM", .{ .location = location, .detail = detail }, @returnAddress());
+}
+
+const PrivateSymbols = struct {
+    const Private = @import("Private.zig");
+
+    child_nodes: Private,
+
+    fn init(isolate: *v8.Isolate) PrivateSymbols {
+        return .{
+            .child_nodes = Private.init(isolate, "child_nodes"),
+        };
+    }
+
+    fn deinit(self: *PrivateSymbols) void {
+        self.child_nodes.deinit();
+    }
+};

src/browser/js/Function.zig

@@ -0,0 +1,267 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const js = @import("js.zig");
+const v8 = js.v8;
+
+const log = @import("../../log.zig");
+const Session = @import("../Session.zig");
+
+const Function = @This();
+
+local: *const js.Local,
+this: ?*const v8.Object = null,
+handle: *const v8.Function,
+
+pub const Result = struct {
+    stack: ?[]const u8,
+    exception: []const u8,
+};
+
+pub fn withThis(self: *const Function, value: anytype) !Function {
+    const local = self.local;
+    const this_obj = if (@TypeOf(value) == js.Object)
+        value.handle
+    else
+        (try local.zigValueToJs(value, .{})).handle;
+
+    return .{
+        .local = local,
+        .this = this_obj,
+        .handle = self.handle,
+    };
+}
+
+pub fn newInstance(self: *const Function, caught: *js.TryCatch.Caught) !js.Object {
+    const local = self.local;
+
+    var try_catch: js.TryCatch = undefined;
+    try_catch.init(local);
+    defer try_catch.deinit();
+
+    // This creates a new instance using this Function as a constructor.
+    // const c_args = @as(?[*]const ?*c.Value, @ptrCast(&.{}));
+    const handle = v8.v8__Function__NewInstance(self.handle, local.handle, 0, null) orelse {
+        caught.* = try_catch.caughtOrError(local.call_arena, error.Unknown);
+        return error.JsConstructorFailed;
+    };
+
+    return .{
+        .local = local,
+        .handle = handle,
+    };
+}
+
+pub fn call(self: *const Function, comptime T: type, args: anytype) !T {
+    var caught: js.TryCatch.Caught = undefined;
+    return self._tryCallWithThis(T, self.getThis(), args, &caught, .{}) catch |err| {
+        log.warn(.js, "call caught", .{ .err = err, .caught = caught });
+        return err;
+    };
+}
+
+pub fn callRethrow(self: *const Function, comptime T: type, args: anytype) !T {
+    var caught: js.TryCatch.Caught = undefined;
+    return self._tryCallWithThis(T, self.getThis(), args, &caught, .{ .rethrow = true }) catch |err| {
+        log.warn(.js, "call caught", .{ .err = err, .caught = caught });
+        return err;
+    };
+}
+
+pub fn callWithThis(self: *const Function, comptime T: type, this: anytype, args: anytype) !T {
+    var caught: js.TryCatch.Caught = undefined;
+    return self._tryCallWithThis(T, this, args, &caught, .{}) catch |err| {
+        log.warn(.js, "callWithThis caught", .{ .err = err, .caught = caught });
+        return err;
+    };
+}
+
+pub fn tryCall(self: *const Function, comptime T: type, args: anytype, caught: *js.TryCatch.Caught) !T {
+    return self._tryCallWithThis(T, self.getThis(), args, caught, .{});
+}
+
+pub fn tryCallWithThis(self: *const Function, comptime T: type, this: anytype, args: anytype, caught: *js.TryCatch.Caught) !T {
+    return self._tryCallWithThis(T, this, args, caught, .{});
+}
+
+const CallOpts = struct {
+    rethrow: bool = false,
+};
+fn _tryCallWithThis(self: *const Function, comptime T: type, this: anytype, args: anytype, caught: *js.TryCatch.Caught, comptime opts: CallOpts) !T {
+    caught.* = .{};
+    const local = self.local;
+
+    // When we're calling a function from within JavaScript itself, this isn't
+    // necessary. We're within a Caller instantiation, which will already have
+    // incremented the call_depth and it won't decrement it until the Caller is
+    // done.
+    // But some JS functions are initiated from Zig code, and not v8. For
+    // example, Observers, some event and window callbacks. In those cases, we
+    // need to increase the call_depth so that the call_arena remains valid for
+    // the duration of the function call. If we don't do this, the call_arena
+    // will be reset after each statement of the function which executes Zig code.
+    const ctx = local.ctx;
+    const call_depth = ctx.call_depth;
+    ctx.call_depth = call_depth + 1;
+    defer ctx.call_depth = call_depth;
+
+    const js_this = blk: {
+        if (@TypeOf(this) == js.Object) {
+            break :blk this;
+        }
+        break :blk try local.zigValueToJs(this, .{});
+    };
+
+    const aargs = if (comptime @typeInfo(@TypeOf(args)) == .null) struct {}{} else args;
+
+    const js_args: []const *const v8.Value = switch (@typeInfo(@TypeOf(aargs))) {
+        .@"struct" => |s| blk: {
+            const fields = s.fields;
+            var js_args: [fields.len]*const v8.Value = undefined;
+            inline for (fields, 0..) |f, i| {
+                js_args[i] = (try local.zigValueToJs(@field(aargs, f.name), .{})).handle;
+            }
+            const cargs: [fields.len]*const v8.Value = js_args;
+            break :blk &cargs;
+        },
+        .pointer => blk: {
+            var values = try local.call_arena.alloc(*const v8.Value, args.len);
+            for (args, 0..) |a, i| {
+                values[i] = (try local.zigValueToJs(a, .{})).handle;
+            }
+            break :blk values;
+        },
+        else => @compileError("JS Function called with invalid paremter type"),
+    };
+
+    const c_args = @as(?[*]const ?*v8.Value, @ptrCast(js_args.ptr));
+
+    var try_catch: js.TryCatch = undefined;
+    try_catch.init(local);
+    defer try_catch.deinit();
+
+    const handle = v8.v8__Function__Call(self.handle, local.handle, js_this.handle, @as(c_int, @intCast(js_args.len)), c_args) orelse {
+        if ((comptime opts.rethrow) and try_catch.hasCaught()) {
+            try_catch.rethrow();
+            return error.TryCatchRethrow;
+        }
+        caught.* = try_catch.caughtOrError(local.call_arena, error.JsException);
+        return error.JsException;
+    };
+
+    if (@typeInfo(T) == .void) {
+        return {};
+    }
+    return local.jsValueToZig(T, .{ .local = local, .handle = handle });
+}
+
+fn getThis(self: *const Function) js.Object {
+    const handle = if (self.this) |t| t else v8.v8__Context__Global(self.local.handle).?;
+    return .{
+        .local = self.local,
+        .handle = handle,
+    };
+}
+
+pub fn src(self: *const Function) ![]const u8 {
+    return self.local.valueToString(.{ .local = self.local, .handle = @ptrCast(self.handle) }, .{});
+}
+
+pub fn getPropertyValue(self: *const Function, name: []const u8) !?js.Value {
+    const local = self.local;
+    const key = local.isolate.initStringHandle(name);
+    const handle = v8.v8__Object__Get(self.handle, self.local.handle, key) orelse {
+        return error.JsException;
+    };
+
+    return .{
+        .local = local,
+        .handle = handle,
+    };
+}
+
+pub fn persist(self: *const Function) !Global {
+    return self._persist(true);
+}
+
+pub fn temp(self: *const Function) !Temp {
+    return self._persist(false);
+}
+
+fn _persist(self: *const Function, comptime is_global: bool) !(if (is_global) Global else Temp) {
+    var ctx = self.local.ctx;
+
+    var global: v8.Global = undefined;
+    v8.v8__Global__New(ctx.isolate.handle, self.handle, &global);
+    if (comptime is_global) {
+        try ctx.trackGlobal(global);
+        return .{ .handle = global, .temps = {} };
+    }
+    try ctx.trackTemp(global);
+    return .{ .handle = global, .temps = &ctx.identity.temps };
+}
+
+pub fn tempWithThis(self: *const Function, value: anytype) !Temp {
+    const with_this = try self.withThis(value);
+    return with_this.temp();
+}
+
+pub fn persistWithThis(self: *const Function, value: anytype) !Global {
+    const with_this = try self.withThis(value);
+    return with_this.persist();
+}
+
+pub const Temp = G(.temp);
+pub const Global = G(.global);
+
+const GlobalType = enum(u8) {
+    temp,
+    global,
+};
+
+fn G(comptime global_type: GlobalType) type {
+    return struct {
+        handle: v8.Global,
+        temps: if (global_type == .temp) *std.AutoHashMapUnmanaged(usize, v8.Global) else void,
+
+        const Self = @This();
+
+        pub fn deinit(self: *Self) void {
+            v8.v8__Global__Reset(&self.handle);
+        }
+
+        pub fn local(self: *const Self, l: *const js.Local) Function {
+            return .{
+                .local = l,
+                .handle = @ptrCast(v8.v8__Global__Get(&self.handle, l.isolate.handle)),
+            };
+        }
+
+        pub fn isEqual(self: *const Self, other: Function) bool {
+            return v8.v8__Global__IsEqual(&self.handle, other.handle);
+        }
+
+        pub fn release(self: *const Self) void {
+            if (self.temps.fetchRemove(self.handle.data_ptr)) |kv| {
+                var g = kv.value;
+                v8.v8__Global__Reset(&g);
+            }
+        }
+    };
+}

src/browser/js/HandleScope.zig

@@ -0,0 +1,40 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const js = @import("js.zig");
+const v8 = js.v8;
+
+const HandleScope = @This();
+
+handle: v8.HandleScope,
+
+// V8 takes an address of the value that's passed in, so it needs to be stable.
+// We can't create the v8.HandleScope here, pass it to v8 and then return the
+// value, as v8 will then have taken the address of the function-scopped (and no
+// longer valid) local.
+pub fn init(self: *HandleScope, isolate: js.Isolate) void {
+    self.initWithIsolateHandle(isolate.handle);
+}
+
+pub fn initWithIsolateHandle(self: *HandleScope, isolate: *v8.Isolate) void {
+    v8.v8__HandleScope__CONSTRUCT(&self.handle, isolate);
+}
+
+pub fn deinit(self: *HandleScope) void {
+    v8.v8__HandleScope__DESTRUCT(&self.handle);
+}

src/browser/js/Identity.zig

@@ -0,0 +1,76 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+// Identity manages the mapping between Zig instances and their v8::Object wrappers.
+// This provides object identity semantics - the same Zig instance always maps to
+// the same JS object within a given Identity scope.
+//
+// Main world contexts share a single Identity (on Session), ensuring that
+// `window.top.document === top's document` works across same-origin frames.
+//
+// Isolated worlds (CDP inspector) have their own Identity, ensuring their
+// v8::Global wrappers don't leak into the main world.
+
+const std = @import("std");
+const js = @import("js.zig");
+
+const Session = @import("../Session.zig");
+
+const v8 = js.v8;
+const Allocator = std.mem.Allocator;
+
+const Identity = @This();
+
+// Maps Zig instance pointers to their v8::Global(Object) wrappers.
+identity_map: std.AutoHashMapUnmanaged(usize, v8.Global) = .empty,
+
+// Tracked global v8 objects that need to be released on cleanup.
+globals: std.ArrayList(v8.Global) = .empty,
+
+// Temporary v8 globals that can be released early. Key is global.data_ptr.
+temps: std.AutoHashMapUnmanaged(usize, v8.Global) = .empty,
+
+// Finalizer callbacks for weak references. Key is @intFromPtr of the Zig instance.
+finalizer_callbacks: std.AutoHashMapUnmanaged(usize, *Session.FinalizerCallback) = .empty,
+
+pub fn deinit(self: *Identity) void {
+    {
+        var it = self.finalizer_callbacks.valueIterator();
+        while (it.next()) |finalizer| {
+            finalizer.*.deinit();
+        }
+    }
+
+    {
+        var it = self.identity_map.valueIterator();
+        while (it.next()) |global| {
+            v8.v8__Global__Reset(global);
+        }
+    }
+
+    for (self.globals.items) |*global| {
+        v8.v8__Global__Reset(global);
+    }
+
+    {
+        var it = self.temps.valueIterator();
+        while (it.next()) |global| {
+            v8.v8__Global__Reset(global);
+        }
+    }
+}

src/browser/js/Inspector.zig

@@ -0,0 +1,462 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const js = @import("js.zig");
+const v8 = js.v8;
+
+const TaggedOpaque = @import("TaggedOpaque.zig");
+
+const Allocator = std.mem.Allocator;
+
+const CONTEXT_GROUP_ID = 1;
+const CLIENT_TRUST_LEVEL = 1;
+const IS_DEBUG = @import("builtin").mode == .Debug;
+
+// Inspector exists for the lifetime of the Isolate/Env. 1 Isolate = 1 Inspector.
+// It combines the v8.Inspector and the v8.InspectorClientImpl. The v8.InspectorClientImpl
+// is our own implementation that fulfills the InspectorClient API, i.e. it's the
+// mechanism v8 provides to let us tweak how the inspector works. For example, it
+// Below, you'll find a few pub export fn v8_inspector__Client__IMPL__XYZ functions
+// which is our implementation of what the v8::Inspector requires of our Client
+// (not much at all)
+const Inspector = @This();
+
+unique_id: i64,
+isolate: *v8.Isolate,
+handle: *v8.Inspector,
+client: *v8.InspectorClientImpl,
+default_context: ?v8.Global,
+session: ?Session,
+
+pub fn init(allocator: Allocator, isolate: *v8.Isolate) !*Inspector {
+    const self = try allocator.create(Inspector);
+    errdefer allocator.destroy(self);
+
+    self.* = .{
+        .unique_id = 1,
+        .session = null,
+        .isolate = isolate,
+        .client = undefined,
+        .handle = undefined,
+        .default_context = null,
+    };
+
+    self.client = v8.v8_inspector__Client__IMPL__CREATE();
+    errdefer v8.v8_inspector__Client__IMPL__DELETE(self.client);
+    v8.v8_inspector__Client__IMPL__SET_DATA(self.client, self);
+
+    self.handle = v8.v8_inspector__Inspector__Create(isolate, self.client).?;
+    errdefer v8.v8_inspector__Inspector__DELETE(self.handle);
+
+    return self;
+}
+
+pub fn deinit(self: *const Inspector, allocator: Allocator) void {
+    var hs: v8.HandleScope = undefined;
+    v8.v8__HandleScope__CONSTRUCT(&hs, self.isolate);
+    defer v8.v8__HandleScope__DESTRUCT(&hs);
+
+    if (self.session) |*s| {
+        s.deinit();
+    }
+    v8.v8_inspector__Client__IMPL__DELETE(self.client);
+    v8.v8_inspector__Inspector__DELETE(self.handle);
+    allocator.destroy(self);
+}
+
+pub fn startSession(self: *Inspector, ctx: anytype) *Session {
+    if (comptime IS_DEBUG) {
+        std.debug.assert(self.session == null);
+    }
+
+    self.session = @as(Session, undefined);
+    Session.init(&self.session.?, self, ctx);
+    return &self.session.?;
+}
+
+pub fn stopSession(self: *Inspector) void {
+    self.session.?.deinit();
+    self.session = null;
+}
+
+// From CDP docs
+// https://chromedevtools.github.io/devtools-protocol/tot/Runtime/#type-ExecutionContextDescription
+// ----
+// - name: Human readable name describing given context.
+// - origin: Execution context origin (ie. URL who initialised the request)
+// - auxData: Embedder-specific auxiliary data likely matching
+// {isDefault: boolean, type: 'default'|'isolated'|'worker', frameId: string}
+// - is_default_context: Whether the execution context is default, should match the auxData
+pub fn contextCreated(
+    self: *Inspector,
+    local: *const js.Local,
+    name: []const u8,
+    origin: []const u8,
+    aux_data: []const u8,
+    is_default_context: bool,
+) void {
+    v8.v8_inspector__Inspector__ContextCreated(
+        self.handle,
+        name.ptr,
+        name.len,
+        origin.ptr,
+        origin.len,
+        aux_data.ptr,
+        aux_data.len,
+        CONTEXT_GROUP_ID,
+        local.handle,
+    );
+
+    if (is_default_context) {
+        self.default_context = local.ctx.handle;
+    }
+}
+
+pub fn contextDestroyed(self: *Inspector, context: *const v8.Context) void {
+    v8.v8_inspector__Inspector__ContextDestroyed(self.handle, context);
+
+    if (self.default_context) |*dc| {
+        if (v8.v8__Global__IsEqual(dc, context)) {
+            self.default_context = null;
+        }
+    }
+}
+
+pub fn resetContextGroup(self: *const Inspector) void {
+    var hs: v8.HandleScope = undefined;
+    v8.v8__HandleScope__CONSTRUCT(&hs, self.isolate);
+    defer v8.v8__HandleScope__DESTRUCT(&hs);
+
+    v8.v8_inspector__Inspector__ResetContextGroup(self.handle, CONTEXT_GROUP_ID);
+}
+
+pub const RemoteObject = struct {
+    handle: *v8.RemoteObject,
+
+    pub fn deinit(self: RemoteObject) void {
+        v8.v8_inspector__RemoteObject__DELETE(self.handle);
+    }
+
+    pub fn getType(self: RemoteObject, allocator: Allocator) ![]const u8 {
+        var ctype_: v8.CZigString = .{ .ptr = null, .len = 0 };
+        if (!v8.v8_inspector__RemoteObject__getType(self.handle, &allocator, &ctype_)) return error.V8AllocFailed;
+        return cZigStringToString(ctype_) orelse return error.InvalidType;
+    }
+
+    pub fn getSubtype(self: RemoteObject, allocator: Allocator) !?[]const u8 {
+        if (!v8.v8_inspector__RemoteObject__hasSubtype(self.handle)) return null;
+
+        var csubtype: v8.CZigString = .{ .ptr = null, .len = 0 };
+        if (!v8.v8_inspector__RemoteObject__getSubtype(self.handle, &allocator, &csubtype)) return error.V8AllocFailed;
+        return cZigStringToString(csubtype);
+    }
+
+    pub fn getClassName(self: RemoteObject, allocator: Allocator) !?[]const u8 {
+        if (!v8.v8_inspector__RemoteObject__hasClassName(self.handle)) return null;
+
+        var cclass_name: v8.CZigString = .{ .ptr = null, .len = 0 };
+        if (!v8.v8_inspector__RemoteObject__getClassName(self.handle, &allocator, &cclass_name)) return error.V8AllocFailed;
+        return cZigStringToString(cclass_name);
+    }
+
+    pub fn getDescription(self: RemoteObject, allocator: Allocator) !?[]const u8 {
+        if (!v8.v8_inspector__RemoteObject__hasDescription(self.handle)) return null;
+
+        var description: v8.CZigString = .{ .ptr = null, .len = 0 };
+        if (!v8.v8_inspector__RemoteObject__getDescription(self.handle, &allocator, &description)) return error.V8AllocFailed;
+        return cZigStringToString(description);
+    }
+
+    pub fn getObjectId(self: RemoteObject, allocator: Allocator) !?[]const u8 {
+        if (!v8.v8_inspector__RemoteObject__hasObjectId(self.handle)) return null;
+
+        var cobject_id: v8.CZigString = .{ .ptr = null, .len = 0 };
+        if (!v8.v8_inspector__RemoteObject__getObjectId(self.handle, &allocator, &cobject_id)) return error.V8AllocFailed;
+        return cZigStringToString(cobject_id);
+    }
+};
+
+// Combines a v8::InspectorSession and a v8::InspectorChannelImpl. The
+// InspectorSession is for zig -> v8 (sending messages to the inspector). The
+// Channel is for v8 -> zig, getting events from the Inspector (that we'll pass
+// back ot some opaque context, i.e the CDP BrowserContext).
+// The channel callbacks are defined below, as:
+//   pub export fn v8_inspector__Channel__IMPL__XYZ
+pub const Session = struct {
+    inspector: *Inspector,
+    handle: *v8.InspectorSession,
+    channel: *v8.InspectorChannelImpl,
+
+    // callbacks
+    ctx: *anyopaque,
+    onNotif: *const fn (ctx: *anyopaque, msg: []const u8) void,
+    onResp: *const fn (ctx: *anyopaque, call_id: u32, msg: []const u8) void,
+
+    fn init(self: *Session, inspector: *Inspector, ctx: anytype) void {
+        const Container = @typeInfo(@TypeOf(ctx)).pointer.child;
+
+        const channel = v8.v8_inspector__Channel__IMPL__CREATE(inspector.isolate);
+        const handle = v8.v8_inspector__Inspector__Connect(
+            inspector.handle,
+            CONTEXT_GROUP_ID,
+            channel,
+            CLIENT_TRUST_LEVEL,
+        ).?;
+        v8.v8_inspector__Channel__IMPL__SET_DATA(channel, self);
+
+        self.* = .{
+            .ctx = ctx,
+            .handle = handle,
+            .channel = channel,
+            .inspector = inspector,
+            .onResp = Container.onInspectorResponse,
+            .onNotif = Container.onInspectorEvent,
+        };
+    }
+
+    fn deinit(self: *const Session) void {
+        v8.v8_inspector__Session__DELETE(self.handle);
+        v8.v8_inspector__Channel__IMPL__DELETE(self.channel);
+    }
+
+    pub fn send(self: *const Session, msg: []const u8) void {
+        const isolate = self.inspector.isolate;
+        var hs: v8.HandleScope = undefined;
+        v8.v8__HandleScope__CONSTRUCT(&hs, isolate);
+        defer v8.v8__HandleScope__DESTRUCT(&hs);
+
+        v8.v8_inspector__Session__dispatchProtocolMessage(
+            self.handle,
+            isolate,
+            msg.ptr,
+            msg.len,
+        );
+    }
+
+    // Gets a value by object ID regardless of which context it is in.
+    // Our TaggedOpaque stores the "resolved" ptr value (the most specific _type,
+    // e.g. we store the ptr to the Div not the EventTarget). But, this is asking for
+    // the pointer to the Node, so we need to use the same resolution mechanism which
+    // is used when we're calling a function to turn the Div into a Node, which is
+    // what TaggedOpaque.fromJS does.
+    pub fn getNodePtr(self: *const Session, allocator: Allocator, object_id: []const u8, local: *js.Local) !*anyopaque {
+        // just to indicate that the caller is responsible for ensuring there's a local environment
+        _ = local;
+
+        const unwrapped = try self.unwrapObject(allocator, object_id);
+        // The values context and groupId are not used here
+        const js_val = unwrapped.value;
+        if (!v8.v8__Value__IsObject(js_val)) {
+            return error.ObjectIdIsNotANode;
+        }
+
+        const Node = @import("../webapi/Node.zig");
+        // Cast to *const v8.Object for typeTaggedAnyOpaque
+        return TaggedOpaque.fromJS(*Node, @ptrCast(js_val)) catch return error.ObjectIdIsNotANode;
+    }
+
+    // Retrieves the RemoteObject for a given value.
+    // The value is loaded through the ExecutionWorld's mapZigInstanceToJs function,
+    // just like a method return value. Therefore, if we've mapped this
+    // value before, we'll get the existing js.Global(js.Object) and if not
+    // we'll create it and track it for cleanup when the context ends.
+    pub fn getRemoteObject(
+        self: *const Session,
+        local: *const js.Local,
+        group: []const u8,
+        value: anytype,
+    ) !RemoteObject {
+        const js_val = try local.zigValueToJs(value, .{});
+
+        // We do not want to expose this as a parameter for now
+        const generate_preview = false;
+        return self.wrapObject(
+            local.isolate.handle,
+            local.handle,
+            js_val.handle,
+            group,
+            generate_preview,
+        );
+    }
+
+    fn wrapObject(
+        self: Session,
+        isolate: *v8.Isolate,
+        ctx: *const v8.Context,
+        val: *const v8.Value,
+        grpname: []const u8,
+        generatepreview: bool,
+    ) !RemoteObject {
+        const remote_object = v8.v8_inspector__Session__wrapObject(
+            self.handle,
+            isolate,
+            ctx,
+            val,
+            grpname.ptr,
+            grpname.len,
+            generatepreview,
+        ).?;
+        return .{ .handle = remote_object };
+    }
+
+    fn unwrapObject(
+        self: Session,
+        allocator: Allocator,
+        object_id: []const u8,
+    ) !UnwrappedObject {
+        const in_object_id = v8.CZigString{
+            .ptr = object_id.ptr,
+            .len = object_id.len,
+        };
+        var out_error: v8.CZigString = .{ .ptr = null, .len = 0 };
+        var out_value_handle: ?*v8.Value = null;
+        var out_context_handle: ?*v8.Context = null;
+        var out_object_group: v8.CZigString = .{ .ptr = null, .len = 0 };
+
+        const result = v8.v8_inspector__Session__unwrapObject(
+            self.handle,
+            &allocator,
+            &out_error,
+            in_object_id,
+            &out_value_handle,
+            &out_context_handle,
+            &out_object_group,
+        );
+
+        if (!result) {
+            const error_str = cZigStringToString(out_error) orelse return error.UnwrapFailed;
+            std.log.err("unwrapObject failed: {s}", .{error_str});
+            return error.UnwrapFailed;
+        }
+
+        return .{
+            .value = out_value_handle.?,
+            .context = out_context_handle.?,
+            .object_group = cZigStringToString(out_object_group),
+        };
+    }
+};
+
+const UnwrappedObject = struct {
+    value: *const v8.Value,
+    context: *const v8.Context,
+    object_group: ?[]const u8,
+};
+
+pub fn getTaggedOpaque(value: *const v8.Value) ?*TaggedOpaque {
+    if (!v8.v8__Value__IsObject(value)) {
+        return null;
+    }
+    const internal_field_count = v8.v8__Object__InternalFieldCount(value);
+    if (internal_field_count == 0) {
+        return null;
+    }
+
+    const tao_ptr = v8.v8__Object__GetAlignedPointerFromInternalField(value, 0).?;
+    return @ptrCast(@alignCast(tao_ptr));
+}
+
+fn cZigStringToString(s: v8.CZigString) ?[]const u8 {
+    if (s.ptr == null) return null;
+    return s.ptr[0..s.len];
+}
+
+// C export functions for Inspector callbacks
+pub export fn v8_inspector__Client__IMPL__generateUniqueId(
+    _: *v8.InspectorClientImpl,
+    data: *anyopaque,
+) callconv(.c) i64 {
+    const inspector: *Inspector = @ptrCast(@alignCast(data));
+    const unique_id = inspector.unique_id + 1;
+    inspector.unique_id = unique_id;
+    return unique_id;
+}
+
+pub export fn v8_inspector__Client__IMPL__runMessageLoopOnPause(
+    _: *v8.InspectorClientImpl,
+    data: *anyopaque,
+    context_group_id: c_int,
+) callconv(.c) void {
+    _ = data;
+    _ = context_group_id;
+}
+
+pub export fn v8_inspector__Client__IMPL__quitMessageLoopOnPause(
+    _: *v8.InspectorClientImpl,
+    data: *anyopaque,
+) callconv(.c) void {
+    _ = data;
+}
+
+pub export fn v8_inspector__Client__IMPL__runIfWaitingForDebugger(
+    _: *v8.InspectorClientImpl,
+    _: *anyopaque,
+    _: c_int,
+) callconv(.c) void {
+    // TODO
+}
+
+pub export fn v8_inspector__Client__IMPL__consoleAPIMessage(
+    _: *v8.InspectorClientImpl,
+    _: *anyopaque,
+    _: c_int,
+    _: v8.MessageErrorLevel,
+    _: *v8.StringView,
+    _: *v8.StringView,
+    _: c_uint,
+    _: c_uint,
+    _: *v8.StackTrace,
+) callconv(.c) void {}
+
+pub export fn v8_inspector__Client__IMPL__ensureDefaultContextInGroup(
+    _: *v8.InspectorClientImpl,
+    data: *anyopaque,
+) callconv(.c) ?*const v8.Context {
+    const inspector: *Inspector = @ptrCast(@alignCast(data));
+    const global_handle = inspector.default_context orelse return null;
+    return v8.v8__Global__Get(&global_handle, inspector.isolate);
+}
+
+pub export fn v8_inspector__Channel__IMPL__sendResponse(
+    _: *v8.InspectorChannelImpl,
+    data: *anyopaque,
+    call_id: c_int,
+    msg: [*c]u8,
+    length: usize,
+) callconv(.c) void {
+    const session: *Session = @ptrCast(@alignCast(data));
+    session.onResp(session.ctx, @intCast(call_id), msg[0..length]);
+}
+
+pub export fn v8_inspector__Channel__IMPL__sendNotification(
+    _: *v8.InspectorChannelImpl,
+    data: *anyopaque,
+    msg: [*c]u8,
+    length: usize,
+) callconv(.c) void {
+    const session: *Session = @ptrCast(@alignCast(data));
+    session.onNotif(session.ctx, msg[0..length]);
+}
+
+pub export fn v8_inspector__Channel__IMPL__flushProtocolNotifications(
+    _: *v8.InspectorChannelImpl,
+    _: *anyopaque,
+) callconv(.c) void {
+    // TODO
+}

src/browser/js/Integer.zig

@@ -0,0 +1,35 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const js = @import("js.zig");
+
+const v8 = js.v8;
+
+const Integer = @This();
+
+handle: *const v8.Integer,
+
+pub fn init(isolate: *v8.Isolate, value: anytype) Integer {
+    const handle = switch (@TypeOf(value)) {
+        i8, i16, i32 => v8.v8__Integer__New(isolate, value).?,
+        u8, u16, u32 => v8.v8__Integer__NewFromUnsigned(isolate, value).?,
+        else => |T| @compileError("cannot create v8::Integer from: " ++ @typeName(T)),
+    };
+    return .{ .handle = handle };
+}

src/browser/js/Isolate.zig

@@ -0,0 +1,131 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const js = @import("js.zig");
+const v8 = js.v8;
+
+const Isolate = @This();
+
+handle: *v8.Isolate,
+
+pub fn init(params: *v8.CreateParams) Isolate {
+    return .{
+        .handle = v8.v8__Isolate__New(params).?,
+    };
+}
+
+pub fn deinit(self: Isolate) void {
+    v8.v8__Isolate__Dispose(self.handle);
+}
+
+pub fn enter(self: Isolate) void {
+    v8.v8__Isolate__Enter(self.handle);
+}
+
+pub fn exit(self: Isolate) void {
+    v8.v8__Isolate__Exit(self.handle);
+}
+
+pub fn lowMemoryNotification(self: Isolate) void {
+    v8.v8__Isolate__LowMemoryNotification(self.handle);
+}
+
+pub const MemoryPressureLevel = enum(u32) {
+    none = v8.kNone,
+    moderate = v8.kModerate,
+    critical = v8.kCritical,
+};
+
+pub fn memoryPressureNotification(self: Isolate, level: MemoryPressureLevel) void {
+    v8.v8__Isolate__MemoryPressureNotification(self.handle, @intFromEnum(level));
+}
+
+pub fn notifyContextDisposed(self: Isolate) void {
+    _ = v8.v8__Isolate__ContextDisposedNotification(self.handle);
+}
+
+pub fn getHeapStatistics(self: Isolate) v8.HeapStatistics {
+    var res: v8.HeapStatistics = undefined;
+    v8.v8__Isolate__GetHeapStatistics(self.handle, &res);
+    return res;
+}
+
+pub fn throwException(self: Isolate, value: *const v8.Value) *const v8.Value {
+    return v8.v8__Isolate__ThrowException(self.handle, value).?;
+}
+
+pub fn initStringHandle(self: Isolate, str: []const u8) *const v8.String {
+    return v8.v8__String__NewFromUtf8(self.handle, str.ptr, v8.kNormal, @as(c_int, @intCast(str.len))).?;
+}
+
+pub fn createError(self: Isolate, msg: []const u8) *const v8.Value {
+    const message = self.initStringHandle(msg);
+    return v8.v8__Exception__Error(message).?;
+}
+
+pub fn createRangeError(self: Isolate, msg: []const u8) *const v8.Value {
+    const message = self.initStringHandle(msg);
+    return v8.v8__Exception__RangeError(message).?;
+}
+
+pub fn createReferenceError(self: Isolate, msg: []const u8) *const v8.Value {
+    const message = self.initStringHandle(msg);
+    return v8.v8__Exception__ReferenceError(message).?;
+}
+
+pub fn createSyntaxError(self: Isolate, msg: []const u8) *const v8.Value {
+    const message = self.initStringHandle(msg);
+    return v8.v8__Exception__SyntaxError(message).?;
+}
+
+pub fn createTypeError(self: Isolate, msg: []const u8) *const v8.Value {
+    const message = self.initStringHandle(msg);
+    return v8.v8__Exception__TypeError(message).?;
+}
+
+pub fn initNull(self: Isolate) *const v8.Value {
+    return v8.v8__Null(self.handle).?;
+}
+
+pub fn initUndefined(self: Isolate) *const v8.Value {
+    return v8.v8__Undefined(self.handle).?;
+}
+
+pub fn initFalse(self: Isolate) *const v8.Value {
+    return v8.v8__False(self.handle).?;
+}
+
+pub fn initTrue(self: Isolate) *const v8.Value {
+    return v8.v8__True(self.handle).?;
+}
+
+pub fn initInteger(self: Isolate, val: anytype) js.Integer {
+    return js.Integer.init(self.handle, val);
+}
+
+pub fn initBigInt(self: Isolate, val: anytype) js.BigInt {
+    return js.BigInt.init(self.handle, val);
+}
+
+pub fn initNumber(self: Isolate, val: anytype) js.Number {
+    return js.Number.init(self.handle, val);
+}
+
+pub fn createExternal(self: Isolate, val: *anyopaque) *const v8.External {
+    return v8.v8__External__New(self.handle, val).?;
+}

src/browser/js/Module.zig

@@ -0,0 +1,137 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const js = @import("js.zig");
+const v8 = js.v8;
+
+const Module = @This();
+
+local: *const js.Local,
+handle: *const v8.Module,
+
+pub const Status = enum(u32) {
+    kUninstantiated = v8.kUninstantiated,
+    kInstantiating = v8.kInstantiating,
+    kInstantiated = v8.kInstantiated,
+    kEvaluating = v8.kEvaluating,
+    kEvaluated = v8.kEvaluated,
+    kErrored = v8.kErrored,
+};
+
+pub fn getStatus(self: Module) Status {
+    return @enumFromInt(v8.v8__Module__GetStatus(self.handle));
+}
+
+pub fn getException(self: Module) js.Value {
+    return .{
+        .local = self.local,
+        .handle = v8.v8__Module__GetException(self.handle).?,
+    };
+}
+
+pub fn getModuleRequests(self: Module) Requests {
+    return .{
+        .context_handle = self.local.handle,
+        .handle = v8.v8__Module__GetModuleRequests(self.handle).?,
+    };
+}
+
+pub fn instantiate(self: Module, cb: v8.ResolveModuleCallback) !bool {
+    var out: v8.MaybeBool = undefined;
+    v8.v8__Module__InstantiateModule(self.handle, self.local.handle, cb, &out);
+    if (out.has_value) {
+        return out.value;
+    }
+    return error.JsException;
+}
+
+pub fn evaluate(self: Module) !js.Value {
+    const res = v8.v8__Module__Evaluate(self.handle, self.local.handle) orelse return error.JsException;
+
+    if (self.getStatus() == .kErrored) {
+        return error.JsException;
+    }
+
+    return .{
+        .local = self.local,
+        .handle = res,
+    };
+}
+
+pub fn getIdentityHash(self: Module) u32 {
+    return @bitCast(v8.v8__Module__GetIdentityHash(self.handle));
+}
+
+pub fn getModuleNamespace(self: Module) js.Value {
+    return .{
+        .local = self.local,
+        .handle = v8.v8__Module__GetModuleNamespace(self.handle).?,
+    };
+}
+
+pub fn getScriptId(self: Module) u32 {
+    return @intCast(v8.v8__Module__ScriptId(self.handle));
+}
+
+pub fn persist(self: Module) !Global {
+    var ctx = self.local.ctx;
+    var global: v8.Global = undefined;
+    v8.v8__Global__New(ctx.isolate.handle, self.handle, &global);
+    try ctx.global_modules.append(ctx.arena, global);
+    return .{ .handle = global };
+}
+
+pub const Global = struct {
+    handle: v8.Global,
+
+    pub fn deinit(self: *Global) void {
+        v8.v8__Global__Reset(&self.handle);
+    }
+
+    pub fn local(self: *const Global, l: *const js.Local) Module {
+        return .{
+            .local = l,
+            .handle = @ptrCast(v8.v8__Global__Get(&self.handle, l.isolate.handle)),
+        };
+    }
+
+    pub fn isEqual(self: *const Global, other: Module) bool {
+        return v8.v8__Global__IsEqual(&self.handle, other.handle);
+    }
+};
+
+const Requests = struct {
+    handle: *const v8.FixedArray,
+    context_handle: *const v8.Context,
+
+    pub fn len(self: Requests) usize {
+        return @intCast(v8.v8__FixedArray__Length(self.handle));
+    }
+
+    pub fn get(self: Requests, idx: usize) Request {
+        return .{ .handle = v8.v8__FixedArray__Get(self.handle, self.context_handle, @intCast(idx)).? };
+    }
+};
+
+const Request = struct {
+    handle: *const v8.ModuleRequest,
+
+    pub fn specifier(self: Request, local: *const js.Local) js.String {
+        return .{ .local = local, .handle = v8.v8__ModuleRequest__GetSpecifier(self.handle).? };
+    }
+};

src/browser/js/Number.zig

@@ -0,0 +1,31 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const js = @import("js.zig");
+
+const v8 = js.v8;
+
+const Number = @This();
+
+handle: *const v8.Number,
+
+pub fn init(isolate: *v8.Isolate, value: anytype) Number {
+    const handle = v8.v8__Number__New(isolate, value).?;
+    return .{ .handle = handle };
+}

src/browser/js/Object.zig

@@ -0,0 +1,209 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const js = @import("js.zig");
+const v8 = js.v8;
+
+const IS_DEBUG = @import("builtin").mode == .Debug;
+
+const Object = @This();
+
+local: *const js.Local,
+handle: *const v8.Object,
+
+pub fn has(self: Object, key: anytype) bool {
+    const ctx = self.local.ctx;
+    const key_handle = if (@TypeOf(key) == *const v8.String) key else ctx.isolate.initStringHandle(key);
+
+    var out: v8.MaybeBool = undefined;
+    v8.v8__Object__Has(self.handle, self.local.handle, key_handle, &out);
+    if (out.has_value) {
+        return out.value;
+    }
+    return false;
+}
+
+pub fn get(self: Object, key: anytype) !js.Value {
+    const ctx = self.local.ctx;
+
+    const key_handle = if (@TypeOf(key) == *const v8.String) key else ctx.isolate.initStringHandle(key);
+    const js_val_handle = v8.v8__Object__Get(self.handle, self.local.handle, key_handle) orelse return error.JsException;
+
+    return .{
+        .local = self.local,
+        .handle = js_val_handle,
+    };
+}
+
+pub fn set(self: Object, key: anytype, value: anytype, comptime opts: js.Caller.CallOpts) !bool {
+    const ctx = self.local.ctx;
+
+    const js_value = try self.local.zigValueToJs(value, opts);
+    const key_handle = if (@TypeOf(key) == *const v8.String) key else ctx.isolate.initStringHandle(key);
+
+    var out: v8.MaybeBool = undefined;
+    v8.v8__Object__Set(self.handle, self.local.handle, key_handle, js_value.handle, &out);
+    return out.has_value;
+}
+
+pub fn defineOwnProperty(self: Object, name: []const u8, value: js.Value, attr: v8.PropertyAttribute) ?bool {
+    const ctx = self.local.ctx;
+    const name_handle = ctx.isolate.initStringHandle(name);
+
+    var out: v8.MaybeBool = undefined;
+    v8.v8__Object__DefineOwnProperty(self.handle, self.local.handle, @ptrCast(name_handle), value.handle, attr, &out);
+
+    if (out.has_value) {
+        return out.value;
+    } else {
+        return null;
+    }
+}
+
+pub fn toValue(self: Object) js.Value {
+    return .{
+        .local = self.local,
+        .handle = @ptrCast(self.handle),
+    };
+}
+
+pub fn format(self: Object, writer: *std.Io.Writer) !void {
+    if (comptime IS_DEBUG) {
+        return self.local.ctx.debugValue(self.toValue(), writer);
+    }
+    const str = self.toString() catch return error.WriteFailed;
+    return writer.writeAll(str);
+}
+
+pub fn persist(self: Object) !Global {
+    var ctx = self.local.ctx;
+
+    var global: v8.Global = undefined;
+    v8.v8__Global__New(ctx.isolate.handle, self.handle, &global);
+
+    try ctx.trackGlobal(global);
+
+    return .{ .handle = global };
+}
+
+pub fn getFunction(self: Object, name: []const u8) !?js.Function {
+    if (self.isNullOrUndefined()) {
+        return null;
+    }
+    const local = self.local;
+
+    const js_name = local.isolate.initStringHandle(name);
+    const js_val_handle = v8.v8__Object__Get(self.handle, local.handle, js_name) orelse return error.JsException;
+
+    if (v8.v8__Value__IsFunction(js_val_handle) == false) {
+        return null;
+    }
+    return .{
+        .local = local,
+        .handle = @ptrCast(js_val_handle),
+    };
+}
+
+pub fn callMethod(self: Object, comptime T: type, method_name: []const u8, args: anytype) !T {
+    const func = try self.getFunction(method_name) orelse return error.MethodNotFound;
+    return func.callWithThis(T, self, args);
+}
+
+pub fn isNullOrUndefined(self: Object) bool {
+    return v8.v8__Value__IsNullOrUndefined(@ptrCast(self.handle));
+}
+
+pub fn getOwnPropertyNames(self: Object) !js.Array {
+    const handle = v8.v8__Object__GetOwnPropertyNames(self.handle, self.local.handle) orelse {
+        // This is almost always a fatal error case. Either we're in some exception
+        // and things are messy, or we're shutting down, or someone has messed up
+        // the object (like some WPT tests do).
+        return error.TypeError;
+    };
+
+    return .{
+        .local = self.local,
+        .handle = handle,
+    };
+}
+
+pub fn getPropertyNames(self: Object) js.Array {
+    const handle = v8.v8__Object__GetPropertyNames(self.handle, self.local.handle).?;
+    return .{
+        .local = self.local,
+        .handle = handle,
+    };
+}
+
+pub fn nameIterator(self: Object) !NameIterator {
+    const handle = v8.v8__Object__GetPropertyNames(self.handle, self.local.handle) orelse {
+        // see getOwnPropertyNames above
+        return error.TypeError;
+    };
+    const count = v8.v8__Array__Length(handle);
+
+    return .{
+        .local = self.local,
+        .handle = handle,
+        .count = count,
+    };
+}
+
+pub fn toZig(self: Object, comptime T: type) !T {
+    const js_value = js.Value{ .local = self.local, .handle = @ptrCast(self.handle) };
+    return self.local.jsValueToZig(T, js_value);
+}
+
+pub const Global = struct {
+    handle: v8.Global,
+
+    pub fn deinit(self: *Global) void {
+        v8.v8__Global__Reset(&self.handle);
+    }
+
+    pub fn local(self: *const Global, l: *const js.Local) Object {
+        return .{
+            .local = l,
+            .handle = @ptrCast(v8.v8__Global__Get(&self.handle, l.isolate.handle)),
+        };
+    }
+
+    pub fn isEqual(self: *const Global, other: Object) bool {
+        return v8.v8__Global__IsEqual(&self.handle, other.handle);
+    }
+};
+
+pub const NameIterator = struct {
+    count: u32,
+    idx: u32 = 0,
+    local: *const js.Local,
+    handle: *const v8.Array,
+
+    pub fn next(self: *NameIterator) !?[]const u8 {
+        const idx = self.idx;
+        if (idx == self.count) {
+            return null;
+        }
+        self.idx += 1;
+
+        const local = self.local;
+        const js_val_handle = v8.v8__Object__GetIndex(@ptrCast(self.handle), local.handle, idx) orelse return error.JsException;
+        return try js.Value.toStringSlice(.{ .local = local, .handle = js_val_handle });
+    }
+};

src/browser/js/Origin.zig

@@ -0,0 +1,73 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+// Origin represents the security token for contexts within the same origin.
+// Multiple contexts (frames) from the same origin share a single Origin,
+// which provides the V8 SecurityToken that allows cross-context access.
+//
+// Note: Identity tracking (mapping Zig instances to v8::Objects) is managed
+// separately via js.Identity - Session has the main world Identity, and
+// IsolatedWorlds have their own Identity instances.
+
+const std = @import("std");
+const js = @import("js.zig");
+
+const App = @import("../../App.zig");
+
+const v8 = js.v8;
+const Allocator = std.mem.Allocator;
+
+const Origin = @This();
+
+rc: usize = 1,
+arena: Allocator,
+
+// The key, e.g. lightpanda.io:443
+key: []const u8,
+
+// Security token - all contexts in this origin must use the same v8::Value instance
+// as their security token for V8 to allow cross-context access
+security_token: v8.Global,
+
+pub fn init(app: *App, isolate: js.Isolate, key: []const u8) !*Origin {
+    const arena = try app.arena_pool.acquire(.{ .debug = "Origin" });
+    errdefer app.arena_pool.release(arena);
+
+    var hs: js.HandleScope = undefined;
+    hs.init(isolate);
+    defer hs.deinit();
+
+    const owned_key = try arena.dupe(u8, key);
+    const token_local = isolate.initStringHandle(owned_key);
+    var token_global: v8.Global = undefined;
+    v8.v8__Global__New(isolate.handle, token_local, &token_global);
+
+    const self = try arena.create(Origin);
+    self.* = .{
+        .rc = 1,
+        .arena = arena,
+        .key = owned_key,
+        .security_token = token_global,
+    };
+    return self;
+}
+
+pub fn deinit(self: *Origin, app: *App) void {
+    v8.v8__Global__Reset(&self.security_token);
+    app.arena_pool.release(self.arena);
+}

src/browser/js/Platform.zig

@@ -0,0 +1,41 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const js = @import("js.zig");
+const v8 = js.v8;
+
+const Platform = @This();
+handle: *v8.Platform,
+
+pub fn init() !Platform {
+    if (v8.v8__V8__InitializeICU() == false) {
+        return error.FailedToInitializeICU;
+    }
+    // 0 - threadpool size, 0 == let v8 decide
+    // 1 - idle_task_support, 1 == enabled
+    const handle = v8.v8__Platform__NewDefaultPlatform(0, 1).?;
+    v8.v8__V8__InitializePlatform(handle);
+    v8.v8__V8__Initialize();
+    return .{ .handle = handle };
+}
+
+pub fn deinit(self: Platform) void {
+    _ = v8.v8__V8__Dispose();
+    v8.v8__V8__DisposePlatform();
+    v8.v8__Platform__DELETE(self.handle);
+}

src/browser/js/Private.zig

@@ -0,0 +1,42 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const js = @import("js.zig");
+const v8 = js.v8;
+
+const Private = @This();
+
+// Unlike most types, we always store the Private as a Global. It makes more
+// sense for this type given how it's used.
+handle: v8.Global,
+
+pub fn init(isolate: *v8.Isolate, name: []const u8) Private {
+    const v8_name = v8.v8__String__NewFromUtf8(isolate, name.ptr, v8.kNormal, @intCast(name.len));
+    const private_handle = v8.v8__Private__New(isolate, v8_name);
+
+    var global: v8.Global = undefined;
+    v8.v8__Global__New(isolate, private_handle, &global);
+
+    return .{
+        .handle = global,
+    };
+}
+
+pub fn deinit(self: *Private) void {
+    v8.v8__Global__Reset(&self.handle);
+}

src/browser/js/Promise.zig

@@ -0,0 +1,108 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const js = @import("js.zig");
+const v8 = js.v8;
+
+const Session = @import("../Session.zig");
+
+const Promise = @This();
+
+local: *const js.Local,
+handle: *const v8.Promise,
+
+pub fn toObject(self: Promise) js.Object {
+    return .{
+        .local = self.local,
+        .handle = @ptrCast(self.handle),
+    };
+}
+
+pub fn toValue(self: Promise) js.Value {
+    return .{
+        .local = self.local,
+        .handle = @ptrCast(self.handle),
+    };
+}
+
+pub fn thenAndCatch(self: Promise, on_fulfilled: js.Function, on_rejected: js.Function) !Promise {
+    if (v8.v8__Promise__Then2(self.handle, self.local.handle, on_fulfilled.handle, on_rejected.handle)) |handle| {
+        return .{
+            .local = self.local,
+            .handle = handle,
+        };
+    }
+    return error.PromiseChainFailed;
+}
+
+pub fn persist(self: Promise) !Global {
+    return self._persist(true);
+}
+
+pub fn temp(self: Promise) !Temp {
+    return self._persist(false);
+}
+
+fn _persist(self: *const Promise, comptime is_global: bool) !(if (is_global) Global else Temp) {
+    var ctx = self.local.ctx;
+
+    var global: v8.Global = undefined;
+    v8.v8__Global__New(ctx.isolate.handle, self.handle, &global);
+    if (comptime is_global) {
+        try ctx.trackGlobal(global);
+        return .{ .handle = global, .temps = {} };
+    }
+    try ctx.trackTemp(global);
+    return .{ .handle = global, .temps = &ctx.identity.temps };
+}
+
+pub const Temp = G(.temp);
+pub const Global = G(.global);
+
+const GlobalType = enum(u8) {
+    temp,
+    global,
+};
+
+fn G(comptime global_type: GlobalType) type {
+    return struct {
+        handle: v8.Global,
+        temps: if (global_type == .temp) *std.AutoHashMapUnmanaged(usize, v8.Global) else void,
+
+        const Self = @This();
+
+        pub fn deinit(self: *Self) void {
+            v8.v8__Global__Reset(&self.handle);
+        }
+
+        pub fn local(self: *const Self, l: *const js.Local) Promise {
+            return .{
+                .local = l,
+                .handle = @ptrCast(v8.v8__Global__Get(&self.handle, l.isolate.handle)),
+            };
+        }
+
+        pub fn release(self: *const Self) void {
+            if (self.temps.fetchRemove(self.handle.data_ptr)) |kv| {
+                var g = kv.value;
+                v8.v8__Global__Reset(&g);
+            }
+        }
+    };
+}

src/browser/js/PromiseRejection.zig

@@ -0,0 +1,41 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const js = @import("js.zig");
+const v8 = js.v8;
+
+const PromiseRejection = @This();
+
+local: *const js.Local,
+handle: *const v8.PromiseRejectMessage,
+
+pub fn promise(self: PromiseRejection) js.Promise {
+    return .{
+        .local = self.local,
+        .handle = v8.v8__PromiseRejectMessage__GetPromise(self.handle).?,
+    };
+}
+
+pub fn reason(self: PromiseRejection) ?js.Value {
+    const value_handle = v8.v8__PromiseRejectMessage__GetValue(self.handle) orelse return null;
+
+    return .{
+        .local = self.local,
+        .handle = value_handle,
+    };
+}

src/browser/js/PromiseResolver.zig

@@ -0,0 +1,139 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const js = @import("js.zig");
+const v8 = js.v8;
+
+const log = @import("../../log.zig");
+
+const DOMException = @import("../webapi/DOMException.zig");
+
+const PromiseResolver = @This();
+
+local: *const js.Local,
+handle: *const v8.PromiseResolver,
+
+pub fn init(local: *const js.Local) PromiseResolver {
+    return .{
+        .local = local,
+        .handle = v8.v8__Promise__Resolver__New(local.handle).?,
+    };
+}
+
+pub fn promise(self: PromiseResolver) js.Promise {
+    return .{
+        .local = self.local,
+        .handle = v8.v8__Promise__Resolver__GetPromise(self.handle).?,
+    };
+}
+
+pub fn resolve(self: PromiseResolver, comptime source: []const u8, value: anytype) void {
+    self._resolve(value) catch |err| {
+        log.err(.bug, "resolve", .{ .source = source, .err = err, .persistent = false });
+    };
+}
+
+fn _resolve(self: PromiseResolver, value: anytype) !void {
+    const local = self.local;
+    const js_val = try local.zigValueToJs(value, .{});
+
+    var out: v8.MaybeBool = undefined;
+    v8.v8__Promise__Resolver__Resolve(self.handle, self.local.handle, js_val.handle, &out);
+    if (!out.has_value or !out.value) {
+        return error.FailedToResolvePromise;
+    }
+    local.runMicrotasks();
+}
+
+pub fn reject(self: PromiseResolver, comptime source: []const u8, value: anytype) void {
+    self._reject(value) catch |err| {
+        log.err(.bug, "reject", .{ .source = source, .err = err, .persistent = false });
+    };
+}
+
+pub const RejectError = union(enum) {
+    /// Not to be confused with `DOMException`; this is bare `Error`.
+    generic_error: []const u8,
+    range_error: []const u8,
+    reference_error: []const u8,
+    syntax_error: []const u8,
+    type_error: []const u8,
+    /// DOM exceptions are unknown to V8, belongs to web standards.
+    dom_exception: struct { err: anyerror },
+};
+
+/// Rejects the promise w/ an error object.
+pub fn rejectError(
+    self: PromiseResolver,
+    comptime source: []const u8,
+    err: RejectError,
+) void {
+    const handle = switch (err) {
+        .generic_error => |msg| self.local.isolate.createError(msg),
+        .range_error => |msg| self.local.isolate.createRangeError(msg),
+        .reference_error => |msg| self.local.isolate.createReferenceError(msg),
+        .syntax_error => |msg| self.local.isolate.createSyntaxError(msg),
+        .type_error => |msg| self.local.isolate.createTypeError(msg),
+        // "Exceptional".
+        .dom_exception => |exception| {
+            self._reject(DOMException.fromError(exception.err) orelse unreachable) catch |reject_err| {
+                log.err(.bug, "rejectDomException", .{ .source = source, .err = reject_err, .persistent = false });
+            };
+            return;
+        },
+    };
+
+    self._reject(js.Value{ .handle = handle, .local = self.local }) catch |reject_err| {
+        log.err(.bug, "rejectError", .{ .source = source, .err = reject_err, .persistent = false });
+    };
+}
+
+fn _reject(self: PromiseResolver, value: anytype) !void {
+    const local = self.local;
+    const js_val = try local.zigValueToJs(value, .{});
+
+    var out: v8.MaybeBool = undefined;
+    v8.v8__Promise__Resolver__Reject(self.handle, local.handle, js_val.handle, &out);
+    if (!out.has_value or !out.value) {
+        return error.FailedToRejectPromise;
+    }
+    local.runMicrotasks();
+}
+
+pub fn persist(self: PromiseResolver) !Global {
+    var ctx = self.local.ctx;
+    var global: v8.Global = undefined;
+    v8.v8__Global__New(ctx.isolate.handle, self.handle, &global);
+    try ctx.trackGlobal(global);
+    return .{ .handle = global };
+}
+
+pub const Global = struct {
+    handle: v8.Global,
+
+    pub fn deinit(self: *Global) void {
+        v8.v8__Global__Reset(&self.handle);
+    }
+
+    pub fn local(self: *const Global, l: *const js.Local) PromiseResolver {
+        return .{
+            .local = l,
+            .handle = @ptrCast(v8.v8__Global__Get(&self.handle, l.isolate.handle)),
+        };
+    }
+};

src/browser/js/Scheduler.zig

@@ -0,0 +1,152 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const builtin = @import("builtin");
+
+const log = @import("../../log.zig");
+const milliTimestamp = @import("../../datetime.zig").milliTimestamp;
+
+const IS_DEBUG = builtin.mode == .Debug;
+
+const Queue = std.PriorityQueue(Task, void, struct {
+    fn compare(_: void, a: Task, b: Task) std.math.Order {
+        const time_order = std.math.order(a.run_at, b.run_at);
+        if (time_order != .eq) return time_order;
+        // Break ties with sequence number to maintain FIFO order
+        return std.math.order(a.sequence, b.sequence);
+    }
+}.compare);
+
+const Scheduler = @This();
+
+_sequence: u64,
+low_priority: Queue,
+high_priority: Queue,
+
+pub fn init(allocator: std.mem.Allocator) Scheduler {
+    return .{
+        ._sequence = 0,
+        .low_priority = Queue.init(allocator, {}),
+        .high_priority = Queue.init(allocator, {}),
+    };
+}
+
+pub fn deinit(self: *Scheduler) void {
+    finalizeTasks(&self.low_priority);
+    finalizeTasks(&self.high_priority);
+}
+
+const AddOpts = struct {
+    name: []const u8 = "",
+    low_priority: bool = false,
+    finalizer: ?Finalizer = null,
+};
+pub fn add(self: *Scheduler, ctx: *anyopaque, cb: Callback, run_in_ms: u32, opts: AddOpts) !void {
+    if (comptime IS_DEBUG) {
+        log.debug(.scheduler, "scheduler.add", .{ .name = opts.name, .run_in_ms = run_in_ms, .low_priority = opts.low_priority });
+    }
+    var queue = if (opts.low_priority) &self.low_priority else &self.high_priority;
+    const seq = self._sequence + 1;
+    self._sequence = seq;
+    return queue.add(.{
+        .ctx = ctx,
+        .callback = cb,
+        .sequence = seq,
+        .name = opts.name,
+        .finalizer = opts.finalizer,
+        .run_at = milliTimestamp(.monotonic) + run_in_ms,
+    });
+}
+
+pub fn run(self: *Scheduler) !void {
+    const now = milliTimestamp(.monotonic);
+    try self.runQueue(&self.low_priority, now);
+    try self.runQueue(&self.high_priority, now);
+}
+
+pub fn hasReadyTasks(self: *Scheduler) bool {
+    const now = milliTimestamp(.monotonic);
+    return queueuHasReadyTask(&self.low_priority, now) or queueuHasReadyTask(&self.high_priority, now);
+}
+
+pub fn msToNextHigh(self: *Scheduler) ?u64 {
+    const task = self.high_priority.peek() orelse return null;
+    const now = milliTimestamp(.monotonic);
+    if (task.run_at <= now) {
+        return 0;
+    }
+    return @intCast(task.run_at - now);
+}
+
+fn runQueue(self: *Scheduler, queue: *Queue, now: u64) !void {
+    if (queue.count() == 0) {
+        return;
+    }
+
+    while (queue.peek()) |*task_| {
+        if (task_.run_at > now) {
+            return;
+        }
+        var task = queue.remove();
+        if (comptime IS_DEBUG) {
+            log.debug(.scheduler, "scheduler.runTask", .{ .name = task.name });
+        }
+
+        const repeat_in_ms = task.callback(task.ctx) catch |err| {
+            log.warn(.scheduler, "task.callback", .{ .name = task.name, .err = err });
+            continue;
+        };
+
+        if (repeat_in_ms) |ms| {
+            // Task cannot be repeated immediately, and they should know that
+            if (comptime IS_DEBUG) {
+                std.debug.assert(ms != 0);
+            }
+            task.run_at = now + ms;
+            try self.low_priority.add(task);
+        }
+    }
+    return;
+}
+
+fn queueuHasReadyTask(queue: *Queue, now: u64) bool {
+    const task = queue.peek() orelse return false;
+    return task.run_at <= now;
+}
+
+fn finalizeTasks(queue: *Queue) void {
+    var it = queue.iterator();
+    while (it.next()) |t| {
+        if (t.finalizer) |func| {
+            func(t.ctx);
+        }
+    }
+}
+
+const Task = struct {
+    run_at: u64,
+    sequence: u64,
+    ctx: *anyopaque,
+    name: []const u8,
+    callback: Callback,
+    finalizer: ?Finalizer,
+};
+
+const Callback = *const fn (ctx: *anyopaque) anyerror!?u32;
+const Finalizer = *const fn (ctx: *anyopaque) void;

src/browser/js/Snapshot.zig

@@ -0,0 +1,637 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const js = @import("js.zig");
+const bridge = @import("bridge.zig");
+const log = @import("../../log.zig");
+
+const IS_DEBUG = @import("builtin").mode == .Debug;
+
+const v8 = js.v8;
+const JsApis = bridge.JsApis;
+const Allocator = std.mem.Allocator;
+
+const Snapshot = @This();
+
+const embedded_snapshot_blob = if (@import("build_config").snapshot_path) |path| @embedFile(path) else "";
+
+// When creating our Snapshot, we use local function templates for every Zig type.
+// You cannot, from what I can tell, create persisted FunctionTemplates at
+// snapshot creation time. But you can embedd those templates (or any other v8
+// Data) so that it's available to contexts created from the snapshot. This is
+// the starting index of those function templates, which we can extract. At
+// creation time, in debug, we assert that this is actually a consecutive integer
+// sequence
+data_start: usize,
+
+// The snapshot data (v8.StartupData is a ptr to the data and len).
+startup_data: v8.StartupData,
+
+// V8 doesn't know how to serialize external references, and pretty much any hook
+// into Zig is an external reference (e.g. every accessor and function callback).
+// When we create the snapshot, we give it an array with the address of every
+// external reference. When we load the snapshot, we need to give it the same
+// array with the exact same number of entries in the same order (but, of course
+// cross-process, the value (address) might be different).
+external_references: [countExternalReferences()]isize,
+
+// Track whether this snapshot owns its data (was created in-process)
+// If false, the data points into embedded_snapshot_blob and will not be freed
+owns_data: bool = false,
+
+pub fn load() !Snapshot {
+    if (loadEmbedded()) |snapshot| {
+        return snapshot;
+    }
+    return create();
+}
+
+fn loadEmbedded() ?Snapshot {
+    // Binary format: [data_start: usize][blob data]
+    const min_size = @sizeOf(usize) + 1000;
+    if (embedded_snapshot_blob.len < min_size) {
+        // our blob should be in the MB, this is just a quick sanity check
+        return null;
+    }
+
+    const data_start = std.mem.readInt(usize, embedded_snapshot_blob[0..@sizeOf(usize)], .little);
+    const blob = embedded_snapshot_blob[@sizeOf(usize)..];
+
+    const startup_data = v8.StartupData{ .data = blob.ptr, .raw_size = @intCast(blob.len) };
+    if (!v8.v8__StartupData__IsValid(startup_data)) {
+        return null;
+    }
+
+    return .{
+        .owns_data = false,
+        .data_start = data_start,
+        .startup_data = startup_data,
+        .external_references = collectExternalReferences(),
+    };
+}
+
+pub fn deinit(self: Snapshot) void {
+    // Only free if we own the data (was created in-process)
+    if (self.owns_data) {
+        // V8 allocated this with `new char[]`, so we need to use the C++ delete[] operator
+        v8.v8__StartupData__DELETE(self.startup_data.data);
+    }
+}
+
+pub fn write(self: Snapshot, writer: *std.Io.Writer) !void {
+    if (!self.isValid()) {
+        return error.InvalidSnapshot;
+    }
+
+    try writer.writeInt(usize, self.data_start, .little);
+    try writer.writeAll(self.startup_data.data[0..@intCast(self.startup_data.raw_size)]);
+}
+
+pub fn fromEmbedded(self: Snapshot) bool {
+    // if the snapshot comes from the embedFile, then it'll be flagged as not
+    // owning (aka, not needing to free) the data.
+    return self.owns_data == false;
+}
+
+fn isValid(self: Snapshot) bool {
+    return v8.v8__StartupData__IsValid(self.startup_data);
+}
+
+pub fn create() !Snapshot {
+    var external_references = collectExternalReferences();
+
+    var params: v8.CreateParams = undefined;
+    v8.v8__Isolate__CreateParams__CONSTRUCT(&params);
+    params.array_buffer_allocator = v8.v8__ArrayBuffer__Allocator__NewDefaultAllocator();
+    defer v8.v8__ArrayBuffer__Allocator__DELETE(params.array_buffer_allocator.?);
+    params.external_references = @ptrCast(&external_references);
+
+    const snapshot_creator = v8.v8__SnapshotCreator__CREATE(&params);
+    defer v8.v8__SnapshotCreator__DESTRUCT(snapshot_creator);
+
+    var data_start: usize = 0;
+    const isolate = v8.v8__SnapshotCreator__getIsolate(snapshot_creator).?;
+
+    {
+        // CreateBlob, which we'll call once everything is setup, MUST NOT
+        // be called from an active HandleScope. Hence we have this scope to
+        // clean it up before we call CreateBlob
+        var handle_scope: v8.HandleScope = undefined;
+        v8.v8__HandleScope__CONSTRUCT(&handle_scope, isolate);
+        defer v8.v8__HandleScope__DESTRUCT(&handle_scope);
+
+        // Create templates (constructors only) FIRST
+        var templates: [JsApis.len]*v8.FunctionTemplate = undefined;
+        inline for (JsApis, 0..) |JsApi, i| {
+            @setEvalBranchQuota(10_000);
+            templates[i] = generateConstructor(JsApi, isolate);
+            attachClass(JsApi, isolate, templates[i]);
+        }
+
+        // Set up prototype chains BEFORE attaching properties
+        // This must come before attachClass so inheritance is set up first
+        inline for (JsApis, 0..) |JsApi, i| {
+            if (comptime protoIndexLookup(JsApi)) |proto_index| {
+                v8.v8__FunctionTemplate__Inherit(templates[i], templates[proto_index]);
+            }
+        }
+
+        // Set up the global template to inherit from Window's template
+        // This way the global object gets all Window properties through inheritance
+        const context = v8.v8__Context__New(isolate, null, null);
+        v8.v8__Context__Enter(context);
+        defer v8.v8__Context__Exit(context);
+
+        // Add templates to context snapshot
+        var last_data_index: usize = 0;
+        inline for (JsApis, 0..) |_, i| {
+            @setEvalBranchQuota(10_000);
+            const data_index = v8.v8__SnapshotCreator__AddData(snapshot_creator, @ptrCast(templates[i]));
+            if (i == 0) {
+                data_start = data_index;
+                last_data_index = data_index;
+            } else {
+                // This isn't strictly required, but it means we only need to keep
+                // the first data_index. This is based on the assumption that
+                // addDataWithContext always increases by 1. If we ever hit this
+                // error, then that assumption is wrong and we should capture
+                // all the indexes explicitly in an array.
+                if (data_index != last_data_index + 1) {
+                    return error.InvalidDataIndex;
+                }
+                last_data_index = data_index;
+            }
+        }
+
+        // Realize all templates by getting their functions and attaching to global
+        const global_obj = v8.v8__Context__Global(context);
+
+        inline for (JsApis, 0..) |JsApi, i| {
+            const func = v8.v8__FunctionTemplate__GetFunction(templates[i], context);
+
+            // Attach to global if it has a name
+            if (@hasDecl(JsApi.Meta, "name")) {
+                if (@hasDecl(JsApi.Meta, "constructor_alias")) {
+                    const alias = JsApi.Meta.constructor_alias;
+                    const v8_class_name = v8.v8__String__NewFromUtf8(isolate, alias.ptr, v8.kNormal, @intCast(alias.len));
+                    var maybe_result: v8.MaybeBool = undefined;
+                    v8.v8__Object__Set(global_obj, context, v8_class_name, func, &maybe_result);
+
+                    // @TODO: This is wrong. This name should be registered with the
+                    // illegalConstructorCallback. I.e. new Image() is OK, but
+                    // new HTMLImageElement() isn't.
+                    // But we _have_ to register the name, i.e. HTMLImageElement
+                    // has to be registered so, for now, instead of creating another
+                    // template, we just hook it into the constructor.
+                    const name = JsApi.Meta.name;
+                    const illegal_class_name = v8.v8__String__NewFromUtf8(isolate, name.ptr, v8.kNormal, @intCast(name.len));
+                    var maybe_result2: v8.MaybeBool = undefined;
+                    v8.v8__Object__DefineOwnProperty(global_obj, context, illegal_class_name, func, 0, &maybe_result2);
+                } else {
+                    const name = JsApi.Meta.name;
+                    const v8_class_name = v8.v8__String__NewFromUtf8(isolate, name.ptr, v8.kNormal, @intCast(name.len));
+                    var maybe_result: v8.MaybeBool = undefined;
+                    var properties: v8.PropertyAttribute = v8.None;
+                    if (@hasDecl(JsApi.Meta, "enumerable") and JsApi.Meta.enumerable == false) {
+                        properties |= v8.DontEnum;
+                    }
+                    v8.v8__Object__DefineOwnProperty(global_obj, context, v8_class_name, func, properties, &maybe_result);
+                }
+            }
+        }
+
+        {
+            // If we want to overwrite the built-in console, we have to
+            // delete the built-in one.
+            const console_key = v8.v8__String__NewFromUtf8(isolate, "console", v8.kNormal, 7);
+            var maybe_deleted: v8.MaybeBool = undefined;
+            v8.v8__Object__Delete(global_obj, context, console_key, &maybe_deleted);
+            if (maybe_deleted.value == false) {
+                return error.ConsoleDeleteError;
+            }
+        }
+
+        // This shouldn't be necessary, but it is:
+        // https://groups.google.com/g/v8-users/c/qAQQBmbi--8
+        // TODO: see if newer V8 engines have a way around this.
+        inline for (JsApis, 0..) |JsApi, i| {
+            if (comptime protoIndexLookup(JsApi)) |proto_index| {
+                const proto_func = v8.v8__FunctionTemplate__GetFunction(templates[proto_index], context);
+                const proto_obj: *const v8.Object = @ptrCast(proto_func);
+
+                const self_func = v8.v8__FunctionTemplate__GetFunction(templates[i], context);
+                const self_obj: *const v8.Object = @ptrCast(self_func);
+
+                var maybe_result: v8.MaybeBool = undefined;
+                v8.v8__Object__SetPrototype(self_obj, context, proto_obj, &maybe_result);
+            }
+        }
+
+        {
+            // Custom exception
+            // TODO: this is an horrible hack, I can't figure out how to do this cleanly.
+            const code_str = "DOMException.prototype.__proto__ = Error.prototype";
+            const code = v8.v8__String__NewFromUtf8(isolate, code_str.ptr, v8.kNormal, @intCast(code_str.len));
+            const script = v8.v8__Script__Compile(context, code, null) orelse return error.ScriptCompileFailed;
+            _ = v8.v8__Script__Run(script, context) orelse return error.ScriptRunFailed;
+        }
+
+        v8.v8__SnapshotCreator__setDefaultContext(snapshot_creator, context);
+    }
+
+    const blob = v8.v8__SnapshotCreator__createBlob(snapshot_creator, v8.kKeep);
+
+    return .{
+        .owns_data = true,
+        .data_start = data_start,
+        .external_references = external_references,
+        .startup_data = blob,
+    };
+}
+
+// Helper to check if a JsApi has a NamedIndexed handler
+fn hasNamedIndexedGetter(comptime JsApi: type) bool {
+    const declarations = @typeInfo(JsApi).@"struct".decls;
+    inline for (declarations) |d| {
+        const value = @field(JsApi, d.name);
+        const T = @TypeOf(value);
+        if (T == bridge.NamedIndexed) {
+            return true;
+        }
+    }
+    return false;
+}
+
+// Count total callbacks needed for external_references array
+fn countExternalReferences() comptime_int {
+    @setEvalBranchQuota(100_000);
+
+    var count: comptime_int = 0;
+
+    // +1 for the illegal constructor callback shared by various types
+    count += 1;
+
+    // +1 for the noop function shared by various types
+    count += 1;
+
+    inline for (JsApis) |JsApi| {
+        // Constructor (only if explicit)
+        if (@hasDecl(JsApi, "constructor")) {
+            count += 1;
+        }
+
+        // Callable (htmldda)
+        if (@hasDecl(JsApi, "callable")) {
+            count += 1;
+        }
+
+        // All other callbacks
+        const declarations = @typeInfo(JsApi).@"struct".decls;
+        inline for (declarations) |d| {
+            const value = @field(JsApi, d.name);
+            const T = @TypeOf(value);
+            if (T == bridge.Accessor) {
+                count += 1; // getter
+                if (value.setter != null) {
+                    count += 1;
+                }
+            } else if (T == bridge.Function) {
+                count += 1;
+            } else if (T == bridge.Iterator) {
+                count += 1;
+            } else if (T == bridge.Indexed) {
+                count += 1;
+                if (value.enumerator != null) {
+                    count += 1;
+                }
+            } else if (T == bridge.NamedIndexed) {
+                count += 1; // getter
+                if (value.setter != null) count += 1;
+                if (value.deleter != null) count += 1;
+            }
+        }
+    }
+
+    // In debug mode, add unknown property callbacks for types without NamedIndexed
+    if (comptime IS_DEBUG) {
+        inline for (JsApis) |JsApi| {
+            if (!hasNamedIndexedGetter(JsApi)) {
+                count += 1;
+            }
+        }
+    }
+
+    return count + 1; // +1 for null terminator
+}
+
+fn collectExternalReferences() [countExternalReferences()]isize {
+    var idx: usize = 0;
+    var references = std.mem.zeroes([countExternalReferences()]isize);
+
+    references[idx] = @bitCast(@intFromPtr(&illegalConstructorCallback));
+    idx += 1;
+
+    references[idx] = @bitCast(@intFromPtr(&bridge.Function.noopFunction));
+    idx += 1;
+
+    inline for (JsApis) |JsApi| {
+        if (@hasDecl(JsApi, "constructor")) {
+            references[idx] = @bitCast(@intFromPtr(JsApi.constructor.func));
+            idx += 1;
+        }
+
+        if (@hasDecl(JsApi, "callable")) {
+            references[idx] = @bitCast(@intFromPtr(JsApi.callable.func));
+            idx += 1;
+        }
+
+        const declarations = @typeInfo(JsApi).@"struct".decls;
+        inline for (declarations) |d| {
+            const value = @field(JsApi, d.name);
+            const T = @TypeOf(value);
+            if (T == bridge.Accessor) {
+                references[idx] = @bitCast(@intFromPtr(value.getter));
+                idx += 1;
+                if (value.setter) |setter| {
+                    references[idx] = @bitCast(@intFromPtr(setter));
+                    idx += 1;
+                }
+            } else if (T == bridge.Function) {
+                references[idx] = @bitCast(@intFromPtr(value.func));
+                idx += 1;
+            } else if (T == bridge.Iterator) {
+                references[idx] = @bitCast(@intFromPtr(value.func));
+                idx += 1;
+            } else if (T == bridge.Indexed) {
+                references[idx] = @bitCast(@intFromPtr(value.getter));
+                idx += 1;
+                if (value.enumerator) |enumerator| {
+                    references[idx] = @bitCast(@intFromPtr(enumerator));
+                    idx += 1;
+                }
+            } else if (T == bridge.NamedIndexed) {
+                references[idx] = @bitCast(@intFromPtr(value.getter));
+                idx += 1;
+                if (value.setter) |setter| {
+                    references[idx] = @bitCast(@intFromPtr(setter));
+                    idx += 1;
+                }
+                if (value.deleter) |deleter| {
+                    references[idx] = @bitCast(@intFromPtr(deleter));
+                    idx += 1;
+                }
+            }
+        }
+    }
+
+    // In debug mode, collect unknown property callbacks for types without NamedIndexed
+    if (comptime IS_DEBUG) {
+        inline for (JsApis) |JsApi| {
+            if (!hasNamedIndexedGetter(JsApi)) {
+                references[idx] = @bitCast(@intFromPtr(bridge.unknownObjectPropertyCallback(JsApi)));
+                idx += 1;
+            }
+        }
+    }
+
+    return references;
+}
+
+// Even if a struct doesn't have a `constructor` function, we still
+// `generateConstructor`, because this is how we create our
+// FunctionTemplate. Such classes exist, but they can't be instantiated
+// via `new ClassName()` - but they could, for example, be created in
+// Zig and returned from a function call, which is why we need the
+// FunctionTemplate.
+fn generateConstructor(comptime JsApi: type, isolate: *v8.Isolate) *v8.FunctionTemplate {
+    const callback = blk: {
+        if (@hasDecl(JsApi, "constructor")) {
+            break :blk JsApi.constructor.func;
+        }
+
+        // Use shared illegal constructor callback
+        break :blk illegalConstructorCallback;
+    };
+
+    const template = @constCast(v8.v8__FunctionTemplate__New__DEFAULT2(isolate, callback).?);
+    {
+        const internal_field_count = comptime countInternalFields(JsApi);
+        if (internal_field_count > 0) {
+            const instance_template = v8.v8__FunctionTemplate__InstanceTemplate(template);
+            v8.v8__ObjectTemplate__SetInternalFieldCount(instance_template, internal_field_count);
+        }
+    }
+    const name_str = if (@hasDecl(JsApi.Meta, "name")) JsApi.Meta.name else @typeName(JsApi);
+    const class_name = v8.v8__String__NewFromUtf8(isolate, name_str.ptr, v8.kNormal, @intCast(name_str.len));
+    v8.v8__FunctionTemplate__SetClassName(template, class_name);
+    return template;
+}
+
+pub fn countInternalFields(comptime JsApi: type) u8 {
+    var last_used_id = 0;
+    var cache_count: u8 = 0;
+
+    inline for (@typeInfo(JsApi).@"struct".decls) |d| {
+        const name: [:0]const u8 = d.name;
+        const value = @field(JsApi, name);
+        const definition = @TypeOf(value);
+
+        switch (definition) {
+            inline bridge.Accessor, bridge.Function => {
+                const cache = value.cache orelse continue;
+                if (cache != .internal) {
+                    continue;
+                }
+                // We assert that they are declared in-order. This isn't necessary
+                // but I don't want to do anything fancy to look for gaps or
+                // duplicates.
+                const internal_id = cache.internal;
+                if (internal_id != last_used_id + 1) {
+                    @compileError(@typeName(JsApi) ++ "." ++ name ++ " has a non-monotonic cache index");
+                }
+                last_used_id = internal_id;
+                cache_count += 1; // this is just last_used, but it's more explicit this way
+            },
+            else => {},
+        }
+    }
+
+    if (@hasDecl(JsApi.Meta, "empty_with_no_proto")) {
+        return cache_count;
+    }
+
+    // we need cache_count internal fields, + 1 for the TAO pointer (the v8 -> Zig)
+    // mapping) itself.
+    return cache_count + 1;
+}
+
+// Attaches JsApi members to the prototype template (normal case)
+fn attachClass(comptime JsApi: type, isolate: *v8.Isolate, template: *v8.FunctionTemplate) void {
+    const instance = v8.v8__FunctionTemplate__InstanceTemplate(template);
+    const prototype = v8.v8__FunctionTemplate__PrototypeTemplate(template);
+
+    const declarations = @typeInfo(JsApi).@"struct".decls;
+    var has_named_index_getter = false;
+
+    inline for (declarations) |d| {
+        const name: [:0]const u8 = d.name;
+        const value = @field(JsApi, name);
+        const definition = @TypeOf(value);
+
+        switch (definition) {
+            bridge.Accessor => {
+                const js_name = v8.v8__String__NewFromUtf8(isolate, name.ptr, v8.kNormal, @intCast(name.len));
+                const getter_callback = @constCast(v8.v8__FunctionTemplate__New__Config(isolate, &.{ .callback = value.getter }).?);
+                if (value.setter == null) {
+                    if (value.static) {
+                        v8.v8__Template__SetAccessorProperty__DEFAULT(@ptrCast(template), js_name, getter_callback);
+                    } else {
+                        v8.v8__ObjectTemplate__SetAccessorProperty__DEFAULT(prototype, js_name, getter_callback);
+                    }
+                } else {
+                    if (comptime IS_DEBUG) {
+                        std.debug.assert(value.static == false);
+                    }
+                    const setter_callback = @constCast(v8.v8__FunctionTemplate__New__Config(isolate, &.{ .callback = value.setter.? }).?);
+                    v8.v8__ObjectTemplate__SetAccessorProperty__DEFAULT2(prototype, js_name, getter_callback, setter_callback);
+                }
+            },
+            bridge.Function => {
+                const function_template = @constCast(v8.v8__FunctionTemplate__New__Config(isolate, &.{ .callback = value.func, .length = value.arity }).?);
+                const js_name = v8.v8__String__NewFromUtf8(isolate, name.ptr, v8.kNormal, @intCast(name.len));
+                if (value.static) {
+                    v8.v8__Template__Set(@ptrCast(template), js_name, @ptrCast(function_template), v8.None);
+                } else {
+                    v8.v8__Template__Set(@ptrCast(prototype), js_name, @ptrCast(function_template), v8.None);
+                }
+            },
+            bridge.Indexed => {
+                var configuration: v8.IndexedPropertyHandlerConfiguration = .{
+                    .getter = value.getter,
+                    .enumerator = value.enumerator,
+                    .setter = null,
+                    .query = null,
+                    .deleter = null,
+                    .definer = null,
+                    .descriptor = null,
+                    .data = null,
+                    .flags = 0,
+                };
+                v8.v8__ObjectTemplate__SetIndexedHandler(instance, &configuration);
+            },
+            bridge.NamedIndexed => {
+                var configuration: v8.NamedPropertyHandlerConfiguration = .{
+                    .getter = value.getter,
+                    .setter = value.setter,
+                    .query = null,
+                    .deleter = value.deleter,
+                    .enumerator = null,
+                    .definer = null,
+                    .descriptor = null,
+                    .data = null,
+                    .flags = v8.kOnlyInterceptStrings | v8.kNonMasking,
+                };
+                v8.v8__ObjectTemplate__SetNamedHandler(instance, &configuration);
+                has_named_index_getter = true;
+            },
+            bridge.Iterator => {
+                const function_template = @constCast(v8.v8__FunctionTemplate__New__Config(isolate, &.{ .callback = value.func }).?);
+                const js_name = if (value.async)
+                    v8.v8__Symbol__GetAsyncIterator(isolate)
+                else
+                    v8.v8__Symbol__GetIterator(isolate);
+                v8.v8__Template__Set(@ptrCast(prototype), js_name, @ptrCast(function_template), v8.None);
+            },
+            bridge.Property => {
+                const js_value = switch (value.value) {
+                    .null => js.simpleZigValueToJs(.{ .handle = isolate }, null, true, false),
+                    inline .bool, .int, .float, .string => |v| js.simpleZigValueToJs(.{ .handle = isolate }, v, true, false),
+                };
+                const js_name = v8.v8__String__NewFromUtf8(isolate, name.ptr, v8.kNormal, @intCast(name.len));
+
+                {
+                    const flags = if (value.readonly) v8.ReadOnly + v8.DontDelete else 0;
+                    v8.v8__Template__Set(@ptrCast(prototype), js_name, js_value, flags);
+                }
+
+                if (value.template) {
+                    // apply it both to the type itself (e.g. Node.Elem)
+                    v8.v8__Template__Set(@ptrCast(template), js_name, js_value, v8.ReadOnly + v8.DontDelete);
+                }
+            },
+            bridge.Constructor => {}, // already handled in generateConstructor
+            else => {},
+        }
+    }
+
+    if (@hasDecl(JsApi.Meta, "htmldda")) {
+        v8.v8__ObjectTemplate__MarkAsUndetectable(instance);
+        v8.v8__ObjectTemplate__SetCallAsFunctionHandler(instance, JsApi.Meta.callable.func);
+    }
+
+    if (@hasDecl(JsApi.Meta, "name")) {
+        const js_name = v8.v8__Symbol__GetToStringTag(isolate);
+        const js_value = v8.v8__String__NewFromUtf8(isolate, JsApi.Meta.name.ptr, v8.kNormal, @intCast(JsApi.Meta.name.len));
+        v8.v8__Template__Set(@ptrCast(instance), js_name, js_value, v8.ReadOnly + v8.DontDelete);
+    }
+
+    if (comptime IS_DEBUG) {
+        if (!has_named_index_getter) {
+            var configuration: v8.NamedPropertyHandlerConfiguration = .{
+                .getter = bridge.unknownObjectPropertyCallback(JsApi),
+                .setter = null,
+                .query = null,
+                .deleter = null,
+                .enumerator = null,
+                .definer = null,
+                .descriptor = null,
+                .data = null,
+                .flags = v8.kOnlyInterceptStrings | v8.kNonMasking,
+            };
+            v8.v8__ObjectTemplate__SetNamedHandler(instance, &configuration);
+        }
+    }
+}
+
+fn protoIndexLookup(comptime JsApi: type) ?bridge.JsApiLookup.BackingInt {
+    @setEvalBranchQuota(2000);
+    comptime {
+        const T = JsApi.bridge.type;
+        if (!@hasField(T, "_proto")) {
+            return null;
+        }
+        const Ptr = std.meta.fieldInfo(T, ._proto).type;
+        const F = @typeInfo(Ptr).pointer.child;
+        return bridge.JsApiLookup.getId(F.JsApi);
+    }
+}
+
+// Shared illegal constructor callback for types without explicit constructors
+fn illegalConstructorCallback(raw_info: ?*const v8.FunctionCallbackInfo) callconv(.c) void {
+    const isolate = v8.v8__FunctionCallbackInfo__GetIsolate(raw_info);
+    log.warn(.js, "Illegal constructor call", .{});
+
+    const message = v8.v8__String__NewFromUtf8(isolate, "Illegal Constructor", v8.kNormal, 19);
+    const js_exception = v8.v8__Exception__TypeError(message);
+
+    _ = v8.v8__Isolate__ThrowException(isolate, js_exception);
+    var return_value: v8.ReturnValue = undefined;
+    v8.v8__FunctionCallbackInfo__GetReturnValue(raw_info, &return_value);
+    v8.v8__ReturnValue__Set(return_value, js_exception);
+}

src/browser/js/String.zig

@@ -0,0 +1,111 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const js = @import("js.zig");
+const SSO = @import("../../string.zig").String;
+
+const Allocator = std.mem.Allocator;
+const IS_DEBUG = @import("builtin").mode == .Debug;
+
+const v8 = js.v8;
+
+const String = @This();
+
+local: *const js.Local,
+handle: *const v8.String,
+
+pub fn toSlice(self: String) ![]u8 {
+    return self._toSlice(false, self.local.call_arena);
+}
+pub fn toSliceZ(self: String) ![:0]u8 {
+    return self._toSlice(true, self.local.call_arena);
+}
+pub fn toSliceWithAlloc(self: String, allocator: Allocator) ![]u8 {
+    return self._toSlice(false, allocator);
+}
+fn _toSlice(self: String, comptime null_terminate: bool, allocator: Allocator) !(if (null_terminate) [:0]u8 else []u8) {
+    const local = self.local;
+    const handle = self.handle;
+    const isolate = local.isolate.handle;
+
+    const len = v8.v8__String__Utf8Length(handle, isolate);
+    const buf = try (if (comptime null_terminate) allocator.allocSentinel(u8, @intCast(len), 0) else allocator.alloc(u8, @intCast(len)));
+    const n = v8.v8__String__WriteUtf8(handle, isolate, buf.ptr, buf.len, v8.NO_NULL_TERMINATION | v8.REPLACE_INVALID_UTF8);
+    if (comptime IS_DEBUG) {
+        std.debug.assert(n == len);
+    }
+
+    return buf;
+}
+
+pub fn toSSO(self: String, comptime global: bool) !(if (global) SSO.Global else SSO) {
+    if (comptime global) {
+        return .{ .str = try self.toSSOWithAlloc(self.local.ctx.session.page_arena) };
+    }
+    return self.toSSOWithAlloc(self.local.call_arena);
+}
+pub fn toSSOWithAlloc(self: String, allocator: Allocator) !SSO {
+    const handle = self.handle;
+    const isolate = self.local.isolate.handle;
+
+    const len: usize = @intCast(v8.v8__String__Utf8Length(handle, isolate));
+
+    if (len <= 12) {
+        var content: [12]u8 = undefined;
+        const n = v8.v8__String__WriteUtf8(handle, isolate, &content[0], content.len, v8.NO_NULL_TERMINATION | v8.REPLACE_INVALID_UTF8);
+        if (comptime IS_DEBUG) {
+            std.debug.assert(n == len);
+        }
+        // Weird that we do this _after_, but we have to..I've seen weird issues
+        // in ReleaseMode where v8 won't write to content if it starts off zero
+        // initiated
+        @memset(content[len..], 0);
+        return .{ .len = @intCast(len), .payload = .{ .content = content } };
+    }
+
+    const buf = try allocator.alloc(u8, len);
+    const n = v8.v8__String__WriteUtf8(handle, isolate, buf.ptr, buf.len, v8.NO_NULL_TERMINATION | v8.REPLACE_INVALID_UTF8);
+    if (comptime IS_DEBUG) {
+        std.debug.assert(n == len);
+    }
+
+    var prefix: [4]u8 = @splat(0);
+    @memcpy(&prefix, buf[0..4]);
+
+    return .{
+        .len = @intCast(len),
+        .payload = .{ .heap = .{
+            .prefix = prefix,
+            .ptr = buf.ptr,
+        } },
+    };
+}
+
+pub fn format(self: String, writer: *std.Io.Writer) !void {
+    const local = self.local;
+    const handle = self.handle;
+    const isolate = local.isolate.handle;
+
+    var small: [1024]u8 = undefined;
+    const len = v8.v8__String__Utf8Length(handle, isolate);
+    var buf = if (len < 1024) &small else local.call_arena.alloc(u8, @intCast(len)) catch return error.WriteFailed;
+
+    const n = v8.v8__String__WriteUtf8(handle, isolate, buf.ptr, buf.len, v8.NO_NULL_TERMINATION | v8.REPLACE_INVALID_UTF8);
+    return writer.writeAll(buf[0..n]);
+}

src/browser/js/TaggedOpaque.zig

@@ -0,0 +1,129 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const js = @import("js.zig");
+const v8 = js.v8;
+const bridge = js.bridge;
+
+// When we return a Zig object to V8, we put it on the heap and pass it into
+// v8 as an *anyopaque (i.e. void *). When V8 gives us back the value, say, as a
+// function parameter, we know what type it _should_ be.
+//
+// In a simple/perfect world, we could use this knowledge to cast the *anyopaque
+// to the parameter type:
+//   const arg: @typeInfo(@TypeOf(function)).@"fn".params[0] = @ptrCast(v8_data);
+//
+// But there are 2 reasons we can't do that.
+//
+// == Reason 1 ==
+// The JS code might pass the wrong type:
+//
+//   var cat = new Cat();
+//   cat.setOwner(new Cat());
+//
+// The zig_setOwner method expects the 2nd parameter to be an *Owner, but
+// the JS code passed a *Cat.
+//
+// To solve this issue, we tag every returned value so that we can check what
+// type it is. In the above case, we'd expect an *Owner, but the tag would tell
+// us that we got a *Cat. We use the type index in our Types lookup as the tag.
+//
+// == Reason 2 ==
+// Because of prototype inheritance, even "correct" code can be a challenge. For
+// example, say the above JavaScript is fixed:
+//
+//   var cat = new Cat();
+//   cat.setOwner(new Owner("Leto"));
+//
+// The issue is that setOwner might not expect an *Owner, but rather a
+// *Person, which is the prototype for Owner. Now our Zig code is expecting
+// a *Person, but it was (correctly) given an *Owner.
+// For this reason, we also store the prototype chain.
+const TaggedOpaque = @This();
+
+prototype_len: u16,
+prototype_chain: [*]const PrototypeChainEntry,
+
+// Ptr to the Zig instance. Between the context where it's called (i.e.
+// we have the comptime parameter info for all functions), and the index field
+// we can figure out what type this is.
+value: *anyopaque,
+
+// When we're asked to describe an object via the Inspector, we _must_ include
+// the proper subtype (and description) fields in the returned JSON.
+// V8 will give us a Value and ask us for the subtype. From the js.Value we
+// can get a js.Object, and from the js.Object, we can get out TaggedOpaque
+// which is where we store the subtype.
+subtype: ?bridge.SubType,
+
+pub const PrototypeChainEntry = struct {
+    index: bridge.JsApiLookup.BackingInt,
+    offset: u16, // offset to the _proto field
+};
+
+// Reverses the mapZigInstanceToJs, making sure that our TaggedOpaque
+// contains a ptr to the correct type.
+pub fn fromJS(comptime R: type, js_obj_handle: *const v8.Object) !R {
+    const ti = @typeInfo(R);
+    if (ti != .pointer) {
+        @compileError("non-pointer Zig parameter type: " ++ @typeName(R));
+    }
+
+    const T = ti.pointer.child;
+    const JsApi = bridge.Struct(T).JsApi;
+
+    if (@hasDecl(JsApi.Meta, "empty_with_no_proto")) {
+        // Empty structs aren't stored as TOAs and there's no data
+        // stored in the JSObject's IntenrnalField. Why bother when
+        // we can just return an empty struct here?
+        return @constCast(@as(*const T, &.{}));
+    }
+
+    const internal_field_count = v8.v8__Object__InternalFieldCount(js_obj_handle);
+    // if it isn't an empty struct, then the v8.Object should have an
+    // InternalFieldCount > 0, since our toa pointer should be embedded
+    // at index 0 of the internal field count.
+    if (internal_field_count == 0) {
+        return error.InvalidArgument;
+    }
+
+    if (!bridge.JsApiLookup.has(JsApi)) {
+        @compileError("unknown Zig type: " ++ @typeName(R));
+    }
+
+    const tao_ptr = v8.v8__Object__GetAlignedPointerFromInternalField(js_obj_handle, 0).?;
+    const tao: *TaggedOpaque = @ptrCast(@alignCast(tao_ptr));
+    const expected_type_index = bridge.JsApiLookup.getId(JsApi);
+
+    const prototype_chain = tao.prototype_chain[0..tao.prototype_len];
+    if (prototype_chain[0].index == expected_type_index) {
+        return @ptrCast(@alignCast(tao.value));
+    }
+
+    // Ok, let's walk up the chain
+    var ptr = @intFromPtr(tao.value);
+    for (prototype_chain[1..]) |proto| {
+        ptr += proto.offset; // the offset to the _proto field
+        const proto_ptr: **anyopaque = @ptrFromInt(ptr);
+        if (proto.index == expected_type_index) {
+            return @ptrCast(@alignCast(proto_ptr.*));
+        }
+        ptr = @intFromPtr(proto_ptr.*);
+    }
+    return error.InvalidArgument;
+}

src/browser/js/TryCatch.zig

@@ -0,0 +1,150 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const js = @import("js.zig");
+const v8 = js.v8;
+
+const IS_DEBUG = @import("builtin").mode == .Debug;
+
+const Allocator = std.mem.Allocator;
+
+const TryCatch = @This();
+
+handle: v8.TryCatch,
+local: *const js.Local,
+
+pub fn init(self: *TryCatch, l: *const js.Local) void {
+    self.local = l;
+    v8.v8__TryCatch__CONSTRUCT(&self.handle, l.isolate.handle);
+}
+
+pub fn hasCaught(self: TryCatch) bool {
+    return v8.v8__TryCatch__HasCaught(&self.handle);
+}
+
+pub fn rethrow(self: *TryCatch) void {
+    if (comptime IS_DEBUG) {
+        std.debug.assert(self.hasCaught());
+    }
+    _ = v8.v8__TryCatch__ReThrow(&self.handle);
+}
+
+pub fn caught(self: TryCatch, allocator: Allocator) ?Caught {
+    if (self.hasCaught() == false) {
+        return null;
+    }
+
+    const l = self.local;
+    const line: ?u32 = blk: {
+        const handle = v8.v8__TryCatch__Message(&self.handle) orelse return null;
+        const line = v8.v8__Message__GetLineNumber(handle, l.handle);
+        break :blk if (line < 0) null else @intCast(line);
+    };
+
+    const exception: ?[]const u8 = blk: {
+        const handle = v8.v8__TryCatch__Exception(&self.handle) orelse break :blk null;
+        var js_val = js.Value{ .local = l, .handle = handle };
+
+        // If it's an Error object, try to get the message property
+        if (js_val.isObject()) {
+            const js_obj = js_val.toObject();
+            if (js_obj.has("message")) {
+                js_val = js_obj.get("message") catch break :blk null;
+            }
+        }
+
+        if (js_val.isString()) |js_str| {
+            break :blk js_str.toSliceWithAlloc(allocator) catch |err| @errorName(err);
+        }
+        break :blk null;
+    };
+
+    const stack: ?[]const u8 = blk: {
+        const handle = v8.v8__TryCatch__StackTrace(&self.handle, l.handle) orelse break :blk null;
+        var js_val = js.Value{ .local = l, .handle = handle };
+
+        // If it's an Error object, try to get the stack property
+        if (js_val.isObject()) {
+            const js_obj = js_val.toObject();
+            if (js_obj.has("stack")) {
+                js_val = js_obj.get("stack") catch break :blk null;
+            }
+        }
+
+        if (js_val.isString()) |js_str| {
+            break :blk js_str.toSliceWithAlloc(allocator) catch |err| @errorName(err);
+        }
+        break :blk null;
+    };
+
+    return .{
+        .line = line,
+        .stack = stack,
+        .caught = true,
+        .exception = exception,
+    };
+}
+
+pub fn caughtOrError(self: TryCatch, allocator: Allocator, err: anyerror) Caught {
+    return self.caught(allocator) orelse .{
+        .caught = false,
+        .line = null,
+        .stack = null,
+        .exception = @errorName(err),
+    };
+}
+
+pub fn deinit(self: *TryCatch) void {
+    v8.v8__TryCatch__DESTRUCT(&self.handle);
+}
+
+pub const Caught = struct {
+    line: ?u32 = null,
+    caught: bool = false,
+    stack: ?[]const u8 = null,
+    exception: ?[]const u8 = null,
+
+    pub fn format(self: Caught, writer: *std.Io.Writer) !void {
+        const separator = @import("../../log.zig").separator();
+        try writer.print("{s}exception: {?s}", .{ separator, self.exception });
+        try writer.print("{s}stack: {?s}", .{ separator, self.stack });
+        try writer.print("{s}line: {?d}", .{ separator, self.line });
+        try writer.print("{s}caught: {any}", .{ separator, self.caught });
+    }
+
+    pub fn logFmt(self: Caught, comptime prefix: []const u8, writer: anytype) !void {
+        try writer.write(prefix ++ ".exception", self.exception orelse "???");
+        try writer.write(prefix ++ ".stack", self.stack orelse "na");
+        try writer.write(prefix ++ ".line", self.line);
+        try writer.write(prefix ++ ".caught", self.caught);
+    }
+
+    pub fn jsonStringify(self: Caught, jw: anytype) !void {
+        try jw.beginObject();
+        try jw.objectField("exception");
+        try jw.write(self.exception);
+        try jw.objectField("stack");
+        try jw.write(self.stack);
+        try jw.objectField("line");
+        try jw.write(self.line);
+        try jw.objectField("caught");
+        try jw.write(self.caught);
+        try jw.endObject();
+    }
+};

src/browser/js/Value.zig

@@ -0,0 +1,391 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const js = @import("js.zig");
+const SSO = @import("../../string.zig").String;
+
+const v8 = js.v8;
+
+const IS_DEBUG = @import("builtin").mode == .Debug;
+
+const Allocator = std.mem.Allocator;
+const Session = @import("../Session.zig");
+
+const Value = @This();
+
+local: *const js.Local,
+handle: *const v8.Value,
+
+pub fn isObject(self: Value) bool {
+    return v8.v8__Value__IsObject(self.handle);
+}
+
+pub fn isString(self: Value) ?js.String {
+    const handle = self.handle;
+    if (!v8.v8__Value__IsString(handle)) {
+        return null;
+    }
+    return .{ .local = self.local, .handle = @ptrCast(handle) };
+}
+
+pub fn isArray(self: Value) bool {
+    return v8.v8__Value__IsArray(self.handle);
+}
+
+pub fn isSymbol(self: Value) bool {
+    return v8.v8__Value__IsSymbol(self.handle);
+}
+
+pub fn isFunction(self: Value) bool {
+    return v8.v8__Value__IsFunction(self.handle);
+}
+
+pub fn isNull(self: Value) bool {
+    return v8.v8__Value__IsNull(self.handle);
+}
+
+pub fn isUndefined(self: Value) bool {
+    return v8.v8__Value__IsUndefined(self.handle);
+}
+
+pub fn isNullOrUndefined(self: Value) bool {
+    return v8.v8__Value__IsNullOrUndefined(self.handle);
+}
+
+pub fn isNumber(self: Value) bool {
+    return v8.v8__Value__IsNumber(self.handle);
+}
+
+pub fn isNumberObject(self: Value) bool {
+    return v8.v8__Value__IsNumberObject(self.handle);
+}
+
+pub fn isInt32(self: Value) bool {
+    return v8.v8__Value__IsInt32(self.handle);
+}
+
+pub fn isUint32(self: Value) bool {
+    return v8.v8__Value__IsUint32(self.handle);
+}
+
+pub fn isBigInt(self: Value) bool {
+    return v8.v8__Value__IsBigInt(self.handle);
+}
+
+pub fn isBigIntObject(self: Value) bool {
+    return v8.v8__Value__IsBigIntObject(self.handle);
+}
+
+pub fn isBoolean(self: Value) bool {
+    return v8.v8__Value__IsBoolean(self.handle);
+}
+
+pub fn isBooleanObject(self: Value) bool {
+    return v8.v8__Value__IsBooleanObject(self.handle);
+}
+
+pub fn isTrue(self: Value) bool {
+    return v8.v8__Value__IsTrue(self.handle);
+}
+
+pub fn isFalse(self: Value) bool {
+    return v8.v8__Value__IsFalse(self.handle);
+}
+
+pub fn isTypedArray(self: Value) bool {
+    return v8.v8__Value__IsTypedArray(self.handle);
+}
+
+pub fn isArrayBufferView(self: Value) bool {
+    return v8.v8__Value__IsArrayBufferView(self.handle);
+}
+
+pub fn isArrayBuffer(self: Value) bool {
+    return v8.v8__Value__IsArrayBuffer(self.handle);
+}
+
+pub fn isUint8Array(self: Value) bool {
+    return v8.v8__Value__IsUint8Array(self.handle);
+}
+
+pub fn isUint8ClampedArray(self: Value) bool {
+    return v8.v8__Value__IsUint8ClampedArray(self.handle);
+}
+
+pub fn isInt8Array(self: Value) bool {
+    return v8.v8__Value__IsInt8Array(self.handle);
+}
+
+pub fn isUint16Array(self: Value) bool {
+    return v8.v8__Value__IsUint16Array(self.handle);
+}
+
+pub fn isInt16Array(self: Value) bool {
+    return v8.v8__Value__IsInt16Array(self.handle);
+}
+
+pub fn isUint32Array(self: Value) bool {
+    return v8.v8__Value__IsUint32Array(self.handle);
+}
+
+pub fn isInt32Array(self: Value) bool {
+    return v8.v8__Value__IsInt32Array(self.handle);
+}
+
+pub fn isBigUint64Array(self: Value) bool {
+    return v8.v8__Value__IsBigUint64Array(self.handle);
+}
+
+pub fn isBigInt64Array(self: Value) bool {
+    return v8.v8__Value__IsBigInt64Array(self.handle);
+}
+
+pub fn isPromise(self: Value) bool {
+    return v8.v8__Value__IsPromise(self.handle);
+}
+
+pub fn toBool(self: Value) bool {
+    return v8.v8__Value__BooleanValue(self.handle, self.local.isolate.handle);
+}
+
+pub fn typeOf(self: Value) js.String {
+    const str_handle = v8.v8__Value__TypeOf(self.handle, self.local.isolate.handle).?;
+    return js.String{ .local = self.local, .handle = str_handle };
+}
+
+pub fn toF32(self: Value) !f32 {
+    return @floatCast(try self.toF64());
+}
+
+pub fn toF64(self: Value) !f64 {
+    var maybe: v8.MaybeF64 = undefined;
+    v8.v8__Value__NumberValue(self.handle, self.local.handle, &maybe);
+    if (!maybe.has_value) {
+        return error.JsException;
+    }
+    return maybe.value;
+}
+
+pub fn toI32(self: Value) !i32 {
+    var maybe: v8.MaybeI32 = undefined;
+    v8.v8__Value__Int32Value(self.handle, self.local.handle, &maybe);
+    if (!maybe.has_value) {
+        return error.JsException;
+    }
+    return maybe.value;
+}
+
+pub fn toU32(self: Value) !u32 {
+    var maybe: v8.MaybeU32 = undefined;
+    v8.v8__Value__Uint32Value(self.handle, self.local.handle, &maybe);
+    if (!maybe.has_value) {
+        return error.JsException;
+    }
+    return maybe.value;
+}
+
+pub fn toPromise(self: Value) js.Promise {
+    if (comptime IS_DEBUG) {
+        std.debug.assert(self.isPromise());
+    }
+    return .{
+        .local = self.local,
+        .handle = @ptrCast(self.handle),
+    };
+}
+
+pub fn toString(self: Value) !js.String {
+    const l = self.local;
+    const value_handle: *const v8.Value = blk: {
+        if (self.isSymbol()) {
+            break :blk @ptrCast(v8.v8__Symbol__Description(@ptrCast(self.handle), l.isolate.handle).?);
+        }
+        break :blk self.handle;
+    };
+
+    const str_handle = v8.v8__Value__ToString(value_handle, l.handle) orelse return error.JsException;
+    return .{ .local = self.local, .handle = str_handle };
+}
+
+pub fn toSSO(self: Value, comptime global: bool) !(if (global) SSO.Global else SSO) {
+    return (try self.toString()).toSSO(global);
+}
+pub fn toSSOWithAlloc(self: Value, allocator: Allocator) !SSO {
+    return (try self.toString()).toSSOWithAlloc(allocator);
+}
+
+pub fn toStringSlice(self: Value) ![]u8 {
+    return (try self.toString()).toSlice();
+}
+pub fn toStringSliceZ(self: Value) ![:0]u8 {
+    return (try self.toString()).toSliceZ();
+}
+pub fn toStringSliceWithAlloc(self: Value, allocator: Allocator) ![]u8 {
+    return (try self.toString()).toSliceWithAlloc(allocator);
+}
+
+pub fn toJson(self: Value, allocator: Allocator) ![]u8 {
+    const local = self.local;
+    const str_handle = v8.v8__JSON__Stringify(local.handle, self.handle, null) orelse return error.JsException;
+    return js.String.toSliceWithAlloc(.{ .local = local, .handle = str_handle }, allocator);
+}
+
+// Currently does not support host objects (Blob, File, etc.) or transferables
+// which require delegate callbacks to be implemented.
+pub fn structuredClone(self: Value) !Value {
+    const local = self.local;
+    const v8_context = local.handle;
+    const v8_isolate = local.isolate.handle;
+
+    const size, const data = blk: {
+        const serializer = v8.v8__ValueSerializer__New(v8_isolate, null) orelse return error.JsException;
+        defer v8.v8__ValueSerializer__DELETE(serializer);
+
+        var write_result: v8.MaybeBool = undefined;
+        v8.v8__ValueSerializer__WriteHeader(serializer);
+        v8.v8__ValueSerializer__WriteValue(serializer, v8_context, self.handle, &write_result);
+        if (!write_result.has_value or !write_result.value) {
+            return error.JsException;
+        }
+
+        var size: usize = undefined;
+        const data = v8.v8__ValueSerializer__Release(serializer, &size) orelse return error.JsException;
+        break :blk .{ size, data };
+    };
+
+    defer v8.v8__ValueSerializer__FreeBuffer(data);
+
+    const cloned_handle = blk: {
+        const deserializer = v8.v8__ValueDeserializer__New(v8_isolate, data, size, null) orelse return error.JsException;
+        defer v8.v8__ValueDeserializer__DELETE(deserializer);
+
+        var read_header_result: v8.MaybeBool = undefined;
+        v8.v8__ValueDeserializer__ReadHeader(deserializer, v8_context, &read_header_result);
+        if (!read_header_result.has_value or !read_header_result.value) {
+            return error.JsException;
+        }
+        break :blk v8.v8__ValueDeserializer__ReadValue(deserializer, v8_context) orelse return error.JsException;
+    };
+
+    return .{ .local = local, .handle = cloned_handle };
+}
+
+pub fn persist(self: Value) !Global {
+    return self._persist(true);
+}
+
+pub fn temp(self: Value) !Temp {
+    return self._persist(false);
+}
+
+fn _persist(self: *const Value, comptime is_global: bool) !(if (is_global) Global else Temp) {
+    var ctx = self.local.ctx;
+
+    var global: v8.Global = undefined;
+    v8.v8__Global__New(ctx.isolate.handle, self.handle, &global);
+    if (comptime is_global) {
+        try ctx.trackGlobal(global);
+        return .{ .handle = global, .temps = {} };
+    }
+    try ctx.trackTemp(global);
+    return .{ .handle = global, .temps = &ctx.identity.temps };
+}
+
+pub fn toZig(self: Value, comptime T: type) !T {
+    return self.local.jsValueToZig(T, self);
+}
+
+pub fn toObject(self: Value) js.Object {
+    if (comptime IS_DEBUG) {
+        std.debug.assert(self.isObject());
+    }
+
+    return .{
+        .local = self.local,
+        .handle = @ptrCast(self.handle),
+    };
+}
+
+pub fn toArray(self: Value) js.Array {
+    if (comptime IS_DEBUG) {
+        std.debug.assert(self.isArray());
+    }
+
+    return .{
+        .local = self.local,
+        .handle = @ptrCast(self.handle),
+    };
+}
+
+pub fn toBigInt(self: Value) js.BigInt {
+    if (comptime IS_DEBUG) {
+        std.debug.assert(self.isBigInt());
+    }
+
+    return .{
+        .handle = @ptrCast(self.handle),
+    };
+}
+
+pub fn format(self: Value, writer: *std.Io.Writer) !void {
+    if (comptime IS_DEBUG) {
+        return self.local.debugValue(self, writer);
+    }
+    const js_str = self.toString() catch return error.WriteFailed;
+    return js_str.format(writer);
+}
+
+pub const Temp = G(.temp);
+pub const Global = G(.global);
+
+const GlobalType = enum(u8) {
+    temp,
+    global,
+};
+
+fn G(comptime global_type: GlobalType) type {
+    return struct {
+        handle: v8.Global,
+        temps: if (global_type == .temp) *std.AutoHashMapUnmanaged(usize, v8.Global) else void,
+
+        const Self = @This();
+
+        pub fn deinit(self: *Self) void {
+            v8.v8__Global__Reset(&self.handle);
+        }
+
+        pub fn local(self: *const Self, l: *const js.Local) Value {
+            return .{
+                .local = l,
+                .handle = @ptrCast(v8.v8__Global__Get(&self.handle, l.isolate.handle)),
+            };
+        }
+
+        pub fn isEqual(self: *const Self, other: Value) bool {
+            return v8.v8__Global__IsEqual(&self.handle, other.handle);
+        }
+
+        pub fn release(self: *const Self) void {
+            if (self.temps.fetchRemove(self.handle.data_ptr)) |kv| {
+                var g = kv.value;
+                v8.v8__Global__Reset(&g);
+            }
+        }
+    };
+}

src/browser/js/bridge.zig

@@ -0,0 +1,906 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const js = @import("js.zig");
+const lp = @import("lightpanda");
+const log = @import("../../log.zig");
+const Page = @import("../Page.zig");
+const Session = @import("../Session.zig");
+
+const v8 = js.v8;
+
+const Caller = @import("Caller.zig");
+const Context = @import("Context.zig");
+
+const IS_DEBUG = @import("builtin").mode == .Debug;
+
+pub fn Builder(comptime T: type) type {
+    return struct {
+        pub const @"type" = T;
+        pub const ClassId = u16;
+
+        pub fn constructor(comptime func: anytype, comptime opts: Constructor.Opts) Constructor {
+            return Constructor.init(T, func, opts);
+        }
+
+        pub fn accessor(comptime getter: anytype, comptime setter: anytype, comptime opts: Caller.Function.Opts) Accessor {
+            return Accessor.init(T, getter, setter, opts);
+        }
+
+        pub fn function(comptime func: anytype, comptime opts: Caller.Function.Opts) Function {
+            return Function.init(T, func, opts);
+        }
+
+        pub fn indexed(comptime getter_func: anytype, comptime enumerator_func: anytype, comptime opts: Indexed.Opts) Indexed {
+            return Indexed.init(T, getter_func, enumerator_func, opts);
+        }
+
+        pub fn namedIndexed(comptime getter_func: anytype, setter_func: anytype, deleter_func: anytype, comptime opts: NamedIndexed.Opts) NamedIndexed {
+            return NamedIndexed.init(T, getter_func, setter_func, deleter_func, opts);
+        }
+
+        pub fn iterator(comptime func: anytype, comptime opts: Iterator.Opts) Iterator {
+            return Iterator.init(T, func, opts);
+        }
+
+        pub fn callable(comptime func: anytype, comptime opts: Callable.Opts) Callable {
+            return Callable.init(T, func, opts);
+        }
+
+        pub fn property(value: anytype, opts: Property.Opts) Property {
+            switch (@typeInfo(@TypeOf(value))) {
+                .bool => return Property.init(.{ .bool = value }, opts),
+                .null => return Property.init(.null, opts),
+                .comptime_int, .int => return Property.init(.{ .int = value }, opts),
+                .comptime_float, .float => return Property.init(.{ .float = value }, opts),
+                .pointer => |ptr| switch (ptr.size) {
+                    .one => {
+                        const one_info = @typeInfo(ptr.child);
+                        if (one_info == .array and one_info.array.child == u8) {
+                            return Property.init(.{ .string = value }, opts);
+                        }
+                    },
+                    else => {},
+                },
+                else => {},
+            }
+            @compileError("Property for " ++ @typeName(@TypeOf(value)) ++ " hasn't been defined yet");
+        }
+
+        const PrototypeChainEntry = @import("TaggedOpaque.zig").PrototypeChainEntry;
+        pub fn prototypeChain() [prototypeChainLength(T)]PrototypeChainEntry {
+            var entries: [prototypeChainLength(T)]PrototypeChainEntry = undefined;
+
+            entries[0] = .{ .offset = 0, .index = JsApiLookup.getId(T.JsApi) };
+
+            if (entries.len == 1) {
+                return entries;
+            }
+
+            var Prototype = T;
+            inline for (entries[1..]) |*entry| {
+                const Next = PrototypeType(Prototype).?;
+                entry.* = .{
+                    .index = JsApiLookup.getId(Next.JsApi),
+                    .offset = @offsetOf(Prototype, "_proto"),
+                };
+                Prototype = Next;
+            }
+            return entries;
+        }
+
+        pub fn finalizer(comptime func: *const fn (self: *T, shutdown: bool, session: *Session) void) Finalizer {
+            return .{
+                .from_zig = struct {
+                    fn wrap(ptr: *anyopaque, session: *Session) void {
+                        func(@ptrCast(@alignCast(ptr)), true, session);
+                    }
+                }.wrap,
+
+                .from_v8 = struct {
+                    fn wrap(handle: ?*const v8.WeakCallbackInfo) callconv(.c) void {
+                        const ptr = v8.v8__WeakCallbackInfo__GetParameter(handle.?).?;
+                        const fc: *Session.FinalizerCallback = @ptrCast(@alignCast(ptr));
+
+                        const value_ptr = fc.ptr;
+                        if (fc.identity.finalizer_callbacks.contains(@intFromPtr(value_ptr))) {
+                            func(@ptrCast(@alignCast(value_ptr)), false, fc.session);
+                            fc.releaseIdentity();
+                        } else {
+                            // A bit weird, but v8 _requires_ that we release it
+                            // If we don't. We'll 100% crash.
+                            v8.v8__Global__Reset(&fc.global);
+                        }
+                    }
+                }.wrap,
+            };
+        }
+    };
+}
+
+pub const Constructor = struct {
+    func: *const fn (?*const v8.FunctionCallbackInfo) callconv(.c) void,
+
+    const Opts = struct {
+        dom_exception: bool = false,
+    };
+
+    fn init(comptime T: type, comptime func: anytype, comptime opts: Opts) Constructor {
+        return .{ .func = struct {
+            fn wrap(handle: ?*const v8.FunctionCallbackInfo) callconv(.c) void {
+                const v8_isolate = v8.v8__FunctionCallbackInfo__GetIsolate(handle).?;
+                var caller: Caller = undefined;
+                caller.init(v8_isolate);
+                defer caller.deinit();
+
+                caller.constructor(T, func, handle.?, .{
+                    .dom_exception = opts.dom_exception,
+                });
+            }
+        }.wrap };
+    }
+};
+
+pub const Function = struct {
+    static: bool,
+    arity: usize,
+    noop: bool = false,
+    cache: ?Caller.Function.Opts.Caching = null,
+    func: *const fn (?*const v8.FunctionCallbackInfo) callconv(.c) void,
+
+    fn init(comptime T: type, comptime func: anytype, comptime opts: Caller.Function.Opts) Function {
+        return .{
+            .cache = opts.cache,
+            .static = opts.static,
+            .arity = getArity(@TypeOf(func)),
+            .func = if (opts.noop) noopFunction else struct {
+                fn wrap(handle: ?*const v8.FunctionCallbackInfo) callconv(.c) void {
+                    Caller.Function.call(T, handle.?, func, opts);
+                }
+            }.wrap,
+        };
+    }
+
+    pub fn noopFunction(_: ?*const v8.FunctionCallbackInfo) callconv(.c) void {}
+
+    fn getArity(comptime T: type) usize {
+        var count: usize = 0;
+        var params = @typeInfo(T).@"fn".params;
+        for (params[1..]) |p| { // start at 1, skip self
+            const PT = p.type.?;
+            if (PT == *Page or PT == *const Page) {
+                break;
+            }
+            if (@typeInfo(PT) == .optional) {
+                break;
+            }
+            count += 1;
+        }
+        return count;
+    }
+};
+
+pub const Accessor = struct {
+    static: bool = false,
+    cache: ?Caller.Function.Opts.Caching = null,
+    getter: ?*const fn (?*const v8.FunctionCallbackInfo) callconv(.c) void = null,
+    setter: ?*const fn (?*const v8.FunctionCallbackInfo) callconv(.c) void = null,
+
+    fn init(comptime T: type, comptime getter: anytype, comptime setter: anytype, comptime opts: Caller.Function.Opts) Accessor {
+        var accessor = Accessor{
+            .cache = opts.cache,
+            .static = opts.static,
+        };
+
+        if (@typeInfo(@TypeOf(getter)) != .null) {
+            accessor.getter = struct {
+                fn wrap(handle: ?*const v8.FunctionCallbackInfo) callconv(.c) void {
+                    Caller.Function.call(T, handle.?, getter, opts);
+                }
+            }.wrap;
+        }
+
+        if (@typeInfo(@TypeOf(setter)) != .null) {
+            accessor.setter = struct {
+                fn wrap(handle: ?*const v8.FunctionCallbackInfo) callconv(.c) void {
+                    Caller.Function.call(T, handle.?, setter, opts);
+                }
+            }.wrap;
+        }
+
+        return accessor;
+    }
+};
+
+pub const Indexed = struct {
+    getter: *const fn (idx: u32, handle: ?*const v8.PropertyCallbackInfo) callconv(.c) u8,
+    enumerator: ?*const fn (handle: ?*const v8.PropertyCallbackInfo) callconv(.c) u8,
+
+    const Opts = struct {
+        as_typed_array: bool = false,
+        null_as_undefined: bool = false,
+    };
+
+    fn init(comptime T: type, comptime getter: anytype, comptime enumerator: anytype, comptime opts: Opts) Indexed {
+        var indexed = Indexed{
+            .enumerator = null,
+            .getter = struct {
+                fn wrap(idx: u32, handle: ?*const v8.PropertyCallbackInfo) callconv(.c) u8 {
+                    const v8_isolate = v8.v8__PropertyCallbackInfo__GetIsolate(handle).?;
+                    var caller: Caller = undefined;
+                    caller.init(v8_isolate);
+                    defer caller.deinit();
+
+                    return caller.getIndex(T, getter, idx, handle.?, .{
+                        .as_typed_array = opts.as_typed_array,
+                        .null_as_undefined = opts.null_as_undefined,
+                    });
+                }
+            }.wrap,
+        };
+
+        if (@typeInfo(@TypeOf(enumerator)) != .null) {
+            indexed.enumerator = struct {
+                fn wrap(handle: ?*const v8.PropertyCallbackInfo) callconv(.c) u8 {
+                    const v8_isolate = v8.v8__PropertyCallbackInfo__GetIsolate(handle).?;
+                    var caller: Caller = undefined;
+                    caller.init(v8_isolate);
+                    defer caller.deinit();
+                    return caller.getEnumerator(T, enumerator, handle.?, .{});
+                }
+            }.wrap;
+        }
+
+        return indexed;
+    }
+};
+
+pub const NamedIndexed = struct {
+    getter: *const fn (c_name: ?*const v8.Name, handle: ?*const v8.PropertyCallbackInfo) callconv(.c) u8,
+    setter: ?*const fn (c_name: ?*const v8.Name, c_value: ?*const v8.Value, handle: ?*const v8.PropertyCallbackInfo) callconv(.c) u8 = null,
+    deleter: ?*const fn (c_name: ?*const v8.Name, handle: ?*const v8.PropertyCallbackInfo) callconv(.c) u8 = null,
+
+    const Opts = struct {
+        as_typed_array: bool = false,
+        null_as_undefined: bool = false,
+    };
+
+    fn init(comptime T: type, comptime getter: anytype, setter: anytype, deleter: anytype, comptime opts: Opts) NamedIndexed {
+        const getter_fn = struct {
+            fn wrap(c_name: ?*const v8.Name, handle: ?*const v8.PropertyCallbackInfo) callconv(.c) u8 {
+                const v8_isolate = v8.v8__PropertyCallbackInfo__GetIsolate(handle).?;
+                var caller: Caller = undefined;
+                caller.init(v8_isolate);
+                defer caller.deinit();
+
+                return caller.getNamedIndex(T, getter, c_name.?, handle.?, .{
+                    .as_typed_array = opts.as_typed_array,
+                    .null_as_undefined = opts.null_as_undefined,
+                });
+            }
+        }.wrap;
+
+        const setter_fn = if (@typeInfo(@TypeOf(setter)) == .null) null else struct {
+            fn wrap(c_name: ?*const v8.Name, c_value: ?*const v8.Value, handle: ?*const v8.PropertyCallbackInfo) callconv(.c) u8 {
+                const v8_isolate = v8.v8__PropertyCallbackInfo__GetIsolate(handle).?;
+                var caller: Caller = undefined;
+                caller.init(v8_isolate);
+                defer caller.deinit();
+
+                return caller.setNamedIndex(T, setter, c_name.?, c_value.?, handle.?, .{
+                    .as_typed_array = opts.as_typed_array,
+                    .null_as_undefined = opts.null_as_undefined,
+                });
+            }
+        }.wrap;
+
+        const deleter_fn = if (@typeInfo(@TypeOf(deleter)) == .null) null else struct {
+            fn wrap(c_name: ?*const v8.Name, handle: ?*const v8.PropertyCallbackInfo) callconv(.c) u8 {
+                const v8_isolate = v8.v8__PropertyCallbackInfo__GetIsolate(handle).?;
+                var caller: Caller = undefined;
+                caller.init(v8_isolate);
+                defer caller.deinit();
+
+                return caller.deleteNamedIndex(T, deleter, c_name.?, handle.?, .{
+                    .as_typed_array = opts.as_typed_array,
+                    .null_as_undefined = opts.null_as_undefined,
+                });
+            }
+        }.wrap;
+
+        return .{
+            .getter = getter_fn,
+            .setter = setter_fn,
+            .deleter = deleter_fn,
+        };
+    }
+};
+
+pub const Iterator = struct {
+    func: *const fn (?*const v8.FunctionCallbackInfo) callconv(.c) void,
+    async: bool,
+
+    const Opts = struct {
+        async: bool = false,
+        null_as_undefined: bool = false,
+    };
+
+    fn init(comptime T: type, comptime struct_or_func: anytype, comptime opts: Opts) Iterator {
+        if (@typeInfo(@TypeOf(struct_or_func)) == .type) {
+            return .{
+                .async = opts.async,
+                .func = struct {
+                    fn wrap(handle: ?*const v8.FunctionCallbackInfo) callconv(.c) void {
+                        const info = Caller.FunctionCallbackInfo{ .handle = handle.? };
+                        info.getReturnValue().set(info.getThis());
+                    }
+                }.wrap,
+            };
+        }
+
+        return .{
+            .async = opts.async,
+            .func = struct {
+                fn wrap(handle: ?*const v8.FunctionCallbackInfo) callconv(.c) void {
+                    return Caller.Function.call(T, handle.?, struct_or_func, .{
+                        .null_as_undefined = opts.null_as_undefined,
+                    });
+                }
+            }.wrap,
+        };
+    }
+};
+
+pub const Callable = struct {
+    func: *const fn (?*const v8.FunctionCallbackInfo) callconv(.c) void,
+
+    const Opts = struct {
+        null_as_undefined: bool = false,
+    };
+
+    fn init(comptime T: type, comptime func: anytype, comptime opts: Opts) Callable {
+        return .{ .func = struct {
+            fn wrap(handle: ?*const v8.FunctionCallbackInfo) callconv(.c) void {
+                Caller.Function.call(T, handle.?, func, .{
+                    .null_as_undefined = opts.null_as_undefined,
+                });
+            }
+        }.wrap };
+    }
+};
+
+pub const Property = struct {
+    value: Value,
+    template: bool,
+    readonly: bool,
+
+    const Value = union(enum) {
+        null,
+        int: i64,
+        float: f64,
+        bool: bool,
+        string: []const u8,
+    };
+
+    const Opts = struct {
+        template: bool,
+        readonly: bool = true,
+    };
+
+    fn init(value: Value, opts: Opts) Property {
+        return .{
+            .value = value,
+            .template = opts.template,
+            .readonly = opts.readonly,
+        };
+    }
+};
+
+const Finalizer = struct {
+    // The finalizer wrapper when called from Zig. This is only called on
+    // Origin.deinit
+    from_zig: *const fn (ctx: *anyopaque, session: *Session) void,
+
+    // The finalizer wrapper when called from V8. This may never be called
+    // (hence why we fallback to calling in Origin.deinit). If it is called,
+    // it is only ever called after we SetWeak on the Global.
+    from_v8: *const fn (?*const v8.WeakCallbackInfo) callconv(.c) void,
+};
+
+pub fn unknownWindowPropertyCallback(c_name: ?*const v8.Name, handle: ?*const v8.PropertyCallbackInfo) callconv(.c) u8 {
+    const v8_isolate = v8.v8__PropertyCallbackInfo__GetIsolate(handle).?;
+    var caller: Caller = undefined;
+    caller.init(v8_isolate);
+    defer caller.deinit();
+
+    const local = &caller.local;
+
+    var hs: js.HandleScope = undefined;
+    hs.init(local.isolate);
+    defer hs.deinit();
+
+    const property: []const u8 = js.String.toSlice(.{ .local = local, .handle = @ptrCast(c_name.?) }) catch {
+        return 0;
+    };
+
+    const page = local.ctx.page;
+    const document = page.document;
+
+    if (document.getElementById(property, page)) |el| {
+        const js_val = local.zigValueToJs(el, .{}) catch return 0;
+        var pc = Caller.PropertyCallbackInfo{ .handle = handle.? };
+        pc.getReturnValue().set(js_val);
+        return 1;
+    }
+
+    if (comptime IS_DEBUG) {
+        if (std.mem.startsWith(u8, property, "__")) {
+            // some frameworks will extend built-in types using a __ prefix
+            // these should always be safe to ignore.
+            return 0;
+        }
+
+        const ignored = std.StaticStringMap(void).initComptime(.{
+            .{ "Deno", {} },
+            .{ "process", {} },
+            .{ "ShadyDOM", {} },
+            .{ "ShadyCSS", {} },
+
+            // a lot of sites seem to like having their own window.config.
+            .{ "config", {} },
+
+            .{ "litNonce", {} },
+            .{ "litHtmlVersions", {} },
+            .{ "litElementVersions", {} },
+            .{ "litHtmlPolyfillSupport", {} },
+            .{ "litElementHydrateSupport", {} },
+            .{ "litElementPolyfillSupport", {} },
+            .{ "reactiveElementVersions", {} },
+
+            .{ "recaptcha", {} },
+            .{ "grecaptcha", {} },
+            .{ "___grecaptcha_cfg", {} },
+            .{ "__recaptcha_api", {} },
+            .{ "__google_recaptcha_client", {} },
+
+            .{ "CLOSURE_FLAGS", {} },
+            .{ "__REACT_DEVTOOLS_GLOBAL_HOOK__", {} },
+            .{ "ApplePaySession", {} },
+        });
+        if (!ignored.has(property)) {
+            const key = std.fmt.bufPrint(&local.ctx.page.buf, "Window:{s}", .{property}) catch return 0;
+            logUnknownProperty(local, key) catch return 0;
+        }
+    }
+
+    // not intercepted
+    return 0;
+}
+
+// Only used for debugging
+pub fn unknownObjectPropertyCallback(comptime JsApi: type) *const fn (?*const v8.Name, ?*const v8.PropertyCallbackInfo) callconv(.c) u8 {
+    if (comptime !IS_DEBUG) {
+        @compileError("unknownObjectPropertyCallback should only be used in debug builds");
+    }
+
+    return struct {
+        fn wrap(c_name: ?*const v8.Name, handle: ?*const v8.PropertyCallbackInfo) callconv(.c) u8 {
+            const v8_isolate = v8.v8__PropertyCallbackInfo__GetIsolate(handle).?;
+
+            var caller: Caller = undefined;
+            caller.init(v8_isolate);
+            defer caller.deinit();
+
+            const local = &caller.local;
+
+            var hs: js.HandleScope = undefined;
+            hs.init(local.isolate);
+            defer hs.deinit();
+
+            const property: []const u8 = js.String.toSlice(.{ .local = local, .handle = @ptrCast(c_name.?) }) catch {
+                return 0;
+            };
+
+            if (std.mem.startsWith(u8, property, "__")) {
+                // some frameworks will extend built-in types using a __ prefix
+                // these should always be safe to ignore.
+                return 0;
+            }
+
+            if (std.mem.startsWith(u8, property, "jQuery")) {
+                return 0;
+            }
+
+            if (JsApi == @import("../webapi/cdata/Text.zig").JsApi or JsApi == @import("../webapi/cdata/Comment.zig").JsApi) {
+                if (std.mem.eql(u8, property, "tagName")) {
+                    // knockout does this, a lot.
+                    return 0;
+                }
+            }
+
+            if (JsApi == @import("../webapi/element/Html.zig").JsApi or JsApi == @import("../webapi/Element.zig").JsApi or JsApi == @import("../webapi/element/html/Custom.zig").JsApi) {
+                // react ?
+                if (std.mem.eql(u8, property, "props")) return 0;
+                if (std.mem.eql(u8, property, "hydrated")) return 0;
+                if (std.mem.eql(u8, property, "isHydrated")) return 0;
+            }
+
+            if (JsApi == @import("../webapi/Console.zig").JsApi) {
+                if (std.mem.eql(u8, property, "firebug")) return 0;
+            }
+
+            const ignored = std.StaticStringMap(void).initComptime(.{});
+            if (!ignored.has(property)) {
+                const key = std.fmt.bufPrint(&local.ctx.page.buf, "{s}:{s}", .{ if (@hasDecl(JsApi.Meta, "name")) JsApi.Meta.name else @typeName(JsApi), property }) catch return 0;
+                logUnknownProperty(local, key) catch return 0;
+            }
+            // not intercepted
+            return 0;
+        }
+    }.wrap;
+}
+
+fn logUnknownProperty(local: *const js.Local, key: []const u8) !void {
+    const ctx = local.ctx;
+    const gop = try ctx.unknown_properties.getOrPut(ctx.arena, key);
+    if (gop.found_existing) {
+        gop.value_ptr.count += 1;
+    } else {
+        gop.key_ptr.* = try ctx.arena.dupe(u8, key);
+        gop.value_ptr.* = .{
+            .count = 1,
+            .first_stack = try ctx.arena.dupe(u8, (try local.stackTrace()) orelse "???"),
+        };
+    }
+}
+
+// Given a Type, returns the length of the prototype chain, including self
+fn prototypeChainLength(comptime T: type) usize {
+    var l: usize = 1;
+    var Next = T;
+    while (PrototypeType(Next)) |N| {
+        Next = N;
+        l += 1;
+    }
+    return l;
+}
+
+// Given a Type, gets its prototype Type (if any)
+fn PrototypeType(comptime T: type) ?type {
+    if (!@hasField(T, "_proto")) {
+        return null;
+    }
+    return Struct(std.meta.fieldInfo(T, ._proto).type);
+}
+
+fn flattenTypes(comptime Types: []const type) [countFlattenedTypes(Types)]type {
+    var index: usize = 0;
+    var flat: [countFlattenedTypes(Types)]type = undefined;
+    for (Types) |T| {
+        if (@hasDecl(T, "registerTypes")) {
+            for (T.registerTypes()) |TT| {
+                flat[index] = TT.JsApi;
+                index += 1;
+            }
+        } else {
+            flat[index] = T.JsApi;
+            index += 1;
+        }
+    }
+    return flat;
+}
+
+fn countFlattenedTypes(comptime Types: []const type) usize {
+    var c: usize = 0;
+    for (Types) |T| {
+        c += if (@hasDecl(T, "registerTypes")) T.registerTypes().len else 1;
+    }
+    return c;
+}
+
+//  T => T
+// *T => T
+pub fn Struct(comptime T: type) type {
+    return switch (@typeInfo(T)) {
+        .@"struct" => T,
+        .pointer => |ptr| ptr.child,
+        else => @compileError("Expecting Struct or *Struct, got: " ++ @typeName(T)),
+    };
+}
+
+pub const JsApiLookup = struct {
+    /// Integer type we use for `JsApiLookup` enum. Can be u8 at min.
+    pub const BackingInt = std.math.IntFittingRange(0, @max(std.math.maxInt(u8), JsApis.len));
+
+    /// Imagine we have a type `Cat` which has a getter:
+    ///
+    ///    fn get_owner(self: *Cat) *Owner {
+    ///        return self.owner;
+    ///    }
+    ///
+    /// When we execute `caller.getter`, we'll end up doing something like:
+    ///
+    ///    const res = @call(.auto, Cat.get_owner, .{cat_instance});
+    ///
+    /// How do we turn `res`, which is an *Owner, into something we can return
+    /// to v8? We need the ObjectTemplate associated with Owner. How do we
+    /// get that? Well, we store all the ObjectTemplates in an array that's
+    /// tied to env. So we do something like:
+    ///
+    ///    env.templates[index_of_owner].initInstance(...);
+    ///
+    /// But how do we get that `index_of_owner`? `Index` is an enum
+    /// that looks like:
+    ///
+    ///    pub const Enum = enum(BackingInt) {
+    ///        cat = 0,
+    ///        owner = 1,
+    ///        ...
+    ///    }
+    ///
+    /// (`BackingInt` is calculated at comptime regarding to interfaces we have)
+    /// So to get the template index of `owner`, simply do:
+    ///
+    ///    const index_id = types.getId(@TypeOf(res));
+    ///
+    pub const Enum = blk: {
+        var fields: [JsApis.len]std.builtin.Type.EnumField = undefined;
+        for (JsApis, 0..) |JsApi, i| {
+            fields[i] = .{ .name = @typeName(JsApi), .value = i };
+        }
+
+        break :blk @Type(.{
+            .@"enum" = .{
+                .fields = &fields,
+                .tag_type = BackingInt,
+                .is_exhaustive = true,
+                .decls = &.{},
+            },
+        });
+    };
+
+    /// Returns a boolean indicating if a type exist in the lookup.
+    pub inline fn has(t: type) bool {
+        return @hasField(Enum, @typeName(t));
+    }
+
+    /// Returns the `Enum` for the given type.
+    pub inline fn getIndex(t: type) Enum {
+        return @field(Enum, @typeName(t));
+    }
+
+    /// Returns the ID for the given type.
+    pub inline fn getId(t: type) BackingInt {
+        return @intFromEnum(getIndex(t));
+    }
+};
+
+pub const SubType = enum {
+    @"error",
+    array,
+    arraybuffer,
+    dataview,
+    date,
+    generator,
+    iterator,
+    map,
+    node,
+    promise,
+    proxy,
+    regexp,
+    set,
+    typedarray,
+    wasmvalue,
+    weakmap,
+    weakset,
+    webassemblymemory,
+};
+
+pub const JsApis = flattenTypes(&.{
+    @import("../webapi/AbortController.zig"),
+    @import("../webapi/AbortSignal.zig"),
+    @import("../webapi/CData.zig"),
+    @import("../webapi/cdata/Comment.zig"),
+    @import("../webapi/cdata/Text.zig"),
+    @import("../webapi/cdata/CDATASection.zig"),
+    @import("../webapi/cdata/ProcessingInstruction.zig"),
+    @import("../webapi/collections.zig"),
+    @import("../webapi/Console.zig"),
+    @import("../webapi/Crypto.zig"),
+    @import("../webapi/Permissions.zig"),
+    @import("../webapi/StorageManager.zig"),
+    @import("../webapi/CSS.zig"),
+    @import("../webapi/css/CSSRule.zig"),
+    @import("../webapi/css/CSSRuleList.zig"),
+    @import("../webapi/css/CSSStyleDeclaration.zig"),
+    @import("../webapi/css/CSSStyleRule.zig"),
+    @import("../webapi/css/CSSStyleSheet.zig"),
+    @import("../webapi/css/CSSStyleProperties.zig"),
+    @import("../webapi/css/FontFace.zig"),
+    @import("../webapi/css/FontFaceSet.zig"),
+    @import("../webapi/css/MediaQueryList.zig"),
+    @import("../webapi/css/StyleSheetList.zig"),
+    @import("../webapi/Document.zig"),
+    @import("../webapi/HTMLDocument.zig"),
+    @import("../webapi/XMLDocument.zig"),
+    @import("../webapi/History.zig"),
+    @import("../webapi/KeyValueList.zig"),
+    @import("../webapi/DocumentFragment.zig"),
+    @import("../webapi/DocumentType.zig"),
+    @import("../webapi/ShadowRoot.zig"),
+    @import("../webapi/DOMException.zig"),
+    @import("../webapi/DOMImplementation.zig"),
+    @import("../webapi/DOMTreeWalker.zig"),
+    @import("../webapi/DOMNodeIterator.zig"),
+    @import("../webapi/DOMRect.zig"),
+    @import("../webapi/DOMParser.zig"),
+    @import("../webapi/XMLSerializer.zig"),
+    @import("../webapi/AbstractRange.zig"),
+    @import("../webapi/Range.zig"),
+    @import("../webapi/NodeFilter.zig"),
+    @import("../webapi/Element.zig"),
+    @import("../webapi/element/DOMStringMap.zig"),
+    @import("../webapi/element/Attribute.zig"),
+    @import("../webapi/element/Html.zig"),
+    @import("../webapi/element/html/IFrame.zig"),
+    @import("../webapi/element/html/Anchor.zig"),
+    @import("../webapi/element/html/Area.zig"),
+    @import("../webapi/element/html/Audio.zig"),
+    @import("../webapi/element/html/Base.zig"),
+    @import("../webapi/element/html/Body.zig"),
+    @import("../webapi/element/html/BR.zig"),
+    @import("../webapi/element/html/Button.zig"),
+    @import("../webapi/element/html/Canvas.zig"),
+    @import("../webapi/element/html/Custom.zig"),
+    @import("../webapi/element/html/Data.zig"),
+    @import("../webapi/element/html/DataList.zig"),
+    @import("../webapi/element/html/Details.zig"),
+    @import("../webapi/element/html/Dialog.zig"),
+    @import("../webapi/element/html/Directory.zig"),
+    @import("../webapi/element/html/DList.zig"),
+    @import("../webapi/element/html/Div.zig"),
+    @import("../webapi/element/html/Embed.zig"),
+    @import("../webapi/element/html/FieldSet.zig"),
+    @import("../webapi/element/html/Font.zig"),
+    @import("../webapi/element/html/Form.zig"),
+    @import("../webapi/element/html/Generic.zig"),
+    @import("../webapi/element/html/Head.zig"),
+    @import("../webapi/element/html/Heading.zig"),
+    @import("../webapi/element/html/HR.zig"),
+    @import("../webapi/element/html/Html.zig"),
+    @import("../webapi/element/html/Image.zig"),
+    @import("../webapi/element/html/Input.zig"),
+    @import("../webapi/element/html/Label.zig"),
+    @import("../webapi/element/html/Legend.zig"),
+    @import("../webapi/element/html/LI.zig"),
+    @import("../webapi/element/html/Link.zig"),
+    @import("../webapi/element/html/Map.zig"),
+    @import("../webapi/element/html/Media.zig"),
+    @import("../webapi/element/html/Meta.zig"),
+    @import("../webapi/element/html/Meter.zig"),
+    @import("../webapi/element/html/Mod.zig"),
+    @import("../webapi/element/html/Object.zig"),
+    @import("../webapi/element/html/OL.zig"),
+    @import("../webapi/element/html/OptGroup.zig"),
+    @import("../webapi/element/html/Option.zig"),
+    @import("../webapi/element/html/Output.zig"),
+    @import("../webapi/element/html/Paragraph.zig"),
+    @import("../webapi/element/html/Picture.zig"),
+    @import("../webapi/element/html/Param.zig"),
+    @import("../webapi/element/html/Pre.zig"),
+    @import("../webapi/element/html/Progress.zig"),
+    @import("../webapi/element/html/Quote.zig"),
+    @import("../webapi/element/html/Script.zig"),
+    @import("../webapi/element/html/Select.zig"),
+    @import("../webapi/element/html/Slot.zig"),
+    @import("../webapi/element/html/Source.zig"),
+    @import("../webapi/element/html/Span.zig"),
+    @import("../webapi/element/html/Style.zig"),
+    @import("../webapi/element/html/Table.zig"),
+    @import("../webapi/element/html/TableCaption.zig"),
+    @import("../webapi/element/html/TableCell.zig"),
+    @import("../webapi/element/html/TableCol.zig"),
+    @import("../webapi/element/html/TableRow.zig"),
+    @import("../webapi/element/html/TableSection.zig"),
+    @import("../webapi/element/html/Template.zig"),
+    @import("../webapi/element/html/TextArea.zig"),
+    @import("../webapi/element/html/Time.zig"),
+    @import("../webapi/element/html/Title.zig"),
+    @import("../webapi/element/html/Track.zig"),
+    @import("../webapi/element/html/Video.zig"),
+    @import("../webapi/element/html/UL.zig"),
+    @import("../webapi/element/html/Unknown.zig"),
+    @import("../webapi/element/Svg.zig"),
+    @import("../webapi/element/svg/Generic.zig"),
+    @import("../webapi/encoding/TextDecoder.zig"),
+    @import("../webapi/encoding/TextEncoder.zig"),
+    @import("../webapi/encoding/TextEncoderStream.zig"),
+    @import("../webapi/encoding/TextDecoderStream.zig"),
+    @import("../webapi/Event.zig"),
+    @import("../webapi/event/CompositionEvent.zig"),
+    @import("../webapi/event/CustomEvent.zig"),
+    @import("../webapi/event/ErrorEvent.zig"),
+    @import("../webapi/event/MessageEvent.zig"),
+    @import("../webapi/event/ProgressEvent.zig"),
+    @import("../webapi/event/NavigationCurrentEntryChangeEvent.zig"),
+    @import("../webapi/event/PageTransitionEvent.zig"),
+    @import("../webapi/event/PopStateEvent.zig"),
+    @import("../webapi/event/UIEvent.zig"),
+    @import("../webapi/event/MouseEvent.zig"),
+    @import("../webapi/event/PointerEvent.zig"),
+    @import("../webapi/event/KeyboardEvent.zig"),
+    @import("../webapi/event/FocusEvent.zig"),
+    @import("../webapi/event/WheelEvent.zig"),
+    @import("../webapi/event/TextEvent.zig"),
+    @import("../webapi/event/InputEvent.zig"),
+    @import("../webapi/event/PromiseRejectionEvent.zig"),
+    @import("../webapi/event/SubmitEvent.zig"),
+    @import("../webapi/MessageChannel.zig"),
+    @import("../webapi/MessagePort.zig"),
+    @import("../webapi/media/MediaError.zig"),
+    @import("../webapi/media/TextTrackCue.zig"),
+    @import("../webapi/media/VTTCue.zig"),
+    @import("../webapi/animation/Animation.zig"),
+    @import("../webapi/EventTarget.zig"),
+    @import("../webapi/Location.zig"),
+    @import("../webapi/Navigator.zig"),
+    @import("../webapi/net/FormData.zig"),
+    @import("../webapi/net/Headers.zig"),
+    @import("../webapi/net/Request.zig"),
+    @import("../webapi/net/Response.zig"),
+    @import("../webapi/net/URLSearchParams.zig"),
+    @import("../webapi/net/XMLHttpRequest.zig"),
+    @import("../webapi/net/XMLHttpRequestEventTarget.zig"),
+    @import("../webapi/streams/ReadableStream.zig"),
+    @import("../webapi/streams/ReadableStreamDefaultReader.zig"),
+    @import("../webapi/streams/ReadableStreamDefaultController.zig"),
+    @import("../webapi/streams/WritableStream.zig"),
+    @import("../webapi/streams/WritableStreamDefaultWriter.zig"),
+    @import("../webapi/streams/WritableStreamDefaultController.zig"),
+    @import("../webapi/streams/TransformStream.zig"),
+    @import("../webapi/Node.zig"),
+    @import("../webapi/storage/storage.zig"),
+    @import("../webapi/URL.zig"),
+    @import("../webapi/Window.zig"),
+    @import("../webapi/Performance.zig"),
+    @import("../webapi/PluginArray.zig"),
+    @import("../webapi/MutationObserver.zig"),
+    @import("../webapi/IntersectionObserver.zig"),
+    @import("../webapi/CustomElementRegistry.zig"),
+    @import("../webapi/ResizeObserver.zig"),
+    @import("../webapi/IdleDeadline.zig"),
+    @import("../webapi/Blob.zig"),
+    @import("../webapi/File.zig"),
+    @import("../webapi/FileList.zig"),
+    @import("../webapi/FileReader.zig"),
+    @import("../webapi/Screen.zig"),
+    @import("../webapi/VisualViewport.zig"),
+    @import("../webapi/PerformanceObserver.zig"),
+    @import("../webapi/navigation/Navigation.zig"),
+    @import("../webapi/navigation/NavigationHistoryEntry.zig"),
+    @import("../webapi/navigation/NavigationActivation.zig"),
+    @import("../webapi/canvas/CanvasRenderingContext2D.zig"),
+    @import("../webapi/canvas/WebGLRenderingContext.zig"),
+    @import("../webapi/canvas/OffscreenCanvas.zig"),
+    @import("../webapi/canvas/OffscreenCanvasRenderingContext2D.zig"),
+    @import("../webapi/SubtleCrypto.zig"),
+    @import("../webapi/CryptoKey.zig"),
+    @import("../webapi/Selection.zig"),
+    @import("../webapi/ImageData.zig"),
+});

src/browser/js/js.zig

@@ -0,0 +1,355 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+pub const v8 = @import("v8").c;
+
+const string = @import("../../string.zig");
+
+pub const Env = @import("Env.zig");
+pub const bridge = @import("bridge.zig");
+pub const Caller = @import("Caller.zig");
+pub const Origin = @import("Origin.zig");
+pub const Identity = @import("Identity.zig");
+pub const Context = @import("Context.zig");
+pub const Local = @import("Local.zig");
+pub const Inspector = @import("Inspector.zig");
+pub const Snapshot = @import("Snapshot.zig");
+pub const Platform = @import("Platform.zig");
+pub const Isolate = @import("Isolate.zig");
+pub const HandleScope = @import("HandleScope.zig");
+
+pub const Value = @import("Value.zig");
+pub const Array = @import("Array.zig");
+pub const String = @import("String.zig");
+pub const Object = @import("Object.zig");
+pub const TryCatch = @import("TryCatch.zig");
+pub const Function = @import("Function.zig");
+pub const Promise = @import("Promise.zig");
+pub const Module = @import("Module.zig");
+pub const BigInt = @import("BigInt.zig");
+pub const Number = @import("Number.zig");
+pub const Integer = @import("Integer.zig");
+pub const PromiseResolver = @import("PromiseResolver.zig");
+pub const PromiseRejection = @import("PromiseRejection.zig");
+
+const Allocator = std.mem.Allocator;
+
+pub fn Bridge(comptime T: type) type {
+    return bridge.Builder(T);
+}
+
+// If a function returns a []i32, should that map to a plain-old
+// JavaScript array, or a Int32Array? It's ambiguous. By default, we'll
+// map arrays/slices to the JavaScript arrays. If you want a TypedArray
+// wrap it in this.
+// Also, this type has nothing to do with the Env. But we place it here
+// for consistency. Want a callback? Env.Callback. Want a JsObject?
+// Env.JsObject. Want a TypedArray? Env.TypedArray.
+pub fn TypedArray(comptime T: type) type {
+    return struct {
+        values: []const T,
+
+        pub fn dupe(self: TypedArray(T), allocator: Allocator) !TypedArray(T) {
+            return .{ .values = try allocator.dupe(T, self.values) };
+        }
+    };
+}
+
+pub const ArrayBuffer = struct {
+    values: []const u8,
+
+    pub fn dupe(self: ArrayBuffer, allocator: Allocator) !ArrayBuffer {
+        return .{ .values = try allocator.dupe(u8, self.values) };
+    }
+};
+
+pub const ArrayType = enum(u8) {
+    int8,
+    uint8,
+    uint8_clamped,
+    int16,
+    uint16,
+    int32,
+    uint32,
+    float16,
+    float32,
+    float64,
+};
+
+pub fn ArrayBufferRef(comptime kind: ArrayType) type {
+    return struct {
+        const Self = @This();
+
+        const BackingInt = switch (kind) {
+            .int8 => i8,
+            .uint8, .uint8_clamped => u8,
+            .int16 => i16,
+            .uint16 => u16,
+            .int32 => i32,
+            .uint32 => u32,
+            .float16 => f16,
+            .float32 => f32,
+            .float64 => f64,
+        };
+
+        local: *const Local,
+        handle: *const v8.Value,
+
+        /// Persisted typed array.
+        pub const Global = struct {
+            handle: v8.Global,
+
+            pub fn deinit(self: *Global) void {
+                v8.v8__Global__Reset(&self.handle);
+            }
+
+            pub fn local(self: *const Global, l: *const Local) Self {
+                return .{ .local = l, .handle = v8.v8__Global__Get(&self.handle, l.isolate.handle).? };
+            }
+        };
+
+        pub fn init(local: *const Local, size: usize) Self {
+            const ctx = local.ctx;
+            const isolate = ctx.isolate;
+            const bits = switch (@typeInfo(BackingInt)) {
+                .int => |n| n.bits,
+                .float => |f| f.bits,
+                else => unreachable,
+            };
+
+            var array_buffer: *const v8.ArrayBuffer = undefined;
+            if (size == 0) {
+                array_buffer = v8.v8__ArrayBuffer__New(isolate.handle, 0).?;
+            } else {
+                const buffer_len = size * bits / 8;
+                const backing_store = v8.v8__ArrayBuffer__NewBackingStore(isolate.handle, buffer_len).?;
+                const backing_store_ptr = v8.v8__BackingStore__TO_SHARED_PTR(backing_store);
+                array_buffer = v8.v8__ArrayBuffer__New2(isolate.handle, &backing_store_ptr).?;
+            }
+
+            const handle: *const v8.Value = switch (comptime kind) {
+                .int8 => @ptrCast(v8.v8__Int8Array__New(array_buffer, 0, size).?),
+                .uint8 => @ptrCast(v8.v8__Uint8Array__New(array_buffer, 0, size).?),
+                .uint8_clamped => @ptrCast(v8.v8__Uint8ClampedArray__New(array_buffer, 0, size).?),
+                .int16 => @ptrCast(v8.v8__Int16Array__New(array_buffer, 0, size).?),
+                .uint16 => @ptrCast(v8.v8__Uint16Array__New(array_buffer, 0, size).?),
+                .int32 => @ptrCast(v8.v8__Int32Array__New(array_buffer, 0, size).?),
+                .uint32 => @ptrCast(v8.v8__Uint32Array__New(array_buffer, 0, size).?),
+                .float16 => @ptrCast(v8.v8__Float16Array__New(array_buffer, 0, size).?),
+                .float32 => @ptrCast(v8.v8__Float32Array__New(array_buffer, 0, size).?),
+                .float64 => @ptrCast(v8.v8__Float64Array__New(array_buffer, 0, size).?),
+            };
+
+            return .{ .local = local, .handle = handle };
+        }
+
+        pub fn persist(self: *const Self) !Global {
+            var ctx = self.local.ctx;
+            var global: v8.Global = undefined;
+            v8.v8__Global__New(ctx.isolate.handle, self.handle, &global);
+            try ctx.trackGlobal(global);
+
+            return .{ .handle = global };
+        }
+    };
+}
+
+// If a WebAPI takes a []const u8, then we'll coerce any JS value to that string
+// so null -> "null". But if a WebAPI takes an optional string, ?[]const u8,
+// how should we handle null? If the parameter _isn't_ passed, then it's obvious
+// that it should be null, but what if `null` is passed? It's ambiguous, should
+// that be null, or "null"? It could depend on the api. So, `null` passed to
+// ?[]const u8 will be `null`. If you want it to be "null", use a `.js.NullableString`.
+pub const NullableString = struct {
+    value: []const u8,
+};
+
+pub const Exception = struct {
+    local: *const Local,
+    handle: *const v8.Value,
+};
+
+// These are simple types that we can convert to JS with only an isolate. This
+// is separated from the Caller's zigValueToJs to make it available when we
+// don't have a caller (i.e., when setting static attributes on types)
+pub fn simpleZigValueToJs(isolate: Isolate, value: anytype, comptime fail: bool, comptime null_as_undefined: bool) if (fail) *const v8.Value else ?*const v8.Value {
+    switch (@typeInfo(@TypeOf(value))) {
+        .void => return isolate.initUndefined(),
+        .null => if (comptime null_as_undefined) return isolate.initUndefined() else return isolate.initNull(),
+        .bool => return if (value) isolate.initTrue() else isolate.initFalse(),
+        .int => |n| {
+            if (comptime n.bits <= 32) {
+                return @ptrCast(isolate.initInteger(value).handle);
+            }
+            if (value >= 0 and value <= 4_294_967_295) {
+                return @ptrCast(isolate.initInteger(@as(u32, @intCast(value))).handle);
+            }
+            return @ptrCast(isolate.initBigInt(value).handle);
+        },
+        .comptime_int => {
+            if (value > -2_147_483_648 and value <= 4_294_967_295) {
+                return @ptrCast(isolate.initInteger(value).handle);
+            }
+            return @ptrCast(isolate.initBigInt(value).handle);
+        },
+        .float, .comptime_float => return @ptrCast(isolate.initNumber(value).handle),
+        .pointer => |ptr| {
+            if (ptr.size == .slice and ptr.child == u8) {
+                return @ptrCast(isolate.initStringHandle(value));
+            }
+            if (ptr.size == .one) {
+                const one_info = @typeInfo(ptr.child);
+                if (one_info == .array and one_info.array.child == u8) {
+                    return @ptrCast(isolate.initStringHandle(value));
+                }
+            }
+        },
+        .array => return simpleZigValueToJs(isolate, &value, fail, null_as_undefined),
+        .optional => {
+            if (value) |v| {
+                return simpleZigValueToJs(isolate, v, fail, null_as_undefined);
+            }
+            if (comptime null_as_undefined) {
+                return isolate.initUndefined();
+            }
+            return isolate.initNull();
+        },
+        .@"struct" => {
+            switch (@TypeOf(value)) {
+                string.String => return isolate.initStringHandle(value.str()),
+                ArrayBuffer => {
+                    const values = value.values;
+                    const len = values.len;
+                    const backing_store = v8.v8__ArrayBuffer__NewBackingStore(isolate.handle, len);
+                    if (len > 0) {
+                        const data: [*]u8 = @ptrCast(@alignCast(v8.v8__BackingStore__Data(backing_store)));
+                        @memcpy(data[0..len], @as([]const u8, @ptrCast(values))[0..len]);
+                    }
+                    const backing_store_ptr = v8.v8__BackingStore__TO_SHARED_PTR(backing_store);
+                    return @ptrCast(v8.v8__ArrayBuffer__New2(isolate.handle, &backing_store_ptr).?);
+                },
+                // zig fmt: off
+                TypedArray(u8), TypedArray(u16), TypedArray(u32), TypedArray(u64),
+                TypedArray(i8), TypedArray(i16), TypedArray(i32), TypedArray(i64),
+                TypedArray(f32), TypedArray(f64),
+                // zig fmt: on
+                => {
+                    const values = value.values;
+                    const value_type = @typeInfo(@TypeOf(values)).pointer.child;
+                    const len = values.len;
+                    const bits = switch (@typeInfo(value_type)) {
+                        .int => |n| n.bits,
+                        .float => |f| f.bits,
+                        else => @compileError("Invalid TypeArray type: " ++ @typeName(value_type)),
+                    };
+
+                    var array_buffer: *const v8.ArrayBuffer = undefined;
+                    if (len == 0) {
+                        array_buffer = v8.v8__ArrayBuffer__New(isolate.handle, 0).?;
+                    } else {
+                        const buffer_len = len * bits / 8;
+                        const backing_store = v8.v8__ArrayBuffer__NewBackingStore(isolate.handle, buffer_len).?;
+                        const data: [*]u8 = @ptrCast(@alignCast(v8.v8__BackingStore__Data(backing_store)));
+                        @memcpy(data[0..buffer_len], @as([]const u8, @ptrCast(values))[0..buffer_len]);
+                        const backing_store_ptr = v8.v8__BackingStore__TO_SHARED_PTR(backing_store);
+                        array_buffer = v8.v8__ArrayBuffer__New2(isolate.handle, &backing_store_ptr).?;
+                    }
+
+                    switch (@typeInfo(value_type)) {
+                        .int => |n| switch (n.signedness) {
+                            .unsigned => switch (n.bits) {
+                                8 => return @ptrCast(v8.v8__Uint8Array__New(array_buffer, 0, len).?),
+                                16 => return @ptrCast(v8.v8__Uint16Array__New(array_buffer, 0, len).?),
+                                32 => return @ptrCast(v8.v8__Uint32Array__New(array_buffer, 0, len).?),
+                                64 => return @ptrCast(v8.v8__BigUint64Array__New(array_buffer, 0, len).?),
+                                else => {},
+                            },
+                            .signed => switch (n.bits) {
+                                8 => return @ptrCast(v8.v8__Int8Array__New(array_buffer, 0, len).?),
+                                16 => return @ptrCast(v8.v8__Int16Array__New(array_buffer, 0, len).?),
+                                32 => return @ptrCast(v8.v8__Int32Array__New(array_buffer, 0, len).?),
+                                64 => return @ptrCast(v8.v8__BigInt64Array__New(array_buffer, 0, len).?),
+                                else => {},
+                            },
+                        },
+                        .float => |f| switch (f.bits) {
+                            32 => return @ptrCast(v8.v8__Float32Array__New(array_buffer, 0, len).?),
+                            64 => return @ptrCast(v8.v8__Float64Array__New(array_buffer, 0, len).?),
+                            else => {},
+                        },
+                        else => {},
+                    }
+                    // We normally don't fail in this function unless fail == true
+                    // but this can never be valid.
+                    @compileError("Invalid TypeArray type: " ++ @typeName(value_type));
+                },
+                inline String, BigInt, Integer, Number, Value, Object => return value.handle,
+                else => {},
+            }
+        },
+        .@"union" => return simpleZigValueToJs(isolate, std.meta.activeTag(value), fail, null_as_undefined),
+        .@"enum" => {
+            const T = @TypeOf(value);
+            if (@hasDecl(T, "toString")) {
+                return simpleZigValueToJs(isolate, value.toString(), fail, null_as_undefined);
+            }
+        },
+        else => {},
+    }
+    if (fail) {
+        @compileError("Unsupported Zig type " ++ @typeName(@TypeOf(value)));
+    }
+    return null;
+}
+
+// These are here, and not in Inspector.zig, because Inspector.zig isn't always
+// included (e.g. in the wpt build).
+
+// This is called from V8. Whenever the v8 inspector has to describe a value
+// it'll call this function to gets its [optional] subtype - which, from V8's
+// point of view, is an arbitrary string.
+pub export fn v8_inspector__Client__IMPL__valueSubtype(
+    _: *v8.InspectorClientImpl,
+    c_value: *const v8.Value,
+) callconv(.c) [*c]const u8 {
+    const external_entry = Inspector.getTaggedOpaque(c_value) orelse return null;
+    return if (external_entry.subtype) |st| @tagName(st) else null;
+}
+
+// Same as valueSubType above, but for the optional description field.
+// From what I can tell, some drivers _need_ the description field to be
+// present, even if it's empty. So if we have a subType for the value, we'll
+// put an empty description.
+pub export fn v8_inspector__Client__IMPL__descriptionForValueSubtype(
+    _: *v8.InspectorClientImpl,
+    v8_context: *const v8.Context,
+    c_value: *const v8.Value,
+) callconv(.c) [*c]const u8 {
+    _ = v8_context;
+
+    // We _must_ include a non-null description in order for the subtype value
+    // to be included. Besides that, I don't know if the value has any meaning
+    const external_entry = Inspector.getTaggedOpaque(c_value) orelse return null;
+    return if (external_entry.subtype == null) null else "";
+}
+
+test "TaggedAnyOpaque" {
+    // If we grow this, fine, but it should be a conscious decision
+    try std.testing.expectEqual(24, @sizeOf(@import("TaggedOpaque.zig")));
+}

src/browser/loader.zig

@@ -1,90 +0,0 @@
-// Copyright (C) 2023-2024  Lightpanda (Selecy SAS)
-//
-// Francis Bouvier <francis@lightpanda.io>
-// Pierre Tachoire <pierre@lightpanda.io>
-//
-// This program is free software: you can redistribute it and/or modify
-// it under the terms of the GNU Affero General Public License as
-// published by the Free Software Foundation, either version 3 of the
-// License, or (at your option) any later version.
-//
-// This program is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// GNU Affero General Public License for more details.
-//
-// You should have received a copy of the GNU Affero General Public License
-// along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-const std = @import("std");
-
-const user_agent = "Lightpanda.io/1.0";
-
-pub const Loader = struct {
-    client: std.http.Client,
-    // use 16KB for headers buffer size.
-    server_header_buffer: [1024 * 16]u8 = undefined,
-
-    pub const Response = struct {
-        alloc: std.mem.Allocator,
-        req: *std.http.Client.Request,
-
-        pub fn deinit(self: *Response) void {
-            self.req.deinit();
-            self.alloc.destroy(self.req);
-        }
-    };
-
-    pub fn init(alloc: std.mem.Allocator) Loader {
-        return Loader{
-            .client = std.http.Client{
-                .allocator = alloc,
-            },
-        };
-    }
-
-    pub fn deinit(self: *Loader) void {
-        self.client.deinit();
-    }
-
-    // see
-    // https://ziglang.org/documentation/master/std/#A;std:http.Client.fetch
-    // for reference.
-    // The caller is responsible for calling `deinit()` on the `Response`.
-    pub fn get(self: *Loader, alloc: std.mem.Allocator, uri: std.Uri) !Response {
-        var resp = Response{
-            .alloc = alloc,
-            .req = try alloc.create(std.http.Client.Request),
-        };
-        errdefer alloc.destroy(resp.req);
-
-        resp.req.* = try self.client.open(.GET, uri, .{
-            .headers = .{
-                .user_agent = .{ .override = user_agent },
-            },
-            .extra_headers = &.{
-                .{ .name = "Accept", .value = "*/*" },
-                .{ .name = "Accept-Language", .value = "en-US,en;q=0.5" },
-            },
-            .server_header_buffer = &self.server_header_buffer,
-        });
-        errdefer resp.req.deinit();
-
-        try resp.req.send();
-        try resp.req.finish();
-        try resp.req.wait();
-
-        return resp;
-    }
-};
-
-test "basic url get" {
-    const alloc = std.testing.allocator;
-    var loader = Loader.init(alloc);
-    defer loader.deinit();
-
-    var result = try loader.get(alloc, "https://en.wikipedia.org/wiki/Main_Page");
-    defer result.deinit();
-
-    try std.testing.expect(result.req.response.status == std.http.Status.ok);
-}

src/browser/markdown.zig

@@ -0,0 +1,692 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+
+const Page = @import("Page.zig");
+const URL = @import("URL.zig");
+const TreeWalker = @import("webapi/TreeWalker.zig");
+const CData = @import("webapi/CData.zig");
+const Element = @import("webapi/Element.zig");
+const Node = @import("webapi/Node.zig");
+const isAllWhitespace = @import("../string.zig").isAllWhitespace;
+
+pub const Opts = struct {
+    // Options for future customization (e.g., dialect)
+};
+
+const State = struct {
+    const ListType = enum { ordered, unordered };
+    const ListState = struct {
+        type: ListType,
+        index: usize,
+    };
+
+    list_depth: usize = 0,
+    list_stack: [32]ListState = undefined,
+    pre_node: ?*Node = null,
+    in_code: bool = false,
+    in_table: bool = false,
+    table_row_index: usize = 0,
+    table_col_count: usize = 0,
+    last_char_was_newline: bool = true,
+};
+
+fn shouldAddSpacing(tag: Element.Tag) bool {
+    return switch (tag) {
+        .p, .h1, .h2, .h3, .h4, .h5, .h6, .blockquote, .pre, .table => true,
+        else => false,
+    };
+}
+
+fn isLayoutBlock(tag: Element.Tag) bool {
+    return switch (tag) {
+        .main, .section, .article, .nav, .aside, .header, .footer, .div, .ul, .ol => true,
+        else => false,
+    };
+}
+
+fn isStandaloneAnchor(el: *Element) bool {
+    const node = el.asNode();
+    const parent = node.parentNode() orelse return false;
+    const parent_el = parent.is(Element) orelse return false;
+
+    if (!isLayoutBlock(parent_el.getTag())) return false;
+
+    var prev = node.previousSibling();
+    while (prev) |p| : (prev = p.previousSibling()) {
+        if (isSignificantText(p)) return false;
+        if (p.is(Element)) |pe| {
+            if (isVisibleElement(pe)) break;
+        }
+    }
+
+    var next = node.nextSibling();
+    while (next) |n| : (next = n.nextSibling()) {
+        if (isSignificantText(n)) return false;
+        if (n.is(Element)) |ne| {
+            if (isVisibleElement(ne)) break;
+        }
+    }
+
+    return true;
+}
+
+fn isSignificantText(node: *Node) bool {
+    const text = node.is(Node.CData.Text) orelse return false;
+    return !isAllWhitespace(text.getWholeText());
+}
+
+fn isVisibleElement(el: *Element) bool {
+    const tag = el.getTag();
+    return !tag.isMetadata() and tag != .svg;
+}
+
+fn getAnchorLabel(el: *Element) ?[]const u8 {
+    return el.getAttributeSafe(comptime .wrap("aria-label")) orelse el.getAttributeSafe(comptime .wrap("title"));
+}
+
+fn hasBlockDescendant(root: *Node) bool {
+    var tw = TreeWalker.FullExcludeSelf.Elements.init(root, .{});
+    while (tw.next()) |el| {
+        if (el.getTag().isBlock()) return true;
+    }
+    return false;
+}
+
+fn hasVisibleContent(root: *Node) bool {
+    var tw = TreeWalker.FullExcludeSelf.init(root, .{});
+    while (tw.next()) |node| {
+        if (isSignificantText(node)) return true;
+        if (node.is(Element)) |el| {
+            if (!isVisibleElement(el)) {
+                tw.skipChildren();
+            } else if (el.getTag() == .img) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+const Context = struct {
+    state: State,
+    writer: *std.Io.Writer,
+    page: *Page,
+
+    fn ensureNewline(self: *Context) !void {
+        if (!self.state.last_char_was_newline) {
+            try self.writer.writeByte('\n');
+            self.state.last_char_was_newline = true;
+        }
+    }
+
+    fn render(self: *Context, node: *Node) error{WriteFailed}!void {
+        switch (node._type) {
+            .document, .document_fragment => {
+                try self.renderChildren(node);
+            },
+            .element => |el| {
+                try self.renderElement(el);
+            },
+            .cdata => |cd| {
+                if (node.is(Node.CData.Text)) |_| {
+                    var text = cd.getData().str();
+                    if (self.state.pre_node) |pre| {
+                        if (node.parentNode() == pre and node.nextSibling() == null) {
+                            text = std.mem.trimRight(u8, text, " \t\r\n");
+                        }
+                    }
+                    try self.renderText(text);
+                }
+            },
+            else => {},
+        }
+    }
+
+    fn renderChildren(self: *Context, parent: *Node) !void {
+        var it = parent.childrenIterator();
+        while (it.next()) |child| {
+            try self.render(child);
+        }
+    }
+
+    fn renderElement(self: *Context, el: *Element) !void {
+        const tag = el.getTag();
+
+        if (!isVisibleElement(el)) return;
+
+        // --- Opening Tag Logic ---
+
+        // Ensure block elements start on a new line (double newline for paragraphs etc)
+        if (tag.isBlock() and !self.state.in_table) {
+            try self.ensureNewline();
+            if (shouldAddSpacing(tag)) {
+                try self.writer.writeByte('\n');
+            }
+        } else if (tag == .li or tag == .tr) {
+            try self.ensureNewline();
+        }
+
+        // Prefixes
+        switch (tag) {
+            .h1 => try self.writer.writeAll("# "),
+            .h2 => try self.writer.writeAll("## "),
+            .h3 => try self.writer.writeAll("### "),
+            .h4 => try self.writer.writeAll("#### "),
+            .h5 => try self.writer.writeAll("##### "),
+            .h6 => try self.writer.writeAll("###### "),
+            .ul => {
+                if (self.state.list_depth < self.state.list_stack.len) {
+                    self.state.list_stack[self.state.list_depth] = .{ .type = .unordered, .index = 0 };
+                    self.state.list_depth += 1;
+                }
+            },
+            .ol => {
+                if (self.state.list_depth < self.state.list_stack.len) {
+                    self.state.list_stack[self.state.list_depth] = .{ .type = .ordered, .index = 1 };
+                    self.state.list_depth += 1;
+                }
+            },
+            .li => {
+                const indent = if (self.state.list_depth > 0) self.state.list_depth - 1 else 0;
+                for (0..indent) |_| try self.writer.writeAll("  ");
+
+                if (self.state.list_depth > 0 and self.state.list_stack[self.state.list_depth - 1].type == .ordered) {
+                    const current_list = &self.state.list_stack[self.state.list_depth - 1];
+                    try self.writer.print("{d}. ", .{current_list.index});
+                    current_list.index += 1;
+                } else {
+                    try self.writer.writeAll("- ");
+                }
+                self.state.last_char_was_newline = false;
+            },
+            .table => {
+                self.state.in_table = true;
+                self.state.table_row_index = 0;
+                self.state.table_col_count = 0;
+            },
+            .tr => {
+                self.state.table_col_count = 0;
+                try self.writer.writeByte('|');
+            },
+            .td, .th => {
+                // Note: leading pipe handled by previous cell closing or tr opening
+                self.state.last_char_was_newline = false;
+                try self.writer.writeByte(' ');
+            },
+            .blockquote => {
+                try self.writer.writeAll("> ");
+                self.state.last_char_was_newline = false;
+            },
+            .pre => {
+                try self.writer.writeAll("```\n");
+                self.state.pre_node = el.asNode();
+                self.state.last_char_was_newline = true;
+            },
+            .code => {
+                if (self.state.pre_node == null) {
+                    try self.writer.writeByte('`');
+                    self.state.in_code = true;
+                    self.state.last_char_was_newline = false;
+                }
+            },
+            .b, .strong => {
+                try self.writer.writeAll("**");
+                self.state.last_char_was_newline = false;
+            },
+            .i, .em => {
+                try self.writer.writeAll("*");
+                self.state.last_char_was_newline = false;
+            },
+            .s, .del => {
+                try self.writer.writeAll("~~");
+                self.state.last_char_was_newline = false;
+            },
+            .hr => {
+                try self.writer.writeAll("---\n");
+                self.state.last_char_was_newline = true;
+                return;
+            },
+            .br => {
+                if (self.state.in_table) {
+                    try self.writer.writeByte(' ');
+                } else {
+                    try self.writer.writeByte('\n');
+                    self.state.last_char_was_newline = true;
+                }
+                return;
+            },
+            .img => {
+                try self.writer.writeAll("![");
+                if (el.getAttributeSafe(comptime .wrap("alt"))) |alt| {
+                    try self.escape(alt);
+                }
+                try self.writer.writeAll("](");
+                if (el.getAttributeSafe(comptime .wrap("src"))) |src| {
+                    const absolute_src = URL.resolve(self.page.call_arena, self.page.base(), src, .{ .encode = true }) catch src;
+                    try self.writer.writeAll(absolute_src);
+                }
+                try self.writer.writeAll(")");
+                self.state.last_char_was_newline = false;
+                return;
+            },
+            .anchor => {
+                const has_content = hasVisibleContent(el.asNode());
+                const label = getAnchorLabel(el);
+                const href_raw = el.getAttributeSafe(comptime .wrap("href"));
+
+                if (!has_content and label == null and href_raw == null) return;
+
+                const has_block = hasBlockDescendant(el.asNode());
+                const href = if (href_raw) |h| URL.resolve(self.page.call_arena, self.page.base(), h, .{ .encode = true }) catch h else null;
+
+                if (has_block) {
+                    try self.renderChildren(el.asNode());
+                    if (href) |h| {
+                        if (!self.state.last_char_was_newline) try self.writer.writeByte('\n');
+                        try self.writer.writeAll("([](");
+                        try self.writer.writeAll(h);
+                        try self.writer.writeAll("))\n");
+                        self.state.last_char_was_newline = true;
+                    }
+                    return;
+                }
+
+                if (isStandaloneAnchor(el)) {
+                    if (!self.state.last_char_was_newline) try self.writer.writeByte('\n');
+                    try self.writer.writeByte('[');
+                    if (has_content) {
+                        try self.renderChildren(el.asNode());
+                    } else {
+                        try self.writer.writeAll(label orelse "");
+                    }
+                    try self.writer.writeAll("](");
+                    if (href) |h| {
+                        try self.writer.writeAll(h);
+                    }
+                    try self.writer.writeAll(")\n");
+                    self.state.last_char_was_newline = true;
+                    return;
+                }
+
+                try self.writer.writeByte('[');
+                if (has_content) {
+                    try self.renderChildren(el.asNode());
+                } else {
+                    try self.writer.writeAll(label orelse "");
+                }
+                try self.writer.writeAll("](");
+                if (href) |h| {
+                    try self.writer.writeAll(h);
+                }
+                try self.writer.writeByte(')');
+                self.state.last_char_was_newline = false;
+                return;
+            },
+            .input => {
+                const type_attr = el.getAttributeSafe(comptime .wrap("type")) orelse return;
+                if (std.ascii.eqlIgnoreCase(type_attr, "checkbox")) {
+                    const checked = el.getAttributeSafe(comptime .wrap("checked")) != null;
+                    try self.writer.writeAll(if (checked) "[x] " else "[ ] ");
+                    self.state.last_char_was_newline = false;
+                }
+                return;
+            },
+            else => {},
+        }
+
+        // --- Render Children ---
+        try self.renderChildren(el.asNode());
+
+        // --- Closing Tag Logic ---
+
+        // Suffixes
+        switch (tag) {
+            .pre => {
+                if (!self.state.last_char_was_newline) {
+                    try self.writer.writeByte('\n');
+                }
+                try self.writer.writeAll("```\n");
+                self.state.pre_node = null;
+                self.state.last_char_was_newline = true;
+            },
+            .code => {
+                if (self.state.pre_node == null) {
+                    try self.writer.writeByte('`');
+                    self.state.in_code = false;
+                    self.state.last_char_was_newline = false;
+                }
+            },
+            .b, .strong => {
+                try self.writer.writeAll("**");
+                self.state.last_char_was_newline = false;
+            },
+            .i, .em => {
+                try self.writer.writeAll("*");
+                self.state.last_char_was_newline = false;
+            },
+            .s, .del => {
+                try self.writer.writeAll("~~");
+                self.state.last_char_was_newline = false;
+            },
+            .blockquote => {},
+            .ul, .ol => {
+                if (self.state.list_depth > 0) self.state.list_depth -= 1;
+            },
+            .table => {
+                self.state.in_table = false;
+            },
+            .tr => {
+                try self.writer.writeByte('\n');
+                if (self.state.table_row_index == 0) {
+                    try self.writer.writeByte('|');
+                    for (0..self.state.table_col_count) |_| {
+                        try self.writer.writeAll("---|");
+                    }
+                    try self.writer.writeByte('\n');
+                }
+                self.state.table_row_index += 1;
+                self.state.last_char_was_newline = true;
+            },
+            .td, .th => {
+                try self.writer.writeAll(" |");
+                self.state.table_col_count += 1;
+                self.state.last_char_was_newline = false;
+            },
+            else => {},
+        }
+
+        // Post-block newlines
+        if (tag.isBlock() and !self.state.in_table) {
+            try self.ensureNewline();
+        }
+    }
+
+    fn renderText(self: *Context, text: []const u8) !void {
+        if (text.len == 0) return;
+
+        if (self.state.pre_node) |_| {
+            try self.writer.writeAll(text);
+            self.state.last_char_was_newline = text[text.len - 1] == '\n';
+            return;
+        }
+
+        // Check for pure whitespace
+        if (isAllWhitespace(text)) {
+            if (!self.state.last_char_was_newline) {
+                try self.writer.writeByte(' ');
+            }
+            return;
+        }
+
+        // Collapse whitespace
+        var it = std.mem.tokenizeAny(u8, text, " \t\n\r");
+        var first = true;
+        while (it.next()) |word| {
+            if (!first or (!self.state.last_char_was_newline and std.ascii.isWhitespace(text[0]))) {
+                try self.writer.writeByte(' ');
+            }
+
+            try self.escape(word);
+            self.state.last_char_was_newline = false;
+            first = false;
+        }
+
+        // Handle trailing whitespace from the original text
+        if (!first and !self.state.last_char_was_newline and std.ascii.isWhitespace(text[text.len - 1])) {
+            try self.writer.writeByte(' ');
+        }
+    }
+
+    fn escape(self: *Context, text: []const u8) !void {
+        for (text) |c| {
+            switch (c) {
+                '\\', '`', '*', '_', '{', '}', '[', ']', '(', ')', '#', '+', '-', '!', '|' => {
+                    try self.writer.writeByte('\\');
+                    try self.writer.writeByte(c);
+                },
+                else => try self.writer.writeByte(c),
+            }
+        }
+    }
+};
+
+pub fn dump(node: *Node, opts: Opts, writer: *std.Io.Writer, page: *Page) !void {
+    _ = opts;
+    var ctx: Context = .{
+        .state = .{},
+        .writer = writer,
+        .page = page,
+    };
+    try ctx.render(node);
+    if (!ctx.state.last_char_was_newline) {
+        try writer.writeByte('\n');
+    }
+}
+
+fn testMarkdownHTML(html: []const u8, expected: []const u8) !void {
+    const testing = @import("../testing.zig");
+    const page = try testing.test_session.createPage();
+    defer testing.test_session.removePage();
+    page.url = "http://localhost/";
+
+    const doc = page.window._document;
+
+    const div = try doc.createElement("div", null, page);
+    try page.parseHtmlAsChildren(div.asNode(), html);
+
+    var aw: std.Io.Writer.Allocating = .init(testing.allocator);
+    defer aw.deinit();
+    try dump(div.asNode(), .{}, &aw.writer, page);
+
+    try testing.expectString(expected, aw.written());
+}
+
+test "browser.markdown: basic" {
+    try testMarkdownHTML("Hello world", "Hello world\n");
+}
+
+test "browser.markdown: whitespace" {
+    try testMarkdownHTML("<span>A</span> <span>B</span>", "A B\n");
+}
+
+test "browser.markdown: escaping" {
+    try testMarkdownHTML("<p># Not a header</p>", "\n\\# Not a header\n");
+}
+
+test "browser.markdown: strikethrough" {
+    try testMarkdownHTML("<s>deleted</s>", "~~deleted~~\n");
+}
+
+test "browser.markdown: task list" {
+    try testMarkdownHTML(
+        \\<input type="checkbox" checked><input type="checkbox">
+    , "[x] [ ] \n");
+}
+
+test "browser.markdown: ordered list" {
+    try testMarkdownHTML(
+        \\<ol><li>First</li><li>Second</li></ol>
+    , "1. First\n2. Second\n");
+}
+
+test "browser.markdown: table" {
+    try testMarkdownHTML(
+        \\<table><thead><tr><th>Head 1</th><th>Head 2</th></tr></thead>
+        \\<tbody><tr><td>Cell 1</td><td>Cell 2</td></tr></tbody></table>
+    ,
+        \\
+        \\| Head 1 | Head 2 |
+        \\|---|---|
+        \\| Cell 1 | Cell 2 |
+        \\
+    );
+}
+
+test "browser.markdown: nested lists" {
+    try testMarkdownHTML(
+        \\<ul><li>Parent<ul><li>Child</li></ul></li></ul>
+    ,
+        \\- Parent
+        \\  - Child
+        \\
+    );
+}
+
+test "browser.markdown: blockquote" {
+    try testMarkdownHTML("<blockquote>Hello world</blockquote>", "\n> Hello world\n");
+}
+
+test "browser.markdown: links" {
+    try testMarkdownHTML("<a href=\"/relative\">Link</a>", "[Link](http://localhost/relative)\n");
+}
+
+test "browser.markdown: images" {
+    try testMarkdownHTML("<img src=\"logo.png\" alt=\"Logo\">", "![Logo](http://localhost/logo.png)\n");
+}
+
+test "browser.markdown: headings" {
+    try testMarkdownHTML("<h1>Title</h1><h2>Subtitle</h2>",
+        \\
+        \\# Title
+        \\
+        \\## Subtitle
+        \\
+    );
+}
+
+test "browser.markdown: code" {
+    try testMarkdownHTML(
+        \\<p>Use git push</p>
+        \\<pre><code>line 1
+        \\line 2</code></pre>
+    ,
+        \\
+        \\Use git push
+        \\
+        \\```
+        \\line 1
+        \\line 2
+        \\```
+        \\
+    );
+}
+
+test "browser.markdown: block link" {
+    try testMarkdownHTML(
+        \\<a href="https://example.com">
+        \\  <h3>Title</h3>
+        \\  <p>Description</p>
+        \\</a>
+    ,
+        \\
+        \\### Title
+        \\
+        \\Description
+        \\([](https://example.com))
+        \\
+    );
+}
+
+test "browser.markdown: inline link" {
+    try testMarkdownHTML(
+        \\<p>Visit <a href="https://example.com">Example</a>.</p>
+    ,
+        \\
+        \\Visit [Example](https://example.com).
+        \\
+    );
+}
+
+test "browser.markdown: standalone anchors" {
+    // Inside main, with whitespace between anchors -> treated as blocks
+    try testMarkdownHTML(
+        \\<main>
+        \\  <a href="1">Link 1</a>
+        \\  <a href="2">Link 2</a>
+        \\</main>
+    ,
+        \\[Link 1](http://localhost/1)
+        \\[Link 2](http://localhost/2)
+        \\
+    );
+}
+
+test "browser.markdown: mixed anchors in main" {
+    // Anchors surrounded by text should remain inline
+    try testMarkdownHTML(
+        \\<main>
+        \\  Welcome <a href="1">Link 1</a>.
+        \\</main>
+    ,
+        \\Welcome [Link 1](http://localhost/1). 
+        \\
+    );
+}
+
+test "browser.markdown: skip empty links" {
+    try testMarkdownHTML(
+        \\<a href="/"></a>
+        \\<a href="/"><svg></svg></a>
+    ,
+        \\[](http://localhost/)
+        \\[](http://localhost/)
+        \\
+    );
+}
+
+test "browser.markdown: resolve links" {
+    const testing = @import("../testing.zig");
+    const page = try testing.test_session.createPage();
+    defer testing.test_session.removePage();
+    page.url = "https://example.com/a/index.html";
+
+    const doc = page.window._document;
+    const div = try doc.createElement("div", null, page);
+    try page.parseHtmlAsChildren(div.asNode(),
+        \\<a href="b">Link</a>
+        \\<img src="../c.png" alt="Img">
+        \\<a href="/my page">Space</a>
+    );
+
+    var aw: std.Io.Writer.Allocating = .init(testing.allocator);
+    defer aw.deinit();
+    try dump(div.asNode(), .{}, &aw.writer, page);
+
+    try testing.expectString(
+        \\[Link](https://example.com/a/b)
+        \\![Img](https://example.com/c.png) 
+        \\[Space](https://example.com/my%20page)
+        \\
+    , aw.written());
+}
+
+test "browser.markdown: anchor fallback label" {
+    try testMarkdownHTML(
+        \\<a href="/discord" aria-label="Discord Server"><svg></svg></a>
+    , "[Discord Server](http://localhost/discord)\n");
+
+    try testMarkdownHTML(
+        \\<a href="/search" title="Search Site"><svg></svg></a>
+    , "[Search Site](http://localhost/search)\n");
+
+    try testMarkdownHTML(
+        \\<a href="/no-label"><svg></svg></a>
+    , "[](http://localhost/no-label)\n");
+}

src/browser/mime.zig

@@ -1,157 +0,0 @@
-// Copyright (C) 2023-2024  Lightpanda (Selecy SAS)
-//
-// Francis Bouvier <francis@lightpanda.io>
-// Pierre Tachoire <pierre@lightpanda.io>
-//
-// This program is free software: you can redistribute it and/or modify
-// it under the terms of the GNU Affero General Public License as
-// published by the Free Software Foundation, either version 3 of the
-// License, or (at your option) any later version.
-//
-// This program is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// GNU Affero General Public License for more details.
-//
-// You should have received a copy of the GNU Affero General Public License
-// along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-const std = @import("std");
-const testing = std.testing;
-
-const strparser = @import("../str/parser.zig");
-const Reader = strparser.Reader;
-const trim = strparser.trim;
-
-const Self = @This();
-
-const MimeError = error{
-    Empty,
-    TooBig,
-    Invalid,
-    InvalidChar,
-};
-
-mtype: []const u8,
-msubtype: []const u8,
-params: []const u8 = "",
-
-charset: ?[]const u8 = null,
-boundary: ?[]const u8 = null,
-
-pub const Empty = Self{ .mtype = "", .msubtype = "" };
-pub const HTML = Self{ .mtype = "text", .msubtype = "html" };
-pub const Javascript = Self{ .mtype = "application", .msubtype = "javascript" };
-
-// https://mimesniff.spec.whatwg.org/#http-token-code-point
-fn isHTTPCodePoint(c: u8) bool {
-    return switch (c) {
-        '!', '#', '$', '%', '&', '\'', '*', '+', '-', '.', '^' => return true,
-        '_', '`', '|', '~' => return true,
-        else => std.ascii.isAlphanumeric(c),
-    };
-}
-
-fn valid(s: []const u8) bool {
-    const ln = s.len;
-    var i: usize = 0;
-    while (i < ln) {
-        if (!isHTTPCodePoint(s[i])) return false;
-        i += 1;
-    }
-    return true;
-}
-
-// https://mimesniff.spec.whatwg.org/#parsing-a-mime-type
-pub fn parse(s: []const u8) Self.MimeError!Self {
-    const ln = s.len;
-    if (ln == 0) return MimeError.Empty;
-    // limit input size
-    if (ln > 255) return MimeError.TooBig;
-
-    var res = Self{ .mtype = "", .msubtype = "" };
-    var r = Reader{ .s = s };
-
-    res.mtype = trim(r.until('/'));
-    if (res.mtype.len == 0) return MimeError.Invalid;
-    if (!valid(res.mtype)) return MimeError.InvalidChar;
-
-    if (!r.skip()) return MimeError.Invalid;
-    res.msubtype = trim(r.until(';'));
-    if (res.msubtype.len == 0) return MimeError.Invalid;
-    if (!valid(res.msubtype)) return MimeError.InvalidChar;
-
-    if (!r.skip()) return res;
-    res.params = trim(r.tail());
-    if (res.params.len == 0) return MimeError.Invalid;
-
-    // parse well known parameters.
-    // don't check invalid parameter format.
-    var rp = Reader{ .s = res.params };
-    while (true) {
-        const name = trim(rp.until('='));
-        if (!rp.skip()) return res;
-        const value = trim(rp.until(';'));
-
-        if (std.ascii.eqlIgnoreCase(name, "charset")) {
-            res.charset = value;
-        }
-        if (std.ascii.eqlIgnoreCase(name, "boundary")) {
-            res.boundary = value;
-        }
-
-        if (!rp.skip()) return res;
-    }
-
-    return res;
-}
-
-test "parse valid" {
-    for ([_][]const u8{
-        "text/html",
-        " \ttext/html",
-        "text \t/html",
-        "text/ \thtml",
-        "text/html \t",
-    }) |tc| {
-        const m = try Self.parse(tc);
-        try testing.expectEqualStrings("text", m.mtype);
-        try testing.expectEqualStrings("html", m.msubtype);
-    }
-    const m2 = try Self.parse("text/javascript1.5");
-    try testing.expectEqualStrings("text", m2.mtype);
-    try testing.expectEqualStrings("javascript1.5", m2.msubtype);
-
-    const m3 = try Self.parse("text/html; charset=utf-8");
-    try testing.expectEqualStrings("text", m3.mtype);
-    try testing.expectEqualStrings("html", m3.msubtype);
-    try testing.expectEqualStrings("charset=utf-8", m3.params);
-    try testing.expectEqualStrings("utf-8", m3.charset.?);
-
-    const m4 = try Self.parse("text/html; boundary=----");
-    try testing.expectEqualStrings("text", m4.mtype);
-    try testing.expectEqualStrings("html", m4.msubtype);
-    try testing.expectEqualStrings("boundary=----", m4.params);
-    try testing.expectEqualStrings("----", m4.boundary.?);
-}
-
-test "parse invalid" {
-    for ([_][]const u8{
-        "",
-        "te xt/html;",
-        "te@xt/html;",
-        "text/ht@ml;",
-        "text/html;",
-        "/text/html",
-        "/html",
-    }) |tc| {
-        _ = Self.parse(tc) catch continue;
-        try testing.expect(false);
-    }
-}
-
-// Compare type and subtype.
-pub fn eql(self: Self, b: Self) bool {
-    if (!std.mem.eql(u8, self.mtype, b.mtype)) return false;
-    return std.mem.eql(u8, self.msubtype, b.msubtype);
-}

src/browser/parser/Parser.zig

@@ -0,0 +1,472 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+const lp = @import("lightpanda");
+const h5e = @import("html5ever.zig");
+
+const Page = @import("../Page.zig");
+const Node = @import("../webapi/Node.zig");
+const Element = @import("../webapi/Element.zig");
+
+pub const AttributeIterator = h5e.AttributeIterator;
+
+const Allocator = std.mem.Allocator;
+const IS_DEBUG = @import("builtin").mode == .Debug;
+
+pub const ParsedNode = struct {
+    node: *Node,
+
+    // Data associated with this element to be passed back to html5ever as needed
+    // We only have this for Elements. For other types, like comments, it's null.
+    // html5ever should never ask us for this data on a non-element, and we'll
+    // assert that, with this opitonal, to make sure our assumption is correct.
+    data: ?*anyopaque,
+};
+
+const Parser = @This();
+
+page: *Page,
+err: ?Error,
+container: ParsedNode,
+arena: Allocator,
+strings: std.StringHashMapUnmanaged(void),
+
+pub fn init(arena: Allocator, node: *Node, page: *Page) Parser {
+    return .{
+        .err = null,
+        .page = page,
+        .strings = .empty,
+        .arena = arena,
+        .container = ParsedNode{
+            .data = null,
+            .node = node,
+        },
+    };
+}
+
+const Error = struct {
+    err: anyerror,
+    source: Source,
+
+    const Source = enum {
+        pop,
+        append,
+        create_element,
+        create_comment,
+        create_processing_instruction,
+        append_doctype_to_document,
+        add_attrs_if_missing,
+        get_template_content,
+        remove_from_parent,
+        reparent_children,
+        append_before_sibling,
+        append_based_on_parent_node,
+    };
+};
+
+pub fn parse(self: *Parser, html: []const u8) void {
+    h5e.html5ever_parse_document(
+        html.ptr,
+        html.len,
+        &self.container,
+        self,
+        createElementCallback,
+        getDataCallback,
+        appendCallback,
+        parseErrorCallback,
+        popCallback,
+        createCommentCallback,
+        createProcessingInstruction,
+        appendDoctypeToDocument,
+        addAttrsIfMissingCallback,
+        getTemplateContentsCallback,
+        removeFromParentCallback,
+        reparentChildrenCallback,
+        appendBeforeSiblingCallback,
+        appendBasedOnParentNodeCallback,
+    );
+}
+
+pub fn parseXML(self: *Parser, xml: []const u8) void {
+    h5e.xml5ever_parse_document(
+        xml.ptr,
+        xml.len,
+        &self.container,
+        self,
+        createXMLElementCallback,
+        getDataCallback,
+        appendCallback,
+        parseErrorCallback,
+        popCallback,
+        createCommentCallback,
+        createProcessingInstruction,
+        appendDoctypeToDocument,
+        addAttrsIfMissingCallback,
+        getTemplateContentsCallback,
+        removeFromParentCallback,
+        reparentChildrenCallback,
+        appendBeforeSiblingCallback,
+        appendBasedOnParentNodeCallback,
+    );
+}
+
+pub fn parseFragment(self: *Parser, html: []const u8) void {
+    h5e.html5ever_parse_fragment(
+        html.ptr,
+        html.len,
+        &self.container,
+        self,
+        createElementCallback,
+        getDataCallback,
+        appendCallback,
+        parseErrorCallback,
+        popCallback,
+        createCommentCallback,
+        createProcessingInstruction,
+        appendDoctypeToDocument,
+        addAttrsIfMissingCallback,
+        getTemplateContentsCallback,
+        removeFromParentCallback,
+        reparentChildrenCallback,
+        appendBeforeSiblingCallback,
+        appendBasedOnParentNodeCallback,
+    );
+}
+
+pub const Streaming = struct {
+    parser: Parser,
+    handle: ?*anyopaque,
+
+    pub fn init(arena: Allocator, node: *Node, page: *Page) Streaming {
+        return .{
+            .handle = null,
+            .parser = Parser.init(arena, node, page),
+        };
+    }
+
+    pub fn deinit(self: *Streaming) void {
+        if (self.handle) |handle| {
+            h5e.html5ever_streaming_parser_destroy(handle);
+        }
+    }
+
+    pub fn start(self: *Streaming) !void {
+        lp.assert(self.handle == null, "Parser.start non-null handle", .{});
+
+        self.handle = h5e.html5ever_streaming_parser_create(
+            &self.parser.container,
+            &self.parser,
+            createElementCallback,
+            getDataCallback,
+            appendCallback,
+            parseErrorCallback,
+            popCallback,
+            createCommentCallback,
+            createProcessingInstruction,
+            appendDoctypeToDocument,
+            addAttrsIfMissingCallback,
+            getTemplateContentsCallback,
+            removeFromParentCallback,
+            reparentChildrenCallback,
+            appendBeforeSiblingCallback,
+            appendBasedOnParentNodeCallback,
+        ) orelse return error.ParserCreationFailed;
+    }
+
+    pub fn read(self: *Streaming, data: []const u8) !void {
+        const result = h5e.html5ever_streaming_parser_feed(
+            self.handle.?,
+            data.ptr,
+            data.len,
+        );
+
+        if (result != 0) {
+            // Parser panicked - clean up and return error
+            // Note: deinit will destroy the handle if it exists
+            if (self.handle) |handle| {
+                h5e.html5ever_streaming_parser_destroy(handle);
+                self.handle = null;
+            }
+            return error.ParserPanic;
+        }
+    }
+
+    pub fn done(self: *Streaming) void {
+        h5e.html5ever_streaming_parser_finish(self.handle.?);
+    }
+};
+
+fn parseErrorCallback(ctx: *anyopaque, err: h5e.StringSlice) callconv(.c) void {
+    _ = ctx;
+    _ = err;
+    // std.debug.print("PEC: {s}\n", .{err.slice()});
+}
+
+fn popCallback(ctx: *anyopaque, node_ref: *anyopaque) callconv(.c) void {
+    const self: *Parser = @ptrCast(@alignCast(ctx));
+    self._popCallback(getNode(node_ref)) catch |err| {
+        self.err = .{ .err = err, .source = .pop };
+    };
+}
+
+fn _popCallback(self: *Parser, node: *Node) !void {
+    try self.page.nodeComplete(node);
+}
+
+fn createElementCallback(ctx: *anyopaque, data: *anyopaque, qname: h5e.QualName, attributes: h5e.AttributeIterator) callconv(.c) ?*anyopaque {
+    return _createElementCallbackWithDefaultnamespace(ctx, data, qname, attributes, .unknown);
+}
+
+fn createXMLElementCallback(ctx: *anyopaque, data: *anyopaque, qname: h5e.QualName, attributes: h5e.AttributeIterator) callconv(.c) ?*anyopaque {
+    return _createElementCallbackWithDefaultnamespace(ctx, data, qname, attributes, .xml);
+}
+
+fn _createElementCallbackWithDefaultnamespace(ctx: *anyopaque, data: *anyopaque, qname: h5e.QualName, attributes: h5e.AttributeIterator, default_namespace: Element.Namespace) ?*anyopaque {
+    const self: *Parser = @ptrCast(@alignCast(ctx));
+    return self._createElementCallback(data, qname, attributes, default_namespace) catch |err| {
+        self.err = .{ .err = err, .source = .create_element };
+        return null;
+    };
+}
+fn _createElementCallback(self: *Parser, data: *anyopaque, qname: h5e.QualName, attributes: h5e.AttributeIterator, default_namespace: Element.Namespace) !*anyopaque {
+    const page = self.page;
+    const name = qname.local.slice();
+    const namespace_string = qname.ns.slice();
+    const namespace = if (namespace_string.len == 0) default_namespace else Element.Namespace.parse(namespace_string);
+    const node = try page.createElementNS(namespace, name, attributes);
+
+    const pn = try self.arena.create(ParsedNode);
+    pn.* = .{
+        .data = data,
+        .node = node,
+    };
+    return pn;
+}
+
+fn createCommentCallback(ctx: *anyopaque, str: h5e.StringSlice) callconv(.c) ?*anyopaque {
+    const self: *Parser = @ptrCast(@alignCast(ctx));
+    return self._createCommentCallback(str.slice()) catch |err| {
+        self.err = .{ .err = err, .source = .create_comment };
+        return null;
+    };
+}
+fn _createCommentCallback(self: *Parser, str: []const u8) !*anyopaque {
+    const page = self.page;
+    const node = try page.createComment(str);
+    const pn = try self.arena.create(ParsedNode);
+    pn.* = .{
+        .data = null,
+        .node = node,
+    };
+    return pn;
+}
+
+fn createProcessingInstruction(ctx: *anyopaque, target: h5e.StringSlice, data: h5e.StringSlice) callconv(.c) ?*anyopaque {
+    const self: *Parser = @ptrCast(@alignCast(ctx));
+    return self._createProcessingInstruction(target.slice(), data.slice()) catch |err| {
+        self.err = .{ .err = err, .source = .create_processing_instruction };
+        return null;
+    };
+}
+fn _createProcessingInstruction(self: *Parser, target: []const u8, data: []const u8) !*anyopaque {
+    const page = self.page;
+    const node = try page.createProcessingInstruction(target, data);
+    const pn = try self.arena.create(ParsedNode);
+    pn.* = .{
+        .data = null,
+        .node = node,
+    };
+    return pn;
+}
+
+fn appendDoctypeToDocument(ctx: *anyopaque, name: h5e.StringSlice, public_id: h5e.StringSlice, system_id: h5e.StringSlice) callconv(.c) void {
+    const self: *Parser = @ptrCast(@alignCast(ctx));
+    self._appendDoctypeToDocument(name.slice(), public_id.slice(), system_id.slice()) catch |err| {
+        self.err = .{ .err = err, .source = .append_doctype_to_document };
+    };
+}
+fn _appendDoctypeToDocument(self: *Parser, name: []const u8, public_id: []const u8, system_id: []const u8) !void {
+    const page = self.page;
+
+    // Create the DocumentType node
+    const DocumentType = @import("../webapi/DocumentType.zig");
+    const doctype = try page._factory.node(DocumentType{
+        ._proto = undefined,
+        ._name = try page.dupeString(name),
+        ._public_id = try page.dupeString(public_id),
+        ._system_id = try page.dupeString(system_id),
+    });
+
+    // Append it to the document
+    try page.appendNew(self.container.node, .{ .node = doctype.asNode() });
+}
+
+fn addAttrsIfMissingCallback(ctx: *anyopaque, target_ref: *anyopaque, attributes: h5e.AttributeIterator) callconv(.c) void {
+    const self: *Parser = @ptrCast(@alignCast(ctx));
+    self._addAttrsIfMissingCallback(getNode(target_ref), attributes) catch |err| {
+        self.err = .{ .err = err, .source = .add_attrs_if_missing };
+    };
+}
+fn _addAttrsIfMissingCallback(self: *Parser, node: *Node, attributes: h5e.AttributeIterator) !void {
+    const element = node.as(Element);
+    const page = self.page;
+
+    const attr_list = try element.getOrCreateAttributeList(page);
+    while (attributes.next()) |attr| {
+        const name = attr.name.local.slice();
+        const value = attr.value.slice();
+        // putNew only adds if the attribute doesn't already exist
+        try attr_list.putNew(name, value, page);
+    }
+}
+
+fn getTemplateContentsCallback(ctx: *anyopaque, target_ref: *anyopaque) callconv(.c) ?*anyopaque {
+    const self: *Parser = @ptrCast(@alignCast(ctx));
+    return self._getTemplateContentsCallback(getNode(target_ref)) catch |err| {
+        self.err = .{ .err = err, .source = .get_template_content };
+        return null;
+    };
+}
+
+fn _getTemplateContentsCallback(self: *Parser, node: *Node) !*anyopaque {
+    const element = node.as(Element);
+    const template = element._type.html.is(Element.Html.Template) orelse unreachable;
+    const content_node = template.getContent().asNode();
+
+    // Create a ParsedNode wrapper for the content DocumentFragment
+    const pn = try self.arena.create(ParsedNode);
+    pn.* = .{
+        .data = null,
+        .node = content_node,
+    };
+    return pn;
+}
+
+fn getDataCallback(ctx: *anyopaque) callconv(.c) *anyopaque {
+    const pn: *ParsedNode = @ptrCast(@alignCast(ctx));
+    // For non-elements, data is null. But, we expect this to only ever
+    // be called for elements.
+    lp.assert(pn.data != null, "Parser.getDataCallback null data", .{});
+    return pn.data.?;
+}
+
+fn appendCallback(ctx: *anyopaque, parent_ref: *anyopaque, node_or_text: h5e.NodeOrText) callconv(.c) void {
+    const self: *Parser = @ptrCast(@alignCast(ctx));
+    self._appendCallback(getNode(parent_ref), node_or_text) catch |err| {
+        self.err = .{ .err = err, .source = .append };
+    };
+}
+fn _appendCallback(self: *Parser, parent: *Node, node_or_text: h5e.NodeOrText) !void {
+    // child node is guaranteed not to belong to another parent
+    switch (node_or_text.toUnion()) {
+        .node => |cpn| {
+            const child = getNode(cpn);
+            if (child._parent) |previous_parent| {
+                // html5ever says this can't happen, but we might be screwing up
+                // the node on our side. We shouldn't be, but we're seeing this
+                // in the wild, and I'm not sure why. In debug, let's crash so
+                // we can try to figure it out. In release, let's disconnect
+                // the child first.
+                if (comptime IS_DEBUG) {
+                    unreachable;
+                }
+                self.page.removeNode(previous_parent, child, .{ .will_be_reconnected = parent.isConnected() });
+            }
+            try self.page.appendNew(parent, .{ .node = child });
+        },
+        .text => |txt| try self.page.appendNew(parent, .{ .text = txt }),
+    }
+}
+
+fn removeFromParentCallback(ctx: *anyopaque, target_ref: *anyopaque) callconv(.c) void {
+    const self: *Parser = @ptrCast(@alignCast(ctx));
+    self._removeFromParentCallback(getNode(target_ref)) catch |err| {
+        self.err = .{ .err = err, .source = .remove_from_parent };
+    };
+}
+fn _removeFromParentCallback(self: *Parser, node: *Node) !void {
+    const parent = node.parentNode() orelse return;
+    _ = try parent.removeChild(node, self.page);
+}
+
+fn reparentChildrenCallback(ctx: *anyopaque, node_ref: *anyopaque, new_parent_ref: *anyopaque) callconv(.c) void {
+    const self: *Parser = @ptrCast(@alignCast(ctx));
+    self._reparentChildrenCallback(getNode(node_ref), getNode(new_parent_ref)) catch |err| {
+        self.err = .{ .err = err, .source = .reparent_children };
+    };
+}
+fn _reparentChildrenCallback(self: *Parser, node: *Node, new_parent: *Node) !void {
+    try self.page.appendAllChildren(node, new_parent);
+}
+
+fn appendBeforeSiblingCallback(ctx: *anyopaque, sibling_ref: *anyopaque, node_or_text: h5e.NodeOrText) callconv(.c) void {
+    const self: *Parser = @ptrCast(@alignCast(ctx));
+    self._appendBeforeSiblingCallback(getNode(sibling_ref), node_or_text) catch |err| {
+        self.err = .{ .err = err, .source = .append_before_sibling };
+    };
+}
+fn _appendBeforeSiblingCallback(self: *Parser, sibling: *Node, node_or_text: h5e.NodeOrText) !void {
+    const parent = sibling.parentNode() orelse return error.NoParent;
+    const node: *Node = switch (node_or_text.toUnion()) {
+        .node => |cpn| blk: {
+            const child = getNode(cpn);
+            if (child._parent) |previous_parent| {
+                // A custom element constructor may have inserted the node into the
+                // DOM before the parser officially places it (e.g. via foster
+                // parenting). Detach it first so insertNodeRelative's assertion holds.
+                self.page.removeNode(previous_parent, child, .{ .will_be_reconnected = parent.isConnected() });
+            }
+            break :blk child;
+        },
+        .text => |txt| try self.page.createTextNode(txt),
+    };
+    try self.page.insertNodeRelative(parent, node, .{ .before = sibling }, .{});
+}
+
+fn appendBasedOnParentNodeCallback(ctx: *anyopaque, element_ref: *anyopaque, prev_element_ref: *anyopaque, node_or_text: h5e.NodeOrText) callconv(.c) void {
+    const self: *Parser = @ptrCast(@alignCast(ctx));
+    self._appendBasedOnParentNodeCallback(getNode(element_ref), getNode(prev_element_ref), node_or_text) catch |err| {
+        self.err = .{ .err = err, .source = .append_based_on_parent_node };
+    };
+}
+fn _appendBasedOnParentNodeCallback(self: *Parser, element: *Node, prev_element: *Node, node_or_text: h5e.NodeOrText) !void {
+    if (element.parentNode()) |_| {
+        try self._appendBeforeSiblingCallback(element, node_or_text);
+    } else {
+        try self._appendCallback(prev_element, node_or_text);
+    }
+}
+
+fn getNode(ref: *anyopaque) *Node {
+    const pn: *ParsedNode = @ptrCast(@alignCast(ref));
+    return pn.node;
+}
+
+fn asUint(comptime string: anytype) std.meta.Int(
+    .unsigned,
+    @bitSizeOf(@TypeOf(string.*)) - 8, // (- 8) to exclude sentinel 0
+) {
+    const byteLength = @sizeOf(@TypeOf(string.*)) - 1;
+    const expectedType = *const [byteLength:0]u8;
+    if (@TypeOf(string) != expectedType) {
+        @compileError("expected : " ++ @typeName(expectedType) ++ ", got: " ++ @typeName(@TypeOf(string)));
+    }
+
+    return @bitCast(@as(*const [byteLength]u8, string).*);
+}

src/browser/parser/html5ever.zig

@@ -0,0 +1,194 @@
+// Copyright (C) 2023-2025  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const ParsedNode = @import("Parser.zig").ParsedNode;
+
+pub extern "c" fn html5ever_parse_document(
+    html: [*c]const u8,
+    len: usize,
+    doc: *anyopaque,
+    ctx: *anyopaque,
+    createElementCallback: *const fn (ctx: *anyopaque, data: *anyopaque, QualName, AttributeIterator) callconv(.c) ?*anyopaque,
+    elemNameCallback: *const fn (node_ref: *anyopaque) callconv(.c) *anyopaque,
+    appendCallback: *const fn (ctx: *anyopaque, parent_ref: *anyopaque, NodeOrText) callconv(.c) void,
+    parseErrorCallback: *const fn (ctx: *anyopaque, StringSlice) callconv(.c) void,
+    popCallback: *const fn (ctx: *anyopaque, node_ref: *anyopaque) callconv(.c) void,
+    createCommentCallback: *const fn (ctx: *anyopaque, StringSlice) callconv(.c) ?*anyopaque,
+    createProcessingInstruction: *const fn (ctx: *anyopaque, StringSlice, StringSlice) callconv(.c) ?*anyopaque,
+    appendDoctypeToDocument: *const fn (ctx: *anyopaque, StringSlice, StringSlice, StringSlice) callconv(.c) void,
+    addAttrsIfMissingCallback: *const fn (ctx: *anyopaque, target_ref: *anyopaque, AttributeIterator) callconv(.c) void,
+    getTemplateContentsCallback: *const fn (ctx: *anyopaque, target_ref: *anyopaque) callconv(.c) ?*anyopaque,
+    removeFromParentCallback: *const fn (ctx: *anyopaque, target_ref: *anyopaque) callconv(.c) void,
+    reparentChildrenCallback: *const fn (ctx: *anyopaque, node_ref: *anyopaque, new_parent_ref: *anyopaque) callconv(.c) void,
+    appendBeforeSiblingCallback: *const fn (ctx: *anyopaque, sibling_ref: *anyopaque, NodeOrText) callconv(.c) void,
+    appendBasedOnParentNodeCallback: *const fn (ctx: *anyopaque, element_ref: *anyopaque, prev_element_ref: *anyopaque, NodeOrText) callconv(.c) void,
+) void;
+
+pub extern "c" fn html5ever_parse_fragment(
+    html: [*c]const u8,
+    len: usize,
+    doc: *anyopaque,
+    ctx: *anyopaque,
+    createElementCallback: *const fn (ctx: *anyopaque, data: *anyopaque, QualName, AttributeIterator) callconv(.c) ?*anyopaque,
+    elemNameCallback: *const fn (node_ref: *anyopaque) callconv(.c) *anyopaque,
+    appendCallback: *const fn (ctx: *anyopaque, parent_ref: *anyopaque, NodeOrText) callconv(.c) void,
+    parseErrorCallback: *const fn (ctx: *anyopaque, StringSlice) callconv(.c) void,
+    popCallback: *const fn (ctx: *anyopaque, node_ref: *anyopaque) callconv(.c) void,
+    createCommentCallback: *const fn (ctx: *anyopaque, StringSlice) callconv(.c) ?*anyopaque,
+    createProcessingInstruction: *const fn (ctx: *anyopaque, StringSlice, StringSlice) callconv(.c) ?*anyopaque,
+    appendDoctypeToDocument: *const fn (ctx: *anyopaque, StringSlice, StringSlice, StringSlice) callconv(.c) void,
+    addAttrsIfMissingCallback: *const fn (ctx: *anyopaque, target_ref: *anyopaque, AttributeIterator) callconv(.c) void,
+    getTemplateContentsCallback: *const fn (ctx: *anyopaque, target_ref: *anyopaque) callconv(.c) ?*anyopaque,
+    removeFromParentCallback: *const fn (ctx: *anyopaque, target_ref: *anyopaque) callconv(.c) void,
+    reparentChildrenCallback: *const fn (ctx: *anyopaque, node_ref: *anyopaque, new_parent_ref: *anyopaque) callconv(.c) void,
+    appendBeforeSiblingCallback: *const fn (ctx: *anyopaque, sibling_ref: *anyopaque, NodeOrText) callconv(.c) void,
+    appendBasedOnParentNodeCallback: *const fn (ctx: *anyopaque, element_ref: *anyopaque, prev_element_ref: *anyopaque, NodeOrText) callconv(.c) void,
+) void;
+
+pub extern "c" fn html5ever_attribute_iterator_next(ctx: *anyopaque) Nullable(Attribute);
+pub extern "c" fn html5ever_attribute_iterator_count(ctx: *anyopaque) usize;
+
+pub extern "c" fn html5ever_get_memory_usage() MemoryUsage;
+
+pub const MemoryUsage = extern struct {
+    resident: usize,
+    allocated: usize,
+};
+
+// Streaming parser API
+pub extern "c" fn html5ever_streaming_parser_create(
+    doc: *anyopaque,
+    ctx: *anyopaque,
+    createElementCallback: *const fn (ctx: *anyopaque, data: *anyopaque, QualName, AttributeIterator) callconv(.c) ?*anyopaque,
+    elemNameCallback: *const fn (node_ref: *anyopaque) callconv(.c) *anyopaque,
+    appendCallback: *const fn (ctx: *anyopaque, parent_ref: *anyopaque, NodeOrText) callconv(.c) void,
+    parseErrorCallback: *const fn (ctx: *anyopaque, StringSlice) callconv(.c) void,
+    popCallback: *const fn (ctx: *anyopaque, node_ref: *anyopaque) callconv(.c) void,
+    createCommentCallback: *const fn (ctx: *anyopaque, StringSlice) callconv(.c) ?*anyopaque,
+    createProcessingInstruction: *const fn (ctx: *anyopaque, StringSlice, StringSlice) callconv(.c) ?*anyopaque,
+    appendDoctypeToDocument: *const fn (ctx: *anyopaque, StringSlice, StringSlice, StringSlice) callconv(.c) void,
+    addAttrsIfMissingCallback: *const fn (ctx: *anyopaque, target_ref: *anyopaque, AttributeIterator) callconv(.c) void,
+    getTemplateContentsCallback: *const fn (ctx: *anyopaque, target_ref: *anyopaque) callconv(.c) ?*anyopaque,
+    removeFromParentCallback: *const fn (ctx: *anyopaque, target_ref: *anyopaque) callconv(.c) void,
+    reparentChildrenCallback: *const fn (ctx: *anyopaque, node_ref: *anyopaque, new_parent_ref: *anyopaque) callconv(.c) void,
+    appendBeforeSiblingCallback: *const fn (ctx: *anyopaque, sibling_ref: *anyopaque, NodeOrText) callconv(.c) void,
+    appendBasedOnParentNodeCallback: *const fn (ctx: *anyopaque, element_ref: *anyopaque, prev_element_ref: *anyopaque, NodeOrText) callconv(.c) void,
+) ?*anyopaque;
+
+pub extern "c" fn html5ever_streaming_parser_feed(
+    parser: *anyopaque,
+    html: [*c]const u8,
+    len: usize,
+) c_int;
+
+pub extern "c" fn html5ever_streaming_parser_finish(
+    parser: *anyopaque,
+) void;
+
+pub extern "c" fn html5ever_streaming_parser_destroy(
+    parser: *anyopaque,
+) void;
+
+pub fn Nullable(comptime T: type) type {
+    return extern struct {
+        tag: u8,
+        value: T,
+
+        pub fn unwrap(self: @This()) ?T {
+            return if (self.tag == 0) null else self.value;
+        }
+
+        pub fn none() @This() {
+            return .{ .tag = 0, .value = undefined };
+        }
+    };
+}
+
+pub const StringSlice = Slice(u8);
+pub fn Slice(comptime T: type) type {
+    return extern struct {
+        ptr: [*]const T,
+        len: usize,
+
+        pub fn slice(self: @This()) []const T {
+            return self.ptr[0..self.len];
+        }
+    };
+}
+
+pub const QualName = extern struct {
+    prefix: Nullable(StringSlice),
+    ns: StringSlice,
+    local: StringSlice,
+};
+
+pub const Attribute = extern struct {
+    name: QualName,
+    value: StringSlice,
+};
+
+pub const AttributeIterator = extern struct {
+    iter: *anyopaque,
+
+    pub fn next(self: AttributeIterator) ?Attribute {
+        return html5ever_attribute_iterator_next(self.iter).unwrap();
+    }
+
+    pub fn count(self: AttributeIterator) usize {
+        return html5ever_attribute_iterator_count(self.iter);
+    }
+};
+
+pub const NodeOrText = extern struct {
+    tag: u8,
+    node: *anyopaque,
+    text: StringSlice,
+
+    pub fn toUnion(self: NodeOrText) Union {
+        if (self.tag == 0) {
+            return .{ .node = @ptrCast(@alignCast(self.node)) };
+        }
+        return .{ .text = self.text.slice() };
+    }
+
+    const Union = union(enum) {
+        node: *ParsedNode,
+        text: []const u8,
+    };
+};
+
+pub extern "c" fn xml5ever_parse_document(
+    html: [*c]const u8,
+    len: usize,
+    doc: *anyopaque,
+    ctx: *anyopaque,
+    createElementCallback: *const fn (ctx: *anyopaque, data: *anyopaque, QualName, AttributeIterator) callconv(.c) ?*anyopaque,
+    elemNameCallback: *const fn (node_ref: *anyopaque) callconv(.c) *anyopaque,
+    appendCallback: *const fn (ctx: *anyopaque, parent_ref: *anyopaque, NodeOrText) callconv(.c) void,
+    parseErrorCallback: *const fn (ctx: *anyopaque, StringSlice) callconv(.c) void,
+    popCallback: *const fn (ctx: *anyopaque, node_ref: *anyopaque) callconv(.c) void,
+    createCommentCallback: *const fn (ctx: *anyopaque, StringSlice) callconv(.c) ?*anyopaque,
+    createProcessingInstruction: *const fn (ctx: *anyopaque, StringSlice, StringSlice) callconv(.c) ?*anyopaque,
+    appendDoctypeToDocument: *const fn (ctx: *anyopaque, StringSlice, StringSlice, StringSlice) callconv(.c) void,
+    addAttrsIfMissingCallback: *const fn (ctx: *anyopaque, target_ref: *anyopaque, AttributeIterator) callconv(.c) void,
+    getTemplateContentsCallback: *const fn (ctx: *anyopaque, target_ref: *anyopaque) callconv(.c) ?*anyopaque,
+    removeFromParentCallback: *const fn (ctx: *anyopaque, target_ref: *anyopaque) callconv(.c) void,
+    reparentChildrenCallback: *const fn (ctx: *anyopaque, node_ref: *anyopaque, new_parent_ref: *anyopaque) callconv(.c) void,
+    appendBeforeSiblingCallback: *const fn (ctx: *anyopaque, sibling_ref: *anyopaque, NodeOrText) callconv(.c) void,
+    appendBasedOnParentNodeCallback: *const fn (ctx: *anyopaque, element_ref: *anyopaque, prev_element_ref: *anyopaque, NodeOrText) callconv(.c) void,
+) void;

src/browser/reflect.zig

@@ -0,0 +1,28 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+// Gets the Parent of child.
+// HtmlElement.of(script) -> *HTMLElement
+pub fn Struct(comptime T: type) type {
+    return switch (@typeInfo(T)) {
+        .pointer => |ptr| ptr.child,
+        .@"struct" => T,
+        .void => T,
+        else => unreachable,
+    };
+}

src/browser/structured_data.zig

@@ -0,0 +1,489 @@
+// Copyright (C) 2023-2026  Lightpanda (Selecy SAS)
+//
+// Francis Bouvier <francis@lightpanda.io>
+// Pierre Tachoire <pierre@lightpanda.io>
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, either version 3 of the
+// License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+const std = @import("std");
+
+const Page = @import("Page.zig");
+const URL = @import("URL.zig");
+const TreeWalker = @import("webapi/TreeWalker.zig");
+const Element = @import("webapi/Element.zig");
+const Node = @import("webapi/Node.zig");
+
+const Allocator = std.mem.Allocator;
+
+/// Key-value pair for structured data properties.
+pub const Property = struct {
+    key: []const u8,
+    value: []const u8,
+};
+
+pub const AlternateLink = struct {
+    href: []const u8,
+    hreflang: ?[]const u8,
+    type: ?[]const u8,
+    title: ?[]const u8,
+};
+
+pub const StructuredData = struct {
+    json_ld: []const []const u8,
+    open_graph: []const Property,
+    twitter_card: []const Property,
+    meta: []const Property,
+    links: []const Property,
+    alternate: []const AlternateLink,
+
+    pub fn jsonStringify(self: *const StructuredData, jw: anytype) !void {
+        try jw.beginObject();
+
+        try jw.objectField("jsonLd");
+        try jw.write(self.json_ld);
+
+        try jw.objectField("openGraph");
+        try writeProperties(jw, self.open_graph);
+
+        try jw.objectField("twitterCard");
+        try writeProperties(jw, self.twitter_card);
+
+        try jw.objectField("meta");
+        try writeProperties(jw, self.meta);
+
+        try jw.objectField("links");
+        try writeProperties(jw, self.links);
+
+        if (self.alternate.len > 0) {
+            try jw.objectField("alternate");
+            try jw.beginArray();
+            for (self.alternate) |alt| {
+                try jw.beginObject();
+                try jw.objectField("href");
+                try jw.write(alt.href);
+                if (alt.hreflang) |v| {
+                    try jw.objectField("hreflang");
+                    try jw.write(v);
+                }
+                if (alt.type) |v| {
+                    try jw.objectField("type");
+                    try jw.write(v);
+                }
+                if (alt.title) |v| {
+                    try jw.objectField("title");
+                    try jw.write(v);
+                }
+                try jw.endObject();
+            }
+            try jw.endArray();
+        }
+
+        try jw.endObject();
+    }
+};
+
+/// Serializes properties as a JSON object. When a key appears multiple times
+/// (e.g. multiple og:image tags), values are grouped into an array.
+/// Alternatives considered: always-array values (verbose), or an array of
+/// {key, value} pairs (preserves order but less ergonomic for consumers).
+fn writeProperties(jw: anytype, properties: []const Property) !void {
+    try jw.beginObject();
+    for (properties, 0..) |prop, i| {
+        // Skip keys already written by an earlier occurrence.
+        var already_written = false;
+        for (properties[0..i]) |prev| {
+            if (std.mem.eql(u8, prev.key, prop.key)) {
+                already_written = true;
+                break;
+            }
+        }
+        if (already_written) continue;
+
+        // Count total occurrences to decide string vs array.
+        var count: usize = 0;
+        for (properties) |p| {
+            if (std.mem.eql(u8, p.key, prop.key)) count += 1;
+        }
+
+        try jw.objectField(prop.key);
+        if (count == 1) {
+            try jw.write(prop.value);
+        } else {
+            try jw.beginArray();
+            for (properties) |p| {
+                if (std.mem.eql(u8, p.key, prop.key)) {
+                    try jw.write(p.value);
+                }
+            }
+            try jw.endArray();
+        }
+    }
+    try jw.endObject();
+}
+
+/// Extract all structured data from the page.
+pub fn collectStructuredData(
+    root: *Node,
+    arena: Allocator,
+    page: *Page,
+) !StructuredData {
+    var json_ld: std.ArrayList([]const u8) = .empty;
+    var open_graph: std.ArrayList(Property) = .empty;
+    var twitter_card: std.ArrayList(Property) = .empty;
+    var meta: std.ArrayList(Property) = .empty;
+    var links: std.ArrayList(Property) = .empty;
+    var alternate: std.ArrayList(AlternateLink) = .empty;
+
+    // Extract language from the root <html> element.
+    if (root.is(Element)) |root_el| {
+        if (root_el.getAttributeSafe(comptime .wrap("lang"))) |lang| {
+            try meta.append(arena, .{ .key = "language", .value = lang });
+        }
+    } else {
+        // Root is document — check documentElement.
+        var children = root.childrenIterator();
+        while (children.next()) |child| {
+            const el = child.is(Element) orelse continue;
+            if (el.getTag() == .html) {
+                if (el.getAttributeSafe(comptime .wrap("lang"))) |lang| {
+                    try meta.append(arena, .{ .key = "language", .value = lang });
+                }
+                break;
+            }
+        }
+    }
+
+    var tw = TreeWalker.Full.init(root, .{});
+    while (tw.next()) |node| {
+        const el = node.is(Element) orelse continue;
+
+        switch (el.getTag()) {
+            .script => {
+                try collectJsonLd(el, arena, &json_ld);
+                tw.skipChildren();
+            },
+            .meta => collectMeta(el, &open_graph, &twitter_card, &meta, arena) catch {},
+            .title => try collectTitle(node, arena, &meta),
+            .link => try collectLink(el, arena, page, &links, &alternate),
+            // Skip body subtree for non-JSON-LD — all other metadata is in <head>.
+            // JSON-LD can appear in <body> so we don't skip the whole body.
+            else => {},
+        }
+    }
+
+    return .{
+        .json_ld = json_ld.items,
+        .open_graph = open_graph.items,
+        .twitter_card = twitter_card.items,
+        .meta = meta.items,
+        .links = links.items,
+        .alternate = alternate.items,
+    };
+}
+
+fn collectJsonLd(
+    el: *Element,
+    arena: Allocator,
+    json_ld: *std.ArrayList([]const u8),
+) !void {
+    const type_attr = el.getAttributeSafe(comptime .wrap("type")) orelse return;
+    if (!std.ascii.eqlIgnoreCase(type_attr, "application/ld+json")) return;
+
+    var buf: std.Io.Writer.Allocating = .init(arena);
+    try el.asNode().getTextContent(&buf.writer);
+    const text = buf.written();
+    if (text.len > 0) {
+        try json_ld.append(arena, std.mem.trim(u8, text, &std.ascii.whitespace));
+    }
+}
+
+fn collectMeta(
+    el: *Element,
+    open_graph: *std.ArrayList(Property),
+    twitter_card: *std.ArrayList(Property),
+    meta: *std.ArrayList(Property),
+    arena: Allocator,
+) !void {
+    // charset: <meta charset="..."> (no content attribute needed).
+    if (el.getAttributeSafe(comptime .wrap("charset"))) |charset| {
+        try meta.append(arena, .{ .key = "charset", .value = charset });
+    }
+
+    const content = el.getAttributeSafe(comptime .wrap("content")) orelse return;
+
+    // Open Graph: <meta property="og:...">
+    if (el.getAttributeSafe(comptime .wrap("property"))) |property| {
+        if (std.mem.startsWith(u8, property, "og:")) {
+            try open_graph.append(arena, .{ .key = property[3..], .value = content });
+            return;
+        }
+        // Article, profile, etc. are OG sub-namespaces.
+        if (std.mem.startsWith(u8, property, "article:") or
+            std.mem.startsWith(u8, property, "profile:") or
+            std.mem.startsWith(u8, property, "book:") or
+            std.mem.startsWith(u8, property, "music:") or
+            std.mem.startsWith(u8, property, "video:"))
+        {
+            try open_graph.append(arena, .{ .key = property, .value = content });
+            return;
+        }
+    }
+
+    // Twitter Cards: <meta name="twitter:...">
+    if (el.getAttributeSafe(comptime .wrap("name"))) |name| {
+        if (std.mem.startsWith(u8, name, "twitter:")) {
+            try twitter_card.append(arena, .{ .key = name[8..], .value = content });
+            return;
+        }
+
+        // Standard meta tags by name.
+        const known_names = [_][]const u8{
+            "description", "author",    "keywords",    "robots",
+            "viewport",    "generator", "theme-color",
+        };
+        for (known_names) |known| {
+            if (std.ascii.eqlIgnoreCase(name, known)) {
+                try meta.append(arena, .{ .key = known, .value = content });
+                return;
+            }
+        }
+    }
+
+    // http-equiv (e.g. Content-Type, refresh)
+    if (el.getAttributeSafe(comptime .wrap("http-equiv"))) |http_equiv| {
+        try meta.append(arena, .{ .key = http_equiv, .value = content });
+    }
+}
+
+fn collectTitle(
+    node: *Node,
+    arena: Allocator,
+    meta: *std.ArrayList(Property),
+) !void {
+    var buf: std.Io.Writer.Allocating = .init(arena);
+    try node.getTextContent(&buf.writer);
+    const text = std.mem.trim(u8, buf.written(), &std.ascii.whitespace);
+    if (text.len > 0) {
+        try meta.append(arena, .{ .key = "title", .value = text });
+    }
+}
+
+fn collectLink(
+    el: *Element,
+    arena: Allocator,
+    page: *Page,
+    links: *std.ArrayList(Property),
+    alternate: *std.ArrayList(AlternateLink),
+) !void {
+    const rel = el.getAttributeSafe(comptime .wrap("rel")) orelse return;
+    const raw_href = el.getAttributeSafe(comptime .wrap("href")) orelse return;
+    const href = URL.resolve(arena, page.base(), raw_href, .{ .encode = true }) catch raw_href;
+
+    if (std.ascii.eqlIgnoreCase(rel, "alternate")) {
+        try alternate.append(arena, .{
+            .href = href,
+            .hreflang = el.getAttributeSafe(comptime .wrap("hreflang")),
+            .type = el.getAttributeSafe(comptime .wrap("type")),
+            .title = el.getAttributeSafe(comptime .wrap("title")),
+        });
+        return;
+    }
+
+    const relevant_rels = [_][]const u8{
+        "canonical",        "icon",       "manifest", "shortcut icon",
+        "apple-touch-icon", "search",     "author",   "license",
+        "dns-prefetch",     "preconnect",
+    };
+    for (relevant_rels) |known| {
+        if (std.ascii.eqlIgnoreCase(rel, known)) {
+            try links.append(arena, .{ .key = known, .value = href });
+            return;
+        }
+    }
+}
+
+// --- Tests ---
+
+const testing = @import("../testing.zig");
+
+fn testStructuredData(html: []const u8) !StructuredData {
+    const page = try testing.test_session.createPage();
+    defer testing.test_session.removePage();
+
+    const doc = page.window._document;
+    const div = try doc.createElement("div", null, page);
+    try page.parseHtmlAsChildren(div.asNode(), html);
+
+    return collectStructuredData(div.asNode(), page.call_arena, page);
+}
+
+fn findProperty(props: []const Property, key: []const u8) ?[]const u8 {
+    for (props) |p| {
+        if (std.mem.eql(u8, p.key, key)) return p.value;
+    }
+    return null;
+}
+
+test "structured_data: json-ld" {
+    const data = try testStructuredData(
+        \\<script type="application/ld+json">
+        \\{"@context":"https://schema.org","@type":"Article","headline":"Test"}
+        \\</script>
+    );
+    try testing.expectEqual(1, data.json_ld.len);
+    try testing.expect(std.mem.indexOf(u8, data.json_ld[0], "Article") != null);
+}
+
+test "structured_data: multiple json-ld" {
+    const data = try testStructuredData(
+        \\<script type="application/ld+json">{"@type":"Organization"}</script>
+        \\<script type="application/ld+json">{"@type":"BreadcrumbList"}</script>
+        \\<script type="text/javascript">var x = 1;</script>
+    );
+    try testing.expectEqual(2, data.json_ld.len);
+}
+
+test "structured_data: open graph" {
+    const data = try testStructuredData(
+        \\<meta property="og:title" content="My Page">
+        \\<meta property="og:description" content="A description">
+        \\<meta property="og:image" content="https://example.com/img.jpg">
+        \\<meta property="og:url" content="https://example.com">
+        \\<meta property="og:type" content="article">
+        \\<meta property="article:published_time" content="2026-03-10">
+    );
+    try testing.expectEqual(6, data.open_graph.len);
+    try testing.expectEqual("My Page", findProperty(data.open_graph, "title").?);
+    try testing.expectEqual("article", findProperty(data.open_graph, "type").?);
+    try testing.expectEqual("2026-03-10", findProperty(data.open_graph, "article:published_time").?);
+}
+
+test "structured_data: open graph duplicate keys" {
+    const data = try testStructuredData(
+        \\<meta property="og:title" content="My Page">
+        \\<meta property="og:image" content="https://example.com/img1.jpg">
+        \\<meta property="og:image" content="https://example.com/img2.jpg">
+        \\<meta property="og:image" content="https://example.com/img3.jpg">
+    );
+    // Duplicate keys are preserved as separate Property entries.
+    try testing.expectEqual(4, data.open_graph.len);
+
+    // Verify serialization groups duplicates into arrays.
+    const json = try std.json.Stringify.valueAlloc(testing.allocator, data, .{});
+    defer testing.allocator.free(json);
+
+    const parsed = try std.json.parseFromSlice(std.json.Value, testing.allocator, json, .{});
+    defer parsed.deinit();
+    const og = parsed.value.object.get("openGraph").?.object;
+    // "title" appears once → string.
+    switch (og.get("title").?) {
+        .string => {},
+        else => return error.TestUnexpectedResult,
+    }
+    // "image" appears 3 times → array.
+    switch (og.get("image").?) {
+        .array => |arr| try testing.expectEqual(3, arr.items.len),
+        else => return error.TestUnexpectedResult,
+    }
+}
+
+test "structured_data: twitter card" {
+    const data = try testStructuredData(
+        \\<meta name="twitter:card" content="summary_large_image">
+        \\<meta name="twitter:site" content="@example">
+        \\<meta name="twitter:title" content="My Page">
+    );
+    try testing.expectEqual(3, data.twitter_card.len);
+    try testing.expectEqual("summary_large_image", findProperty(data.twitter_card, "card").?);
+    try testing.expectEqual("@example", findProperty(data.twitter_card, "site").?);
+}
+
+test "structured_data: meta tags" {
+    const data = try testStructuredData(
+        \\<title>Page Title</title>
+        \\<meta name="description" content="A test page">
+        \\<meta name="author" content="Test Author">
+        \\<meta name="keywords" content="test, example">
+        \\<meta name="robots" content="index, follow">
+    );
+    try testing.expectEqual("Page Title", findProperty(data.meta, "title").?);
+    try testing.expectEqual("A test page", findProperty(data.meta, "description").?);
+    try testing.expectEqual("Test Author", findProperty(data.meta, "author").?);
+    try testing.expectEqual("test, example", findProperty(data.meta, "keywords").?);
+    try testing.expectEqual("index, follow", findProperty(data.meta, "robots").?);
+}
+
+test "structured_data: link elements" {
+    const data = try testStructuredData(
+        \\<link rel="canonical" href="https://example.com/page">
+        \\<link rel="icon" href="/favicon.ico">
+        \\<link rel="manifest" href="/manifest.json">
+        \\<link rel="stylesheet" href="/style.css">
+    );
+    try testing.expectEqual(3, data.links.len);
+    try testing.expectEqual("https://example.com/page", findProperty(data.links, "canonical").?);
+    // stylesheet should be filtered out
+    try testing.expectEqual(null, findProperty(data.links, "stylesheet"));
+}
+
+test "structured_data: alternate links" {
+    const data = try testStructuredData(
+        \\<link rel="alternate" href="https://example.com/fr" hreflang="fr" title="French">
+        \\<link rel="alternate" href="https://example.com/de" hreflang="de">
+    );
+    try testing.expectEqual(2, data.alternate.len);
+    try testing.expectEqual("fr", data.alternate[0].hreflang.?);
+    try testing.expectEqual("French", data.alternate[0].title.?);
+    try testing.expectEqual("de", data.alternate[1].hreflang.?);
+    try testing.expectEqual(null, data.alternate[1].title);
+}
+
+test "structured_data: non-metadata elements ignored" {
+    const data = try testStructuredData(
+        \\<div>Just text</div>
+        \\<p>More text</p>
+        \\<a href="/link">Link</a>
+    );
+    try testing.expectEqual(0, data.json_ld.len);
+    try testing.expectEqual(0, data.open_graph.len);
+    try testing.expectEqual(0, data.twitter_card.len);
+    try testing.expectEqual(0, data.meta.len);
+    try testing.expectEqual(0, data.links.len);
+}
+
+test "structured_data: charset and http-equiv" {
+    const data = try testStructuredData(
+        \\<meta charset="utf-8">
+        \\<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+    );
+    try testing.expectEqual("utf-8", findProperty(data.meta, "charset").?);
+    try testing.expectEqual("text/html; charset=utf-8", findProperty(data.meta, "Content-Type").?);
+}
+
+test "structured_data: mixed content" {
+    const data = try testStructuredData(
+        \\<title>My Site</title>
+        \\<meta property="og:title" content="OG Title">
+        \\<meta name="twitter:card" content="summary">
+        \\<meta name="description" content="A page">
+        \\<link rel="canonical" href="https://example.com">
+        \\<script type="application/ld+json">{"@type":"WebSite"}</script>
+    );
+    try testing.expectEqual(1, data.json_ld.len);
+    try testing.expectEqual(1, data.open_graph.len);
+    try testing.expectEqual(1, data.twitter_card.len);
+    try testing.expectEqual("My Site", findProperty(data.meta, "title").?);
+    try testing.expectEqual("A page", findProperty(data.meta, "description").?);
+    try testing.expectEqual(1, data.links.len);
+}

src/browser/tests/animation/animation.html

@@ -0,0 +1,70 @@
+<!DOCTYPE html>
+<script src="../testing.js"></script>
+
+<script id=animation>
+  let a1 = document.createElement('div').animate(null, null);
+  testing.expectEqual('idle', a1.playState);
+
+  let cb = [];
+  a1.finished.then((x) => {
+    cb.push(a1.playState);
+    cb.push(x == a1);
+  });
+  a1.ready.then(() => {
+    cb.push(a1.playState);
+    a1.play();
+    cb.push(a1.playState);
+  });
+  testing.onload(() => testing.expectEqual(['idle', 'running', 'finished', true], cb));
+</script>
+
+<!-- <script id=startTime>
+  let a2 = document.createElement('div').animate(null, null);
+  // startTime defaults to null
+  testing.expectEqual(null, a2.startTime);
+  // startTime is settable
+  a2.startTime = 42.5;
+  testing.expectEqual(42.5, a2.startTime);
+  // startTime can be reset to null
+  a2.startTime = null;
+  testing.expectEqual(null, a2.startTime);
+</script>
+
+<script id=onfinish>
+  let a3 = document.createElement('div').animate(null, null);
+  // onfinish defaults to null
+  testing.expectEqual(null, a3.onfinish);
+
+  let calls = [];
+  // onfinish callback should be scheduled and called asynchronously
+  a3.onfinish = function() { calls.push('finish'); };
+  a3.play();
+  testing.onload(() => testing.expectEqual(['finish'], calls));
+</script>
+
+<script id=pause>
+  let a4 = document.createElement('div').animate(null, null);
+  let cb4 = [];
+  a4.finished.then((x) => { cb4.push(a4.playState) });
+  a4.ready.then(() => {
+    a4.play();
+    cb4.push(a4.playState)
+    a4.pause();
+    cb4.push(a4.playState)
+  });
+  testing.onload(() => testing.expectEqual(['running', 'paused'], cb4));
+</script>
+
+<script id=finish>
+  let a5 = document.createElement('div').animate(null, null);
+  testing.expectEqual('idle', a5.playState);
+
+  let cb5 = [];
+  a5.finished.then((x) => { cb5.push(a5.playState) });
+  a5.ready.then(() => {
+    cb5.push(a5.playState);
+    a5.play();
+  });
+  testing.onload(() => testing.expectEqual(['idle', 'finished'], cb5));
+</script>
+ -->

src/browser/tests/blob.html

@@ -0,0 +1,194 @@
+<!DOCTYPE html>
+<meta charset="UTF-8">
+<script src="./testing.js"></script>
+
+<script id=basic>
+  {
+    const parts = ["\r\nthe quick brown\rfo\rx\r", "\njumps over\r\nthe\nlazy\r", "\ndog"];
+    // "transparent" ending should not modify the final buffer.
+    const blob = new Blob(parts, { type: "text/html" });
+
+    const expected = parts.join("");
+    testing.expectEqual(expected.length, blob.size);
+    testing.expectEqual("text/html", blob.type);
+    testing.async(async () => { testing.expectEqual(expected, await blob.text()) });
+  }
+
+  {
+    const parts = ["\rhello\r", "\nwor\r\nld"];
+    // "native" ending should modify the final buffer.
+    const blob = new Blob(parts, { endings: "native" });
+
+    const expected = "\nhello\n\nwor\nld";
+    testing.expectEqual(expected.length, blob.size);
+    testing.async(async () => { testing.expectEqual(expected, await blob.text()) });
+  }
+</script>
+
+<!-- Firefox and Safari only -->
+<script id=bytes>
+  {
+    const parts = ["light ", "panda ", "rocks ", "!"];
+    const blob = new Blob(parts);
+
+    testing.async(async() => {
+      const expected = new Uint8Array([108, 105, 103, 104, 116, 32, 112, 97,
+                                       110, 100, 97, 32, 114, 111, 99, 107, 115,
+                                       32, 33]);
+      const result = await blob.bytes();
+      testing.expectEqual(true, result instanceof Uint8Array);
+      testing.expectEqual(expected, result);
+    });
+  }
+
+  // Test for SIMD.
+  {
+    const parts = [
+      "\rThe opened package\r\nof potato\nchi\rps",
+      "held the\r\nanswer to the\r mystery. Both det\rectives looke\r\rd\r",
+      "\rat it but failed to realize\nit was\r\nthe\rkey\r\n",
+      "\r\nto solve the \rcrime.\r"
+    ];
+
+    const blob = new Blob(parts, { type: "text/html", endings: "native" });
+    testing.expectEqual(161, blob.size);
+    testing.expectEqual("text/html", blob.type);
+    testing.async(async() => {
+      const expected = new Uint8Array([10, 84, 104, 101, 32, 111, 112, 101, 110,
+                                       101, 100, 32, 112, 97, 99, 107, 97, 103,
+                                       101, 10, 111, 102, 32, 112, 111, 116, 97,
+                                       116, 111, 10, 99, 104, 105, 10, 112, 115,
+                                       104, 101, 108, 100, 32, 116, 104, 101, 10,
+                                       97, 110, 115, 119, 101, 114, 32, 116, 111,
+                                       32, 116, 104, 101, 10, 32, 109, 121, 115,
+                                       116, 101, 114, 121, 46, 32, 66, 111, 116,
+                                       104, 32, 100, 101, 116, 10, 101, 99, 116,
+                                       105, 118, 101, 115, 32, 108, 111, 111, 107,
+                                       101, 10, 10, 100, 10, 10, 97, 116, 32, 105,
+                                       116, 32, 98, 117, 116, 32, 102, 97, 105, 108,
+                                       101, 100, 32, 116, 111, 32, 114, 101, 97,
+                                       108, 105, 122, 101, 10, 105, 116, 32, 119, 97,
+                                       115, 10, 116, 104, 101, 10, 107, 101, 121,
+                                       10, 10, 116, 111, 32, 115, 111, 108, 118, 101,
+                                       32, 116, 104, 101, 32, 10, 99, 114, 105, 109,
+                                       101, 46, 10]);
+      const result = await blob.bytes();
+      testing.expectEqual(true, result instanceof Uint8Array);
+      testing.expectEqual(expected, result);
+    });
+  }
+</script>
+
+<script id=stream>
+  {
+    const parts = ["may", "thy", "knife", "chip", "and", "shatter"];
+    const blob = new Blob(parts);
+    const reader = blob.stream().getReader();
+
+    testing.async(async () => {
+      const {done: done, value: value} = await reader.read()
+      const expected = new Uint8Array([109, 97, 121, 116, 104, 121, 107, 110,
+                                       105, 102, 101, 99, 104, 105, 112, 97,
+                                       110, 100, 115, 104, 97, 116, 116, 101,
+                                       114]);
+      testing.expectEqual(false, done);
+      testing.expectEqual(true, value instanceof Uint8Array);
+      testing.expectEqual(expected, value);
+    });
+  }
+</script>
+
+<script id=mime_parsing>
+  // MIME types are lowercased
+  {
+    const blob = new Blob([], { type: "TEXT/HTML" });
+    testing.expectEqual("text/html", blob.type);
+  }
+
+  {
+    const blob = new Blob([], { type: "Application/JSON" });
+    testing.expectEqual("application/json", blob.type);
+  }
+
+  // MIME with parameters - lowercased
+  {
+    const blob = new Blob([], { type: "text/html; charset=UTF-8" });
+    testing.expectEqual("text/html; charset=utf-8", blob.type);
+  }
+
+  // Any ASCII string is accepted and lowercased (no MIME structure validation)
+  {
+    const blob = new Blob([], { type: "invalid" });
+    testing.expectEqual("invalid", blob.type);
+  }
+
+  {
+    const blob = new Blob([], { type: "/" });
+    testing.expectEqual("/", blob.type);
+  }
+
+  // Non-ASCII characters cause empty string (chars outside U+0020-U+007E)
+  {
+    const blob = new Blob([], { type: "ý/x" });
+    testing.expectEqual("", blob.type);
+  }
+
+  {
+    const blob = new Blob([], { type: "text/plàin" });
+    testing.expectEqual("", blob.type);
+  }
+
+  // Control characters cause empty string
+  {
+    const blob = new Blob([], { type: "text/html\x00" });
+    testing.expectEqual("", blob.type);
+  }
+
+  // Empty type stays empty
+  {
+    const blob = new Blob([]);
+    testing.expectEqual("", blob.type);
+  }
+
+  {
+    const blob = new Blob([], { type: "" });
+    testing.expectEqual("", blob.type);
+  }
+</script>
+
+<script id=slice>
+  {
+    const parts = ["la", "symphonie", "des", "éclairs"];
+    const blob = new Blob(parts);
+    testing.async(async () => {
+      const result = await blob.arrayBuffer();
+      testing.expectEqual(true, result instanceof ArrayBuffer)
+    });
+
+    let temp = blob.slice(0);
+    testing.expectEqual(blob.size, temp.size);
+    testing.async(async () => {
+      testing.expectEqual("lasymphoniedeséclairs", await temp.text());
+    });
+
+    temp = blob.slice(-4, -2, "custom");
+    testing.expectEqual(2, temp.size);
+    testing.expectEqual("custom", temp.type);
+    testing.async(async () => {
+      testing.expectEqual("ai", await temp.text());
+    });
+
+    temp = blob.slice(14);
+    testing.expectEqual(8, temp.size);
+    testing.async(async () => {
+      testing.expectEqual("éclairs", await temp.text());
+    });
+
+    temp = blob.slice(6, -10, "text/eclair");
+    testing.expectEqual(6, temp.size);
+    testing.expectEqual("text/eclair", temp.type);
+    testing.async(async () => {
+      testing.expectEqual("honied", await temp.text());
+    });
+  }
+</script>

src/browser/tests/canvas/canvas_rendering_context_2d.html

@@ -0,0 +1,137 @@
+<!DOCTYPE html>
+<script src="../testing.js"></script>
+
+<script id=CanvasRenderingContext2D>
+{
+  const element = document.createElement("canvas");
+  const ctx = element.getContext("2d");
+  testing.expectEqual(true, ctx instanceof CanvasRenderingContext2D);
+  // We can't really test this but let's try to call it at least.
+  ctx.fillRect(0, 0, 0, 0);
+}
+</script>
+
+<script id=CanvasRenderingContext2D#fillStyle>
+{
+  const element = document.createElement("canvas");
+  const ctx = element.getContext("2d");
+
+  // Black by default.
+  testing.expectEqual(ctx.fillStyle, "#000000");
+  ctx.fillStyle = "red";
+  testing.expectEqual(ctx.fillStyle, "#ff0000");
+  ctx.fillStyle = "rebeccapurple";
+  testing.expectEqual(ctx.fillStyle, "#663399");
+  // No changes made if color is invalid.
+  ctx.fillStyle = "invalid-color";
+  testing.expectEqual(ctx.fillStyle, "#663399");
+  ctx.fillStyle = "#fc0";
+  testing.expectEqual(ctx.fillStyle, "#ffcc00");
+  ctx.fillStyle = "#ff0000";
+  testing.expectEqual(ctx.fillStyle, "#ff0000");
+  ctx.fillStyle = "#fF00000F";
+  testing.expectEqual(ctx.fillStyle, "rgba(255, 0, 0, 0.06)");
+}
+</script>
+
+<script id="CanvasRenderingContext2D#createImageData(width, height)">
+{
+  const element = document.createElement("canvas");
+  const ctx = element.getContext("2d");
+
+  const imageData = ctx.createImageData(100, 200);
+  testing.expectEqual(true, imageData instanceof ImageData);
+  testing.expectEqual(imageData.width, 100);
+  testing.expectEqual(imageData.height, 200);
+  testing.expectEqual(imageData.data.length, 100 * 200 * 4);
+  testing.expectEqual(true, imageData.data instanceof Uint8ClampedArray);
+
+  // All pixels should be initialized to 0.
+  testing.expectEqual(imageData.data[0], 0);
+  testing.expectEqual(imageData.data[1], 0);
+  testing.expectEqual(imageData.data[2], 0);
+  testing.expectEqual(imageData.data[3], 0);
+}
+</script>
+
+<script id="CanvasRenderingContext2D#createImageData(imageData)">
+{
+  const element = document.createElement("canvas");
+  const ctx = element.getContext("2d");
+
+  const source = ctx.createImageData(50, 75);
+  const imageData = ctx.createImageData(source);
+  testing.expectEqual(true, imageData instanceof ImageData);
+  testing.expectEqual(imageData.width, 50);
+  testing.expectEqual(imageData.height, 75);
+  testing.expectEqual(imageData.data.length, 50 * 75 * 4);
+}
+</script>
+
+<script id="CanvasRenderingContext2D#putImageData">
+{
+  const element = document.createElement("canvas");
+  const ctx = element.getContext("2d");
+
+  const imageData = ctx.createImageData(10, 10);
+  testing.expectEqual(true, imageData instanceof ImageData);
+  // Modify some pixel data.
+  imageData.data[0] = 255;
+  imageData.data[1] = 0;
+  imageData.data[2] = 0;
+  imageData.data[3] = 255;
+
+  // putImageData should not throw.
+  ctx.putImageData(imageData, 0, 0);
+  ctx.putImageData(imageData, 10, 20);
+  // With dirty rect parameters.
+  ctx.putImageData(imageData, 0, 0, 0, 0, 5, 5);
+}
+</script>
+
+<script id="CanvasRenderingContext2D#getImageData">
+{
+  const element = document.createElement("canvas");
+  element.width = 100;
+  element.height = 50;
+  const ctx = element.getContext("2d");
+
+  const imageData = ctx.getImageData(0, 0, 10, 20);
+  testing.expectEqual(true, imageData instanceof ImageData);
+  testing.expectEqual(imageData.width, 10);
+  testing.expectEqual(imageData.height, 20);
+  testing.expectEqual(imageData.data.length, 10 * 20 * 4);
+  testing.expectEqual(true, imageData.data instanceof Uint8ClampedArray);
+
+  // Undrawn canvas should return transparent black pixels.
+  testing.expectEqual(imageData.data[0], 0);
+  testing.expectEqual(imageData.data[1], 0);
+  testing.expectEqual(imageData.data[2], 0);
+  testing.expectEqual(imageData.data[3], 0);
+}
+</script>
+
+<script id="CanvasRenderingContext2D#getImageData invalid">
+{
+  const element = document.createElement("canvas");
+  const ctx = element.getContext("2d");
+
+  // Zero or negative width/height should throw IndexSizeError.
+  testing.expectError('Index or size', () => ctx.getImageData(0, 0, 0, 10));
+  testing.expectError('Index or size', () => ctx.getImageData(0, 0, 10, 0));
+  testing.expectError('Index or size', () => ctx.getImageData(0, 0, -5, 10));
+  testing.expectError('Index or size', () => ctx.getImageData(0, 0, 10, -5));
+}
+</script>
+
+
+<script id="getter">
+{
+  const element = document.createElement("canvas");
+  const ctx = element.getContext("2d");
+  testing.expectEqual('10px sans-serif', ctx.font);
+  ctx.font = 'bold 48px serif'
+  testing.expectEqual('bold 48px serif', ctx.font);
+
+}
+</script>

src/browser/tests/canvas/offscreen_canvas.html

@@ -0,0 +1,87 @@
+<!DOCTYPE html>
+<script src="../testing.js"></script>
+
+<script id=OffscreenCanvas>
+{
+  const canvas = new OffscreenCanvas(256, 256);
+  testing.expectEqual(true, canvas instanceof OffscreenCanvas);
+  testing.expectEqual(canvas.width, 256);
+  testing.expectEqual(canvas.height, 256);
+}
+</script>
+
+<script id=OffscreenCanvas#width>
+{
+  const canvas = new OffscreenCanvas(100, 200);
+  testing.expectEqual(canvas.width, 100);
+  canvas.width = 300;
+  testing.expectEqual(canvas.width, 300);
+}
+</script>
+
+<script id=OffscreenCanvas#height>
+{
+  const canvas = new OffscreenCanvas(100, 200);
+  testing.expectEqual(canvas.height, 200);
+  canvas.height = 400;
+  testing.expectEqual(canvas.height, 400);
+}
+</script>
+
+<script id=OffscreenCanvas#getContext>
+{
+  const canvas = new OffscreenCanvas(64, 64);
+  const ctx = canvas.getContext("2d");
+  testing.expectEqual(true, ctx instanceof OffscreenCanvasRenderingContext2D);
+  // We can't really test rendering but let's try to call it at least.
+  ctx.fillRect(0, 0, 10, 10);
+}
+</script>
+
+<script id=OffscreenCanvas#convertToBlob>
+{
+  const canvas = new OffscreenCanvas(64, 64);
+  const promise = canvas.convertToBlob();
+  testing.expectEqual(true, promise instanceof Promise);
+  // The promise should resolve to a Blob (even if empty)
+  promise.then(blob => {
+    testing.expectEqual(true, blob instanceof Blob);
+    testing.expectEqual(blob.size, 0); // Empty since no rendering
+  });
+}
+</script>
+
+<script id=HTMLCanvasElement#transferControlToOffscreen>
+{
+  const htmlCanvas = document.createElement("canvas");
+  htmlCanvas.width = 128;
+  htmlCanvas.height = 96;
+  const offscreen = htmlCanvas.transferControlToOffscreen();
+  testing.expectEqual(true, offscreen instanceof OffscreenCanvas);
+  testing.expectEqual(offscreen.width, 128);
+  testing.expectEqual(offscreen.height, 96);
+}
+</script>
+
+<script id=OffscreenCanvasRenderingContext2D#getImageData>
+{
+  const canvas = new OffscreenCanvas(100, 50);
+  const ctx = canvas.getContext("2d");
+
+  const imageData = ctx.getImageData(0, 0, 10, 20);
+  testing.expectEqual(true, imageData instanceof ImageData);
+  testing.expectEqual(imageData.width, 10);
+  testing.expectEqual(imageData.height, 20);
+  testing.expectEqual(imageData.data.length, 10 * 20 * 4);
+
+  // Undrawn canvas should return transparent black pixels.
+  testing.expectEqual(imageData.data[0], 0);
+  testing.expectEqual(imageData.data[1], 0);
+  testing.expectEqual(imageData.data[2], 0);
+  testing.expectEqual(imageData.data[3], 0);
+
+  // Zero or negative dimensions should throw.
+  testing.expectError('Index or size', () => ctx.getImageData(0, 0, 0, 10));
+  testing.expectError('Index or size', () => ctx.getImageData(0, 0, 10, -5));
+}
+</script>

src/browser/tests/canvas/webgl_rendering_context.html

@@ -0,0 +1,87 @@
+<!DOCTYPE html>
+<script src="../testing.js"></script>
+
+<script id=WebGLRenderingContext#getSupportedExtensions>
+{
+  const element = document.createElement("canvas");
+  const ctx = element.getContext("webgl");
+  testing.expectEqual(true, ctx instanceof WebGLRenderingContext);
+
+  const supportedExtensions = ctx.getSupportedExtensions();
+  // The order Chrome prefer.
+  const expectedExtensions = [
+      "ANGLE_instanced_arrays",
+      "EXT_blend_minmax",
+      "EXT_clip_control",
+      "EXT_color_buffer_half_float",
+      "EXT_depth_clamp",
+      "EXT_disjoint_timer_query",
+      "EXT_float_blend",
+      "EXT_frag_depth",
+      "EXT_polygon_offset_clamp",
+      "EXT_shader_texture_lod",
+      "EXT_texture_compression_bptc",
+      "EXT_texture_compression_rgtc",
+      "EXT_texture_filter_anisotropic",
+      "EXT_texture_mirror_clamp_to_edge",
+      "EXT_sRGB",
+      "KHR_parallel_shader_compile",
+      "OES_element_index_uint",
+      "OES_fbo_render_mipmap",
+      "OES_standard_derivatives",
+      "OES_texture_float",
+      "OES_texture_float_linear",
+      "OES_texture_half_float",
+      "OES_texture_half_float_linear",
+      "OES_vertex_array_object",
+      "WEBGL_blend_func_extended",
+      "WEBGL_color_buffer_float",
+      "WEBGL_compressed_texture_astc",
+      "WEBGL_compressed_texture_etc",
+      "WEBGL_compressed_texture_etc1",
+      "WEBGL_compressed_texture_pvrtc",
+      "WEBGL_compressed_texture_s3tc",
+      "WEBGL_compressed_texture_s3tc_srgb",
+      "WEBGL_debug_renderer_info",
+      "WEBGL_debug_shaders",
+      "WEBGL_depth_texture",
+      "WEBGL_draw_buffers",
+      "WEBGL_lose_context",
+      "WEBGL_multi_draw",
+      "WEBGL_polygon_mode"
+  ];
+
+  testing.expectEqual(expectedExtensions.length, supportedExtensions.length);
+  for (let i = 0; i < expectedExtensions.length; i++) {
+    testing.expectEqual(expectedExtensions[i], supportedExtensions[i]);
+  }
+}
+</script>
+
+<script id=WebGLRenderingCanvas#getExtension>
+// WEBGL_debug_renderer_info
+{
+  const element = document.createElement("canvas");
+  const ctx = element.getContext("webgl");
+  const rendererInfo = ctx.getExtension("WEBGL_debug_renderer_info");
+  testing.expectEqual(true, rendererInfo instanceof WEBGL_debug_renderer_info);
+
+  const { UNMASKED_VENDOR_WEBGL, UNMASKED_RENDERER_WEBGL } = rendererInfo;
+  testing.expectEqual(UNMASKED_VENDOR_WEBGL, 0x9245);
+  testing.expectEqual(UNMASKED_RENDERER_WEBGL, 0x9246);
+
+  testing.expectEqual("", ctx.getParameter(UNMASKED_VENDOR_WEBGL));
+  testing.expectEqual("", ctx.getParameter(UNMASKED_RENDERER_WEBGL));
+}
+
+// WEBGL_lose_context
+{
+  const element = document.createElement("canvas");
+  const ctx = element.getContext("webgl");
+  const loseContext = ctx.getExtension("WEBGL_lose_context");
+  testing.expectEqual(true, loseContext instanceof WEBGL_lose_context);
+
+  loseContext.loseContext();
+  loseContext.restoreContext();
+}
+</script>

src/browser/tests/cdata/cdata_section.html

@@ -0,0 +1,217 @@
+cdataClassName<!DOCTYPE html>
+<script src="../testing.js"></script>
+
+<div id="container"></div>
+
+<script id="createInHTMLDocument">
+{
+  try {
+    document.createCDATASection('test');
+    testing.fail('Should have thrown NotSupportedError');
+  } catch (err) {
+    testing.expectEqual('NotSupportedError', err.name);
+  }
+}
+</script>
+
+<script id="createInXMLDocument">
+{
+  const doc = new Document();
+  const cdata = doc.createCDATASection('Hello World');
+
+  testing.expectEqual(4, cdata.nodeType);
+  testing.expectEqual('#cdata-section', cdata.nodeName);
+  testing.expectEqual('Hello World', cdata.data);
+  testing.expectEqual(11, cdata.length);
+}
+</script>
+
+<script id="cdataWithSpecialChars">
+{
+  const doc = new Document();
+  const cdata = doc.createCDATASection('<tag>&amp;"quotes"</tag>');
+
+  testing.expectEqual('<tag>&amp;"quotes"</tag>', cdata.data);
+}
+</script>
+
+<script id="cdataRejectsEndMarker">
+{
+  const doc = new Document();
+
+  testing.withError((err) => {
+    testing.expectEqual('InvalidCharacterError', err.name);
+  }, () => doc.createCDATASection('foo ]]> bar'));
+}
+</script>
+
+<script id="cdataRejectsEndMarkerEdgeCase">
+{
+  const doc = new Document();
+
+  testing.withError((err) => {
+    testing.expectEqual('InvalidCharacterError', err.name);
+  }, () => doc.createCDATASection(']]>'));
+
+  testing.withError((err) => {
+    testing.expectEqual('InvalidCharacterError', err.name);
+  }, () => doc.createCDATASection('start]]>end'));
+}
+</script>
+
+<script id="cdataAllowsSimilarPatterns">
+{
+  const doc = new Document();
+
+  const cdata1 = doc.createCDATASection(']>');
+  testing.expectEqual(']>', cdata1.data);
+
+  const cdata2 = doc.createCDATASection(']]');
+  testing.expectEqual(']]', cdata2.data);
+
+  const cdata3 = doc.createCDATASection('] ]>');
+  testing.expectEqual('] ]>', cdata3.data);
+}
+</script>
+
+<script id="cdataCharacterDataMethods">
+{
+  const doc = new Document();
+  const cdata = doc.createCDATASection('Hello');
+
+  cdata.appendData(' World');
+  testing.expectEqual('Hello World', cdata.data);
+  testing.expectEqual(11, cdata.length);
+
+  cdata.deleteData(5, 6);
+  testing.expectEqual('Hello', cdata.data);
+
+  cdata.insertData(0, 'Hi ');
+  testing.expectEqual('Hi Hello', cdata.data);
+
+  cdata.replaceData(0, 3, 'Bye');
+  testing.expectEqual('ByeHello', cdata.data);
+
+  const sub = cdata.substringData(0, 3);
+  testing.expectEqual('Bye', sub);
+}
+</script>
+
+<script id="cdataInheritance">
+{
+  const doc = new Document();
+  const cdata = doc.createCDATASection('test');
+
+  testing.expectEqual(true, cdata instanceof CDATASection);
+  testing.expectEqual(true, cdata instanceof Text);
+  testing.expectEqual(true, cdata instanceof CharacterData);
+  testing.expectEqual(true, cdata instanceof Node);
+}
+</script>
+
+<script id="cdataWholeText">
+{
+  const doc = new Document();
+  const cdata = doc.createCDATASection('test data');
+
+  testing.expectEqual('test data', cdata.wholeText);
+}
+</script>
+
+<script id="cdataClone">
+{
+  const doc = new Document();
+  const cdata = doc.createCDATASection('original data');
+
+  const clone = cdata.cloneNode(false);
+
+  testing.expectEqual(4, clone.nodeType);
+  testing.expectEqual('#cdata-section', clone.nodeName);
+  testing.expectEqual('original data', clone.data);
+  testing.expectEqual(true, clone !== cdata);
+}
+</script>
+
+<script id="cdataRemove">
+{
+  const doc = new Document();
+  const cdata = doc.createCDATASection('test');
+
+  const root = doc.createElement('root');
+  doc.appendChild(root);
+  root.appendChild(cdata);
+
+  testing.expectEqual(1, root.childNodes.length);
+  testing.expectEqual(root, cdata.parentNode);
+
+  cdata.remove();
+  testing.expectEqual(0, root.childNodes.length);
+  testing.expectEqual(null, cdata.parentNode);
+}
+</script>
+
+<script id="cdataBeforeAfter">
+{
+  const doc = new Document();
+  const root = doc.createElement('root');
+  doc.appendChild(root);
+
+  const cdata = doc.createCDATASection('middle');
+  root.appendChild(cdata);
+
+  const text1 = doc.createTextNode('before');
+  const text2 = doc.createTextNode('after');
+
+  cdata.before(text1);
+  cdata.after(text2);
+
+  testing.expectEqual(3, root.childNodes.length);
+}
+</script>
+
+<script id="cdataReplaceWith">
+{
+  const doc = new Document();
+  const root = doc.createElement('root');
+  doc.appendChild(root);
+
+  const cdata = doc.createCDATASection('old');
+  root.appendChild(cdata);
+
+  const replacement = doc.createTextNode('new');
+  cdata.replaceWith(replacement);
+
+  testing.expectEqual(1, root.childNodes.length);
+  testing.expectEqual('new', root.childNodes[0].data);
+  testing.expectEqual(null, cdata.parentNode);
+}
+</script>
+
+<script id="cdataSiblingNavigation">
+{
+  const doc = new Document();
+  const root = doc.createElement('root');
+  doc.appendChild(root);
+
+  const elem1 = doc.createElement('first');
+  const cdata = doc.createCDATASection('middle');
+  const elem2 = doc.createElement('last');
+
+  root.appendChild(elem1);
+  root.appendChild(cdata);
+  root.appendChild(elem2);
+
+  testing.expectEqual('last', cdata.nextElementSibling.tagName);
+  testing.expectEqual('first', cdata.previousElementSibling.tagName);
+}
+</script>
+
+<script id="cdataEmptyString">
+{
+  const doc = new Document();
+  const cdata = doc.createCDATASection('');
+
+  testing.expectEqual('', cdata.data);
+  testing.expectEqual(0, cdata.length);
+}
+</script>

src/browser/tests/cdata/character_data.html

@@ -0,0 +1,730 @@
+<!DOCTYPE html>
+<script src="../testing.js"></script>
+
+<div id="container"></div>
+
+<script id="lengthProperty">
+{
+  // length property
+  const text = document.createTextNode('Hello');
+  testing.expectEqual(5, text.length);
+  testing.expectEqual(5, text.data.length);
+
+  const empty = document.createTextNode('');
+  testing.expectEqual(0, empty.length);
+
+  const comment = document.createComment('test comment');
+  testing.expectEqual(12, comment.length);
+}
+</script>
+
+<script id="appendDataBasic">
+{
+  // appendData basic
+  const text = document.createTextNode('Hello');
+  text.appendData(' World');
+  testing.expectEqual('Hello World', text.data);
+  testing.expectEqual(11, text.length);
+}
+</script>
+
+<script id="appendDataEmpty">
+{
+  // appendData to empty
+  const text = document.createTextNode('');
+  text.appendData('First');
+  testing.expectEqual('First', text.data);
+
+  // appendData empty string
+  text.appendData('');
+  testing.expectEqual('First', text.data);
+}
+</script>
+
+<script id="deleteDataBasic">
+{
+  // deleteData from middle
+  const text = document.createTextNode('Hello World');
+  text.deleteData(5, 6); // Remove ' World'
+  testing.expectEqual('Hello', text.data);
+  testing.expectEqual(5, text.length);
+}
+</script>
+
+<script id="deleteDataStart">
+{
+  // deleteData from start
+  const text = document.createTextNode('Hello World');
+  text.deleteData(0, 6); // Remove 'Hello '
+  testing.expectEqual('World', text.data);
+}
+</script>
+
+<script id="deleteDataEnd">
+{
+  // deleteData from end
+  const text = document.createTextNode('Hello World');
+  text.deleteData(5, 100); // Remove ' World' (count exceeds length)
+  testing.expectEqual('Hello', text.data);
+}
+</script>
+
+<script id="deleteDataAll">
+{
+  // deleteData everything
+  const text = document.createTextNode('Hello');
+  text.deleteData(0, 5);
+  testing.expectEqual('', text.data);
+  testing.expectEqual(0, text.length);
+}
+</script>
+
+<script id="deleteDataZeroCount">
+{
+  // deleteData with count=0
+  const text = document.createTextNode('Hello');
+  text.deleteData(2, 0);
+  testing.expectEqual('Hello', text.data);
+}
+</script>
+
+<script id="deleteDataInvalidOffset">
+{
+  // deleteData with invalid offset
+  const text = document.createTextNode('Hello');
+  testing.expectError('IndexSizeError: Index or size is negative or greater than the allowed amount', () => text.deleteData(10, 5));
+  testing.expectEqual('Hello', text.data); // unchanged
+}
+</script>
+
+<script id="insertDataMiddle">
+{
+  // insertData in middle
+  const text = document.createTextNode('Hello');
+  text.insertData(5, ' World');
+  testing.expectEqual('Hello World', text.data);
+}
+</script>
+
+<script id="insertDataStart">
+{
+  // insertData at start
+  const text = document.createTextNode('World');
+  text.insertData(0, 'Hello ');
+  testing.expectEqual('Hello World', text.data);
+}
+</script>
+
+<script id="insertDataEnd">
+{
+  // insertData at end
+  const text = document.createTextNode('Hello');
+  text.insertData(5, ' World');
+  testing.expectEqual('Hello World', text.data);
+}
+</script>
+
+<script id="insertDataEmpty">
+{
+  // insertData into empty
+  const text = document.createTextNode('');
+  text.insertData(0, 'Hello');
+  testing.expectEqual('Hello', text.data);
+}
+</script>
+
+<script id="insertDataInvalidOffset">
+{
+  // insertData with invalid offset
+  const text = document.createTextNode('Hello');
+  testing.expectError('IndexSizeError: Index or size is negative or greater than the allowed amount', () => text.insertData(10, 'X'));
+  testing.expectEqual('Hello', text.data);
+}
+</script>
+
+<script id="replaceDataBasic">
+{
+  // replaceData basic
+  const text = document.createTextNode('Hello World');
+  text.replaceData(6, 5, 'Universe');
+  testing.expectEqual('Hello Universe', text.data);
+}
+</script>
+
+<script id="replaceDataShorter">
+{
+  // replaceData with shorter string
+  const text = document.createTextNode('Hello World');
+  text.replaceData(6, 5, 'Hi');
+  testing.expectEqual('Hello Hi', text.data);
+}
+</script>
+
+<script id="replaceDataLonger">
+{
+  // replaceData with longer string
+  const text = document.createTextNode('Hello Hi');
+  text.replaceData(6, 2, 'World');
+  testing.expectEqual('Hello World', text.data);
+}
+</script>
+
+<script id="replaceDataExceedingCount">
+{
+  // replaceData with count exceeding length
+  const text = document.createTextNode('Hello World');
+  text.replaceData(6, 100, 'Everyone');
+  testing.expectEqual('Hello Everyone', text.data);
+}
+</script>
+
+<script id="replaceDataZeroCount">
+{
+  // replaceData with count=0 (acts like insert)
+  const text = document.createTextNode('Hello World');
+  text.replaceData(5, 0, '!!!');
+  testing.expectEqual('Hello!!! World', text.data);
+}
+</script>
+
+<script id="substringDataBasic">
+{
+  // substringData basic
+  const text = document.createTextNode('Hello World');
+  const sub = text.substringData(0, 5);
+  testing.expectEqual('Hello', sub);
+  testing.expectEqual('Hello World', text.data); // original unchanged
+}
+</script>
+
+<script id="substringDataMiddle">
+{
+  // substringData from middle
+  const text = document.createTextNode('Hello World');
+  const sub = text.substringData(6, 5);
+  testing.expectEqual('World', sub);
+}
+</script>
+
+<script id="substringDataExceedingCount">
+{
+  // substringData with count exceeding length
+  const text = document.createTextNode('Hello World');
+  const sub = text.substringData(6, 100);
+  testing.expectEqual('World', sub);
+}
+</script>
+
+<script id="substringDataZeroCount">
+{
+  // substringData with count=0
+  const text = document.createTextNode('Hello');
+  const sub = text.substringData(0, 0);
+  testing.expectEqual('', sub);
+}
+</script>
+
+<script id="substringDataInvalidOffset">
+{
+  // substringData with invalid offset
+  const text = document.createTextNode('Hello');
+  testing.expectError('IndexSizeError: Index or size is negative or greater than the allowed amount', () => text.substringData(10, 5));
+}
+</script>
+
+<script id="commentCharacterData">
+{
+  // CharacterData methods work on comments too
+  const comment = document.createComment('Hello');
+
+  comment.appendData(' World');
+  testing.expectEqual('Hello World', comment.data);
+
+  comment.deleteData(5, 6);
+  testing.expectEqual('Hello', comment.data);
+
+  comment.insertData(0, 'Start: ');
+  testing.expectEqual('Start: Hello', comment.data);
+
+  comment.replaceData(0, 7, 'End: ');
+  testing.expectEqual('End: Hello', comment.data);
+
+  const sub = comment.substringData(5, 5);
+  testing.expectEqual('Hello', sub);
+}
+</script>
+
+<script id="dataChangeNotifications">
+{
+  // Verify data changes are reflected in DOM
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const text = document.createTextNode('Original');
+  container.appendChild(text);
+
+  text.appendData(' Text');
+  testing.expectEqual('Original Text', container.textContent);
+
+  text.deleteData(0, 9);
+  testing.expectEqual('Text', container.textContent);
+
+  text.data = 'Changed';
+  testing.expectEqual('Changed', container.textContent);
+}
+</script>
+
+<script id="removeWithSiblings">
+{
+  // remove() when node has siblings
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const text1 = document.createTextNode('A');
+  const text2 = document.createTextNode('B');
+  const text3 = document.createTextNode('C');
+  container.appendChild(text1);
+  container.appendChild(text2);
+  container.appendChild(text3);
+
+  testing.expectEqual(3, container.childNodes.length);
+  testing.expectEqual('ABC', container.textContent);
+
+  text2.remove();
+
+  testing.expectEqual(2, container.childNodes.length);
+  testing.expectEqual('AC', container.textContent);
+  testing.expectEqual(null, text2.parentNode);
+  testing.expectEqual(text3, text1.nextSibling);
+}
+</script>
+
+<script id="removeOnlyChild">
+{
+  // remove() when node is only child
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const text = document.createTextNode('Only');
+  container.appendChild(text);
+
+  testing.expectEqual(1, container.childNodes.length);
+
+  text.remove();
+
+  testing.expectEqual(0, container.childNodes.length);
+  testing.expectEqual(null, text.parentNode);
+}
+</script>
+
+<script id="removeNoParent">
+{
+  // remove() when node has no parent (should do nothing)
+  const text = document.createTextNode('Orphan');
+  text.remove(); // Should not throw
+  testing.expectEqual(null, text.parentNode);
+}
+</script>
+
+<script id="removeCommentWithElementSiblings">
+{
+  // remove() comment with element siblings
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const div1 = document.createElement('div');
+  div1.textContent = 'First';
+  const comment = document.createComment('middle');
+  const div2 = document.createElement('div');
+  div2.textContent = 'Last';
+
+  container.appendChild(div1);
+  container.appendChild(comment);
+  container.appendChild(div2);
+
+  testing.expectEqual(3, container.childNodes.length);
+
+  comment.remove();
+
+  testing.expectEqual(2, container.childNodes.length);
+  testing.expectEqual('DIV', container.childNodes[0].tagName);
+  testing.expectEqual('DIV', container.childNodes[1].tagName);
+  testing.expectEqual(div2, div1.nextSibling);
+}
+</script>
+
+<script id="beforeWithSiblings">
+{
+  // before() when node has siblings
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const text1 = document.createTextNode('A');
+  const text2 = document.createTextNode('C');
+  container.appendChild(text1);
+  container.appendChild(text2);
+
+  const textB = document.createTextNode('B');
+  text2.before(textB);
+
+  testing.expectEqual(3, container.childNodes.length);
+  testing.expectEqual('ABC', container.textContent);
+  testing.expectEqual(textB, text1.nextSibling);
+  testing.expectEqual(text2, textB.nextSibling);
+}
+</script>
+
+<script id="beforeMultipleNodes">
+{
+  // before() with multiple nodes
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const text = document.createTextNode('Z');
+  container.appendChild(text);
+
+  const text1 = document.createTextNode('A');
+  const text2 = document.createTextNode('B');
+  const text3 = document.createTextNode('C');
+
+  text.before(text1, text2, text3);
+
+  testing.expectEqual(4, container.childNodes.length);
+  testing.expectEqual('ABCZ', container.textContent);
+}
+</script>
+
+<script id="beforeMixedTypes">
+{
+  // before() with mixed node types
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const target = document.createTextNode('Target');
+  container.appendChild(target);
+
+  const elem = document.createElement('span');
+  elem.textContent = 'E';
+  const text = document.createTextNode('T');
+  const comment = document.createComment('C');
+
+  target.before(elem, text, comment);
+
+  testing.expectEqual(4, container.childNodes.length);
+  testing.expectEqual(1, container.childNodes[0].nodeType); // ELEMENT_NODE
+  testing.expectEqual(3, container.childNodes[1].nodeType); // TEXT_NODE
+  testing.expectEqual(8, container.childNodes[2].nodeType); // COMMENT_NODE
+  testing.expectEqual(3, container.childNodes[3].nodeType); // TEXT_NODE (target)
+}
+</script>
+
+<script id="beforeNoParent">
+{
+  // before() when node has no parent (should do nothing)
+  const orphan = document.createTextNode('Orphan');
+  const text = document.createTextNode('Test');
+  orphan.before(text);
+
+  testing.expectEqual(null, orphan.parentNode);
+  testing.expectEqual(null, text.parentNode);
+}
+</script>
+
+<script id="beforeOnlyChild">
+{
+  // before() when target is only child
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const target = document.createTextNode('B');
+  container.appendChild(target);
+
+  const textA = document.createTextNode('A');
+  target.before(textA);
+
+  testing.expectEqual(2, container.childNodes.length);
+  testing.expectEqual('AB', container.textContent);
+  testing.expectEqual(textA, container.firstChild);
+  testing.expectEqual(target, textA.nextSibling);
+}
+</script>
+
+<script id="afterWithSiblings">
+{
+  // after() when node has siblings
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const text1 = document.createTextNode('A');
+  const text2 = document.createTextNode('C');
+  container.appendChild(text1);
+  container.appendChild(text2);
+
+  const textB = document.createTextNode('B');
+  text1.after(textB);
+
+  testing.expectEqual(3, container.childNodes.length);
+  testing.expectEqual('ABC', container.textContent);
+  testing.expectEqual(textB, text1.nextSibling);
+  testing.expectEqual(text2, textB.nextSibling);
+}
+</script>
+
+<script id="afterMultipleNodes">
+{
+  // after() with multiple nodes
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const text = document.createTextNode('A');
+  container.appendChild(text);
+
+  const text1 = document.createTextNode('B');
+  const text2 = document.createTextNode('C');
+  const text3 = document.createTextNode('D');
+
+  text.after(text1, text2, text3);
+
+  testing.expectEqual(4, container.childNodes.length);
+  testing.expectEqual('ABCD', container.textContent);
+}
+</script>
+
+<script id="afterMixedTypes">
+{
+  // after() with mixed node types
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const target = document.createTextNode('Start');
+  container.appendChild(target);
+
+  const elem = document.createElement('div');
+  elem.textContent = 'E';
+  const comment = document.createComment('comment');
+  const text = document.createTextNode('T');
+
+  target.after(elem, comment, text);
+
+  testing.expectEqual(4, container.childNodes.length);
+  testing.expectEqual(3, container.childNodes[0].nodeType); // TEXT_NODE (target)
+  testing.expectEqual(1, container.childNodes[1].nodeType); // ELEMENT_NODE
+  testing.expectEqual(8, container.childNodes[2].nodeType); // COMMENT_NODE
+  testing.expectEqual(3, container.childNodes[3].nodeType); // TEXT_NODE
+}
+</script>
+
+<script id="afterNoParent">
+{
+  // after() when node has no parent (should do nothing)
+  const orphan = document.createTextNode('Orphan');
+  const text = document.createTextNode('Test');
+  orphan.after(text);
+
+  testing.expectEqual(null, orphan.parentNode);
+  testing.expectEqual(null, text.parentNode);
+}
+</script>
+
+<script id="afterAsLastChild">
+{
+  // after() when target is last child
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const target = document.createTextNode('A');
+  container.appendChild(target);
+
+  const textB = document.createTextNode('B');
+  target.after(textB);
+
+  testing.expectEqual(2, container.childNodes.length);
+  testing.expectEqual('AB', container.textContent);
+  testing.expectEqual(target, container.firstChild);
+  testing.expectEqual(textB, container.lastChild);
+  testing.expectEqual(null, textB.nextSibling);
+}
+</script>
+
+<script id="replaceWithSingleNode">
+{
+  // replaceWith() with single node
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const old = document.createTextNode('Old');
+  container.appendChild(old);
+
+  const replacement = document.createTextNode('New');
+  old.replaceWith(replacement);
+
+  testing.expectEqual(1, container.childNodes.length);
+  testing.expectEqual('New', container.textContent);
+  testing.expectEqual(null, old.parentNode);
+  testing.expectEqual(container, replacement.parentNode);
+}
+</script>
+
+<script id="replaceWithMultipleNodes">
+{
+  // replaceWith() with multiple nodes
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const old = document.createTextNode('X');
+  container.appendChild(old);
+
+  const text1 = document.createTextNode('A');
+  const text2 = document.createTextNode('B');
+  const text3 = document.createTextNode('C');
+
+  old.replaceWith(text1, text2, text3);
+
+  testing.expectEqual(3, container.childNodes.length);
+  testing.expectEqual('ABC', container.textContent);
+  testing.expectEqual(null, old.parentNode);
+}
+</script>
+
+<script id="replaceWithOnlyChild">
+{
+  // replaceWith() when target is only child
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const old = document.createTextNode('Only');
+  container.appendChild(old);
+
+  testing.expectEqual(1, container.childNodes.length);
+
+  const replacement = document.createTextNode('Replaced');
+  old.replaceWith(replacement);
+
+  testing.expectEqual(1, container.childNodes.length);
+  testing.expectEqual('Replaced', container.textContent);
+  testing.expectEqual(replacement, container.firstChild);
+}
+</script>
+
+<script id="replaceWithBetweenSiblings">
+{
+  // replaceWith() when node has siblings on both sides
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const text1 = document.createTextNode('A');
+  const text2 = document.createTextNode('X');
+  const text3 = document.createTextNode('C');
+  container.appendChild(text1);
+  container.appendChild(text2);
+  container.appendChild(text3);
+
+  const replacement = document.createTextNode('B');
+  text2.replaceWith(replacement);
+
+  testing.expectEqual(3, container.childNodes.length);
+  testing.expectEqual('ABC', container.textContent);
+  testing.expectEqual(replacement, text1.nextSibling);
+  testing.expectEqual(text3, replacement.nextSibling);
+}
+</script>
+
+<script id="replaceWithMixedTypes">
+{
+  // replaceWith() with mixed node types
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const old = document.createComment('old');
+  container.appendChild(old);
+
+  const elem = document.createElement('span');
+  elem.textContent = 'E';
+  const text = document.createTextNode('T');
+  const comment = document.createComment('C');
+
+  old.replaceWith(elem, text, comment);
+
+  testing.expectEqual(3, container.childNodes.length);
+  testing.expectEqual(1, container.childNodes[0].nodeType); // ELEMENT_NODE
+  testing.expectEqual(3, container.childNodes[1].nodeType); // TEXT_NODE
+  testing.expectEqual(8, container.childNodes[2].nodeType); // COMMENT_NODE
+  testing.expectEqual(null, old.parentNode);
+}
+</script>
+
+<script id="nextElementSiblingText">
+{
+  // nextElementSibling on text node with element siblings
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const text1 = document.createTextNode('A');
+  const comment = document.createComment('comment');
+  const div = document.createElement('div');
+  div.id = 'found';
+  const text2 = document.createTextNode('B');
+
+  container.appendChild(text1);
+  container.appendChild(comment);
+  container.appendChild(div);
+  container.appendChild(text2);
+
+  testing.expectEqual('found', text1.nextElementSibling.id);
+  testing.expectEqual('found', comment.nextElementSibling.id);
+  testing.expectEqual(null, text2.nextElementSibling);
+}
+</script>
+
+<script id="nextElementSiblingNoElement">
+{
+  // nextElementSibling when there's no element sibling
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const text = document.createTextNode('A');
+  const comment = document.createComment('B');
+  container.appendChild(text);
+  container.appendChild(comment);
+
+  testing.expectEqual(null, text.nextElementSibling);
+  testing.expectEqual(null, comment.nextElementSibling);
+}
+</script>
+
+<script id="previousElementSiblingComment">
+{
+  // previousElementSibling on comment with element siblings
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const div = document.createElement('div');
+  div.id = 'found';
+  const text = document.createTextNode('text');
+  const comment = document.createComment('comment');
+
+  container.appendChild(div);
+  container.appendChild(text);
+  container.appendChild(comment);
+
+  testing.expectEqual('found', text.previousElementSibling.id);
+  testing.expectEqual('found', comment.previousElementSibling.id);
+  testing.expectEqual(null, div.previousElementSibling);
+}
+</script>
+
+<script id="previousElementSiblingNoElement">
+{
+  // previousElementSibling when there's no element sibling
+  const container = $('#container');
+  container.innerHTML = '';
+
+  const text = document.createTextNode('A');
+  const comment = document.createComment('B');
+  container.appendChild(text);
+  container.appendChild(comment);
+
+  testing.expectEqual(null, text.previousElementSibling);
+  testing.expectEqual(null, comment.previousElementSibling);
+}
+</script>

src/browser/tests/cdata/comment.html

@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<script src="../testing.js"></script>
+
+<script id=comment>
+  testing.expectEqual('', new Comment().data);
+  testing.expectEqual('over 9000! ', new Comment('over 9000! ').data);
+
+  testing.expectEqual('null', new Comment(null).data);
+</script>

src/browser/tests/cdata/data.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<script src="../testing.js"></script>
+
+<div id=a><!-- spice --></div>
+<div id=b>flow</div>
+
+<script id=data>
+  testing.expectEqual(' spice ', $('#a').firstChild.data);
+  testing.expectEqual('flow', $('#b').firstChild.data);
+</script>

src/browser/tests/cdata/text.html

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<a id="link" href="foo" class="ok">OK</a>
+
+<script src="../testing.js"></script>
+<script id=text>
+  let t = new Text('foo');
+  testing.expectEqual('foo', t.data);
+
+  let emptyt = new Text();
+  testing.expectEqual('', emptyt.data);
+
+  let text = $('#link').firstChild;
+  testing.expectEqual('OK', text.wholeText);
+
+  text.data = 'OK modified';
+  let split = text.splitText('OK'.length);
+  testing.expectEqual(' modified', split.data);
+  testing.expectEqual('OK', text.data);
+
+    let x = new Text(null);
+    testing.expectEqual("null", x.data);
+</script>

src/browser/tests/cdp/dom1.html

@@ -0,0 +1 @@
+<p>1</p> <p>2</p>

src/browser/tests/cdp/dom2.html

@@ -0,0 +1 @@
+<div><p>2</p></div>

src/browser/tests/cdp/dom3.html

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Test Page</title>
+</head>
+<body>
+    <h1>Test Page</h1>
+    <nav>
+        <a href="/page1" id="link1">First Link</a>
+        <a href="/page2" id="link2">Second Link</a>
+    </nav>
+    <form id="testForm" action="/submit" method="post">
+        <label for="username">Username:</label>
+        <input type="text" id="username" name="username" placeholder="Enter username">
+
+        <label for="email">Email:</label>
+        <input type="email" id="email" name="email" placeholder="Enter email">
+
+        <label for="password">Password:</label>
+        <input type="password" id="password" name="password">
+
+        <button type="submit">Submit</button>
+    </form>
+</body>
+</html>