simcord 2.0.2__tar.gz → 2.2.0__tar.gz

simcord-2.2.0/.github/workflows/ci.yml

@@ -0,0 +1,13 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    uses: ./.github/workflows/verify.yml

{simcord-2.0.2 → simcord-2.2.0}/.github/workflows/release.yml

@@ -32,54 +32,12 @@ jobs:
           print(f"Releasing simcord {project_version}")
           PY
 
-  lint:
-    needs: version
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v7
-      - run: uv sync --extra dev
-      - run: uv run ruff check src tests examples benchmarks scripts
-      - run: uv run ruff format --check src tests examples benchmarks scripts
-      - run: uv run pyright src
-
-  test:
-    needs: version
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.11", "3.12", "3.13", "3.14"]
-    steps:
-      - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v7
-        with:
-          python-version: ${{ matrix.python-version }}
-      - run: uv sync --extra dev
-      - run: uv run coverage run -m pytest tests examples -q
-      - run: uv run coverage report
-
-  docs:
-    needs: version
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v7
-      - run: uv sync --extra docs
-      - run: uv run mkdocs build --strict
-      - run: uv run python scripts/check_discoverability.py site
-
-  benchmark:
-    needs: version
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v7
-      - uses: astral-sh/setup-uv@v7
-      - run: uv sync --extra bench
-      - run: uv run pytest benchmarks
+  verify:
+    needs: [version]
+    uses: ./.github/workflows/verify.yml
 
   build:
-    needs: [version, lint, test, docs, benchmark]
+    needs: [version, verify]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7

simcord-2.2.0/.github/workflows/verify.yml

@@ -0,0 +1,99 @@
+name: Verify
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      # screenshot extra pulls in playwright/PIL/markdown-it so pyright resolves
+      # the lazy optional imports in simcord.preview with real type info.
+      - run: uv sync --extra dev --extra screenshot
+      - run: uv run ruff check src tests examples benchmarks scripts
+      - run: uv run ruff format --check src tests examples benchmarks scripts
+      - run: uv run pyright src
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      # preview extra adds markdown-it + Pillow so non-browser preview tests run;
+      # playwright stays absent so capture tests skip via importorskip.
+      - run: uv sync --extra dev --extra preview
+      - run: uv run coverage run -m pytest tests examples -q
+      - run: uv run coverage report
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync --extra docs
+      - run: uv run mkdocs build --strict
+      - run: uv run python scripts/check_discoverability.py site
+
+  preview-package:
+    name: Preview package + pinned Linux Chromium
+    runs-on: ubuntu-22.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+      - run: uv sync --extra screenshot --extra pytest
+      - run: uv run python -m playwright install --with-deps chromium
+      - run: uv run pytest tests/integration/test_preview*.py -q
+      - run: uv build
+      - run: uv run python scripts/check_package.py dist
+      - name: Install the wheel outside the checkout
+        shell: bash
+        run: |
+          set -euo pipefail
+          tmp="$(mktemp -d)"
+          mkdir -p package-smoke-artifacts
+          uv venv --python 3.12 "$tmp/venv"
+          wheel="$(printf '%s\n' "$GITHUB_WORKSPACE"/dist/*.whl)"
+          uv pip install --python "$tmp/venv/bin/python" \
+            "simcord[screenshot] @ file://$wheel"
+          "$tmp/venv/bin/python" -m playwright install --with-deps chromium
+          cp examples/bot.py examples/preview_example.py "$tmp/"
+          (
+            cd "$tmp"
+            "$tmp/venv/bin/python" preview_example.py > "$GITHUB_WORKSPACE/package-smoke-artifacts/preview-report.json"
+          )
+          cp "$tmp/preview-example.png" package-smoke-artifacts/
+      - uses: actions/upload-artifact@v7
+        if: failure()
+        with:
+          name: preview-package-failure
+          path: package-smoke-artifacts/
+          if-no-files-found: ignore
+
+  benchmark:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      # The perf guards (absolute budget + same-run scaling ratio) fail the build
+      # on a catastrophic regression; the JSON is uploaded as a non-gating trend.
+      - run: uv sync --extra bench
+      - run: uv run pytest benchmarks --benchmark-json=benchmark.json
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: benchmark-results
+          path: benchmark.json

{simcord-2.0.2 → simcord-2.2.0}/.gitignore

