# Web 兼容性

运行时的渲染器是自研的 (不是 Chromium), 页面的 JS 跑在它内嵌的 V8 里. 原则是**标准接口和浏览器完全兼容**: 行为、签名、事件、错误都照规范; 做不到的就是缺口, 不拿长得像的私有版本顶替. 下面列出值得知道的地方.

## 源

所有应用页面的源都是 `http://acde.local`. 每个应用的存储是分开的分区, 互相看不到.

## 存储

| 接口 | 说明 |
| --- | --- |
| `localStorage` | 同一应用的所有窗口共用; 5 MiB 配额; 别的窗口改了收 `storage` 事件 |
| `sessionStorage` | 每个窗口自己的, 只在内存; `location.reload()` 之后**不**保留 (和浏览器不同) |
| IndexedDB | 完整实现, 存在 SQLite 里; 用 promise 包装的库 (idb 等) 行为和浏览器一致 |
| Cache API | `caches` 支持 |
| cookie | 同源 (自己的后端) 的照常存取; 跨源请求不带也不存 cookie |
| `navigator.storage` | `estimate()`; `persist()` 总是 `true`; `getDirectory()` 是私有文件系统 (OPFS) |

数据在 `$XDG_DATA_HOME/acde/storage/app-<id>/`.

## 网络

