feat: add Swift Package Manager support for iOS and fix iOS available-memory reporting

.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: Build & publish docs
+
+# Builds the Nextra site from website/ and publishes website/out/ to the root of
+# the gh-pages branch. GitHub Pages must be pointed at that branch once
+# (Settings > Pages > Source: "Deploy from a branch", branch: gh-pages,
+# folder: / (root)). The branch is not protected, so the bot can push to it,
+# which is not possible on the protected main branch.
+#
+# 从 website/ 构建 Nextra 站点，并把 website/out/ 发布到 gh-pages 分支根目录。
+# GitHub Pages 需在仓库设置里一次性指向该分支（Settings > Pages > Source:
+# "Deploy from a branch"，branch: gh-pages，folder: / (root)）。
+# 该分支不受保护，bot 可以推送；受保护的 main 分支则不行。
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'website/**'
+      - 'pubspec.yaml'
+  workflow_dispatch:
+
+# Serialize runs so two concurrent builds cannot fight over the branch.
+concurrency:
+  group: docs-publish
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  publish-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: website/package-lock.json
+
+      - name: Install website dependencies
+        run: npm ci
+        working-directory: website
+
+      # --ci forces the build: CI checks out a clean tree, so the script's
+      # change detection (staged / unstaged diff) would otherwise skip it.
+      # The result lands in website/out/, with .nojekyll added by the script.
+      - name: Build site
+        run: node website/scripts/sync-docs.mjs --ci
+
+      # force_orphan keeps gh-pages at a single commit holding only the built
+      # site, so the branch does not accumulate build history.
+      - name: Publish to gh-pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_branch: gh-pages
+          publish_dir: website/out
+          force_orphan: true
+          user_name: 'github-actions[bot]'
+          user_email: '41898282+github-actions[bot]@users.noreply.github.com'
+          commit_message: 'chore(docs): publish built site'

.github/workflows/link-check.yml

@@ -15,7 +15,13 @@ on:
       - 'README.md'
       - 'README_zh.md'
       - 'CHANGELOG.md'
-      - 'docs/**'
+      # website/pages/ is intentionally NOT scanned: the Nextra source uses
+      # extensionless route links (for example /Custom-Database-Provider) that
+      # lychee resolves as local files and reports as missing, which are false
+      # positives. Those routes are validated by the site build itself.
+      # 刻意不扫描 website/pages/：Nextra 源码使用无扩展名的路由链接（例如
+      # /Custom-Database-Provider），lychee 会按本地文件解析并误报缺失。
+      # 这些站内路由由站点构建本身保证。
   # Allow manual runs from the Actions tab.
   # 允许在 Actions 页手动触发。
   workflow_dispatch:
@@ -44,7 +50,7 @@ jobs:
             --retry-wait-time 2
             --max-retries 2
             --exclude "https://raw.githubusercontent.com/zero-labsco/zero_inspector_kit/main/image/mascot/.*"
-            README.md README_zh.md CHANGELOG.md "docs/**"
+            README.md README_zh.md CHANGELOG.md
           fail: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.pubignore

@@ -1,8 +1,3 @@
-# Exclude the GitHub Pages documentation site from the published package.
-# The docs/ folder is served via the docs/github-pages branch (GitHub Pages),
-# not distributed through pub.dev.
-docs/
-
 # Project-internal agent/IDE data — must not be published to pub.dev.
 .codebuddy/
 

AGENTS.md