@@ -24,3 +24,8 @@ htmlcov/
 PLAN.md
 .claude/
 site/
+
+docs/plans/
+
+# Local Discord visual references (never committed or packaged)
+.discord-reference-captures/

{simcord-2.0.2 → simcord-2.2.0}/CHANGELOG.md

@@ -4,6 +4,38 @@ This changelog is generated with [towncrier](https://towncrier.readthedocs.io/).
 
 <!-- towncrier release notes start -->
 
+## 2.2.0 (2026-09-23)
+
+### Features
+
+- Add an optional local component preview with real callback interactions, authorized viewer contexts, offline media assets, and deterministic Playwright screenshot reports. The base package remains lazy and networkless; install `simcord[preview]` for the bridge or `simcord[screenshot]` plus Chromium for capture.
+- Breaking in SimCord 2.2: remove `Env.http_log`; use `Env.http_requests` and its `HttpLogEntry` records instead.
+- Extend the local component preview: `env.preview(port=...)` pins the loopback port for stable capability URLs and pre-created SSH forwards, `await preview.snapshot()` returns the detached JSON projection as the structured/agent read surface, `screenshot(path=None)` captures in memory with PNG bytes on `PreviewCapture.png`, `window.simcordPreview` exposes `viewerId`/`targetId`, localhost origins are accepted, and internal bridge methods are now private by default.
+- Hardened the local preview with deterministic presentation diagnostics, generation-scoped media readiness, modal focus isolation, safe page release, and strict action-envelope validation.
+- Preview snapshots now publish protocol 2: `messageIndex` is picker-only summary data, `messages` maps authorized IDs to full projections, and `targetId` replaces `selected`. Component and modal controls use scoped stable control keys, mutating browser actions carry an explicit target and published revision, and `presentation_time` is deterministic and timezone-aware. Snapshot consumers must migrate; protocol 1 keys are not supported.
+- Settlement now recognizes intentional timer-bounded waits — store-registered View/Modal expiry timers, `wait_for` timeouts on listener waits, `discord.ext.tasks` loop intervals, and wake-up timers scheduled inside `env.external_wait` — and makes them virtual-only: they fire only via `env.advance_time()` or their awaited input, never the wall clock, so they no longer burn real settle time or expire mid-operation. Migration: tests that relied on a View expiring on the wall clock without `advance_time` must now call `await env.advance_time(<timeout>)`.
+
+### Documentation
+
+- Improve the preview demo onboarding: `examples/preview_example.py` gains a `--keep-open` flag
+  that keeps the session live for clicking (it calls `preview.wait_closed()`), the URL and
+  human-facing notes move to stderr so stdout carries only the JSON capture report, the
+  quickstart's next-steps list links to the preview guide, and CONTRIBUTING documents which
+  optional extras unlock the preview tests, example, and type-checking.
+
+### Miscellaneous
+
+- Removed redundant code in the preview snapshot projection.
+- The local component preview renders the Discord dark theme only: the `theme=` option and the browser theme toggle were removed. `profile.theme` still reports `"dark"` in snapshots and capture reports.
+
+
+## 2.1.0 (2026-09-19)
+
+### Features
+
+- Add `Env.http_requests` records with query parameters and audit reasons while preserving the deprecated live `Env.http_log` tuple list for 2.x compatibility.
+
+
 ## 2.0.2 (2026-09-18)
 
 ### Bug fixes

{simcord-2.0.2 → simcord-2.2.0}/CONTRIBUTING.md

@@ -19,6 +19,18 @@ uv run pyright src
 The pre-commit hooks mirror the CI `lint` job (ruff on commit, pyright on push)
 using the project's own pinned tools, so a clean commit means a green CI lint.
 
+Optional extras layer on top of `dev` depending on what you work on:
+
+| Extra | Unlocks |
+| --- | --- |
+| `preview` | `markdown-it-py` + `Pillow`, so the non-browser preview tests run; browser capture tests still skip via `importorskip`. |
+| `screenshot` | Playwright as well — the full preview suite, `examples/preview_example.py`, and real types for pyright's check of the lazy optional imports. |
+
+```bash
+uv sync --extra dev --extra screenshot                # matches the CI lint job
+uv run playwright install --with-deps chromium        # needed once for browser capture tests + the example
+```
+
 ## Project layout
 
 - `src/simcord/backend/`: the virtual Discord with dataclass models, wire-format

{simcord-2.0.2 → simcord-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simcord
-Version: 2.0.2
+Version: 2.2.0
 Summary: Offline discord.py bot testing with pytest. No network, token, or test server.
 Project-URL: Homepage, https://github.com/SilentHacks/simcord
 Project-URL: Documentation, https://simcord.readthedocs.io/
@@ -30,6 +30,7 @@ Requires-Dist: pytest>=8; extra == 'bench'
 Provides-Extra: dev
 Requires-Dist: coverage[toml]>=7; extra == 'dev'
 Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: jsonschema>=4; extra == 'dev'
 Requires-Dist: pre-commit>=3; extra == 'dev'
 Requires-Dist: pyright>=1.1; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
@@ -40,9 +41,19 @@ Requires-Dist: towncrier>=24; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Provides-Extra: preview
+Requires-Dist: aiohttp>=3.9; extra == 'preview'
+Requires-Dist: markdown-it-py>=3; extra == 'preview'
+Requires-Dist: pillow>=10; extra == 'preview'
 Provides-Extra: pytest
+Requires-Dist: jsonschema>=4; extra == 'pytest'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'pytest'
 Requires-Dist: pytest>=8; extra == 'pytest'
+Provides-Extra: screenshot
+Requires-Dist: aiohttp>=3.9; extra == 'screenshot'
+Requires-Dist: markdown-it-py>=3; extra == 'screenshot'
+Requires-Dist: pillow>=10; extra == 'screenshot'
+Requires-Dist: playwright>=1.45; extra == 'screenshot'
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -116,9 +127,14 @@ uv add --dev "simcord[pytest]"
 ```
 
 Requires **Python >=3.11** (tested on **3.11–3.14**) and **discord.py >=2.7.1,<3**.
-The locked CI matrix tests discord.py 2.7.1; a separate weekly workflow runs against
-upstream `master`, rather than continuously testing every released 2.x version. No
-dependencies beyond discord.py itself.
+The locked CI matrix tests discord.py 2.7.1; a separate weekly workflow checks upstream
+`master`, rather than continuously testing every released 2.x version. The base simulation
+adds no runtime dependency beyond discord.py.
+
+For an authenticated local browser page showing real component callbacks, install
+`simcord[preview]`; for deterministic PNGs also run `playwright install chromium` after installing
+`simcord[screenshot]`. See the [component preview and screenshots guide](https://simcord.readthedocs.io/en/latest/guides/preview/)
+for lifecycle, access, limits, SSH forwarding, diagnostics, and fidelity boundaries.
 
 ## Quickstart
 
@@ -228,6 +244,7 @@ See [Core concepts](https://simcord.readthedocs.io/en/latest/concepts/) for the
 | **Polls** | `vote`, `remove_vote` | Poll answers and results. |
 | **Voice & events** | `join_voice`, `leave_voice`, `set_voice`, `subscribe_event` | Voice state, scheduled-event subscriptions. |
 | **DMs** | `send_dm` | Direct-message channels and flows. |
+| **Browser preview** | `env.preview`, `preview.refresh`, `preview.screenshot` | Loopback component pages, real callbacks, authorized viewers, explicit refresh, and immutable capture diagnostics. |
 
 Responses come back as a rich [`InteractionResult`](https://simcord.readthedocs.io/en/latest/api/)
 exposing `acknowledged`, `deferred`, `ephemeral`, `response`, `followups` and `modal`. Threads,
@@ -263,7 +280,11 @@ When something goes wrong, the `env` tells you what happened:
 
 - `env.transcript()`: the ordered log of gateway events and REST calls, auto-attached to
   failing pytest tests.
-- `env.http_log`: every REST request the bot made, to assert on or inspect.
+- `env.http_requests`: structured records for every attempted REST request (`method`, `path`,
+  `params`, `json`, `reason`). Values are discord.py transport arguments, not wire-normalized
+  strings or headers; uploaded files are not captured. JSON bodies retain their supplied
+  JSON-compatible shape, including top-level arrays. `params` and `json` are detached deep
+  snapshots, so later source-container mutations do not change a record.
 - `env.errors`: exceptions the bot swallowed.
 - `env.inject_error("POST", "/channels/*/messages", status=500)`: make matching REST calls
   fail, to test your bot's error handling.
@@ -313,6 +334,7 @@ More in the [architecture docs](https://simcord.readthedocs.io/en/latest/archite
 | 🍳 [Recipes](https://simcord.readthedocs.io/en/latest/cookbook/) | Copy-paste patterns for common cases. |
 | 📋 [Parity matrix](https://simcord.readthedocs.io/en/latest/parity-matrix/) | Exactly what's implemented. |
 | 🔖 [API reference](https://simcord.readthedocs.io/en/latest/api/) | Every public object and verb. |
+| 🖥️ [Component preview](https://simcord.readthedocs.io/en/latest/guides/preview/) | Real browser callbacks, page-local viewers, offline assets, and deterministic screenshot reports. |
 
 ## Contributing
 

{simcord-2.0.2 → simcord-2.2.0}/README.md

@@ -69,9 +69,14 @@ uv add --dev "simcord[pytest]"
 ```
 
 Requires **Python >=3.11** (tested on **3.11–3.14**) and **discord.py >=2.7.1,<3**.
-The locked CI matrix tests discord.py 2.7.1; a separate weekly workflow runs against
-upstream `master`, rather than continuously testing every released 2.x version. No
-dependencies beyond discord.py itself.
+The locked CI matrix tests discord.py 2.7.1; a separate weekly workflow checks upstream
+`master`, rather than continuously testing every released 2.x version. The base simulation
+adds no runtime dependency beyond discord.py.
+
+For an authenticated local browser page showing real component callbacks, install
+`simcord[preview]`; for deterministic PNGs also run `playwright install chromium` after installing
+`simcord[screenshot]`. See the [component preview and screenshots guide](https://simcord.readthedocs.io/en/latest/guides/preview/)
+for lifecycle, access, limits, SSH forwarding, diagnostics, and fidelity boundaries.
 
 ## Quickstart
 
@@ -181,6 +186,7 @@ See [Core concepts](https://simcord.readthedocs.io/en/latest/concepts/) for the
 | **Polls** | `vote`, `remove_vote` | Poll answers and results. |
 | **Voice & events** | `join_voice`, `leave_voice`, `set_voice`, `subscribe_event` | Voice state, scheduled-event subscriptions. |
 | **DMs** | `send_dm` | Direct-message channels and flows. |
+| **Browser preview** | `env.preview`, `preview.refresh`, `preview.screenshot` | Loopback component pages, real callbacks, authorized viewers, explicit refresh, and immutable capture diagnostics. |
 
 Responses come back as a rich [`InteractionResult`](https://simcord.readthedocs.io/en/latest/api/)
 exposing `acknowledged`, `deferred`, `ephemeral`, `response`, `followups` and `modal`. Threads,
@@ -216,7 +222,11 @@ When something goes wrong, the `env` tells you what happened:
 
 - `env.transcript()`: the ordered log of gateway events and REST calls, auto-attached to
   failing pytest tests.
-- `env.http_log`: every REST request the bot made, to assert on or inspect.
+- `env.http_requests`: structured records for every attempted REST request (`method`, `path`,
+  `params`, `json`, `reason`). Values are discord.py transport arguments, not wire-normalized
+  strings or headers; uploaded files are not captured. JSON bodies retain their supplied
+  JSON-compatible shape, including top-level arrays. `params` and `json` are detached deep
+  snapshots, so later source-container mutations do not change a record.
 - `env.errors`: exceptions the bot swallowed.
 - `env.inject_error("POST", "/channels/*/messages", status=500)`: make matching REST calls
   fail, to test your bot's error handling.
@@ -266,6 +276,7 @@ More in the [architecture docs](https://simcord.readthedocs.io/en/latest/archite
 | 🍳 [Recipes](https://simcord.readthedocs.io/en/latest/cookbook/) | Copy-paste patterns for common cases. |
 | 📋 [Parity matrix](https://simcord.readthedocs.io/en/latest/parity-matrix/) | Exactly what's implemented. |
 | 🔖 [API reference](https://simcord.readthedocs.io/en/latest/api/) | Every public object and verb. |
+| 🖥️ [Component preview](https://simcord.readthedocs.io/en/latest/guides/preview/) | Real browser callbacks, page-local viewers, offline assets, and deterministic screenshot reports. |
 
 ## Contributing
 

{simcord-2.0.2 → simcord-2.2.0}/docs/api.md

@@ -26,6 +26,17 @@ top-level `simcord` package.
 Use `await env.external_wait(awaitable, reason="...")` for one explicitly scoped external
 input wait. Unknown waits remain active and produce a diagnostic timeout.
 
+
+## Request observability
+
+::: simcord.HttpLogEntry
+
+`Env.http_requests` exposes these records for transport-level assertions. The `params` and
+`reason` fields contain discord.py transport arguments, not wire-normalized query strings or
+encoded headers; uploaded files are not captured. The `json` field preserves the supplied
+JSON-compatible shape, including top-level arrays. `params` and `json` are detached deep
+snapshots, so later mutations to source containers do not alter a record.
+
 ## Builders
 
 Synchronous, omnipotent handles for arranging the virtual Discord. Returned by `env`/`guild`
@@ -46,6 +57,30 @@ The simulated human that drives your bot. Created by `guild.add_member(...)`. Se
 
 ::: simcord.MemberActor
 
+## Local preview
+
+The optional [`Env.preview`](guides/preview.md#start-and-stop-a-session) context manager serves
+viewer-authorized messages and real component callbacks from a loopback browser. It is not a
+Discord connection. Install `simcord[preview]` for the bridge, or
+`simcord[screenshot]` and `playwright install --with-deps chromium` for managed PNG capture.
+`port=` pins the loopback origin so a pre-created forward can use the same origin on both ends;
+it never makes the capability-bearing URL stable or safe to log. Keep `preview.url` secret.
+
+::: simcord.preview.Preview
+
+::: simcord.preview.Preview.screenshot
+    options:
+      heading_level: 4
+
+::: simcord.preview.PreviewCapture
+
+`Preview.snapshot()` returns the detached JSON projection the bundled page renders — the structured
+read surface for non-visual checks and text-only tooling. `PreviewCapture` is an immutable report.
+Its `ready`, `complete`, and `calibrated` fields are independent; inspect `diagnostics`, `action`,
+`profile`, and `geometry` rather than inferring success from a PNG path. When `screenshot()` is
+called with `path=None`, `PreviewCapture.path` is `None` and `PreviewCapture.png` carries the PNG
+bytes in memory. Internal `/api/*` payloads and DOM/CSS names are not extension APIs.
+
 ## Results
 
 Returned by the interaction verbs (`slash`, `context_menu`, `click`, `select`,

{simcord-2.0.2 → simcord-2.2.0}/docs/architecture.md

@@ -63,6 +63,21 @@ test ──► builders/actors ──► virtual backend (single source of truth
   discord.py's master branch to catch drift early.
 - **Deterministic snowflakes** with valid embedded timestamps, from a fixed virtual epoch.
 
+## Optional browser presentation
+
+`Env.preview(...)` adds a local presentation layer above the same backend; it is not another
+Discord transport. An `aiohttp` server binds to `127.0.0.1` only, serves packaged ES modules/CSS,
+and exposes viewer-filtered snapshots and closed action envelopes. A random capability in the URL
+fragment plus page context headers authorize reads and real actor callbacks. Python owns the
+session and default presentation; each browser page and managed screenshot has an independent
+viewer/focus/generation, so one tab cannot retarget another.
+
+Preview polling is explicit and revision-based rather than websocket-driven. `refresh()` settles
+the environment and republishes current projections; it does not make background mutations live.
+Optional Pillow media work is bounded and outside Env's loop. Optional Playwright capture pins a
+settled projection and reports geometry, readiness, completeness, calibration, and diagnostics.
+Base imports do not allocate any preview server, worker, or browser.
+
 ## What it will never do
 
 Connect to Discord. There is no "integration mode"; automating a real client violates

{simcord-2.0.2 → simcord-2.2.0}/docs/concepts.md

@@ -23,8 +23,7 @@ async def test_something(simcord_env):
 ```
 
 The `Env` owns the virtual backend, tracks the bot's background tasks, captures errors,
-holds the virtual clock, and exposes the diagnostics (`env.http_log`, `env.transcript()`).
-A fresh `Env` is created for each test, so tests never leak state into each other.
+holds the virtual clock, and exposes the diagnostics (`env.http_requests`, `env.transcript()`).
 
 !!! info "One environment per event loop"
     `Env` monkeypatches `loop.create_task` and `time.monotonic` while it's live so it can
@@ -95,10 +94,16 @@ assert channel.last_message.content == "Pong!"   # the reply is already here
 ```
 
 Bot-owned work stays bot-owned across parking, timeout, cancellation, later actions, startup,
-and restart. Recognized waits — `Client.wait_for`, View/Modal completion, composed
-`gather`/`shield`/`wait`/`TaskGroup`, explicit `env.external_wait(...)`, and verified
-far-future sleeps — may remain. Unknown waits remain active and time out. Use a reasoned,
-scoped declaration for external input:
+and restart. Recognized waits — `Client.wait_for` (including its `timeout=`), View/Modal
+completion, store-registered View/Modal expiry timers, `discord.ext.tasks` loop intervals,
+composed `gather`/`shield`/`wait`/`TaskGroup`, explicit `env.external_wait(...)`, and verified
+far-future sleeps — may remain. A timer whose only job is resuming a recognized wait — a
+`wait_for` deadline on a listener, a View/Modal expiry, a loop interval, a wake-up timer
+scheduled inside `external_wait` — is virtual: it fires only via `env.advance_time()` or the
+awaited input, never the wall clock. Verified far-future sleeps keep their real fallback, and
+a View sent with no dispatchable items never registers (its expiry keeps real-time behavior).
+Unknown waits remain active and time out. Use a reasoned, scoped declaration for external
+input:
 
 ```python
 await env.external_wait(stop.wait(), reason="wait for the next message")
@@ -132,7 +137,7 @@ channel.history(viewer=mod)          # ephemeral-aware: what `mod` would see
 channel.pinned_messages()            # list[discord.Message]
 guild.get_ban(target)                # ban record | None
 env.errors                           # exceptions the bot swallowed
-env.http_log                         # every REST call the bot made
+env.http_requests                    # structured REST request records
 ```
 
 Interaction verbs return a richer [`InteractionResult`](api.md#simcord.InteractionResult) capturing

{simcord-2.0.2 → simcord-2.2.0}/docs/cookbook.md

@@ -246,7 +246,11 @@ async def test_no_double_post(simcord_env):
 
     await alice.send(channel, "!announce")
 
-    posts = [c for c in simcord_env.http_log if c[0] == "POST" and "/messages" in c[1]]
+    posts = [
+        entry
+        for entry in simcord_env.http_requests
+        if entry.method == "POST" and "/messages" in entry.path
+    ]
     assert len(posts) == 1
 ```
 
@@ -265,6 +269,27 @@ async def test_reaction_role(simcord_env):
     assert any(r.name == "Gamer" for r in alice.member.roles)
 ```
 
+## Preview a component message and capture a screenshot
+
+```python
+async def test_panel_preview(simcord_env):
+    channel = simcord_env.create_guild().create_text_channel("roles")
+    alice = simcord_env.guild.add_member(simcord_env.create_user("alice"))
+    await alice.slash(channel, "panel")
+
+    async with simcord_env.preview(channel, viewers=[alice]) as preview:
+        capture = await preview.screenshot("panel.png")
+        assert capture.complete and capture.ready
+        snapshot = await preview.snapshot()
+        target = snapshot["messages"].get(snapshot["targetId"])
+        assert target is not None
+```
+
+Reach for a preview when assertions alone aren't enough: the screenshot verifies what a user would
+actually see, and `snapshot()` returns the structured projection for agent or text-only checks. It
+requires the `simcord[preview]` extra (plus `simcord[screenshot]` and Chromium for `screenshot()`);
+see the [preview guide](guides/preview.md) for lifecycle, viewer access, and resource limits.
+
 ## See also
 
 - [Messages](guides/messages.md) · [Slash commands](guides/interactions.md) ·

{simcord-2.0.2 → simcord-2.2.0}/docs/faq.md

@@ -27,6 +27,14 @@ No. The library makes no outbound network requests and collects no usage or runt
 telemetry. Package hosts and source platforms may publish their own aggregate statistics,
 but SimCord does not transmit data from your tests.
 
+## Does the component preview connect to Discord?
+
+No. The optional preview uses a loopback-only `aiohttp` server and an authenticated capability;
+it does not need a bot token or a Discord connection. Install `simcord[preview]` for the browser
+bridge, and `simcord[screenshot]` plus `playwright install chromium` for managed screenshots.
+The [preview guide](guides/preview.md) documents forwarding, access checks, limits, and
+incomplete/uncalibrated captures.
+
 ## Is this a mock library?
 
 It's more than a mock. It is a **simulator**. A mock returns canned responses; SimCord

{simcord-2.0.2 → simcord-2.2.0}/docs/guides/ai-coding-agents.md

@@ -111,6 +111,20 @@ all required repository gates before reporting completion.
 - Do not test source text, call counts, or private plumbing when behavior is observable.
 - Do not connect CI to a Discord test guild.
 
+## Use the local component preview
+
+When a change affects a panel, modal, or other component presentation, install
+`simcord[preview]` and use [Component preview and screenshots](preview.md). A browser click
+dispatches the real callback; do not replace it with a DOM mock. Use `await preview.refresh()` after
+Python-side mutations, wait for `window.simcordPreview.ready`, and inspect `lastAction`,
+`complete`, `calibration`, and `diagnostics` separately. Prefer `await preview.snapshot()` for
+assertions and text-only agents: it settles, republishes, and returns the protocol-2 projection dict
+(`messages[targetId]`, `messageIndex`, `timeline`, `diagnostics`, `lastAction`, …) without a browser.
+Browser tooling can read `viewerId`/`targetId` on `window.simcordPreview` alongside `ready`.
+Pass `port=` to `env.preview` for a repeatable capability URL across reruns and pre-created SSH
+forwards. Managed captures require `simcord[screenshot]` plus `playwright install --with-deps chromium`;
+never put the capability-bearing `preview.url` in agent logs or artifacts.
+
 ## Machine-readable documentation
 
 SimCord publishes a curated [`llms.txt`](../llms.txt) index for agent navigation. It is an optional convenience, not a replacement for HTML documentation, `robots.txt`, sitemaps, or ordinary search indexing.

{simcord-2.0.2 → simcord-2.2.0}/docs/guides/components.md

@@ -165,6 +165,13 @@ Pass a freshly built client — re-running the same instance would re-execute `s
 - [Slash commands](interactions.md) — invoking commands and the interaction lifecycle.
 - [Time control](time-control.md) — firing view timeouts and cooldowns instantly.
 - [Recipes](../cookbook.md) — a reusable paginator test, among others.
+
+## Inspect the result in a browser
+
+For an authenticated local page that renders the same real callback flow, see
+[Component preview and screenshots](preview.md). The preview is optional, keeps Python and browser
+presentations independent, and labels stale, incomplete, and uncalibrated output explicitly.
+
 ## Settlement and external input
 
 View/Modal completion waits are recognized by settlement. If a component flow waits on a

{simcord-2.0.2 → simcord-2.2.0}/docs/guides/diagnostics.md

@@ -107,19 +107,28 @@ The [pytest plugin attaches this to failing tests automatically](fixtures.md#the
 so a failure shows you exactly what the bot did, in order — usually enough to diagnose
 without a debugger.
 
-## The HTTP log (`env.http_log`)
+## HTTP request records (`env.http_requests`)
 
-For fine-grained assertions, `env.http_log` is the list of every REST call the bot made, as
-`(method, path, json_body)` tuples:
+For fine-grained assertions, `env.http_requests` is the list of every REST call the bot made,
+as [`simcord.HttpLogEntry`](../api.md#simcord.HttpLogEntry) records:
 
 ```python
-posts = [c for c in simcord_env.http_log if c[0] == "POST" and "/messages" in c[1]]
-assert len(posts) == 1                       # the bot sent exactly one message
-assert posts[0][2]["content"] == "Pong!"
+posts = [
+    entry
+    for entry in simcord_env.http_requests
+    if entry.method == "POST" and "/messages" in entry.path
+]
+assert len(posts) == 1
+assert posts[0].json["content"] == "Pong!"
 ```
 
-This is how you assert the bot **didn't** do something (e.g. didn't double-post), or made
-exactly the calls you expect.
+Each record exposes `method`, `path`, `params`, `json`, and `reason`. These values are the
+arguments discord.py passed to its transport: query parameters are not wire-normalized
+strings, and `reason` is not an encoded HTTP header value. Uploaded files are not captured.
+The `json` field preserves every supplied JSON-compatible shape, including top-level arrays.
+`params` and `json` are detached deep snapshots, so later mutations to source containers do
+not alter a record. The request record is appended before fault injection and route handling,
+so failed and unimplemented requests remain observable.
 
 ## Injecting API failures