- `fetch`、`XMLHttpRequest`、`WebSocket`、`EventSource` 都支持.
- 同源路径和 `localhost` 送到应用自己的后端, 见 [后端](https://docs.dopame.ai/zh/guide/backend.md).
- 访问别的主机走系统的 DNS 和网络, 证书照常校验, 并按系统的设置走代理: 会话里设了 `http_proxy`、`https_proxy` 或 `all_proxy` 时, 只看这些变量 (和 `no_proxy`); 否则用系统的代理设置 (Windows: 用户的 Internet 设置, 包括配置脚本和自动检测; macOS: 网络设置; Linux 没有别的来源). `localhost`、回环地址和应用自己的后端总是直连. 不支持代理认证和 `https://` 代理. 响应不自动解压 (不发 `Accept-Encoding`).
- 跨源请求照浏览器的规则: 带 `Origin`、CORS 预检、响应头过滤、`no-cors` 的不透明响应.
- 被禁的请求头 (`Host`、`Cookie`、`Origin`、`Referer`、`Sec-*` ……) 设了也不发.
- 同步 XHR 只能读应用自己的文件.

## 外部资源

图片 (`<img>` 和 CSS 里的图片)、样式表 (`<link rel="stylesheet">`) 和字体可以从别的主机加载, 和在浏览器里一样: 图片和样式表不需要 CORS, 字体要有允许这个页面的 `Access-Control-Allow-Origin`, 样式表只接受 2xx 的 `text/css` 响应. 它们出现在 `acdev network` 里, 种类是 `image`、`stylesheet` 和 `font`; 加载失败的会有一条控制台错误 `Failed to load resource: <url>: <reason>`. `<link rel="stylesheet">` 在它的样式表取到并生效之后触发 `load`, 取不到时触发 `error` (它 `@import` 的样式表取不到时也一样); 从这时起 `link.sheet` 和 `document.styleSheets` 里有这张样式表. 别的主机来的样式表, 它的规则 (`sheet.cssRules`) 会抛 `SecurityError`, 除非这个 link 带 `crossorigin`, 并且那个主机用 `Access-Control-Allow-Origin` 允许这个页面; 它的 `@font-face` 字体仍在 `document.fonts` 里. **不能从别的主机 `import` ES 模块** (`module … is not a local file`): 把依赖的代码打进应用里. 类型是 JavaScript MIME 类型 (`text/javascript`) 的 `blob:` 和 `data:` 模块可以 import. (经典 `<script src>` 可以从别的主机取.) 要在没有网络时也能用的应用, 把图片、样式和字体也打进去.

## 脚本

支持经典 `<script>`、`type="module"` 和 `type="importmap"`.

## 文件选择器

`showOpenFilePicker`、`showSaveFilePicker`、`showDirectoryPicker`、`<input type="file">` 弹系统的对话框, 见 [文件与文件夹](https://docs.dopame.ai/zh/guide/files.md).

拖进窗口的文件和文件夹按标准的方式送达: `dataTransfer.files`, 以及 `dataTransfer.items[i].getAsFileSystemHandle()` 给的只读句柄. 文件夹和超过 64 MiB 的文件不在 `files` 里, 用句柄. 见 [拖进来的文件](https://docs.dopame.ai/zh/guide/files.md#拖进来的文件).

## 媒体

`Audio` / `AudioContext` 支持, `OfflineAudioContext` (一或两个声道, 没有 `suspend()`)、效果节点 (biquad、delay、wave shaper、compressor、convolver、analyser) 和自定义的 `PeriodicWave` 也支持; `ChannelSplitterNode`、`ChannelMergerNode`、`IIRFilterNode` 和 `AudioWorklet` 还没有. WebGPU 目前只在 Linux 上有.

`<video>` 能放系统自己的解码器打得开的东西, 所以各平台支持的格式不同: macOS 上 MP4 / QuickTime 能放, WebM 不能. 选源之前先问 `canPlayType()`.

`navigator.mediaDevices.getUserMedia()` 需要配置里有 `camera` / `microphone` 能力, 并在第一次用时得到用户的回答 (见 [系统能力](https://docs.dopame.ai/zh/guide/capabilities.md#摄像头和麦克风)). Windows 上不可用.

- 必需的能力在第一次用时问, 被拒绝只让那些调用失败. 还没问过的[可选](https://docs.dopame.ai/zh/guide/capabilities.md#可选能力)能力由 `getUserMedia()` 自己问, 用的就是 `request('camera')` 引出的那个提示; 两样都要的调用先问麦克风, 再问摄像头. 用户允许后这次调用 resolve, 用户拒绝时以 `NotAllowedError` (`Permission denied`) reject; 之后的调用不再问.
- `navigator.permissions.query({ name: 'camera' })` (或 `'microphone'`) 在用户回答之前回 `prompt`, 被拒绝或批准被收回之后回 `denied`; 用户回答时它的 `change` 事件触发. 用户允许之后, 回的是宿主系统自己对这个设备的权限 (系统也允许时是 `granted`).
- 在没有声明这个能力的应用里, 查询回 `denied`, `getUserMedia()` 以 `NotAllowedError` reject, 不出提示.
- 先判断约束: 没有设备能满足的请求以 `OverconstrainedError` reject, 谁也不问.
- 对还没被允许的那一类设备, `enumerateDevices()` 列出一个不带标签的条目.
- 要在没有真实摄像头或麦克风的情况下试页面, 用 `ACDE_CAPTURE=fake` 启动会话: 这时设备是 `Fake camera` 和 `Fake microphone`.

## 渲染和 canvas

样式由 Firefox 的样式引擎 Stylo 计算; 布局和绘制是 libacde 自己的. 还不能用的:

- Canvas 2D: `drawImage()` 只画 `<img>` 或 `<canvas>`; 别的源 (`<video>`、`ImageBitmap`) 什么都不画, 也不抛错. `createConicGradient()` 画不出锥形渐变. `ctx.filter` 支持 `blur()`、`brightness()`、`contrast()`、`grayscale()`、`hue-rotate()`、`invert()`、`opacity()`、`saturate()`、`sepia()` 和 `drop-shadow()`, 不支持 `url()`.
- WebGL: transform feedback (`beginTransformFeedback` 以 `INVALID_OPERATION` 失败)、经 `PIXEL_PACK_BUFFER` / `PIXEL_UNPACK_BUFFER` 的上传和读回、`EXT_disjoint_timer_query`, 以及向 `DEPTH_COMPONENT24` / `DEPTH32F` 纹理上传数据 (只有 16 位深度接受数据). 别的主机来的图片可以读回 (没有 origin-clean 检查, 和 2D canvas 一样), 丢失的上下文不会恢复 (`restoreContext()` 什么都不做).
- SVG 几何: `getTotalLength()` 和 `getPointAtLength()` 是从元素的盒子估算的, 不是从它的路径; `isPointInFill()` 和 `isPointInStroke()` 总是 `false`.

这些和浏览器里一样能用:

- WebGL 1 和 2: `getContext('webgl')` 和 `getContext('webgl2')` 在每个系统上都给出上下文, 用和页面同一块 GPU 绘制 (three.js 和 pixi 能用), 例外见上.
- 内联 `<svg>` 里的图形、文字和组都有盒子 (`getBBox()`、`getBoundingClientRect()`), `getComputedTextLength()` 能量文字.
- Canvas 2D 能画 SVG 图片.
- 指向页面上另一个 `<svg>` (sprite sheet、共用的渐变) 的 `<use href="#id">` 和 `url(#id)` 能用.
- macOS 上 `font-family: monospace` 是 Menlo, 和 Safari、Chrome 一样. 字体栈里没有哪个字体有的符号 (`✕` `✔` `❤`) 由系统补上字体, 只有常规字重的字体的 `font-weight: 700` 是合成的.
- `:has()` 选择器 (Tailwind 的 `has-*` 变体).
- `animationstart`、`animationiteration`、`animationend`、`animationcancel`、`transitionrun`、`transitionstart`、`transitionend` 和 `transitioncancel` (等 `animationend` 之后才卸载的对话框和菜单).
- `<textarea>` 的 `scrollHeight` 覆盖它的文字, `field-sizing: content` 让框跟着文字变大.
- 带 `src` 的 `new Image()` 不在文档里也会加载 (并触发 `load` / `error`).
- 用 `oklch()`、`lab()` 或 `color-mix()` 给的内联 SVG 颜色 (Tailwind 4 的调色板) 能画出来.
- SVG 图片和内联 SVG 里, 由一条填充路径构成的 `<mask>` 按这条路径裁剪 (别的 mask 按它的区域裁剪), 由模糊、投影和颜色矩阵构成的组 `filter` 会生效 (Figma 导出的图标上的光晕).
- 带 `id` 的元素可以作为全局变量拿到 (`window.wave`).
- 认识 `pointer-events: all` 和其他 SVG 的取值 (`visible`、`painted`、`fill`、`stroke` …), 都当作 `auto`.
- 用作 `background-image` 或 `mask-image` 的 SVG 图片会画出来.
- 没有 `viewBox` 的内联 `<svg>` 以 CSS 像素从左上角画它的内容, 并裁到自己的盒子里, 和浏览器一样.
- `<input>` 和 `<textarea>` 能撤销和重做: `Ctrl+Z`, 以及 `Ctrl+Shift+Z` 或 `Ctrl+Y`.

## 暂不支持

`<datalist>`、`<select>` 的 `appearance: base-select`、`SharedWorker`、发给 worker 的 `MessagePort` 和 `SharedArrayBuffer` (专用 worker 能用)、`crypto.subtle`、OffscreenCanvas / `createImageBitmap`、Fullscreen API (`requestFullscreen()` 以 `NotSupportedError` reject; 应用窗口用 [`acde:window`](https://docs.dopame.ai/zh/guide/window.md#窗口状态) 的 `requestState('fullscreen')` 进全屏)、`:target`、Storage Buckets、Service Worker.

## 与浏览器的差异

- `alert()` 画在窗口里; `confirm()` 返回 `false`, `prompt()` 返回 `null`.
- 没有顶层 (top layer): 打开的 popover 和模态 `<dialog>` 改为得到最高的 `z-index`, 所以祖先的 `transform`、`filter` 或 `contain` 仍会裁掉它们, 它们也没有 `::backdrop`.
- `navigator.userAgent` 和 `navigator.platform` 在每个系统上都说是 Linux (`Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) acde/<version>` 和 `Linux x86_64`), 编辑用的快捷键在哪里都用 Ctrl, 所以应用在每个宿主系统上的行为都一样. 要知道真实的系统, 读 [`acde:capabilities`](https://docs.dopame.ai/zh/guide/capabilities.md#acdecapabilities) 的 `platform`.
- 除了 [调试工具](https://docs.dopame.ai/zh/guide/tools.md) 和 [MCP](https://docs.dopame.ai/zh/guide/mcp.md), `acdev dev` 能在一张页面上打开 Chrome 或 Edge 的 DevTools (在窗口里按 F12, 或 `acdev devtools`); 见 [acdev dev](https://docs.dopame.ai/zh/guide/dev.md#devtools).
- 页面没有安全沙箱 (还没有系统调用级隔离): 不要运行你不信任的代码.
