@gespenst/core

中文文档
0.2.0发布于 2026/10/28MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 4715

TypeScript 和网络的快速 Ghostty 驱动终端模拟器

中文使用文档
文档目录12 节
  1. 安装
  2. 浏览器终端
  3. 连接 PTY
  4. 布局和字体
  5. 主题
  6. 配置基线
  7. 应用政策
  8. 缓冲和视图状态
  9. 无头运行时间
  10. 业绩做法
  11. 文档
  12. 许可证

@ gespensst/ 调值

一个高性能浏览器终端和无头 VT运行时间 由官方夜间供电 ghostty-vt.wasm。 。 。 .

文档、指南和现场演示: (原始内容存档于2018-10-21). gespent.dev

本地API面向字节并围绕Web Streams而建. 浏览器终端使用工人 当可用时, 选择 WebGPU、 WebGL2 或运行时的 Canvas 2D, 并保留应用程序政策 在制造器外面.

幽灵的 tip 艺术品是夜造的 每个已出版的软件包版本的针和检查和 an 确切的文物。 在部署前将这个软件包版本固定在生产和测试升级中.

安装

pnpm add @gespenst/core

浏览器终端

导入样式表并给主机一个清晰的高度 :

<div id="terminal"></div>

<style>
  #terminal {
    width: 100%;
    height: 32rem;
  }
</style>
import { createTerminal } from '@gespenst/core';
import '@gespenst/core/style.css';

const terminal = await createTerminal({
  container: document.querySelector<HTMLElement>('#terminal')!,
  worker: 'dedicated',
  renderer: 'auto',
});

terminal.write('\x1b[1;32mGhostty is ready\x1b[0m\r\n');
terminal.focus();

默认工人政策选择一个专职工人,当 Worker 财务报告和审定财务报表 OffscreenCanvas 为: 可用,如果工人启动失败,则重试主线。 自动渲染器尝试 WebGPU, 然后WebGL2,然后Canvas 2D用于单元格背景,然后在加速时向下移动 后端无法在运行时恢复 。 浏览器 Canvas 2D 在每个渲染器路径上塑造文本 。 发布运行 chrimium 的完整浏览器套件,以及Firefox和WebKit中的重点API兼容性测试; 3; 硬件 WebGPU 可用性不需要,因为渲染器会自动倒回.

连接 PTY

核心接受双向字节流,而不强制服务器协议 :

const connection = terminal.connect({
  readable: ptyOutput, // ReadableStream<Uint8Array>
  writable: ptyInput, // WritableStream<Uint8Array>
});

terminal.on('resize', ({ cols, rows }) => {
  sendPtyResize({ cols, rows });
});

await connection.closed;

将 PTY 字节保留为 Uint8Array 从套接字到Ghostty的数据。 使用 @gespenst/websocket 用于现成的二进制 WebSocket 传输,并调整消息大小, 后压,以及可选的再连接行为.

布局和字体

终端填充主机,因此主机必须具有非零宽度和高度. A 类 ResizeObserver 将网格与容器变化相匹配。 打电话 fit() 显示隐藏标签中创建的终端后 或对话.

默认字体堆栈使用已安装的系统单空间字体. 自定义字体具有灵活性, 不使用 来源于预定义的列表 :

await terminal.loadFont({
  family: 'JetBrains Mono',
  source: 'url(/fonts/jetbrains-mono.woff2)',
  descriptors: { weight: '400 700' },
});

await terminal.setFont({
  family: 'JetBrains Mono, ui-monospace, monospace',
  sizePx: 14,
  lineHeight: 1.25,
});

loadFont() 在文档和渲染器中安装面相 重新测量.

主题

主题使用便携式 CSS 字符串或 RGB(A) 对象,并包括命名为 ANSI 的xterm相容性, 选择,以及光标的颜色。 安装 @gespenst/themes 用于审计的可动摇树的预设:

import { catppuccinMocha } from '@gespenst/themes/catppuccin-mocha';

await terminal.setTheme(catppuccinMocha); // replaces the current theme
await terminal.updateTheme({ cursor: '#ffffff' }); // patches it

启用 allowTransparency 当非选择的颜色使用α时创建。 设定 minimumContrastRatio 当需要自动文本对比时。 缺少扩展的 ANSI 颜色为 由Ghostty生成一次,而不是在单元格递归回路中计算出一次.

配置基线

