Skip to content

feat(browser): adopt Ghostty v1.4 WASM through a maintained upstream wrapper #41

New issue
New issue
Open
Task
Open
feat(browser): adopt Ghostty v1.4 WASM through a maintained upstream wrapper#41
Task
Labels
P3Low-risk cleanup, docs, polish, ergonomics, or speculative feature.dependenciesPull requests that update a dependency fileenhancementNew feature or requestissue-rating: 🌊 off-meta tidepoolIssue quality rating does not apply to this item.

Description

@vincentkoc
vincentkoc
opened on Jul 29, 2026

Problem

@openclaw/libterminal currently pins ghostty-web@0.4.0, whose bundled WASM predates Ghostty's v1.4.0 VT throughput work and native libghostty-vt terminal/render APIs.

Ghostty's July 2026 parser changes report roughly 1.5x to 6x throughput improvements, but those changes are currently available only on Ghostty main/tip. Adopting an unreleased commit or maintaining a private ABI patch in this repository would make libterminal responsible for an unstable upstream boundary.

Upstream gates

Do not start the dependency upgrade until both conditions are true:

  • Ghostty publishes a stable v1.4.0 tag.
  • A maintained upstream package publishes a Ghostty v1.4-compatible browser/WASM wrapper that provides the runtime and terminal surface libterminal consumes.

Tracking:

Ownership boundary

libterminal must not fork, patch, or port the Ghostty C/WASM ABI.

Consume a maintained upstream release with a reproducible build and stable package contract. If no compatible upstream wrapper is published, leave this issue blocked rather than importing that ABI maintenance burden into libterminal.

Proposed work

  • Replace the ghostty-web@0.4.0 pin with the stable compatible release.
  • Confirm the wrapper still exposes the browser runtime surface used by loadGhosttyRuntime, including initialization, terminal construction, fitting, writes, resize, disposal, and input events.
  • Regenerate the embedded Worker module, WASM, and browser-external assets with pnpm run generate:worker-assets.
  • Verify Node asset serving still resolves the exact module and WASM shipped by the pinned package.
  • Re-evaluate the default-color query compatibility responder. Remove or narrow it only if the new wrapper demonstrably emits the required OSC 10-12 responses itself.
  • Add an Unreleased changelog entry describing the runtime dependency and performance change.

Performance evidence

Capture comparable before/after results using the existing ghostty-web@0.4.0 build as the baseline:

  • sustained terminal write/parse throughput for plain text, Unicode/CJK, and escape-heavy output
  • end-to-end browser write-to-render time under high output
  • startup/WASM initialization time
  • shipped WASM and generated Worker asset size
  • peak memory under a bounded scrollback workload

The goal is to prove a meaningful product-level improvement, not repeat upstream parser-only benchmark claims.

Acceptance criteria

  • The dependency is pinned to a stable published version, not Ghostty main, tip, a Git commit, or a locally patched artifact.
  • No Ghostty ABI implementation or compatibility fork is added to this repository.
  • Existing browser, Worker, and Node asset APIs remain compatible.
  • Focused runtime tests and asset byte-integrity tests pass.
  • Browser smoke proves a nonblank terminal, input, resize, disposal, and sustained high-output rendering.
  • Before/after performance and artifact-size results are recorded in the pull request.
  • pnpm test, pnpm test:browser, pnpm check, and pnpm run check:release pass.

