@lingxia/skill 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingxia/skill",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "description": "Agent skill for the LingXia cross-platform app framework. Installs a markdown skill bundle into your project so AI coding tools — Claude Code, Claude Agent SDK, OpenAI Codex, Cursor, or any agent that reads project markdown — can build lxapps, host apps, and native Rust extensions on LingXia.",
   "type": "module",

package/skill/SKILL.md

@@ -91,6 +91,7 @@ For the full surface of `lx.*` and which namespace covers what, see [`./lxapp/lx
 | Need | File |
 |---|---|
 | Every CLI command, flag, env var (daily use) | [`./cli/reference.md`](./cli/reference.md) |
+| Drive a running `lingxia dev` session (`lxdev`: browser/app/lxapp/logs automation) | [`./cli/lxdev.md`](./cli/lxdev.md) |
 | Page authoring: `Page({})`, `useLxPage`, events | [`./lxapp/guide.md`](./lxapp/guide.md) |
 | **Native components: `LxInput`, `LxVideo`, `LxMediaSwiper`, `LxPicker`, `LxNavigator`, `LxTextarea`** | [`./lxapp/components.md`](./lxapp/components.md) |
 | **Logic-side `lx.*` API surface map** | [`./lxapp/lx-api.md`](./lxapp/lx-api.md) |

package/skill/cli/reference.md

@@ -205,6 +205,8 @@ lingxia dev --release
 
 > **Note:** For standalone lxapp projects, `--device`, `--abis`, and non-macOS `--platform` are not supported. Runner currently launches locally on macOS.
 
+> **Driving a live session:** once `lingxia dev` is running, use the separate **`lxdev`** binary to automate the running app — open URLs, click/type/eval in browser tabs and lxapp pages, screenshot windows, and tail logs without restarting. See [`lxdev` — Drive a running dev session](./lxdev.md).
+
 ---
 
 ### `lingxia install`

package/skill/skill-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingxia/skill",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "entry": "SKILL.md",
-  "syncedAt": "2026-05-25T06:51:06.410Z"
+  "syncedAt": "2026-06-08T07:07:15.339Z"
 }

package/skill/cli/lxdev.md

@@ -1,195 +0,0 @@
-# `lxdev` — Drive a running dev session
-
-`lxdev` is the external automation client for a running LingXia `lingxia dev` session. It ships from the same crate as `lingxia` and is on `PATH` after a standard install. Use it to inspect / drive the host app's browser tabs, the lxapps inside it, and the dev log stream — without rebuilding or restarting the dev session.
-
-This is the **agent-facing** dev surface: every command takes plain flags, prints predictable JSON (with `--json`), and never owns a long-running process. Run it from anywhere inside the project tree.
-
----
-
-## How it finds the session
-
-`lingxia dev` writes one file per active session under `.lingxia/sessions/<session_id>.json` and removes it on clean exit. `lxdev` scans that directory on every invocation. Each file records:
-
-| Field | Purpose |
-|---|---|
-| `session_id` | `<unix-ms>-<uuid>`; stable for the whole session |
-| `pid` | The `lingxia dev` process — diagnostics only |
-| `platform` | `android` / `ios` / `macos` / `harmony` / `lxapp` |
-| `started_at` | Unix milliseconds |
-| `ws_url` | `ws://host:port` the dev websocket is listening on |
-| `log_file` | Path to the session's JSONL log file |
-
-There is no daemon. The CLI process that started the session owns its file; nothing else writes there.
-
----
-
-## Selecting a session
-
-When `lxdev` is invoked **without** `--session` or `--platform`:
-
-- **One live session in the project** → use it (no probe).
-- **Multiple live sessions** → refuse and list candidates. The user must add `--session <id-prefix>` or `--platform <name>`.
-
-Why refuse rather than pick a default? In a project where a human and an agent (Claude / Codex / CI) might both be running dev sessions concurrently, "default to the most recent" silently routes commands to the wrong target. Explicit selection beats a guess.
-
-Flags (both are global — they go before the subcommand):
-
-```bash
-lxdev --session 20260520-abc browser tabs
-lxdev --platform ios browser tabs
-```
-
-`--session` matches by prefix, so a short unique fragment is enough. `--platform` is exact (case-insensitive). Selectors error out if zero or multiple sessions match.
-
----
-
-## `lxdev sessions`
-
-Inspect / clean up session state:
-
-```bash
-lxdev sessions              # human-readable table
-lxdev sessions --json       # JSON array — each entry has a `stale` boolean
-lxdev sessions prune        # remove session files whose WS server no longer responds
-```
-
-A session is considered **stale** when a 200ms TCP probe to its `ws_url` fails. Stale entries are normally cleaned up automatically — by the next `lingxia dev` startup (which prunes before checking same-platform conflicts), and by `lxdev` when ambiguity forces it to probe. `lxdev sessions prune` is the manual escape hatch after a hard crash (`kill -9`, IDE force-stop, etc.).
-
----
-
-## Subcommand families
-
-`lxdev` exposes four families of commands, all of which target a single resolved session:
-
-### `lxdev browser …`
-
-Drive the host app's browser tabs. Roughly a subset of Playwright's automation surface, scoped to a single LingXia browser instance:
-
-`open`, `tabs`, `current`, `activate`, `close`, `reload`, `back`, `forward`, `eval`, `query`, `wait`, `wait-url`, `wait-navigation`, `click`, `type`, `fill`, `press`, `scroll`, `scroll-to`, `cookies list|set|delete|clear`, `screenshot`.
-
-Most subcommands accept `--tab current|<tab-id>` (default: `current`) and `--json`. Wait/navigation commands take `--timeout-ms`.
-
-**Screenshot** captures a PNG of the tab's visible content via the platform WebView's native snapshot API. By default writes to `.lingxia/screenshots/<tab>-<ts>.png`; pass `--output <path>` or `--output -` for stdout, or `--json` to get the base64-encoded payload inline.
-
-This is the **WebView-scope** screenshot — only web content, no host UI overlays. For the entire window (including native sidebars, surfaces, etc.) see `lxdev app screenshot` below.
-
-| Platform | WebView screenshot | App/window screenshot |
-|---|---|---|
-| macOS | ✅ WKWebView `takeSnapshotWithConfiguration:` → `NSImage` → `NSBitmapImageRep` PNG | ✅ `NSView.cacheDisplayInRect:toBitmapImageRep:` (no Screen Recording permission needed) |
-| iOS | ✅ WKWebView `takeSnapshotWithConfiguration:` → `UIImagePNGRepresentation` | ✅ `UIWindow.layer.renderInContext:` (key UIWindow via scene + fallback chain) |
-| Android | ✅ `WebView.draw(Canvas)` onto a `Bitmap` → `Bitmap.compress(PNG)` via JNI | ✅ `PixelCopy.request(window.decorView)` (API 26+) → `View.draw(Canvas)` fallback |
-| HarmonyOS | ✅ `WebviewController.webPageSnapshot` → `image.PixelMap` → `ImagePacker` PNG | ✅ `window.snapshot` → `ImagePacker` PNG |
-
-All platforms time out after 5 seconds. The PNG bytes are returned to the CLI base64-encoded in the JSON envelope; `lxdev` decodes and writes the binary file.
-
-### `lxdev app …`
-
-Operate at the host-app scope (not lxapp-scope): window enumeration and full window screenshot.
-
-```bash
-lxdev app windows                          # list all NSWindow / Activity / UIWindow
-lxdev app windows --json                   # same as JSON
-lxdev app screenshot                       # capture key/focused window
-lxdev app screenshot --scope screen        # full device display (default off iOS)
-lxdev app screenshot --scope window        # app's own window only (default on iOS)
-lxdev app screenshot --window <id>         # specific window (id from `app windows`); window scope only
-lxdev app screenshot --output ~/x.png      # custom path; default .lingxia/screenshots/app-<platform>-<ts>.png
-lxdev app screenshot --output -            # PNG bytes to stdout
-lxdev app screenshot --json                # JSON envelope (window-scope only — screen scope writes a file)
-```
-
-#### Scope: `screen` vs `window`
-
-These two scopes capture **different things**; the same command produces different output across platforms because Apple's iOS doesn't expose a host-side screen-capture CLI.
-
-- **`screen`** — full device display via host tools (`adb shell screencap` / `hdc shell snapshot_display` / `screencapture`). Includes IME, status bar, dialogs from other windows, system overlays. No in-app code, no consent prompt, no foreground service. Default on android / harmony / macos.
-- **`window`** — only the app's own window via the in-app `PixelCopy` / `webPageSnapshot` / `UIWindow.layer.render` path. Excludes IME and system bars. Required default on **iOS** (no public CLI screen capture) and the only way to target a specific `--window` on multi-window platforms (macOS).
-
-| Platform | Default | `--scope screen` | `--scope window` |
-|---|---|---|---|
-| android | screen | adb screencap (full incl. IME) | PixelCopy (app window) |
-| harmony | screen | hdc snapshot_display (full incl. IME) | webPageSnapshot (app window) |
-| macos | screen | screencapture (full display) | NSWindow capture |
-| **ios** | **window** | **errors — Apple platform limit** | UIWindow.layer.render |
-
-If you're using `lxdev` to verify a layout change against an IME / keyboard scenario, you need `--scope screen` (the default everywhere except iOS). On iOS that case can only be verified manually because there's no CLI screen-capture tool — Apple does not expose one through `xcrun devicectl` today.
-
-**Multi-window** matters mainly on desktop. On macOS, `lx.surface({kind:'window'})` creates a separate NSWindow. Use `lxdev app windows` to enumerate; `--window <id>` selects one in `window` scope (the `id` is the platform-native window number — NSWindow.windowNumber on macOS, HWND on future Windows). Mobile platforms have a single foreground window and `--window` is ignored.
-
-#### How `screen` finds the right device
-
-`lingxia dev` set up an `adb forward` / `hdc fport` mapping when it created the session — the port forward is the only persistent record of which physical device this session belongs to. `lxdev` discovers the device at screenshot time by reading `adb forward --list` (or `hdc fport ls`) and matching its `ws_url` port against the host side of every forward. No device id is duplicated into session metadata, so there's nothing to keep in sync — the forward table is the source of truth.
-
-### `lxdev lxapp …`
-
-Manage lxapps running inside the session:
-
-`list`, `current`, `info`, `pages`, `page`, `eval`, `open`, `close`, `restart`, `uninstall`.
-
-`lxdev lxapp eval` runs JavaScript inside the lxapp's Logic runtime (AppService); useful for inspecting state or invoking actions without a UI round-trip.
-
-### `lxdev logs`
-
-Tail and filter the session log stream:
-
-```bash
-lxdev logs                                    # last 200 lines
-lxdev logs -f                                 # follow
-lxdev logs -f --level error                   # filter by level
-lxdev logs --source webview --grep CSP        # filter by source + text
-lxdev logs --path pages/home --json           # JSONL output
-```
-
-Levels: `verbose`, `debug`, `info`, `warn`, `error`.
-Sources: `native`, `webview`, `logic`, `web_view_console`, `lx_app_service_console`.
-
----
-
-## Concurrency rules
-
-The whole design is built around "a human and one or more agents may be doing dev in parallel." The rules are:
-
-1. **`lingxia dev` refuses to start a second same-platform session** unless `--parallel` is passed. This is the primary defense — if you never trip this, you'll never have an ambiguous `lxdev` call.
-2. **`lxdev` refuses to act when ambiguity exists.** It will not silently pick a session for you; it prints the candidates and asks for a `--session` / `--platform`.
-3. **Stale sessions don't count.** Pruning happens in three places (`lingxia dev` startup, `lxdev sessions prune`, and `lxdev` itself when ambiguity forces it), so a hard-crashed `lingxia dev` won't keep blocking future runs.
-4. **`--parallel` is per-launch.** It does not persist; each subsequent `lingxia dev` for that platform must opt in again.
-
----
-
-## Typical agent flow
-
-```bash
-# Discover what's available
-lxdev sessions
-
-# Single session, no ambiguity → zero-arg invocation
-lxdev browser open https://example.com
-lxdev browser eval --js "document.title"
-lxdev logs -f --level warn
-
-# Visual regression / what-does-the-user-see
-lxdev app windows                  # see all host windows
-lxdev app screenshot               # current focused window
-lxdev browser screenshot           # just the web content of the current tab
-
-# Two sessions running (e.g. ios + harmony) → disambiguate by platform
-lxdev --platform ios browser tabs
-lxdev --platform harmony logs --grep BridgeError
-
-# After a crash leaves residue
-lxdev sessions prune
-```
-
----
-
-## Symptom router
-
-| Symptom | Fix |
-|---|---|
-| `No active dev session found` | Run `lingxia dev` in this project. |
-| `Multiple active dev sessions match` | Add `--session <prefix>` or `--platform <name>`. |
-| `All matching dev sessions are unreachable` | Run `lxdev sessions prune`, then start a fresh `lingxia dev`. |
-| `Existing <platform> dev session is already running` (from `lingxia dev`) | Stop the other one, or pass `--parallel` if you genuinely want two. |
-| `lxdev` connects but commands hang | The host app likely lost its bridge — restart `lingxia dev`. |
-
-For the underlying design rationale (why no daemon, why this specific file layout), see the project draft `docs/draft/dev-session-multi.md` in the LingXia repo.