@@ -85,7 +85,7 @@ Notes / 说明:
 - `stale.yml`: `actions/stale@v11` marks stale issues/PRs.
 - `dependabot-pr-bilingual.yml`: `actions/github-script@v7` appends a bilingual (EN-primary, ZH-secondary) summary to the **body** of Dependabot PRs only (`github.actor == 'dependabot[bot]'`, idempotent via marker). It does NOT touch the PR title or commit subject — those stay English per the Conventional Commits rule. When reviewing Dependabot PRs, verify the build passes, check changelogs for breaking changes on major bumps, and confirm the caret (`^`) constraint is preserved.
 - `dart-format-fix.yml`: on PR `opened`/`synchronize`/`reopened` (and `workflow_dispatch` manual trigger), runs `dart format .` and, if it changed anything, auto-commits and pushes the fix back to the **same PR branch** as `github-actions[bot]`. Keeps style consistent without reviewer nudging. Note: uses `pull_request` (not `pull_request_target`) with `permissions: contents: write`; if branch protection blocks workflow pushes or requires signed commits, switch it to open a fix branch / post a comment instead.
-- `link-check.yml`: on PR changes to `README.md`, `README_zh.md`, `CHANGELOG.md`, `docs/**` (and `workflow_dispatch` manual trigger), runs `lychee-action@v2` to scan those docs for dead/broken links and fails only on real broken links (mailto and common redirects/rate-limits are excluded). Use the Actions tab manual run to scan the default branch on demand.
+- `link-check.yml`: on PR changes to `README.md`, `README_zh.md`, `CHANGELOG.md` (and `workflow_dispatch` manual trigger), runs `lychee-action@v2` to scan those docs for dead/broken links and fails only on real broken links (mailto and common redirects/rate-limits are excluded). `website/pages/` is deliberately **not** scanned: the Nextra source uses extensionless route links (for example `/Custom-Database-Provider`) that lychee resolves as local files and reports as missing, producing false positives — those routes are validated by the site build instead. Use the Actions tab manual run to scan the default branch on demand.
 - `pr-title-check.yml` details: allowed types are `feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert`; `requireScope` is `false`; PRs labeled `dependencies` or `github-actions` are ignored. The same type list applies to commit messages (Conventional Commits).
 - `paths-ignore` skips pure assets/non-package files (images `**.png`/`**.jpg`/`**gif`/`**webp`/`**svg`/`**ico`, `**.txt`, `**.gitignore`, `LICENSE`, example build artifacts, etc.) but it MUST NOT blanket-ignore all `**.md` or `docs/**`. `README*.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `TODO.md`, `docs/**` are intentionally **kept OUT of `paths-ignore`** so docs-only PRs still trigger the `ci.yml` workflow — otherwise the entire workflow would be skipped and the branch-protection required checks would never appear (yellow), blocking merge.
 - Whether a triggered run actually executes the heavy jobs is decided by the `path-filter` job's `code` output:
@@ -117,7 +117,7 @@ Notes / 说明:
      / 每条变更必须英中双语（英文为主、中文为辅，EN-primary, ZH-secondary）。不要用 ` / ` 斜杠分隔中英文（太不显眼）。改用嵌套子条目：英文描述作为一级条目，中文翻译缩进为其下方子条目，且**不要**加"中文：" / "EN:" 这类显式标签。小节标题保持 `### Fixed / 修复`、`### Changed / 优化`、`### Added / 新增` 形式。
    - **Changelog scope rule / 变更日志范围规则:** Only changes to `lib/` (i.e. published-package runtime behavior) earn a CHANGELOG entry. Pure documentation updates (`README*.md`, `website/`, `docs/`) and `example/` changes must NOT get a CHANGELOG entry — they do not change the released package's runtime behavior. The single exception is a **pure version-bump commit**: bumping the version legitimately updates the CHANGELOG (and the doc version strings) as part of cutting the release, which is allowed. / 只有 `lib/` 的改动（即已发布包的运行行为）才进 CHANGELOG；纯文档（`README*.md`、`website/`、`docs/`）与 `example/` 的改动不应写进 CHANGELOG——它们不改变发布包的运行行为。唯一的例外是「单纯 bump 版本」的提交：为发版而更新 CHANGELOG（及文档版本号）是允许的。
    - Grep sanity check before committing: `grep -rn "old_version" README.md README_zh.md website/pages` must return NOTHING (only legitimate historical prose may remain; the `__ZIK_VERSION__` placeholder is expected and is not a real version).
-   **Website (Nextra docs site):** `website/` is built and synced to `docs/` automatically by the `pre-commit` hook (`website/scripts/sync-docs.mjs`). Version references in `website/pages/*.md` use the `__ZIK_VERSION__` placeholder, which is filled from `pubspec.yaml` at build time — bumping `pubspec.yaml` propagates to the site automatically. Never edit `docs/` by hand; it is regenerated on every commit that touches `website/`.
+   **Website (Nextra docs site):** `website/` is built by CI — `.github/workflows/docs.yml` runs `website/scripts/sync-docs.mjs --ci` whenever `website/**` or `pubspec.yaml` changes on `main`, and publishes `website/out/` to the root of the `gh-pages` branch. Version references in `website/pages/*.md` use the `__ZIK_VERSION__` placeholder, which is filled from `pubspec.yaml` at build time — bumping `pubspec.yaml` propagates to the site automatically. `main` no longer contains a generated `docs/` directory, so there is no build output to commit and nothing to conflict on.
 2. Update `README.md` / `CHANGELOG.md` as needed.
 3. Locally verify before pushing:
    - `dart format .` — must report no changes. The `dart-format-fix.yml` CI workflow auto-commits any formatting diff back to the PR branch, so keep the tree formatted locally to avoid surprise commits.
@@ -136,16 +136,17 @@ Notes / 说明:
 
 - **Checked-in file ignored by `.gitignore`** — Pub flags any file that is BOTH in the git index AND matched by `.gitignore` (error message points at e.g. `.codebuddy/skills/zero-inspector-kit/SKILL.md`). Fix: do NOT try to solve this with `.pubignore` (pub's "checked-in but ignored" check ignores `.pubignore`); instead **untrack** the path so it is no longer "checked in":
   `git rm -r --cached .codebuddy` (file stays on disk, remains gitignored, no longer in the index). Keep `.codebuddy/` ignored in `.gitignore` — it is personal IDE data.
-- **Top-level `docs/` directory (plural name)** — Pub warns that plural top-level dirs aren't recognized by its layout convention and suggests renaming to `doc/`. Do NOT rename: `docs/` is the GitHub Pages site (served from `docs/github-pages`), renaming breaks the Pages workflow. Fix: exclude it from the package via `.pubignore` (`docs/`).
-- **`.pubignore` usage** — Add a `.pubignore` at repo root to keep repo-internal content out of the published tarball. Recommended entries: `docs/`, `.codebuddy/`, `AGENTS.md`, `CONTRIBUTING.md`, `TODO.md`. `.pubignore` is respected by `dart pub publish` but does NOT silence the "checked-in but gitignored" conflict above.
+- **Top-level `docs/` directory (plural name)** — Pub used to warn that plural top-level dirs aren't recognized by its layout convention and suggested renaming to `doc/`. This no longer applies: the generated `docs/` directory has been removed from `main`, because the site is now published to the `gh-pages` branch instead. Do not reintroduce a checked-in `docs/`.
+- **`.pubignore` usage** — Add a `.pubignore` at repo root to keep repo-internal content out of the published tarball. Recommended entries: `.codebuddy/`, `AGENTS.md`, `CONTRIBUTING.md`, `TODO.md` (the old `docs/` entry is obsolete — that directory no longer exists). `.pubignore` is respected by `dart pub publish` but does NOT silence the "checked-in but gitignored" conflict above.
 
 When re-tagging after a fix, force-update both the `vX.Y.Z` tag and the `release/vX.Y.Z` archive branch to the new commit so the publish job runs against the corrected tree.
 
 ### Documentation site (GitHub Pages)
-- Source content lives in `docs/`. The legacy `wiki/` directory was removed; `docs/` is now the single source of truth.
-- Publishing branch: `docs/github-pages`; GitHub Pages serves the `/docs` folder of that branch.
+- Source content lives in `website/` (Nextra) and is the only hand-edited documentation source.
+- GitHub Pages serves the **root** of the `gh-pages` branch (Source: "Deploy from a branch", branch `gh-pages`, folder `/ (root)`). This is a one-time repository setting. The branch is generated and force-pushed by CI, so never commit to it by hand.
 - Live site: https://zero-labsco.github.io/zero_inspector_kit/
-- To update docs: edit `docs/` on `docs/github-pages`, commit, push; Pages redeploys automatically.
+- Builds run in CI, not locally: pushes to `main` touching `website/**` or `pubspec.yaml` trigger `docs.yml`, which builds `website/out/` and force-orphan-publishes it to `gh-pages` as `github-actions[bot]`. A separate Pages branch is required because `main` is branch-protected — the bot cannot push there.
+- To preview locally: `cd website && npm ci && npm run build` (output in `website/out/`), or `node website/scripts/sync-docs.mjs --ci`.
 - `pubspec.yaml` has a `documentation:` field pointing to the site (rendered on pub.dev). Keep it in sync after the site URL is stable.
 
 ## New feature development checklist
@@ -156,5 +157,5 @@ When re-tagging after a fix, force-update both the `vX.Y.Z` tag and the `release
 - [ ] Run `flutter analyze` and `flutter test` locally before pushing.
 - [ ] Use a typed branch (`feat/...`) and a Conventional Commits PR title.
 - [ ] Ensure the 3 required status checks pass before requesting review/merge.
-- [ ] For user-facing changes, update `README.md` and the `website/` source (the `docs/` site is built and synced automatically by the pre-commit hook).
+- [ ] For user-facing changes, update `README.md` and the `website/` source (the site is rebuilt and published by the `docs.yml` CI workflow once the change lands on `main`).
 - [ ] For releases, bump `version` AND follow the **Mandatory version-bump checklist** under "Release and publish" above (pubspec, iOS podspec, README.md, README_zh.md, `website/pages/*.md` via the `__ZIK_VERSION__` placeholder, CHANGELOG.md — grep for the old version string to confirm nothing is left). Tag `vX.Y.Z` (triggers publish), and optionally push a `release/vX.Y.Z` archive branch via explicit refspec.

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.15.0
+
+### Added / 新增
+- Added Swift Package Manager (SPM) support for iOS. The iOS native code now ships as a Swift package (`ios/zero_inspector_kit/Package.swift`, library `zero-inspector-kit`, iOS 13.0 or later), so projects that have migrated off CocoaPods can consume the plugin. CocoaPods support is retained, as Flutter requires plugins to support both until further notice.
+  - 新增 iOS 端 Swift Package Manager（SPM）支持。iOS 原生代码现以 Swift 包形式提供（`ios/zero_inspector_kit/Package.swift`，库名 `zero-inspector-kit`，iOS 13.0 及以上），便于已从 CocoaPods 迁移的项目接入。仍保留 CocoaPods 支持，因为 Flutter 要求插件暂时同时支持两者。
+
+### Changed / 优化
+- Moved the iOS native sources from `ios/Classes` and `ios/Resources` into the Swift package layout at `ios/zero_inspector_kit/Sources/zero_inspector_kit/`; the podspec now points at the new paths, and `PrivacyInfo.xcprivacy` (present but previously unused) is now bundled.
+  - 将 iOS 原生源码从 `ios/Classes` 与 `ios/Resources` 迁移到 Swift 包布局 `ios/zero_inspector_kit/Sources/zero_inspector_kit/`；podspec 同步指向新路径，并打包此前存在但未生效的 `PrivacyInfo.xcprivacy`。
+
+### Fixed / 修复
+- Fixed iOS `availMem` reporting: it was estimated as "device total physical memory minus this process RSS", which ignored other processes and badly over-reported available memory (for example reporting roughly 5.8 GB when only about 800 MB was actually free). It now uses `os_proc_available_memory()` on iOS 13+, whose semantics are the memory available to the current process. The now-unused `getUsedMemory()` helper was removed.
+  - 修复 iOS `availMem` 上报错误：此前按「设备总物理内存减去本进程 RSS」估算，忽略其它进程占用，会严重高估可用内存（例如实际仅剩约 800MB 时上报约 5.8GB）。现改用 `os_proc_available_memory()`（iOS 13+），语义为当前进程可用内存。同时移除了不再使用的 `getUsedMemory()` 辅助方法。
+
 ## 1.14.1
 
 ### Fixed / 修复

CONTRIBUTING.md

@@ -30,7 +30,7 @@ This project is licensed under MPL-2.0. By participating, you are expected to up
 
 - Flutter >= 3.3.0 (stable channel)
 - Dart >= 3.11.0
-- Node.js (required by the pre-commit `docs-sync` hook; without it `git commit` fails the hook)
+- Node.js (only needed to preview the docs site locally: `cd website && npm ci && npm run build`. The site build runs in CI, so committing does not require Node)
 - Android Studio / Xcode (for platform-specific testing)
 - Git
 
@@ -160,7 +160,7 @@ Name test files `<source_file>_test.dart` and place them under `test/` mirroring
 ## Pull Request Process
 
 1. **Update CHANGELOG.md** under an `## [Unreleased]` section (or create one if missing). Describe what changed and why.
-2. **Update documentation** if your change affects public API or user-facing behavior (README.md, README_zh.md, docs/).
+2. **Update documentation** if your change affects public API or user-facing behavior (README.md, README_zh.md, `website/pages/`).
 3. **Bilingual comments** must be added for any new code.
 4. **CI must pass** — the CI workflow runs format check, analyze, and tests on every PR.
 5. **Keep PRs focused** — one feature/fix per PR makes review faster.

README.md

@@ -19,7 +19,7 @@ An in-app developer console for Flutter: inspect HTTP, WebSocket & gRPC traffic,
 [![Dart](https://img.shields.io/badge/Dart-✓-0175C2?logo=dart)](https://dart.dev)
 [![Style: effective dart](https://img.shields.io/badge/style-effective_dart-40c4ff.svg)](https://pub.dev/packages/effective_dart)
 
-> **🔔 Upgrade recommended:** This release fixes an iOS correctness bug: the `lowMemory` field in `getProcessMemoryInfo` previously reported `ProcessInfo.isLowPowerModeEnabled` (Low Power / low-battery mode) instead of the actual low-memory state, mismatching Android/OHOS. It now reflects real system memory pressure via a `DispatchSource` memory-pressure monitor. All users are encouraged to upgrade to the latest version (`^1.14.1`).
+> **🔔 Upgrade recommended:** This release adds Swift Package Manager (SPM) support for iOS (CocoaPods support is retained), and fixes iOS available-memory reporting: it was previously estimated as "device total memory minus this process RSS", which badly over-reported available memory, and now uses `os_proc_available_memory()`. All users are encouraged to upgrade to the latest version (`^1.15.0`).
 
 🌐 **[Official Website](https://www.zerolabsco.com/)**  ·  📦 **[View on pub.dev](https://pub.dev/packages/zero_inspector_kit)**  ·  🔗 **[View on GitHub](https://github.com/zero-labsco/zero_inspector_kit)**
 
@@ -102,7 +102,7 @@ An in-app developer console for Flutter: inspect HTTP, WebSocket & gRPC traffic,
 
 ```yaml
 dependencies:
-  zero_inspector_kit: ^1.14.1
+  zero_inspector_kit: ^1.15.0
 ```
 
 ### GitHub
@@ -112,7 +112,7 @@ dependencies:
   zero_inspector_kit:
     git:
       url: https://github.com/zero-labsco/zero_inspector_kit.git
-      ref: release/v1.14.1   # replace 1.14.1 with the version you need
+      ref: release/v1.15.0   # replace 1.15.0 with the version you need
 ```
 
 ---