docs: Document macOS font-kit requirement

website/docs/getting-started.md

@@ -24,6 +24,35 @@ gpui-kit = "{{gpui_kit_version}}"
 
 This single dependency includes GPUI, GPUI Base, the styled GPUI Component library and its default icon assets. Application code accesses GPUI through `use gpui_kit::*;` and components through `gpui_kit::component`. You can change the feature selection later; see [Icons & Assets](./assets.md).
 
+### macOS text rendering: `font-kit`
+
+**macOS needs the `font-kit` feature on `gpui-pre-platform` to render text.**
+The `gpui-kit` dependency above already enables it, so this guide needs no
+additional dependency or feature setting.
+
+If you maintain an application that depends on GPUI directly, enable the feature
+on the `gpui_platform` dependency instead. For a macOS-only GPUI application,
+the dependency entries are:
+
+```toml
+[dependencies]
+gpui = { package = "gpui-pre", version = "={{gpui_pre_version}}" }
+gpui_platform = { package = "gpui-pre-platform", version = "={{gpui_pre_version}}", features = ["font-kit"] }
+```
+
+Keep any other platform features your application uses, and keep the GPUI
+snapshot versions aligned. This is an alternative for direct GPUI users; keep
+the single `gpui-kit` dependency for the Kit example below. Do not add
+`features = ["font-kit"]` to `gpui` or `gpui-kit`, or add a separate `font-kit`
+dependency: the feature belongs to `gpui-pre-platform` and enables
+`gpui-pre-macos/font-kit`.
+
+`gpui-pre-platform` does not enable `font-kit` by default. Without it, the macOS
+backend uses `NoopTextSystem`: a window can open while no text is rendered,
+and `all_font_names()` returns an empty list. After updating your manifest,
+rebuild with `cargo run`. On macOS, `cargo tree -e features -i gpui-pre-macos`
+shows which dependencies enable the backend's features; check for `font-kit`.
+
 ## Add a view
 
 Replace `src/main.rs` with:

website/docs/installation.md

@@ -81,6 +81,7 @@ For a new project instead, follow [Getting Started](./getting-started). It creat
 | Windows reports `link.exe` missing or cannot find a Windows SDK. | Confirm the Visual Studio C++ workload and SDK are installed, then build with an MSVC Rust toolchain from a Visual Studio Developer PowerShell if needed. |
 | Linux reports a missing `pkg-config` executable, X11, Wayland, fontconfig, or WebKit header. | Install the Ubuntu packages above, or their equivalents for your distribution. If `pkg-config` itself is missing, install the `pkg-config` package too. The error identifies the missing tool or system library. |
 | The program compiles but no window appears on Linux. | Check that the process is running in a graphical Wayland or X11 session and that a Vulkan driver works for that session. A headless shell or Vulkan loader without a driver is insufficient. |
+| A window opens on macOS, but no text is rendered. | If you depend on GPUI directly, enable `font-kit` on `gpui-pre-platform` and rebuild. `gpui-kit` already enables it. See [Getting Started](./getting-started.md#macos-text-rendering-font-kit) for the manifest and feature check. |
 | Cargo cannot resolve `gpui-pre` or APIs differ from these examples. | Keep the `gpui-kit` requirement and update dependencies together. Kit pins a matching `gpui-pre-*` snapshot; do not override one GPUI package to a different version. In a repository checkout, use the checked-in `Cargo.lock`. |
 
 For errors after a window opens, continue with [Getting Started](./getting-started) and inspect the relevant guide for the feature you are using.

website/zh-CN/docs/getting-started.md

@@ -24,6 +24,30 @@ gpui-kit = "{{gpui_kit_version}}"
 
 只需这一个依赖，即可使用 GPUI、GPUI Base、带样式的 GPUI Component 和默认图标资源。应用代码通过 `use gpui_kit::*;` 使用 GPUI，通过 `gpui_kit::component` 使用组件。以后可以调整 feature 选择，详见[图标与资源](./assets.md)。
 
+### macOS 文字渲染：`font-kit`
+
+**macOS 需要启用 `gpui-pre-platform` 的 `font-kit` feature 才能渲染文字。**
+上面的 `gpui-kit` 依赖已经启用了它，按本指南创建应用时无需额外添加依赖或配置 feature。
+
+如果你维护的应用直接依赖 GPUI，需要在 `gpui_platform` 依赖上启用这个 feature。
+仅面向 macOS 的 GPUI 应用可使用以下依赖配置：
+
+```toml
+[dependencies]
+gpui = { package = "gpui-pre", version = "={{gpui_pre_version}}" }
+gpui_platform = { package = "gpui-pre-platform", version = "={{gpui_pre_version}}", features = ["font-kit"] }
+```
+
+保留应用原有的其他平台 features，并保持 GPUI 快照版本一致。这是直接使用 GPUI 时的配置；
+本页后续 Kit 示例仍只需 `gpui-kit` 一个依赖。不要把 `features = ["font-kit"]` 加到
+`gpui` 或 `gpui-kit` 上，也无需单独添加 `font-kit` crate：这个 feature 属于
+`gpui-pre-platform`，会启用 `gpui-pre-macos/font-kit`。
+
+`gpui-pre-platform` 默认不启用 `font-kit`。未启用时，macOS 后端会使用 `NoopTextSystem`：
+窗口可以打开，但不会渲染文字，`all_font_names()` 也会返回空列表。修改 manifest 后，
+重新运行 `cargo run`。在 macOS 上，可以用 `cargo tree -e features -i gpui-pre-macos`
+查看后端的 features 由哪些依赖启用，确认其中包含 `font-kit`。
+
 ## 添加视图
 
 将 `src/main.rs` 替换为：

website/zh-CN/docs/installation.md

@@ -81,6 +81,7 @@ cargo run -p hello_world
 | Windows 提示缺少 `link.exe` 或 Windows SDK。 | 检查 Visual Studio C++ workload 和 SDK，并确认使用 MSVC Rust 工具链；必要时从 Visual Studio Developer PowerShell 构建。 |
 | Linux 提示缺少 `pkg-config` 命令、X11、Wayland、fontconfig 或 WebKit 头文件。 | 安装上面的 Ubuntu 开发包，或对应发行版的等价包。如果缺少 `pkg-config` 命令本身，还需安装 `pkg-config` 包；根据报错定位具体工具或系统库。 |
 | Linux 上编译成功，但没有出现窗口。 | 确认程序运行于 Wayland 或 X11 图形会话，并且会话中有可用的 Vulkan 驱动。无图形环境的终端或只有 Vulkan loader 都不够。 |
+| macOS 上窗口可以打开，但没有文字。 | 如果直接依赖 GPUI，请在 `gpui-pre-platform` 上启用 `font-kit` 并重新构建。`gpui-kit` 已经启用了它。配置示例和 feature 检查命令见 [Getting Started](./getting-started.md#macos-文字渲染font-kit)。 |
 | Cargo 无法解析 `gpui-pre`，或 API 与示例不一致。 | 保留 `gpui-kit` 依赖要求，并一起更新依赖。Kit 固定一组匹配的 `gpui-pre-*` 快照；不要把其中某个 GPUI 包单独覆盖为别的版本。在本仓库中使用已提交的 `Cargo.lock`。 |
 
 窗口打开后的功能问题，可继续阅读[Getting Started](./getting-started)以及对应功能指南。