@itmetsam/samurai-framework 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx tsc *)"
+    ]
+  }
+}

package/.env.example

@@ -0,0 +1,3 @@
+# Copy to .env.<environment>, e.g. .env.staging. Never commit real values.
+# Tests read these as secrets.TEST_CARD; real environment variables win over this file.
+SAMURAI_SECRET_TEST_CARD=

package/.github/actions/setup/action.yml

@@ -0,0 +1,16 @@
+name: Setup
+description: Install bun, Node and the locked dependencies
+
+runs:
+  using: composite
+  steps:
+    - uses: oven-sh/setup-bun@v2
+      with:
+        bun-version: 1.3.0
+    # The test scripts run tsx on Node's test runner, which needs Node 22+ (fs/promises glob)
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 26
+    - name: Install dependencies
+      shell: bash
+      run: bun install --frozen-lockfile

package/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
+      - name: Typecheck
+        run: bunx tsc --noEmit -p .
+
+  unit:
+    name: Unit tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
+      - name: Unit tests
+        run: bun run test
+
+  browser:
+    name: Browser tests (Firefox)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
+      - name: Firefox version
+        run: firefox --version
+      - name: Browser tests
+        timeout-minutes: 12
+        run: bun run test:browser
+      - name: Upload logs
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: browser-test-logs
+          path: |
+            logs/
+            result/
+          retention-days: 7
+          if-no-files-found: ignore
+
+  trunk:
+    name: Code quality (Trunk)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      checks: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      # Checks only what the PR or push changed; linters come from .trunk/trunk.yaml
+      - uses: trunk-io/trunk-action@v1

package/.trunk/configs/.markdownlint.yaml

@@ -0,0 +1,2 @@
+# Prettier friendly markdownlint config (all formatting rules disabled)
+extends: markdownlint/style/prettier

package/.trunk/configs/.yamllint.yaml

@@ -0,0 +1,7 @@
+rules:
+  quoted-strings:
+    required: only-when-needed
+    extra-allowed: ["{|}"]
+  key-duplicates: {}
+  octal-values:
+    forbid-implicit-octal: true

package/.trunk/configs/svgo.config.mjs

@@ -0,0 +1,14 @@
+export default {
+  plugins: [
+    {
+      name: "preset-default",
+      params: {
+        overrides: {
+          removeViewBox: false, // https://github.com/svg/svgo/issues/1128
+          sortAttrs: true,
+          removeOffCanvasPaths: true,
+        },
+      },
+    },
+  ],
+};

package/.trunk/trunk.yaml

@@ -0,0 +1,34 @@
+# This file controls the behavior of Trunk: https://docs.trunk.io/cli
+# To learn more about the format of this file, see https://docs.trunk.io/reference/trunk-yaml
+version: 0.1
+cli:
+  version: 1.25.0
+# Trunk provides extensibility via plugins. (https://docs.trunk.io/plugins)
+plugins:
+  sources:
+    - id: trunk
+      ref: v1.11.0
+      uri: https://github.com/trunk-io/plugins
+# Many linters and tools depend on runtimes - configure them here. (https://docs.trunk.io/runtimes)
+runtimes:
+  enabled:
+    - node@22.16.0
+    - python@3.14.4
+# This is the section where you manage your linters. (https://docs.trunk.io/check/configuration)
+lint:
+  enabled:
+    - checkov@3.3.22
+    - git-diff-check
+    - grype@0.119.0
+    - markdownlint@0.49.1
+    - osv-scanner@2.6.0
+    - prettier@3.9.9
+    - svgo@4.1.0
+    - trufflehog@3.97.9
+    - yamllint@1.38.0
+actions:
+  enabled:
+    - trunk-announce
+    - trunk-check-pre-push
+    - trunk-fmt-pre-commit
+    - trunk-upgrade-available

package/docs/superpowers/bidi-roadmap.md