Activity

  1. vincentkoc
    added
    enhancementNew feature or request
    dependenciesPull requests that update a dependency file
    on Jul 29, 2026
  2. vincentkoc
    added the
    Task
    issue type on Jul 29, 2026
  3. clawsweeper
    added
    P3Low-risk cleanup, docs, polish, ergonomics, or speculative feature.
    issue-rating: 🌊 off-meta tidepoolIssue quality rating does not apply to this item.
    clawsweeper:no-new-fix-prClawSweeper does not recommend queueing a new automated fix PR for this issue.
    clawsweeper:needs-maintainer-reviewClawSweeper marked this issue as needing maintainer review before automation.
    clawsweeper:needs-product-decisionClawSweeper marked this issue as needing a product or behavior decision.
    on Jul 29, 2026

  4. clawsweeper commented on Jul 29, 2026

    @clawsweeper
    clawsweeperBot
    on Jul 29, 2026 – with ClawSweeper

    Codex review: this still needs some work.

    Summary
    Keep this issue open: adoption remains unimplemented, both publication gates remain unmet, and MEMBER authorship protects it from automatic closure.

    Reproducibility: This requests future runtime adoption rather than a reproducible defect; source confirms the existing pin, and direct publication checks establish the outstanding prerequisites.

    Root-cause cluster
    Relationship: canonical
    Canonical: #41
    Summary: This issue owns runtime adoption; related searches found validation groundwork without a replacement adoption item.

    Members:

    Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

    Next step
    Retain the publication hold, then select and validate an exact stable wrapper once both upstream gates are met.

    Review details

    Best possible solution:

    Adopt a qualifying stable upstream release with compatible public APIs, regenerated assets, comparable performance evidence, and complete peak-memory measurements.

    Do we have a high-confidence way to reproduce the issue?

    This requests future runtime adoption rather than a reproducible defect; source confirms the existing pin, and direct publication checks establish the outstanding prerequisites.

    Is this the best way to solve the issue?

    The maintained-release approach respects the recorded ABI ownership boundary, and the merged baseline supports comparison once a candidate exists; complete peak-memory measurement must supplement sampled JS heap.

    AGENTS.md: found and applied where relevant.

    Remaining risk / open question:

    • Neither the stable Ghostty v1.4 tag nor a qualifying stable wrapper in the named dependency channel is available.
    • Candidate compatibility, reproducible build provenance, product-level performance gains, and complete peak memory remain unverified.

    Codex review notes: model internal, reasoning medium; reviewed against d029be0e2bc6.

    Label changes

    Label changes:

    No label changes.

    Label justifications:

    • P3: This is a gated future runtime improvement without an established current-user failure or urgent regression.
    Evidence reviewed

    What I checked:

    Likely related people:

    • Vincent Koc: Raw commit 402f019 adds src/worker-assets.ts:15 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 402f019f2b17; files: src/worker-assets.ts)
    • Peter Steinberger: Raw commit 7dbbe58 adds docs/ghostty-upgrade.md:5 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 7dbbe58089ca; files: docs/ghostty-upgrade.md)
    How this review workflow works
    • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
    • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
    • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
    • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
    • Maintainers can also comment @clawsweeper review to request a fresh review only.
    • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge; those execution lanes are retired.
    • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

    Reviewed October 12, 2026, 11:50 AM ET / 15:50 UTC.

  5. clawsweeper
    added
    clawsweeper:needs-maintainer-reviewClawSweeper marked this issue as needing maintainer review before automation.
    impact:otherThis issue has meaningful maintainer-visible impact outside the owned taxonomy.
    clawsweeper:fix-shape-clearClawSweeper found a clear likely implementation shape for this issue.
    and removed
    clawsweeper:needs-maintainer-reviewClawSweeper marked this issue as needing maintainer review before automation.
    impact:otherThis issue has meaningful maintainer-visible impact outside the owned taxonomy.
    on Jul 31, 2026

  6. 13 remaining items

  7. clawsweeper
    added
    impact:otherThis issue has meaningful maintainer-visible impact outside the owned taxonomy.
    clawsweeper:needs-maintainer-reviewClawSweeper marked this issue as needing maintainer review before automation.
    and removed
    clawsweeper:needs-maintainer-reviewClawSweeper marked this issue as needing maintainer review before automation.
    impact:otherThis issue has meaningful maintainer-visible impact outside the owned taxonomy.
    on Sep 2, 2026
  8. steipete
    added a commit that references this issue on Sep 4, 2026

    chore(deps-dev): refresh development toolchain (#57)

    cf9b92c
  9. clawsweeper
    added
    impact:otherThis issue has meaningful maintainer-visible impact outside the owned taxonomy.
    on Sep 4, 2026
  10. steipete
    added 2 commits that reference this issue on Sep 5, 2026

    chore(deps-dev): upgrade build and test toolchain

    010f1aa

    chore(deps): refresh browser tooling and pnpm setup

    8da88d2
  11. clawsweeper
    removed
    clawsweeper:no-new-fix-prClawSweeper does not recommend queueing a new automated fix PR for this issue.
    clawsweeper:needs-maintainer-reviewClawSweeper marked this issue as needing maintainer review before automation.
    clawsweeper:needs-product-decisionClawSweeper marked this issue as needing a product or behavior decision.
    impact:otherThis issue has meaningful maintainer-visible impact outside the owned taxonomy.
    on Sep 8, 2026

  12. steipete commented on Sep 14, 2026

    @steipete
    steipete
    on Sep 14, 2026
    Contributor

    Implementation status (September 14, 2026): the validation groundwork landed in #77, squash commit 7dbbe58089ca484f0289742e175a5a577db09d16; the v1.4 adoption remains blocked on the two publication gates, so this issue stays open.

    Rechecked upstream: the exact Ghostty refs/tags/v1.4.0 lookup returns 404, npm still reports stable ghostty-web@0.4.0 (next: 0.4.0-next.20.g1858a59), and wrapper PR #169 and release-candidate PR #182 remain open/unmerged. There is no qualifying published wrapper in the named dependency channel to adopt. The existing core and OSC 10–12 compatibility responder remain intact; no private ABI implementation was added.

    #77 expands the previous nonblank-canvas smoke into Node/Worker asset lifecycle checks and six plain/Unicode/escape-heavy sustained-output cases. They verify input/read-only transitions, resize callbacks, fit, disposal, every retained numbered output line, and changing rendered canvas pixels. JSON baselines record startup, write-call throughput, write-to-observed-canvas latency, artifact size, sampled JS heap, and retained buffer length. The PR records the measurements and their limits; docs/ghostty-upgrade.md provides the reproducible method.

    Exact-head CI run 34888536574 passed on e977518084e47c1f41f7ead3d7addf06d3e2de58, including Node 22/24 on Linux, macOS, and Windows, Node 26 on Linux, workflow lint, and browser smoke; CodeQL also passed. Local proof: pnpm check:release passed, including all 106 unit tests, nine browser tests, formatting, build, portable type checks, lint, and package checks. Final independent P0–P2 autoreview is scoped-clean after strengthening retained-output validation and timeout handling. Functional browser proof uses synthetic fixtures with the actual built package and shipped WASM; existing-profile Chrome automation was unavailable. The current wrapper retained up to 1,160 total buffer lines with configured scrollback 100, so the test explicitly avoids treating that setting as an exact line cap.

    Remaining work: wait for stable Ghostty v1.4 and a maintained compatible wrapper release; verify provenance/reproducible build, pin that exact version, regenerate assets, rerun the lifecycle and byte-integrity gates, evaluate native OSC responses, and record comparable before/after performance plus complete WASM/native/process peak memory. The sampled JS heap diagnostic does not satisfy the full-memory acceptance criterion. No v1.4 performance improvement is claimed yet.

  13. clawsweeper commented on Sep 28, 2026

    @clawsweeper
    clawsweeperBot
    on Sep 28, 2026 – with ClawSweeper

    🦞⚠️
    Automatic implementation stopped before completion.
    Reason: The worker failed while it planned the implementation. Open the workflow run for the exact blocker.
    Worker: https://github.com/openclaw/clawsweeper/actions/runs/38096885994

  14. vincentkoc commented on Oct 31, 2026

    @vincentkoc
    vincentkoc
    on Oct 31, 2026
    MemberAuthor

    Maintainer status (2026-10-31): the first publication gate is now met. Ghostty published the signed v1.4.0 tag on October 27, 2026, pointing to commit 83fb95624b0439ee660c2679b43b38c8b63769cd. The issue checklist now reflects that.

    The wrapper gate remains blocked: the npm registry still reports stable ghostty-web@0.4.0, with prerelease 0.4.0-next.21.g640db46. Both wrapper upgrade PR and release-candidate PR remain open and unmerged. There is no qualifying stable v1.4 wrapper in the current package channel.

    Keep this issue open. The unblock action is a maintained, stable Ghostty v1.4-compatible wrapper release; then pin the exact release and complete the existing lifecycle, asset-integrity, OSC, performance, and full-memory acceptance criteria. The existing 0.4.0 pin and ABI ownership boundary remain appropriate. No v1.4 performance improvement is claimed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P3Low-risk cleanup, docs, polish, ergonomics, or speculative feature.dependenciesPull requests that update a dependency fileenhancementNew feature or requestissue-rating: 🌊 off-meta tidepoolIssue quality rating does not apply to this item.

    Type

    Task

    Fields

    Priority

    None yet

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions