If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/gosub-io/gosub-engine shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit today
• 5 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 91% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live gosub-io/gosub-engine repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gosub-io/gosub-engine.

What it runs against: a local clone of gosub-io/gosub-engine — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in gosub-io/gosub-engine | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gosub-io/gosub-engine. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gosub-io/gosub-engine.git
#   cd gosub-engine
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of gosub-io/gosub-engine and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "gosub-io/gosub-engine(\\.git)?\\b" \\
  && ok "origin remote is gosub-io/gosub-engine" \\
  || miss "origin remote is not gosub-io/gosub-engine (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "crates/gosub_engine/src/lib.rs" \\
  && ok "crates/gosub_engine/src/lib.rs" \\
  || miss "missing critical file: crates/gosub_engine/src/lib.rs"
test -f "crates/gosub_html5/src/lib.rs" \\
  && ok "crates/gosub_html5/src/lib.rs" \\
  || miss "missing critical file: crates/gosub_html5/src/lib.rs"
test -f "crates/gosub_css3/src/lib.rs" \\
  && ok "crates/gosub_css3/src/lib.rs" \\
  || miss "missing critical file: crates/gosub_css3/src/lib.rs"
test -f "crates/gosub_taffy/src/lib.rs" \\
  && ok "crates/gosub_taffy/src/lib.rs" \\
  || miss "missing critical file: crates/gosub_taffy/src/lib.rs"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/gosub-io/gosub-engine"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Gosub is a modular, embeddable browser engine written in Rust that implements HTML5 parsing, CSS3 styling, async networking, layout via Taffy (flexbox), and multi-tab/zone architecture with pluggable render backends (Cairo/GTK4, Vello/wgpu, or headless). It gives developers a production-grade foundation for embedding browser capabilities in Rust applications without reimplementing the entire web stack. Monorepo with crates/ subdirectory containing ~20 specialized crates: gosub_engine (unified entry point), gosub_html5 & gosub_css3 (parsers), gosub_net (async networking), gosub_taffy (layout), gosub_cairo & gosub_vello (renderers), gosub_jsapi & gosub_v8 (scripting), gosub_config (settings). Root Cargo.toml defines workspace; examples/ contain runnable integration demos (gtk-renderer, vello-renderer, hello-world, multi-tab).

Rust developers building embedded applications that need to render HTML/CSS and execute web content (e.g., desktop apps, kiosks, custom UAs, headless scrapers). Contributors are those interested in browser engine internals, Rust systems programming, or bringing the open-source web platform to non-traditional environments.

Actively developed (ongoing commits visible in CI setup and examples) but not production-ready: core parsing and rendering pipelines work, but pixel-perfect output is incomplete, JavaScript execution integration is in progress, and the accessibility tree is missing. The project uses Rust 1.80+ with full CI/CD (GitHub Actions, clippy, benches) but predates any major version release.

Moderate-to-high risk: the engine is a large, complex undertaking (2.4M lines of Rust across 10+ crates) with multiple unfinished subsystems (JS integration, full layout pipeline), making it a long-term bet. Dependencies are standard (tokio, serde, cairo, wgpu) but the project currently lacks a large user base to validate production stability. Single-point-of-failure risk around core parsing and rendering decisions.

Incomplete rendering pipeline is the active focus: geometry is computed but pixel output needs work across cairo and vello backends (src/render/window.rs, crates/gosub_cairo/src/render/). JavaScript integration via gosub_v8 and gosub_jsapi is in active development. Layout engine is partially integrated via Taffy. GitHub Actions CI validates Rust compilation and likely benchmarks (bench.yaml, bencher.yaml files present but disabled).

git clone https://github.com/gosub-io/gosub-engine.git
cd gosub-engine
cargo build --release
cargo run --example hello-world

Daily commands: For headless parsing: cargo run --example html5-parser. For GTK renderer: cargo run --example gtk-renderer (requires GTK4 system libs). For Vello/wgpu: cargo run --example vello-renderer. For multi-tab demo: cargo run --example multi-tab. Core engine is library-driven; no single 'dev server'—drive it via GosubEngine::new() in async Tokio context.

