From c0178e39a5129208011761cc28b2869e592260fa Mon Sep 17 00:00:00 2001 From: Noah Lyons Date: Thu, 20 Nov 2025 23:16:41 -0500 Subject: [PATCH 1/5] Add Playwright screenshot helper and usage guide --- .gitignore | 2 ++ README.md | 33 +++++++++++++++++++++++++++++ scripts/playwright_capture.py | 39 +++++++++++++++++++++++++++++++++++ 3 files changed, 74 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 scripts/playwright_capture.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7a60b85 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +__pycache__/ +*.pyc diff --git a/README.md b/README.md new file mode 100644 index 0000000..24f90f9 --- /dev/null +++ b/README.md @@ -0,0 +1,33 @@ +# SEC3ENGINE Playwright Access + +This repository contains static web demos under the project root and within the `Sec3Engine/` folder. To visually verify changes from within this environment, you can serve the files locally and capture screenshots with Playwright. + +## 1. Serve the project locally +From the repository root, start a simple HTTP server on port 8000: + +```bash +python -m http.server 8000 +``` + +- The root `index.html` and `particleDemo.html` will be available at `http://localhost:8000/`. +- The Sec3Engine assets can be accessed under `http://localhost:8000/Sec3Engine/` (for example, `http://localhost:8000/Sec3Engine/index.html`). + +Keep this server running in its own terminal while you capture screenshots. + +## 2. Capture a screenshot with Playwright +Use the provided helper script to open a page and grab a screenshot. The script is designed to work with the built-in Playwright environment available through the `browser_container` tool, but it can also run anywhere Playwright is installed. + +```bash +python scripts/playwright_capture.py --url http://localhost:8000/index.html --out artifacts/home.png --wait 1500 +``` + +- `--url` is the page to open. +- `--out` is where the screenshot is saved (directories will be created if they do not exist). +- `--wait` adds an optional delay (in milliseconds) after navigation to let assets finish loading. + +When running inside this workspace, you can call the `browser_container.run_playwright_script` helper with the same script to render the live server and return the screenshot artifact. + +## 3. Troubleshooting +- If you change the server port, pass the matching URL to `--url`. +- The Playwright script launches Chromium headless by default. If you need a different viewport, use `--width` and `--height`. +- For local (non-workspace) usage, ensure the `playwright` Python package and browsers are installed (`pip install playwright && playwright install`). diff --git a/scripts/playwright_capture.py b/scripts/playwright_capture.py new file mode 100644 index 0000000..c834980 --- /dev/null +++ b/scripts/playwright_capture.py @@ -0,0 +1,39 @@ +import argparse +import asyncio +from pathlib import Path + +from playwright.async_api import async_playwright + + +def parse_args(): + parser = argparse.ArgumentParser(description="Capture a screenshot of a URL using Playwright") + parser.add_argument("--url", default="http://localhost:8000/index.html", help="Page URL to capture") + parser.add_argument("--out", default="artifacts/screenshot.png", help="Path to save the screenshot") + parser.add_argument("--wait", type=int, default=0, help="Delay in milliseconds after navigation") + parser.add_argument("--width", type=int, default=1280, help="Viewport width") + parser.add_argument("--height", type=int, default=720, help="Viewport height") + return parser.parse_args() + + +async def capture(url: str, out_path: Path, wait_ms: int, width: int, height: int) -> None: + out_path.parent.mkdir(parents=True, exist_ok=True) + + async with async_playwright() as p: + browser = await p.chromium.launch() + page = await browser.new_page(viewport={"width": width, "height": height}) + await page.goto(url) + + if wait_ms > 0: + await page.wait_for_timeout(wait_ms) + + await page.screenshot(path=str(out_path), full_page=True) + await browser.close() + + +async def main(): + args = parse_args() + await capture(args.url, Path(args.out), args.wait, args.width, args.height) + + +if __name__ == "__main__": + asyncio.run(main()) From 2de716415d14fcdffd3f9fa21c547f4c0f064435 Mon Sep 17 00:00:00 2001 From: Noah Lyons Date: Sat, 22 Nov 2025 21:58:10 -0500 Subject: [PATCH 2/5] Harden Playwright helper and documentation --- .gitignore | 6 ++++++ README.md | 11 ++++++++--- scripts/playwright_capture.py | 26 +++++++++++++++++--------- 3 files changed, 31 insertions(+), 12 deletions(-) diff --git a/.gitignore b/.gitignore index 7a60b85..9551b9b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,8 @@ __pycache__/ *.pyc +artifacts/ +.venv/ +.idea/ +.vscode/ +*.DS_Store +node_modules/ diff --git a/README.md b/README.md index 24f90f9..c6499f5 100644 --- a/README.md +++ b/README.md @@ -23,11 +23,16 @@ python scripts/playwright_capture.py --url http://localhost:8000/index.html --ou - `--url` is the page to open. - `--out` is where the screenshot is saved (directories will be created if they do not exist). -- `--wait` adds an optional delay (in milliseconds) after navigation to let assets finish loading. +- `--wait` adds an optional delay (in milliseconds) after navigation to let assets finish loading (defaults to `0`). When running inside this workspace, you can call the `browser_container.run_playwright_script` helper with the same script to render the live server and return the screenshot artifact. ## 3. Troubleshooting - If you change the server port, pass the matching URL to `--url`. -- The Playwright script launches Chromium headless by default. If you need a different viewport, use `--width` and `--height`. -- For local (non-workspace) usage, ensure the `playwright` Python package and browsers are installed (`pip install playwright && playwright install`). +- The Playwright script launches Chromium headless by default with container-friendly flags (`--no-sandbox` and `--disable-dev-shm-usage`). If you need a different viewport, use `--width` and `--height`. +- For local (non-workspace) usage, ensure the `playwright` Python package and browsers are installed: + + ```bash + pip install playwright + playwright install + ``` diff --git a/scripts/playwright_capture.py b/scripts/playwright_capture.py index c834980..088150f 100644 --- a/scripts/playwright_capture.py +++ b/scripts/playwright_capture.py @@ -19,15 +19,23 @@ async def capture(url: str, out_path: Path, wait_ms: int, width: int, height: in out_path.parent.mkdir(parents=True, exist_ok=True) async with async_playwright() as p: - browser = await p.chromium.launch() - page = await browser.new_page(viewport={"width": width, "height": height}) - await page.goto(url) - - if wait_ms > 0: - await page.wait_for_timeout(wait_ms) - - await page.screenshot(path=str(out_path), full_page=True) - await browser.close() + browser = await p.chromium.launch( + headless=True, + args=["--no-sandbox", "--disable-dev-shm-usage"], + ) + context = await browser.new_context(viewport={"width": width, "height": height}) + page = await context.new_page() + + try: + await page.goto(url) + + if wait_ms > 0: + await page.wait_for_timeout(wait_ms) + + await page.screenshot(path=str(out_path), full_page=True) + finally: + await context.close() + await browser.close() async def main(): From f105a34045e5867ad24571a775fe6195d8f37658 Mon Sep 17 00:00:00 2001 From: Noah Lyons Date: Sat, 22 Nov 2025 21:58:14 -0500 Subject: [PATCH 3/5] Document workspace Playwright usage and dependency --- README.md | 28 ++++++++++++++++++++++++++++ requirements.txt | 1 + 2 files changed, 29 insertions(+) create mode 100644 requirements.txt diff --git a/README.md b/README.md index c6499f5..1422ce1 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,34 @@ python scripts/playwright_capture.py --url http://localhost:8000/index.html --ou When running inside this workspace, you can call the `browser_container.run_playwright_script` helper with the same script to render the live server and return the screenshot artifact. +Example (inside this workspace): + +```python +from browser_container import run_playwright_script + +run_playwright_script( + ports_to_forward=[8000], + script=""" +import asyncio +from playwright.async_api import async_playwright + +async def main(): + async with async_playwright() as p: + browser = await p.chromium.launch(headless=True, args=[\"--no-sandbox\", \"--disable-dev-shm-usage\"]) + context = await browser.new_context(viewport={"width": 1280, "height": 720}) + page = await context.new_page() + await page.goto('http://127.0.0.1:8000/index.html') + await page.wait_for_timeout(1000) + await page.screenshot(path='artifacts/example.png', full_page=True) + await browser.close() + +asyncio.run(main()) +""", +) +``` + +> Note: The Python `playwright` package is not preinstalled in this environment and external network access is restricted, so `pip install playwright` may fail. If you need to run the helper locally, install the dependency where network access is available. + ## 3. Troubleshooting - If you change the server port, pass the matching URL to `--url`. - The Playwright script launches Chromium headless by default with container-friendly flags (`--no-sandbox` and `--disable-dev-shm-usage`). If you need a different viewport, use `--width` and `--height`. diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..508a5f4 --- /dev/null +++ b/requirements.txt @@ -0,0 +1 @@ +playwright From bb5fc46c643f89cbb59480a65c8e5d2535487a20 Mon Sep 17 00:00:00 2001 From: Noah Lyons Date: Sat, 22 Nov 2025 21:58:20 -0500 Subject: [PATCH 4/5] Integrate Playwright guidance into README --- README.md | 55 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 30 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 1422ce1..3546466 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,44 @@ -# SEC3ENGINE Playwright Access +# SEC3ENGINE -This repository contains static web demos under the project root and within the `Sec3Engine/` folder. To visually verify changes from within this environment, you can serve the files locally and capture screenshots with Playwright. +A collection of WebGL demos and a lightweight engine prototype for rendering experiments. The repository contains the core engine under `Sec3Engine/`, a few HTML entry points, and an older "NoEngines" demo for comparison. -## 1. Serve the project locally -From the repository root, start a simple HTTP server on port 8000: +## Project layout +- **`index.html`**: Loads the Sec3Engine core and runs the `SEC3DEMO` scene (water/particle-style rendering) inside a canvas. +- **`particleDemo.html`**: Alternate entry that exercises the particle system. +- **`Sec3Engine/`**: Engine sources (`js/core`, `js/math`, `js/3party`), shaders, and an additional `sec3index.html` demo page. +- **`NoEngines/`**: Legacy demo without the engine abstraction. Open `NoEngines/index.html` to compare behaviors. + +## Running locally +Serve the repo root so the demos can load their assets via HTTP. The simplest option uses Python: ```bash python -m http.server 8000 ``` -- The root `index.html` and `particleDemo.html` will be available at `http://localhost:8000/`. -- The Sec3Engine assets can be accessed under `http://localhost:8000/Sec3Engine/` (for example, `http://localhost:8000/Sec3Engine/index.html`). +Then open one of the pages in your browser: + +- Main demo: `http://localhost:8000/index.html` +- Particle demo: `http://localhost:8000/particleDemo.html` +- Engine sample page: `http://localhost:8000/Sec3Engine/sec3index.html` +- Legacy comparison: `http://localhost:8000/NoEngines/index.html` -Keep this server running in its own terminal while you capture screenshots. +> If you change ports, update the URLs accordingly. -## 2. Capture a screenshot with Playwright -Use the provided helper script to open a page and grab a screenshot. The script is designed to work with the built-in Playwright environment available through the `browser_container` tool, but it can also run anywhere Playwright is installed. +## Capturing screenshots with Playwright +You can automate visual checks using the included helper script. It works both locally (with Playwright installed) and inside this workspace via the built-in `browser_container` runtime. ```bash python scripts/playwright_capture.py --url http://localhost:8000/index.html --out artifacts/home.png --wait 1500 ``` -- `--url` is the page to open. -- `--out` is where the screenshot is saved (directories will be created if they do not exist). -- `--wait` adds an optional delay (in milliseconds) after navigation to let assets finish loading (defaults to `0`). +Flags: +- `--url`: page to open. +- `--out`: where to save the screenshot (directories are created automatically). +- `--wait`: optional delay in milliseconds after navigation (defaults to `0`). +- `--width` / `--height`: viewport size (defaults to `1280x720`). -When running inside this workspace, you can call the `browser_container.run_playwright_script` helper with the same script to render the live server and return the screenshot artifact. - -Example (inside this workspace): +### Workspace usage +If you are in the ChatGPT/Codex workspace, start the local server and call `browser_container.run_playwright_script` to reuse the Playwright runtime without installing anything: ```python from browser_container import run_playwright_script @@ -53,14 +64,8 @@ asyncio.run(main()) ) ``` -> Note: The Python `playwright` package is not preinstalled in this environment and external network access is restricted, so `pip install playwright` may fail. If you need to run the helper locally, install the dependency where network access is available. - -## 3. Troubleshooting -- If you change the server port, pass the matching URL to `--url`. -- The Playwright script launches Chromium headless by default with container-friendly flags (`--no-sandbox` and `--disable-dev-shm-usage`). If you need a different viewport, use `--width` and `--height`. -- For local (non-workspace) usage, ensure the `playwright` Python package and browsers are installed: +> Note: The Python `playwright` package is optional and may not install in restricted environments. Install it (and run `playwright install`) on a machine with network access if you want to run the helper locally. - ```bash - pip install playwright - playwright install - ``` +## Troubleshooting +- Use a modern browser with WebGL enabled; if assets fail to load, confirm you’re serving over HTTP rather than `file://`. +- For Playwright captures, ensure the server is running and the forwarded port matches the URL passed to the script. From 731a15ea395e1a95e741b2609d5cb173e33ff1d5 Mon Sep 17 00:00:00 2001 From: Noah Lyons Date: Tue, 9 Dec 2025 16:42:58 -0500 Subject: [PATCH 5/5] Update README with integrated project guidance --- README.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 3546466..26558ce 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,18 @@ # SEC3ENGINE -A collection of WebGL demos and a lightweight engine prototype for rendering experiments. The repository contains the core engine under `Sec3Engine/`, a few HTML entry points, and an older "NoEngines" demo for comparison. +A collection of WebGL rendering demos plus a lightweight engine prototype. The repository includes multiple HTML entry points and the `Sec3Engine` source tree (core, math helpers, third-party utilities, shaders, textures, and sample models). ## Project layout -- **`index.html`**: Loads the Sec3Engine core and runs the `SEC3DEMO` scene (water/particle-style rendering) inside a canvas. -- **`particleDemo.html`**: Alternate entry that exercises the particle system. -- **`Sec3Engine/`**: Engine sources (`js/core`, `js/math`, `js/3party`), shaders, and an additional `sec3index.html` demo page. -- **`NoEngines/`**: Legacy demo without the engine abstraction. Open `NoEngines/index.html` to compare behaviors. +- **`index.html`** – Loads the Sec3Engine core and runs the `SEC3DEMO` scene inside a canvas. +- **`particleDemo.html`** – Alternate entry that focuses on the particle system. +- **`Sec3Engine/`** – Engine sources and assets: + - `js/core`: scene graph, renderer, and runtime helpers. + - `js/math`: small math/geometry utility layer. + - `js/3party`: third-party JavaScript helpers used by the engine. + - `shader`: GLSL programs consumed by the demos. + - `textures` and `models`: sample assets (Sponza, spheres, planes, cube world, etc.). + - `demos` / `misc`: additional experiments and supporting files. +- **`NoEngines/`** – Legacy demo without the engine abstraction; open `NoEngines/index.html` to compare behaviors. ## Running locally Serve the repo root so the demos can load their assets via HTTP. The simplest option uses Python: @@ -16,7 +22,6 @@ python -m http.server 8000 ``` Then open one of the pages in your browser: - - Main demo: `http://localhost:8000/index.html` - Particle demo: `http://localhost:8000/particleDemo.html` - Engine sample page: `http://localhost:8000/Sec3Engine/sec3index.html` @@ -25,7 +30,7 @@ Then open one of the pages in your browser: > If you change ports, update the URLs accordingly. ## Capturing screenshots with Playwright -You can automate visual checks using the included helper script. It works both locally (with Playwright installed) and inside this workspace via the built-in `browser_container` runtime. +Automate visual checks using the helper script. It works both locally (with Playwright installed) and inside this workspace via the built-in Playwright runtime. ```bash python scripts/playwright_capture.py --url http://localhost:8000/index.html --out artifacts/home.png --wait 1500 @@ -66,6 +71,11 @@ asyncio.run(main()) > Note: The Python `playwright` package is optional and may not install in restricted environments. Install it (and run `playwright install`) on a machine with network access if you want to run the helper locally. +## Development notes +- Assets and shaders are loaded relative to the repository root; serving over HTTP avoids CORS and local file access issues. +- The engine JavaScript is split between `js/core` (scene and renderer plumbing) and `js/math` utilities; third-party helpers live in `js/3party`. +- Sample models (Sponza, spheres, planes, cube world) reside under `Sec3Engine/models/` and are referenced by the demo HTML pages. + ## Troubleshooting - Use a modern browser with WebGL enabled; if assets fail to load, confirm you’re serving over HTTP rather than `file://`. - For Playwright captures, ensure the server is running and the forwarded port matches the URL passed to the script.