@@ -0,0 +1,60 @@
+# WebDriver BiDi adoption — roadmap
+
+Date: 2026-09-29
+Source: https://www.w3.org/TR/webdriver-bidi/
+Status: all 15 specs (0 to 14) are implemented.
+
+Each item links to its spec in `docs/superpowers/specs/`. Order respects dependencies (`←`).
+
+## Todo
+
+### Phase 0 — prerequisite
+- [x] **0. Foundation** — connector error replies, command typings, refcounted subscriptions, context tree, `newPage` fix — [spec](specs/2026-09-29-bidi-foundation-design.md)
+
+### Phase 1 — locator core
+- [x] **1. `script.callFunction` (+ `script.disown`)** ← 0 — [spec](specs/2026-09-29-script-call-function-design.md)
+- [x] **2. `script.addPreloadScript`** ← 0, 1 — [spec](specs/2026-09-29-preload-scripts-design.md)
+- [x] **3. `browsingContext.locateNodes`** ← 1 (2 optional) — [spec](specs/2026-09-29-locate-nodes-design.md)
+- [x] **4. `input.setFiles`** ← 1, 3 — [spec](specs/2026-09-29-set-files-design.md)
+
+### Phase 2 — waiting correctness
+- [x] **5. Network tracking + real network idle** ← 0 — [spec](specs/2026-09-29-network-tracking-design.md)
+- [x] **6. Navigation waits (`navigate` wait, load events, reload)** ← 0, 5 — [spec](specs/2026-09-29-navigation-waits-design.md)
+- [x] **7. User prompts (`handleUserPrompt`)** ← 0 — [spec](specs/2026-09-29-user-prompts-design.md)
+- [x] **8. Logs and page errors (`log.entryAdded`)** ← 0, 1 — [spec](specs/2026-09-29-logs-and-errors-design.md)
+
+### Phase 3 — features
+- [x] **9. Network interception (mock / block / modify)** ← 0, 5 — [spec](specs/2026-09-29-network-interception-design.md)
+- [x] **10. Network data (cache control, response bodies)** ← 5 — [spec](specs/2026-09-29-network-data-design.md)
+- [x] **11. Page API completeness (viewport, reload, history, close, pdf, screenshot)** ← 0, 1 — [spec](specs/2026-09-29-page-api-design.md)
+- [x] **12. User contexts + storage** ← 0 — [spec](specs/2026-09-29-contexts-and-storage-design.md)
+
+### Phase 4 — nice to have
+- [x] **13. Emulation** ← 12 — [spec](specs/2026-09-29-emulation-design.md)
+- [x] **14. Downloads + file dialogs** ← 0, 4 — [spec](specs/2026-09-29-downloads-and-file-dialogs-design.md)
+
+## Dependency graph
+
+```
+0 ─┬─ 1 ─┬─ 2
+   │     ├─ 3 ── 4 ── 14
+   │     ├─ 8
+   │     └─ 11
+   ├─ 5 ─┬─ 6
+   │     ├─ 9
+   │     └─ 10
+   ├─ 7
+   └─ 12 ── 13
+```
+
+## Deliberately skipped
+
+`webExtension.*`, `session.end`, `script.getRealms`, `script.removePreloadScript` as public API (used internally only), `network.continueWithAuth` (folded into spec 9 as a follow-up).
+
+## Cross-cutting rules for every spec
+
+- Test-first: each unit test before its implementation, using `src/testing/stub-connector.ts`; browser tests in `*.browser-test.ts` (`npm run test:browser`).
+- Any feature that needs an event subscribes through the refcounted API from spec 0, never a bare `session.subscribe`.
+- Every command a feature sends must be typed in `BiDiCommands` (spec 0 lists the missing ones).
+- Timeouts resolve through `resolveTimeout` (actions/assertions) or the navigation timeout from spec 6 (navigation); no unbounded waits.
+- Browser support is verified against Firefox (the only `SupportedBrowser` today). A command Firefox lacks is documented in its spec and surfaced as `UnsupportedOperationError`, not a hang.