• crates/gosub_engine/src/lib.rs — Entry point for GosubEngine; every contributor must understand the unified engine architecture and its async Tab/Zone model.
• crates/gosub_html5/src/lib.rs — HTML5 tokenizer and parser; critical for document ingestion and AST construction before layout/styling.
• crates/gosub_css3/src/lib.rs — CSS3 parser and matcher; essential for styling pipeline and understanding how rules are applied to the DOM.
• crates/gosub_taffy/src/lib.rs — Layout engine (Flexbox); core to the render pipeline after styling is resolved.
• Cargo.toml — Workspace root; defines crate dependencies and member layout; guides understanding of modular architecture.
• crates/gosub_cairo/src/engine_backend.rs — Render backend trait implementation; shows how custom rendering backends integrate with the engine.
• crates/gosub_net/src/lib.rs — Async networking stack with per-zone isolation; critical for resource fetching and security boundaries.

Add a new CSS at-rule parser (e.g., @layer, @supports)

1. Create parser module for the at-rule in crates/gosub_css3/src/parser/at_rule/ (crates/gosub_css3/src/parser/at_rule/my_rule.rs)
2. Import and register the parser in crates/gosub_css3/src/parser/at_rule.rs (crates/gosub_css3/src/parser/at_rule.rs)
3. Add AST variant to crates/gosub_css3/src/ast.rs for the new rule type (crates/gosub_css3/src/ast.rs)
4. Add matcher logic in crates/gosub_css3/src/matcher/styling.rs to apply rules during cascade (crates/gosub_css3/src/matcher/styling.rs)

Add a new render backend (e.g., Skia, Metal)

1. Create new crate crates/gosub_skia with Cargo.toml and src/lib.rs (crates/gosub_skia/src/lib.rs)
2. Implement the RenderBackend trait from crates/gosub_engine to handle frame rendering (crates/gosub_skia/src/backend.rs)
3. Follow element drawing patterns from crates/gosub_cairo/src/elements/ for rect, text, image, etc. (crates/gosub_skia/src/elements.rs)
4. Register backend in example usage (e.g., examples/skia-renderer/main.rs) (examples/skia-renderer/main.rs)

Add a new CSS function parser (e.g., calc, var, attr)

1. Create function module in crates/gosub_css3/src/functions/my_function.rs (crates/gosub_css3/src/functions/my_function.rs)
2. Import and dispatch in crates/gosub_css3/src/functions.rs (crates/gosub_css3/src/functions.rs)
3. Add AST node variant in crates/gosub_css3/src/ast.rs if needed (crates/gosub_css3/src/ast.rs)
4. Update syntax matcher in crates/gosub_css3/src/matcher/syntax_matcher.rs to validate function syntax (crates/gosub_css3/src/matcher/syntax_matcher.rs)

Add a new HTML element with custom rendering

1. Parse element in crates/gosub_html5/src/parser.rs (uses built-in HTML5 spec) (crates/gosub_html5/src/parser.rs)
2. Add layout hints if needed in gosub_taffy integration (crates/gosub_taffy/src/lib.rs)
3. Implement rendering in crates/gosub_cairo/src/elements/ or custom backend (crates/gosub_cairo/src/elements.rs)

• Rust + async/await — Memory safety without GC; efficient async I/O for networking and DOM parsing; zero-cost abstractions for layout/render hot paths.
• HTML5 spec-compliant tokenizer/parser — Ensures web compatibility; incremental parsing enables streaming and early rendering; handles malformed markup like browsers.
• CSS3 parser + cascade/specificity matcher — Full CSS spec compliance; property validation via JSON definitions; matcher isolates rule application from parsing.
• Taffy (flexbox) layout engine — Proven Rust flexbox; integrates seamlessly; modular (can swap for grid-focused library later).
• Cairo / Vello render backends — Cairo: stable GTK4 integration; Vello: GPU-accelerated wgpu for modern compositing; abstraction enables swappable backends.
• Per-zone networking stack — Security isolation (cookies/storage per tab); async resource loading; streaming support for large documents.

• Modular crate architecture (7+ crates) vs. monolithic lib

  • Why: Allows users to import only needed components (e.g., just HTML parser); enables independent versioning; clearer dependency graph.
  • Consequence: Increased workspace complexity; more interdependencies to manage; larger build times if all crates used.

• Incremental HTML parsing (streaming) vs. full-buffer parse

  • Why: Enables progressive rendering and early DOM/style application; matches real browser behavior.
  • Consequence: More complex parser state machine; potential for spec edge cases in streaming mode.

• Abstract RenderBackend trait vs. hardcoded Cairo

  • Why: Users can provide custom backends (Skia, Metal, Vulkan); reduces coupling to single graphics library.
  • Consequence: Render trait must be generic enough; potential for misaligned assumptions between backends.

• Zone-based isolation for cookies/storage/networking

  • Why: Prevents data leakage across tabs; matches browser security model; enables proper cookie domain/path rules.
  • Consequence: Adds complexity to zone lifecycle; requires careful cleanup; may impact performance in many-tab scenarios.

• Does not implement JavaScript execution (no JS engine embedded; pure layout/render).
• Does not handle authentication, login, or credential management (that is UA responsibility).
• Does not provide a full browser UI (chrome, address bar, tabs are UA's job).
• Does not optimize for real-time video playback or WebGL (render backends are 2D-focused).
• Not intended

System dependencies: GTK4 and Cairo development headers required for gtk-renderer example on Linux/macOS (install via apt/brew). V8 bindings: gosub_v8 crate may require pre-built V8 libs or build from source; check crates/gosub_v8/Cargo.toml for platform-specific requirements. Async runtime: GosubEngine requires Tokio full features (spawning, timers, I/O); do not use with other async runtimes. Incomplete rendering: pixel output is not yet pixel-perfect even on supported backends—layout is computed but visual fidelity is WIP. No 'default' backend: you must explicitly choose NullBackend, Cairo, or Vello; no automatic fallback.

• HTML5 tree-building algorithm — Gosub's parser (gosub_html5) implements the official W3C algorithm; understanding how it handles foster parenting, adoption agency, and error recovery is essential to debugging parsing bugs.
• CSS cascade & specificity — Gosub's CSS parser produces a stylesheet tree that must resolve conflicts via cascade rules; misunderstanding selector specificity causes incorrect style application.
• Flexbox layout model — Gosub delegates layout to Taffy, a pure-Rust flexbox engine; understanding flex growth/shrinking and main/cross axes is needed to debug layout bugs in gosub_taffy integration.
• Zone-based origin isolation — Gosub's multi-tab model uses zones to isolate cookies, storage, and cache per site; this is a critical security boundary—misunderstanding zone boundaries can leak data between tabs.
• Async streaming HTTP with coalescing — Gosub's fetcher (gosub_net) combines multiple identical requests into a single network round-trip; understanding coalescing and priority queues avoids duplicate fetch bugs.
• Render backend trait abstraction — Gosub defines a RenderBackend trait that Cairo, Vello, and Null backends implement; new renderers must satisfy this contract, so understanding the trait is critical for graphics work.
• Event bus & tab command model — GosubEngine communicates via EngineEvent (redraw, navigation, resource) and receives TabCommand (navigate, reload); this event model is the primary external API, so understanding flow is essential.

• servo/servo — Full-featured Rust browser engine; Gosub is a lighter-weight, more embeddable alternative with pluggable backends.
• taffy-rs/taffy — Standalone Rust flexbox layout engine that Gosub integrates; useful for understanding the layout subsystem.
• gfx-rs/wgpu — GPU abstraction layer used by Gosub's Vello renderer backend; critical for graphics pipeline.
• mozilla/moz-central — Firefox/Gecko engine; canonical reference for HTML5/CSS3 parsing and rendering spec compliance.
• bytecodealliance/wasmtime — WASM runtime; potential future integration point for sandboxed JavaScript or plugin execution in Gosub.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for gosub_css3 property parsing

The gosub_css3 crate contains CSS property definitions (crates/gosub_css3/resources/definitions/definitions_properties.json) and parsing logic, but there are no visible test files in the crate structure. This is critical for a CSS parser—adding unit tests for property parsing, value validation, and selector handling will catch regressions early and improve confidence in CSS compliance.

• [ ] Create crates/gosub_css3/tests/property_parsing_tests.rs with tests for each CSS property type
• [ ] Add tests for at-rules parsing using definitions_at-rules.json
• [ ] Add tests for selector parsing using definitions_selectors.json
• [ ] Add tests for CSS value parsing (colors, gradients, transforms) from definitions_values.json
• [ ] Run cargo test in crates/gosub_css3 and ensure >80% coverage

Create CI workflow for benchmark tracking with Bencher integration

The repo has benchmark files (benches/bytestream.rs, benches/tree_iterator.rs) and disabled Bencher workflow files (.github/workflows/bencher.yaml.disabled, bencher_baseline.yaml.disabled), but they are not active. Re-enabling and properly configuring these workflows will help track performance regressions across PRs—critical for a browser engine where performance is essential.

• [ ] Rename and enable .github/workflows/bencher.yaml.disabled to bencher.yaml
• [ ] Configure bencher.yaml to run on PR events and track gosub_html5 parser and tree_iterator benchmarks
• [ ] Set up Bencher project integration with appropriate thresholds for regression detection
• [ ] Update .github/workflows/bencher_baseline.yaml.disabled for baseline establishment on main branch
• [ ] Document benchmark results in CONTRIBUTING.md with guidance for contributors

Add integration tests for gosub_engine multi-tab/zone isolation

The README mentions that GosubEngine owns a 'multi-zone/tab model' with 'cookie and storage isolation per zone', but there are no visible integration test files demonstrating this critical feature. Adding tests will verify zone isolation works correctly and prevent future security/correctness regressions.

• [ ] Create crates/gosub_engine/tests/zone_isolation_tests.rs
• [ ] Add tests verifying cookie isolation between zones using gosub_config storage layer
• [ ] Add tests verifying DOM/localStorage isolation between tabs in the same zone
• [ ] Add tests for concurrent tab operations and event bus message routing per zone
• [ ] Reference examples/multi-tab.rs as a starting point for test scenarios
• [ ] Document expected behaviors in crates/gosub_engine/ZONE_ISOLATION.md

• Add integration tests for crates/gosub_html5/src/parser.rs against real HTML5 test suite (e.g., parse a library of known-good documents and verify tree structure); currently missing regression test coverage for edge cases.
• Implement missing CSS3 selector support in crates/gosub_css3/src/parser.rs—pseudoclasses like :nth-child() and :not() are partially stubbed; complete these with spec-compliant parsing.
• Write documentation + examples for gosub_config's per-zone isolation model in crates/gosub_config/src/lib.rs; the cookie jar and storage partitioning logic is powerful but underdocumented for new contributors.

The Gosub browser engine codebase demonstrates reasonable foundational security practices with version pinning, workspace organization, and a security contact mechanism. However, the security posture is hindered by: (1) an incomplete security policy lacking disclosure timelines and procedures, (2) a malformed PGP key in security documentation, (3) limited visibility into dependency security scanning and CI/CD security controls, and (4) missing supply chain transparency measures. For a browser engine processing untrusted web content, stronger security governance and automated vulnerability detection are recommended. No critical vulnerabilities were identified in the provided file structure, but a full code review would be necessary to assess injection risks and secure coding practices.

• Medium · Incomplete Security Policy — SECURITY.md. The SECURITY.md file states 'we do not have a security policy in place' and only provides a contact email. There is no defined vulnerability disclosure timeline, severity guidelines, or patch release procedures. This could lead to delayed security responses. Fix: Implement a comprehensive security policy including: vulnerability disclosure timeline (e.g., 90 days), severity classification system, patch release procedures, and security update notification mechanism. Reference industry standards like CVSS scoring.
• Medium · Incomplete PGP Key in Security Documentation — SECURITY.md. The PGP public key block in SECURITY.md appears truncated ('-----BEGIN PGP PUBLIC KEY BLOCK-----' followed by key data but ending abruptly without '-----END PGP PUBLIC KEY BLOCK-----'). This may indicate the key is malformed or incomplete, reducing trust in the security contact mechanism. Fix: Provide a complete, valid PGP public key with proper formatting. Verify the key is importable and functional. Consider publishing the key on a keyserver for verification.
• Low · Missing Dependency Security Scanning Configuration — Cargo.toml, audit.toml. While an 'audit.toml' file exists, the codebase uses 'registry = "gosub"' for internal dependencies which may not be publicly available or security-audited. No evidence of automated dependency vulnerability scanning in CI/CD pipeline (ci.yaml workflow shown but content not visible). Fix: Ensure cargo-audit or similar tools are integrated into CI/CD. Verify the 'gosub' registry is properly secured. Consider using 'cargo-deny' for additional supply chain security checks. Make audit results visible in pull requests.
• Low · No SBOM or Dependency Transparency — Cargo.toml, Cargo.lock. The provided Cargo.toml is truncated and no Software Bill of Materials (SBOM) is evident. For a browser engine handling untrusted content, complete dependency transparency is important for security audits. Fix: Generate and maintain an SBOM using tools like 'cargo-cyclonedx'. Publish SBOM with releases. Include all transitive dependencies with versions in documentation.
• Low · Limited CI/CD Security Configuration Visibility — .github/workflows/. Multiple workflow files are disabled (.disabled extension), and the enabled ci.yaml content is not visible. Cannot verify if security checks (SAST, dependency scanning, signed commits) are enforced. Fix: Enable and document security-focused CI/CD checks: enable SAST (e.g., cargo-clippy), require signed commits for main branch, implement branch protection rules, add dependency scanning, and run security tests on all PRs.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.