html-api-sdk

# window.Magic API — HTML Micro-App Guide

## How to Use This Document

- API signatures & constraints → this document
- App manifest & permission declarations → `app.json`
- TiptapJSON & @mention structures → [references/tiptap-json-format.md](references/tiptap-json-format.md)
- Complete HTML examples → [references/complete-examples.md](references/complete-examples.md)

## Important Constraints

1. All `window.Magic.*` APIs are **pre-injected** — no imports needed. External CDN allowed.
2. File paths are relative to **app root** (`index.html` dir) by default. `../` is forbidden. Use leading-slash paths such as `"/shared/data.json"` to access project-root files. Writing, deleting, moving, or renaming files outside the app root triggers host confirmation.
3. `window.Magic.llm` tokens hosted; no `api_key` in HTML.
4. **No inline event handlers** — use `addEventListener`. For buttons rendered by `innerHTML`, bind one delegated listener on a stable container and use `data-action`/`data-id`.
5. **LLM calls must include model selector UI** unless user specifies model. Default `"auto"`.
6. **Complex file-based AI** → use `createTopicAndSend` + `@file` + companion skill. Simple → `readFile` + `llm.chat/stream`.
7. **High-risk APIs are permission-gated** — new HTML micro-apps must declare requested scopes in `app.json.permissions.scopes`. The host asks the user to approve high-risk runtime calls for a limited duration.
8. **User info is privacy-gated** — `window.Magic.user.getInfo()` returns only `name` and `avatar` by default. Sensitive fields require a matching permission declaration, a runtime `getInfo({ scopes, reason })` request, and user confirmation.
9. **Use `app.json` as the micro-app manifest** — every new HTML micro-app folder should include `app.json` next to `index.html`. Put `type`, `name`, `entry`, `anonymous`, file aliases, watch hints, and permissions there. Also generate a minimal `magic.project.js` display bridge that mirrors only `version/type/name/entry/icon`; do not put `anonymous`, permissions, files, watch, or business state in `magic.project.js`.
   ```json
   {
     "version": "1.0.0",
     "type": "micro-app",
     "name": "App Name",
     "entry": "index.html",
     "anonymous": false,
     "files": {},
     "watch": [],
     "permissions": {
       "scopes": [],
       "reason": ""
     }
   }
   ```

10. **Administrator page access is runtime-controlled** — when an app has administrator-only pages, put `window.MagicAppConfig.admin_pages` in the shared `app.js` and call `window.Magic.db.getProjectAdminAccess()` before loading each listed page. The result is based on the real logged-in user; a share token is only an access proof and is never a user identity.

---

## HTML Interaction Safety

Generated micro-app controls must be wired through real JavaScript listeners, not HTML event attributes.

- Do not generate `onclick`, `onchange`, `oninput`, `onsubmit`, or other inline event attributes.
- For lists, cards, table rows, and menus rendered with `innerHTML`, use event delegation: `container.addEventListener("click", handler)` and buttons such as `<button data-action="edit" data-id="...">`.
- Do not attach action functions to `window` just to make inline event handlers work.
- If using `new FormData(form)`, every value read with `formData.get("field")` must have a matching `name="field"` on the input/select/textarea. Having only `id="field"` is not enough.
- Before calling `.trim()`, normalize possibly missing form values, for example `String(formData.get("title") || "").trim()`.
- If a form is read by DOM IDs instead, use `.value` consistently and do not mix it with `FormData.get()` for unnamed controls.

## 1. File System (`window.Magic.fs`)

### `readFile(path)` → `Promise<string>`

```javascript
const raw = await window.Magic.fs.readFile("data/tasks/20260624153000__open__a8f3k2__follow-up.json");
const task = JSON.parse(raw);
```

- `path: string` — relative to app root. Max 5 MB; rejects if not found.

### `writeFile(path, content)` → `Promise<void>`

```javascript
await window.Magic.fs.writeFile(
  "data/tasks/20260624153000__open__a8f3k2__follow-up.json",
  JSON.stringify(record, null, 2),
);
// Binary (up to 500 MB):
await window.Magic.fs.writeFile("data/large.bin", blob);
```

- `content: string | Blob | ArrayBuffer`. String max 5 MB. Auto-creates dirs. `../` blocked.

> ⚠️ Paths relative to `index.html` dir, NOT workspace root.

### File Paths and Project-Root Access

By default, relative `window.Magic.fs.*` paths resolve inside the app folder next to `index.html`. Use a leading slash for project-root paths. Project-root reads require `fs.project.read`; project-root writes/deletes/moves/renames require `fs.project.write` plus a host path confirmation for each destructive operation.

Path rules:

- `"data/config.json"` -> app root, e.g. `my-app/data/config.json`.
- `"/shared/config.json"` -> project root.
- `"/"` lists project-root entries.
- `../` remains blocked in all scopes.
- Reading project-root file contents or temporary URLs requires `fs.project.read`.
- Writing, deleting, moving, or renaming files outside the app root requires `fs.project.write`, then triggers host path confirmation and may be rejected by the user.
- `listFiles("/")` and `listDir("/")` are not gated in the current version, but do not depend on them for sensitive directory discovery.

### `listFiles(dir?)` → `Promise<string[]>`

```javascript
const files = await window.Magic.fs.listFiles("data/");
```

- Compatibility API. It returns direct child names only. Prefer `listDir()` for new list UIs.

### `listDir(dir?)` → `Promise<Array<{name,path,isDirectory,updatedAt?}>>`

```javascript
const entries = await window.Magic.fs.listDir("data/tasks/");
entries
  .map((entry) => parseRecordFileName(entry.name))
  .filter(Boolean)
  .sort((a, b) => b.sortKey.localeCompare(a.sortKey));
```

- Returns direct children only. It does not read file contents.
- Use it for list pages. Read the JSON det