const terminal = await createTerminal({
  container,
  worker: 'dedicated',
  renderer: 'auto',
  scrollbackLines: 10_000,
  accessibility: 'basic',
  minimumContrastRatio: 1,
});
  • 使用 worker: 'shared' 当许多终端共享一个工作事件循环时.
  • 使用 worker: false 用于确定主线行执行或不支持的环境.
  • 使用 accessibility: 'full' 当产品需要现场取景口文本镜时.
  • 读取 terminal.renderer.backend 以查看实际选择哪个渲染器.
  • 许多并行终端或内存受限设备的下回滚.

应用政策

终端逃生序列可以请求剪贴板写作和桌面通知. 核心发射 类型 clipboardWrite 财务报告和审定财务报表 notification 事件但不执行这些浏览器动作 自动。 版本0.1.0 拒绝远程剪贴板写入; 使用 clipboardWrite 仅作为审计 记录。 在显示通知前验证会话信任、用户意图和浏览器权限 .

对于用户启动的文本和 MIME 粘贴, 安装 @gespenst/clipboard。它保持剪贴板支持 禁用到加载加载, 支持 Kitty 模式 5522 粘贴事件, 拒绝远程写入 , 在不安全的文本可以绕过正常的粘贴安全之前,需要应用确认钩. 见 剪贴板指南。 。 。 .

每个 on() 调用返回一次性订阅。 通话 terminal.dispose() 关闭活动 连接、处理添加、删除听众和已装入的字体、释放渲染资源以及 终止所有工人.

缓冲和视图状态

使用页面缓冲 API 来进行滚动条、搜索、链接、记录视图和兼容层:

const visible = await terminal.readBuffer();
const history = await terminal.readBuffer({
  start: 0,
  end: visible.state.totalRows,
});

terminal.on('viewportChange', ({ state: { viewportY, totalRows, viewportLength } }) => {
  updateScrollbar({ viewportY, totalRows, viewportLength });
});

行直接从Ghostty的活性格读取; Gespenst 不运行第二个 VT 剖析器. 范围 半开并被夹住. viewportY 编辑 scroll 事件使用绝对零取自 最古老的保留行。 在热路径上只打印行需要的特性 .

无头运行时间

import { createCoreRuntime } from '@gespenst/core/headless';

const runtime = await createCoreRuntime();
const terminal = runtime.createTerminal({ cols: 100, rows: 30 });

terminal.write('\x1b[34mParsed by Ghostty VT\x1b[0m\r\n');
const text = terminal
  .viewport()
  .viewportRows.map((row) => row.text)
  .join('\n');

console.log(text);
runtime.dispose();

重用一个 CoreRuntime 对于多个终端,所以他们共享编译的Ghostty模块. 这个 无头运行时间工作没有DOM 并暴露解析细胞,脏行,光标状态,效果, 选择、快照和输入编码.

业绩做法

  • 保持输出字节本地化并避免解码-编码周期.
  • 使用 writeAsync() 当生产者需要解析和渲染边界时.
  • 保存有意义的运输块,而不是一次写一个字节.
  • 在输出热道上将回转并避免频繁取景或快照读取.
  • 首页d readBuffer() 区域重建所有保留回滚.
  • 量身定做和共享的工人 与真正的终端计数和输出程序.

工作空间基准旨在进行有控制的比较,而不是一项普遍的吞吐量主张:

pnpm bench:throughput

文档

核心指南涵盖PTY架构,每个配置组,字体和主题,事件政策, 性能测量,无头使用,xterm.js迁移,和故障排除.

许可证

麻省理工学院. 卖家Ghostty WASM持有麻省理工学院的执照 THIRD_PARTY_NOTICES.md。 。 。 .

版本与发布记录

@gespenst/core 共发布 4 个版本,首次发布于 2026/08/26;过去 12 个月发布了 4 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.2.0latest2026/10/2818 天前
0.1.22026/08/302 个月前
0.1.12026/08/272 个月前
0.1.02026/08/262 个月前

关于 @gespenst/core 的常见问题

@gespenst/core 是什么?

TypeScript 和网络的快速 Ghostty 驱动终端模拟器

如何安装 @gespenst/core?

在项目目录运行 npm install @gespenst/core,或使用 pnpm add / yarn add / bun add。

@gespenst/core 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gespenst/core 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gespenst/core 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js ^20.19.0 || >=22.12.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gespenst/core 可以商用吗?

@gespenst/core 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gespenst/core 的下载量有多少?

根据 npm 官方下载统计,@gespenst/core 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,715 次,日均约 157 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gespenst/core 还在维护吗?

最新版本 0.2.0 发布于 2026/10/28(18 天前);至今共发布 4 个版本,其中过去 12 个月发布了 4 个;首次发布于 2026/08/26。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。