dsh-ios-webview-app-control 0.0.0-stage → 0.2.2

package/docs/verification.md

@@ -0,0 +1,64 @@
+# 验证说明
+
+这里说明怎么验证本插件，什么结果算通过。某次开发验证的原始记录放在文末。
+
+## 验证范围与边界
+
+- 本插件只描述自己的 `ios_*` 工具能力；不是 DSH 会话的完整工具清单。
+- 验证不得访问未授权设备；自动测试使用隔离 Context、内存 Session 与假设备派发。
+- 本验证不覆盖其它平台工具、真实手机业务、私有 Python 环境完整性或 UI 视觉渲染。
+
+## 自动验证
+
+在项目根目录执行下面这些命令。
+
+```powershell
+npm run build
+npm run check
+npm test
+New-Item -ItemType Directory -Path artifacts -Force | Out-Null
+npm pack --pack-destination artifacts
+node scripts/verify-package.mjs
+node scripts/smoke-package.mjs
+```
+
+什么算通过。
+
+- build 从 `src` 生成 `lib`，顺便做 Node 语法检查。
+- check 校验包入口、bundle 配置、运行资源锁、中英文元数据、图标及文档链接。
+- test 覆盖 ToolRuntime/SystemPrompt/ApprovalService/Session 服务链、Typert Gateway/Client、环境管理、作用域专项、核心与租约、归档校验。全部通过，没有 skip 才算过。
+- verify-package 校验归档 version/engines/peers、全部 lib 字节、Client、locale、资源锁与许可原文一致。
+- smoke-package 从 tgz 实际导入、注册 13 个工具、拒绝 Flutter 与 never、清理完成，不访问设备。
+
+## 作用域专项回归
+
+- `ios_capabilities` 含 `source`、`scope=plugin-only`、`inventory=not-session-inventory`；`android`、`nativeTap` 等保持 false。
+- 独立注册的 fixture 工具不会因本插件 false 被隐藏，也不能被当作已授权。
+- Android/native/Flutter/unknown 仍在本插件入口拒绝；审批与设备 I/O 为零。
+- 审批拒绝后不能通过 shell、CLI、核心导入等改道执行同一操作。
+- CLI、connect 内嵌能力、UI 文案与文档表达同一作用域。
+
+## 运行时验收
+
+- Config 查询存在 `include:ios-webview-app-control`，且 schema 可用。
+- Tool Inspect 显示 13 个工具，`ios_capabilities` 的描述要写清「不是会话能力清单或连接检查」。
+- 真实调用 `ios_capabilities` 返回新作用域字段。旧进程或旧 Agent 可能还在返回旧模块结果，要完整重启后再验一次。
+- `applied`、`enabled`、fiber `active` 都不能替代实际工具调用与描述核对。
+
+## 未覆盖项
+
+- 未访问或操作真实 iOS/Android 手机；未证明目标技术类型、UDID、App 身份、USB 连接或业务结果。
+- 未调查其它会话工具；不能从本插件 scope 标记推断外部工具存在或缺失。
+- UI/图标视觉渲染未验收；Client 仅通过隔离注册与测试核对。
+- 旧会话历史中的错误结论不会因升级自动消失。
+
+## 已验证环境（仅开发环境快照）
+
+这是某次开发验证的快照，不是兼容承诺，也不是运行前提。
+
+- 2026-10-31，Windows x64；Node 22.18.0；DSH 0.2.1-rc.5；Cordis 4.0.5；Schemastery 3.18.5。
+- 0.2.1 归档 57 文件、163,988 字节，SHA256 `e62eae32011c1d394bbc35e94b805ceb39c55f162dbb080facb02bcf9d73d138`；204 项测试通过（0 failed，0 skipped）；build、check、pack、verify-package、smoke 均通过。
+- 修订前 GUIDANCE + 13 工具 schema 为 13,424 UTF-8 字节，修订后 13,387 字节（按 bytes/4 粗估 3,356 → 3,347，不是供应商 tokenizer）。
+- 完整重启前真实工具与描述仍为旧内容；重启后 `ios_capabilities` 返回 scope/inventory，新描述生效。该对照说明 `applied` 不等于当前 Agent 已加载新说明。
+- 该快照中私有 Python 环境准备未完成（下载阶段 `runtime_timeout`），不作为已验收项。
+- 0.2.0 的 199 项回归和安装是上一版本历史，不能冒充 0.2.1 的说明/运行时验收。

package/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="iOS WebView App Control">
+  <!-- Original artwork, distributed under the package MIT license. -->
+  <rect width="64" height="64" rx="16" fill="#163A59"/>
+  <rect x="17" y="7" width="30" height="50" rx="7" fill="#E7F5FB"/>
+  <rect x="21" y="16" width="22" height="29" rx="3" fill="#226A8C"/>
+  <path d="m28 24-5 6 5 6m8-12 5 6-5 6m-3-14-3 16" fill="none" stroke="#BFF8E8" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M28 11h8m-6 40h4" fill="none" stroke="#163A59" stroke-width="2.5" stroke-linecap="round"/>
+</svg>

package/lib/cli.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import {IosControl} from './core/service.mjs';
+import {EnvironmentManager} from './runtime/environment-manager.mjs';
+const command=process.argv[2]||'help';
+const print=value=>console.log(JSON.stringify(value,null,2));
+if(command==='capabilities'){
+  const service=new IosControl();
+  try{print(await service.execute('capabilities'));}finally{await service.dispose();}
+}else if(command==='environment'){
+  const action=process.argv[3]||'status';
+  const options=process.argv.slice(4);
+  const allowed=new Set(['--directory','--python','--offline','--private','--yes']);
+  const config={runtime:{}};let forcePrivate=false,confirmed=false;
+  for(let index=0;index<options.length;index++){
+    const key=options[index];if(!allowed.has(key))throw Error('Unknown environment option: '+key);
+    if(key==='--directory'||key==='--python'){
+      const value=options[++index];if(!value||value.startsWith('--'))throw Error('Missing option value: '+key);
+      if(key==='--directory')config.runtime.directory=value;else config.pythonPath=value;
+    }else if(key==='--offline')config.runtime.offline=true;
+    else if(key==='--private')forcePrivate=true;
+    else if(key==='--yes')confirmed=true;
+  }
+  if(!['status','prepare','cleanup'].includes(action))throw Error('Environment CLI supports status, prepare and cleanup only.');
+  if(action==='cleanup'&&!confirmed)throw Error('Cleanup requires --yes and removes unused plugin-owned runtime resources only.');
+  const environment=new EnvironmentManager(config);
+  const controller=new AbortController();
+  const cancel=()=>{controller.abort();environment.cancel();};
+  process.once('SIGINT',cancel);process.once('SIGTERM',cancel);
+  try{
+    if(action==='prepare'){
+      let previous='';
+      environment.subscribe(state=>{
+        const line=[state.phase,state.step].filter(Boolean).join(': ');
+        if(line!==previous){process.stderr.write(line+'\n');previous=line;}
+      });
+      print(await environment.prepare({signal:controller.signal,forcePrivate}));
+    }else if(action==='cleanup')print(await environment.cleanup({signal:controller.signal}));
+    else print(environment.status());
+  }catch(error){
+    print({ok:false,error:{code:error.code||'environment_error',message:error.message},state:environment.status()});
+    process.exitCode=1;
+  }finally{
+    process.removeListener('SIGINT',cancel);process.removeListener('SIGTERM',cancel);
+    await environment.dispose();
+  }
+}else if(command==='help'){
+  console.log('dsh-ios-webview-app-control capabilities\ndsh-ios-webview-app-control environment status\ndsh-ios-webview-app-control environment prepare [--python ABSOLUTE_PATH] [--directory ABSOLUTE_PATH] [--offline] [--private]\ndsh-ios-webview-app-control environment cleanup --yes [--directory ABSOLUTE_PATH]\nEnvironment preparation installs only private dependencies. Device operations remain DSH approval-gated. This plugin handles only iOS WebView/hybrid targets. Its capabilities are plugin-only, not a DSH/session tool inventory; independently inspect other available tools and their permissions for other tasks.');
+}else{
+  console.error('Unsupported CLI operation. Use DSH plugin tools with per-call approval for device access.');
+  process.exitCode=1;
+}

package/lib/client.js

@@ -0,0 +1,223 @@
+window.__ModuleLoader__.load({
+  id: 'dsh-ios-webview-app-control',
+  factory(require) {
+    const React = require('react');
+    const { z } = require('zod');
+    const h = React.createElement;
+    const PACKAGE = 'dsh-ios-webview-app-control';
+    const NS = 'ios-environment';
+    const PHASES = ['unprepared', 'checking', 'downloading', 'creating', 'installing', 'verifying', 'ready', 'failed', 'cancelled'];
+    // Own, hand-authored Host-for-Client contribution. No Harness package imports.
+    const snapshotSchema = z.strictObject({
+      phase: z.enum(PHASES), busy: z.boolean(), step: z.string().max(256),
+      progress: z.strictObject({
+        completedBytes: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+        totalBytes: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+      }).nullable().optional(),
+      python: z.strictObject({
+        path: z.string().max(8192), version: z.string().max(128), source: z.enum(['host', 'private']), abi: z.string().max(128).optional(),
+      }).nullable().optional(),
+      runtimeDir: z.string().max(8192).optional(), pymobiledevice3: z.string().max(128).optional(),
+      error: z.strictObject({ code: z.string().max(128), message: z.string().max(2048) }).nullable().optional(),
+    });
+    const codec = Object.freeze({
+      mode: 'strict', typeSymbol: `${PACKAGE}#EnvironmentSnapshot`,
+      create: () => snapshotSchema,
+      decode: value => snapshotSchema.parse(value),
+      encode: value => snapshotSchema.parse(value),
+    });
+    const remoteContribution = Object.freeze({
+      package: PACKAGE,
+      descriptors: Object.freeze(['status', 'prepare', 'cancel', 'cleanup', 'follow'].map(method => Object.freeze({
+        id: `${PACKAGE}#iosEnvironment/${method}`, service: 'iosEnvironment', namespace: 'iosEnvironment', method,
+        invocation: Object.freeze({ kind: 'direct' }), parameters: Object.freeze([]),
+        cancellation: Object.freeze({ parameter: 'signal' }),
+        ...(method === 'follow' ? { mode: 'stream' } : {}), result: codec,
+      }))),
+    });
+    const dictionaries = {
+      zh: {
+        tab: 'iOS 环境', title: 'iOS WebView 环境', activationTitle: '准备 iOS WebView 运行环境',
+        intro: '只准备本机 Python 与固定版本依赖；不会发现、配对或连接手机，也不会启动桥接。',
+        boundary: '本插件仅提供 iOS WebView / 混合应用控制，不提供原生、Flutter、React Native 或 Android 控制；这不是 DSH 会话的完整工具清单。其它工具需独立核对能力和权限；本插件的设备操作仍逐次审批。',
+        loading: '正在读取环境状态…', source: '解释器来源', sourceHost: '宿主 Python', sourcePrivate: '插件私有 Python',
+        python: 'Python 版本', path: '解释器路径', abi: 'ABI', runtimeDir: '私有环境目录', dependency: 'pymobiledevice3',
+        missing: '尚未准备', phase: '当前阶段', progress: '下载进度', bytes: '{completed} / {total} 字节', bytesUnknown: '已下载 {completed} 字节',
+        prepare: '准备环境', retry: '重试准备', cancel: '取消准备', cleanup: '清理闲置环境', refresh: '刷新状态',
+        cleanupTitle: '确认清理闲置环境？', cleanupBody: '仅删除本插件管理的未使用旧环境与闲置下载缓存，保留当前活跃环境。不会卸载宿主 Python、删除设备证据或停止外部桥接。',
+        cleanupConfirm: '确认清理', back: '保留环境', dismiss: '关闭', details: '查看插件详情',
+        failure: '环境操作失败', followFailure: '状态订阅中断，请刷新状态后重试。', ownerRequired: '只有已认证的本机所有者界面可以管理环境；当前请求未获得此权限。',
+        step: '步骤', errorCode: '错误代码', working: '正在处理…', readyHint: '本机环境已就绪；这不表示任何设备或 App 已连接、已授权。',
+        'phase.unprepared': '未准备', 'phase.checking': '检查宿主解释器', 'phase.downloading': '下载 Python / 依赖',
+        'phase.creating': '创建私有环境', 'phase.installing': '安装固定依赖', 'phase.verifying': '验证环境',
+        'phase.ready': '就绪', 'phase.failed': '准备失败', 'phase.cancelled': '已取消',
+      },
+      en: {
+        tab: 'iOS environment', title: 'iOS WebView environment', activationTitle: 'Prepare the iOS WebView environment',
+        intro: 'Prepares local Python and pinned dependencies only. Does not discover, pair, or connect to a phone, or start a bridge.',
+        boundary: 'This plugin provides iOS WebView / hybrid control only, not native, Flutter, React Native or Android control. This is not a DSH/session tool inventory. Inspect independent tools and their permissions separately; device operations in this plugin still require individual approval.',
+        loading: 'Reading environment status…', source: 'Interpreter source', sourceHost: 'Host Python', sourcePrivate: 'Plugin-private Python',
+        python: 'Python version', path: 'Interpreter path', abi: 'ABI', runtimeDir: 'Private environment directory', dependency: 'pymobiledevice3',
+        missing: 'Not prepared', phase: 'Current phase', progress: 'Download progress', bytes: '{completed} / {total} bytes', bytesUnknown: '{completed} bytes downloaded',
+        prepare: 'Prepare environment', retry: 'Retry preparation', cancel: 'Cancel preparation', cleanup: 'Clean up unused environments', refresh: 'Refresh status',
+        cleanupTitle: 'Clean up unused environments?', cleanupBody: 'Deletes only unused old environments and idle download caches managed by this plugin, retaining the active environment. Does not uninstall host Python, remove device evidence, or stop an external bridge.',
+        cleanupConfirm: 'Confirm cleanup', back: 'Keep environment', dismiss: 'Close', details: 'Plugin details',
+        failure: 'Environment operation failed', followFailure: 'Status subscription ended. Refresh the status and retry.', ownerRequired: 'Only an authenticated owner UI can manage this environment. This request has no such authority.',
+        step: 'Step', errorCode: 'Error code', working: 'Working…', readyHint: 'The local environment is ready. No device or app is connected or authorized by this state.',
+        'phase.unprepared': 'Not prepared', 'phase.checking': 'Checking host interpreter', 'phase.downloading': 'Downloading Python / dependencies',
+        'phase.creating': 'Creating private environment', 'phase.installing': 'Installing pinned dependencies', 'phase.verifying': 'Verifying environment',
+        'phase.ready': 'Ready', 'phase.failed': 'Preparation failed', 'phase.cancelled': 'Cancelled',
+      },
+    };
+    // Native settings row spacing / typography; only Host light/dark tokens.
+    const css = `
+.iosenv-root{max-width:760px;min-width:0;color:var(--dsw-alias-label-primary);font-size:13px;line-height:20px;display:flex;flex-direction:column;gap:12px}
+.iosenv-root h3{font-size:16px;line-height:24px;font-weight:600;margin:0}.iosenv-root p{margin:0}.iosenv-muted{color:var(--dsw-alias-label-secondary)}
+.iosenv-state{background:var(--dsw-alias-bg-layer-1);border:.5px solid var(--dsw-alias-border-l2);border-radius:8px;padding:14px 16px;display:flex;flex-direction:column;gap:8px}
+.iosenv-statehead{display:flex;align-items:center;justify-content:space-between;gap:12px}.iosenv-phase{font-size:14px;font-weight:500}.iosenv-rows{margin:0;display:flex;flex-direction:column}
+.iosenv-row{display:grid;grid-template-columns:minmax(100px,150px) minmax(0,1fr);gap:12px;padding:10px 0;border-bottom:.5px solid var(--dsw-alias-border-l2)}
+.iosenv-row dt{color:var(--dsw-alias-label-secondary)}.iosenv-row dd{margin:0;overflow-wrap:anywhere}.iosenv-mono{font-family:ui-monospace,SFMono-Regular,Consolas,monospace;font-size:12px}
+.iosenv-actions{display:flex;flex-wrap:wrap;gap:8px}.iosenv-button{font:inherit;font-size:13px;line-height:20px;min-height:32px;border:.5px solid var(--dsw-alias-border-l2);border-radius:7px;padding:5px 12px;color:var(--dsw-alias-label-primary);background:var(--dsw-alias-bg-layer-1);cursor:pointer}
+.iosenv-button:hover:not(:disabled){background:var(--dsw-alias-bg-layer-2)}.iosenv-button:disabled{cursor:not-allowed;opacity:.45}.iosenv-button:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:2px}
+.iosenv-primary{color:var(--dsw-alias-brand-primary);font-weight:500}.iosenv-error{border-left:3px solid var(--dsw-alias-state-error-primary);padding:8px 12px;background:var(--dsw-alias-bg-layer-1);overflow-wrap:anywhere}
+.iosenv-confirm{border:.5px solid var(--dsw-alias-border-l2);border-radius:8px;padding:14px 16px;display:flex;flex-direction:column;gap:10px}.iosenv-progress{width:100%;height:6px;accent-color:var(--dsw-alias-brand-primary)}
+.iosenv-boundary{padding-top:8px;border-top:.5px solid var(--dsw-alias-border-l2)}
+@media(max-width:520px){.iosenv-row{grid-template-columns:1fr;gap:3px}}
+`;
+    const messageOf = (error, t) => error?.code === 'ios-environment/owner-required'
+      ? t('ownerRequired')
+      : typeof error?.message === 'string' ? error.message.slice(0, 2048) : t('failure');
+
+    async function apply(ctx) {
+      const t = ctx.locale.bind(NS);
+      ctx.effect(() => ctx.locale.register(NS, dictionaries), 'iosEnvironment dictionaries');
+      // Await concrete namespace installation before either slot is registered.
+      await ctx.remote.$mount(remoteContribution);
+      // $mount creates the traced namespace Service dynamically. Read it through
+      // the public optional-service accessor; it cannot be a static inject before mount.
+      const environment = ctx.get('remote.iosEnvironment');
+      if (!environment) throw new Error('iosEnvironment Remote namespace did not mount.');
+      const subscribeLocale = listener => ctx.locale.subscribe(listener);
+      const localeSnapshot = () => ctx.locale.getSnapshot();
+      function EnvironmentPanel(props) {
+        React.useSyncExternalStore(subscribeLocale, localeSnapshot, localeSnapshot);
+        const [snapshot, setSnapshot] = React.useState(null);
+        const [error, setError] = React.useState(null);
+        const [working, setWorking] = React.useState(false);
+        const [confirmCleanup, setConfirmCleanup] = React.useState(false);
+        const [revision, setRevision] = React.useState(0);
+        const live = React.useRef(null);
+        const confirmedButton = React.useRef(null);
+        const dismissed = React.useRef(false);
+        const panelId = React.useId();
+        React.useEffect(() => {
+          const control = new AbortController();
+          live.current = control;
+          let stream;
+          let active = true;
+          (async () => {
+            try {
+              stream = environment.follow(control.signal);
+              for await (const value of stream) {
+                if (!active) return;
+                setSnapshot(snapshotSchema.parse(value));
+                setError(null);
+              }
+              if (active && !control.signal.aborted) setError({ message: t('followFailure') });
+            } catch (failure) {
+              if (active && !control.signal.aborted) setError(failure);
+            }
+          })();
+          return () => {
+            active = false;
+            control.abort();
+            stream?.dispose();
+            if (live.current === control) live.current = null;
+          };
+        }, [revision]);
+        React.useEffect(() => { if (confirmCleanup) confirmedButton.current?.focus(); }, [confirmCleanup]);
+        // Activation guidance exists to get the environment ready, so it closes
+        // itself once preparation settles in a state that needs no action.
+        const settledReady = snapshot !== null && snapshot.phase === 'ready' && snapshot.busy !== true;
+        React.useEffect(() => {
+          if (!props.activation || !settledReady || dismissed.current) return;
+          dismissed.current = true;
+          if (typeof props.onDismiss === 'function') props.onDismiss();
+        }, [props.activation, settledReady, props.onDismiss]);
+        async function run(action) {
+          const control = live.current;
+          if (!control || control.signal.aborted || (working && !(action === 'cancel' && working === 'prepare'))) return;
+          setWorking(action);
+          setError(null);
+          try {
+            const result = await environment[action](control.signal);
+            if (control.signal.aborted) return;
+            if (!result.ok) { setError(result.error); return; }
+            setSnapshot(snapshotSchema.parse(result.value));
+          } catch (failure) {
+            if (!control.signal.aborted) setError(failure);
+          } finally {
+            if (!control.signal.aborted) setWorking(false);
+          }
+        }
+        function button(label, action, disabled, extra = {}) {
+          return h('button', { type: 'button', className: 'iosenv-button', disabled: Boolean(disabled), onClick: action, ...extra }, label);
+        }
+        function row(label, value, mono = false) {
+          return h('div', { className: 'iosenv-row', key: label }, h('dt', null, label), h('dd', { className: mono ? 'iosenv-mono' : undefined }, value || t('missing')));
+        }
+        const busy = snapshot?.busy === true;
+        // Step and byte counts describe an in-flight preparation only; once it
+        // settles they must not read like a stalled download.
+        const progress = busy ? snapshot?.progress : null;
+        const step = busy ? snapshot?.step : null;
+        const total = progress?.totalBytes;
+        const progressText = progress ? t(total === undefined ? 'bytesUnknown' : 'bytes', { completed: progress.completedBytes, total }) : null;
+        const phase = snapshot?.phase;
+        const rows = snapshot ? [
+          row(t('source'), snapshot.python ? t(snapshot.python.source === 'host' ? 'sourceHost' : 'sourcePrivate') : null),
+          row(t('python'), snapshot.python?.version), row(t('path'), snapshot.python?.path, true),
+          ...(snapshot.python?.abi ? [row(t('abi'), snapshot.python.abi, true)] : []),
+          ...(snapshot.runtimeDir ? [row(t('runtimeDir'), snapshot.runtimeDir, true)] : []),
+          row(t('dependency'), snapshot.pymobiledevice3),
+        ] : [];
+        return h('section', { className: 'iosenv-root', 'aria-labelledby': `${panelId}-title` },
+          h('style', null, css),
+          h('h3', { id: `${panelId}-title` }, t(props.activation ? 'activationTitle' : 'title')),
+          h('p', { className: 'iosenv-muted' }, t('intro')),
+          h('div', { className: 'iosenv-state', role: 'status', 'aria-live': 'polite' },
+            h('div', { className: 'iosenv-statehead' }, h('span', null, t('phase')), h('strong', { className: 'iosenv-phase' }, snapshot ? t(`phase.${phase}`) : t('loading'))),
+            step ? h('p', { className: 'iosenv-muted' }, `${t('step')}: ${step}`) : null,
+            progressText ? h('p', null, progressText) : null,
+            progress ? h('progress', { className: 'iosenv-progress', 'aria-label': t('progress'), ...(total > 0 ? { max: total, value: Math.min(progress.completedBytes, total) } : {}) }) : null,
+            phase === 'ready' ? h('p', { className: 'iosenv-muted' }, t('readyHint')) : null),
+          snapshot ? h('dl', { className: 'iosenv-rows' }, ...rows) : null,
+          snapshot?.error ? h('div', { className: 'iosenv-error', role: 'alert' }, h('p', null, snapshot.error.message), h('p', { className: 'iosenv-muted' }, `${t('errorCode')}: ${snapshot.error.code}`)) : null,
+          error ? h('div', { className: 'iosenv-error', role: 'alert' }, messageOf(error, t)) : null,
+          h('div', { className: 'iosenv-actions' },
+            button(t(phase === 'failed' || phase === 'cancelled' ? 'retry' : 'prepare'), () => run('prepare'), working || busy || !snapshot, { className: 'iosenv-button iosenv-primary' }),
+            button(t('cancel'), () => run('cancel'), !busy || (working && working !== 'prepare')),
+            button(t('cleanup'), () => setConfirmCleanup(true), working || busy || !snapshot),
+            button(t('refresh'), () => { setWorking(false); setRevision(value => value + 1); }, working)),
+          working ? h('p', { className: 'iosenv-muted', role: 'status' }, t('working')) : null,
+          confirmCleanup ? h('div', { className: 'iosenv-confirm', role: 'alertdialog', 'aria-labelledby': `${panelId}-confirm`, 'aria-describedby': `${panelId}-cleanup`, onKeyDown: event => { if (event.key === 'Escape') { event.preventDefault(); setConfirmCleanup(false); } } },
+            h('strong', { id: `${panelId}-confirm` }, t('cleanupTitle')),
+            h('p', { id: `${panelId}-cleanup`, className: 'iosenv-muted' }, t('cleanupBody')),
+            h('div', { className: 'iosenv-actions' },
+              button(t('back'), () => setConfirmCleanup(false), false, { ref: confirmedButton }),
+              button(t('cleanupConfirm'), () => { setConfirmCleanup(false); run('cleanup'); }, working || busy))) : null,
+          h('p', { className: 'iosenv-muted iosenv-boundary' }, t('boundary')),
+          props.activation ? h('div', { className: 'iosenv-actions' },
+            button(t('details'), props.onOpenDetails, false), button(t('dismiss'), props.onDismiss, false)) : null);
+      }
+      ctx.effect(() => ctx.slots.inject('settings.plugins.tab', () => ctx.slots.register({
+        name: 'settings.plugins.tab', id: 'ios-environment', order: 80,
+        label: () => t('tab'),
+      }, EnvironmentPanel)), 'iosEnvironment settings tab');
+      ctx.effect(() => ctx.slots.inject('plugins.bundle.activation', () => ctx.slots.register({
+        name: 'plugins.bundle.activation', key: PACKAGE,
+      }, props => h(EnvironmentPanel, { ...props, activation: true }))), 'iosEnvironment activation panel');
+    }
+    return { inject: ['slots', 'locale', 'remote'], apply };
+  },
+});

package/lib/core/dom.mjs

@@ -0,0 +1,26 @@
+// This function is serialized into the selected WebView. No application/framework knowledge.
+export function domAction(args,env=globalThis){
+  const selector=args.selector;
+  const nodes=selector?env.document.querySelectorAll(selector):[env.document.scrollingElement];
+  if(nodes.length!==1||!nodes[0])throw new Error('selector must match exactly one element');
+  const e=nodes[0];
+  if(args.action==='scroll'){
+    if(!Number.isFinite(args.y)||args.y<0)throw new Error('y must be nonnegative');
+    const before=e.scrollTop;e.scrollTop=args.y;
+    return {kind:'programmatic-scroll',before,actual:e.scrollTop,eventDispatched:true,effectVerified:false,nativeGestureVerified:false};
+  }
+  for(let a=e;a;a=a.parentElement){const s=env.getComputedStyle(a);if(a.hidden||a.inert||a.disabled||a.getAttribute?.('aria-disabled')==='true'||s.display==='none'||s.visibility==='hidden'||s.visibility==='collapse'||Number(s.opacity)===0||s.pointerEvents==='none')throw new Error('element/ancestor is hidden, inert or disabled');}
+  const r=e.getBoundingClientRect(),l=Math.max(0,r.left),t=Math.max(0,r.top),rr=Math.min(env.innerWidth,r.right),b=Math.min(env.innerHeight,r.bottom);
+  if(r.width<=0||r.height<=0||rr<=l||b<=t)throw new Error('element is outside the WebView viewport');
+  const hit=env.document.elementFromPoint((l+rr)/2,(t+b)/2);if(!hit||(hit!==e&&!e.contains(hit)))throw new Error('element is covered by a DOM overlay');
+  if(args.action==='click')e.click();
+  else if(args.action==='input'){
+    const tag=e.tagName?.toLowerCase(),type=String(e.type||'text').toLowerCase();
+    if(!['input','textarea'].includes(tag)||['password','file','hidden','submit','button','checkbox','radio'].includes(type))throw new Error('unsupported or sensitive input type');
+    if(e.readOnly)throw new Error('input is read-only');
+    const proto=tag==='input'?env.HTMLInputElement.prototype:env.HTMLTextAreaElement.prototype;
+    const setter=Object.getOwnPropertyDescriptor(proto,'value')?.set;if(!setter)throw new Error('standard input value setter unavailable');
+    setter.call(e,args.value);e.dispatchEvent(new env.Event('input',{bubbles:true}));e.dispatchEvent(new env.Event('change',{bubbles:true}));
+  }else throw new Error('unsupported DOM action');
+  return {kind:'dom-'+args.action,eventDispatched:true,effectVerified:false,nativeTouchVerified:false};
+}

package/lib/core/leases.mjs

@@ -0,0 +1,31 @@
+import { mkdir, open, readFile, unlink } from 'node:fs/promises';
+import { createHash,randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { IosError } from './protocol.mjs';
+const key=s=>createHash('sha256').update(s).digest('hex');
+export class LeaseStore {
+  constructor(dir,maxSeconds=120){this.dir=dir;this.maxSeconds=maxSeconds;}
+  file(device){return path.join(this.dir,key(device)+'.lease.json');}
+  async acquire(device,owner,seconds=60){
+    if(!Number.isInteger(seconds)||seconds<5||seconds>this.maxSeconds)throw new IosError('invalid_lease_duration','Lease seconds must be 5..'+this.maxSeconds);
+    await mkdir(this.dir,{recursive:true});const record={deviceHash:key(device),owner,token:randomUUID(),pid:process.pid,expiresAt:Date.now()+seconds*1000};
+    let h;try{h=await open(this.file(device),'wx',0o600);}catch(e){if(e.code==='EEXIST')throw new IosError('device_busy','Device lease exists. Do not steal expired/stale leases; verify and release its owner first.');throw e;}
+    try{await h.writeFile(JSON.stringify(record));}finally{await h.close();}return record;
+  }
+  async read(device){try{return JSON.parse(await readFile(this.file(device),'utf8'));}catch(e){if(e.code==='ENOENT')throw new IosError('lease_required','Acquire this device first.');throw e;}}
+  async assert(device,owner,token){const r=await this.read(device);if(r.owner!==owner||r.token!==token)throw new IosError('lease_not_owned','Lease belongs to another session.');if(r.expiresAt<=Date.now())throw new IosError('lease_expired','Lease expired; release your own token then acquire again.');return r;}
+  async release(device,owner,token){
+    const busy=this.file(device)+'.busy';let h;
+    try{h=await open(busy,'wx',0o600);}catch(e){if(e.code==='EEXIST')throw new IosError('device_busy','Cannot release a lease while its command is still running.');throw e;}
+    try{const r=await this.read(device);if(r.owner!==owner||r.token!==token)throw new IosError('lease_not_owned','Cannot release another session lease.');await unlink(this.file(device));return {released:true};}
+    finally{await h.close();await unlink(busy).catch(()=>{});}
+  }
+  async withCommand(device,owner,token,callback){
+    await this.assert(device,owner,token);const file=this.file(device)+'.busy';let h;
+    try{h=await open(file,'wx',0o600);}catch(e){if(e.code==='EEXIST')throw new IosError('device_busy','A command for this device is still in progress; no parallel input/read attachments.');throw e;}
+    let retain=false;
+    try{await h.writeFile(JSON.stringify({owner,pid:process.pid,startedAt:new Date().toISOString()}));await this.assert(device,owner,token);return await callback();}
+    catch(e){retain=e.details?.retainDeviceLock===true;throw e;}
+    finally{await h.close();if(!retain)await unlink(file).catch(()=>{});}
+  }
+}

package/lib/core/protocol.mjs

@@ -0,0 +1,101 @@
+import { createHash } from 'node:crypto';
+export class IosError extends Error {
+  constructor(code,message,details={}) { super(message);this.code=code;this.details=details; }
+}
+export function normalizeError(error,extra={}){
+  const code=typeof error?.code==='string'?error.code:(error?.name==='AbortError'?'cancelled':'operation_failed');
+  const message=error instanceof Error?error.message:(typeof error==='string'?error:'Operation failed or was cancelled.');
+  const details=error?.details&&Object.getPrototypeOf(error.details)===Object.prototype?error.details:{};
+  return new IosError(code,message,{...details,...extra});
+}
+export function assertSupported(platform,appType) {
+  if(platform!=='ios')throw new IosError('unsupported_platform','本插件拒绝此次非 iOS 调用：ios_* 设备工具仅接受 iOS WebView / 混合应用。本错误不评估 DSH 会话中其它工具的能力。');
+  if(!['webview','hybrid'].includes(appType))throw new IosError('unsupported_app_type','本插件拒绝此应用类型：仅接受明确确认的 iOS WebView / 混合应用；不能为通过校验而改标原生、Flutter、React Native 或未知应用。本错误不评估其它工具。');
+}
+export const CAPABILITIES=Object.freeze({source:'dsh-ios-webview-app-control',scope:'plugin-only',inventory:'not-session-inventory',platforms:['ios'],appTypes:['webview','hybrid'],webDom:true,jsEval:'disabled-by-default',webviewScreenshot:true,nativeElementTree:false,nativeTap:false,nativeSwipe:false,nativeScreenshot:false,nativeApps:false,flutterApps:false,android:false});
+export function endpointUrl(value='http://127.0.0.1:9333') {
+  const u=new URL(value);
+  if(u.protocol!=='http:'||!['127.0.0.1','localhost'].includes(u.hostname)||u.username||u.password||u.search||u.hash||u.pathname!=='/')throw new IosError('unsafe_endpoint','Only loopback HTTP bridge origins without paths or credentials are supported.');
+  u.hostname='127.0.0.1';return u.origin;
+}
+export function boundedSignal(signal,ms) {return signal?AbortSignal.any([signal,AbortSignal.timeout(ms)]):AbortSignal.timeout(ms);}
+export async function fetchJson(endpoint,pathname,{signal,timeoutMs=15000}={}) {
+  if(!['/json','/json/version'].includes(pathname))throw new IosError('invalid_bridge_path','Unsupported bridge discovery path.');
+  const r=await fetch(endpoint+pathname,{signal:boundedSignal(signal,timeoutMs),redirect:'error'});
+  if(!r.ok)throw new IosError('bridge_http_error','Bridge returned HTTP '+r.status);
+  const reader=r.body.getReader();const chunks=[];let size=0;
+  try{for(;;){const item=await reader.read();if(item.done)break;size+=item.value.byteLength;if(size>2*1024*1024){await reader.cancel();throw new IosError('result_too_large','Bridge discovery exceeded 2MiB.');}chunks.push(item.value);}}finally{reader.releaseLock();}
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+export function assertLosslessJson(value,seen=new Set()){
+  if(value===null||typeof value==='string'||typeof value==='boolean')return;
+  if(typeof value==='number'&&Number.isFinite(value)&&!Object.is(value,-0))return;
+  if(typeof value!=='object'||seen.has(value)||(!Array.isArray(value)&&Object.getPrototypeOf(value)!==Object.prototype))throw new IosError('non_json_result','Result must contain only lossless JSON values.');
+  seen.add(value);
+  if(Array.isArray(value)){for(let i=0;i<value.length;i++){if(!Object.hasOwn(value,i))throw new IosError('non_json_result','Sparse arrays are not lossless JSON.');assertLosslessJson(value[i],seen);}}
+  else for(const key of Reflect.ownKeys(value)){if(typeof key!=='string')throw new IosError('non_json_result','Symbol keys are not JSON.');const d=Object.getOwnPropertyDescriptor(value,key);if(!Object.hasOwn(d,'value'))throw new IosError('non_json_result','Accessor results are not JSON.');assertLosslessJson(d.value,seen);}
+  seen.delete(value);
+}
+export async function targets(endpoint,options){const a=await fetchJson(endpoint,'/json',options);if(!Array.isArray(a))throw new IosError('invalid_bridge','Expected a target array.');return a;}
+export function exactPage(list,id,endpoint){
+  const matches=list.filter(t=>t.id===id&&t.type==='page');
+  if(matches.length!==1)throw new IosError('target_not_found','Exact page target is absent; list targets again. Node/JSContext is not a DOM page.');
+  const t=matches[0],ws=new URL(t.webSocketDebuggerUrl),base=new URL(endpoint);
+  if(ws.protocol!=='ws:'||!['127.0.0.1','localhost'].includes(ws.hostname)||ws.port!==base.port||ws.username||ws.password)throw new IosError('unsafe_websocket','Target socket does not belong to the selected loopback bridge.');
+  ws.hostname=base.hostname;return {...t,webSocketDebuggerUrl:ws.href};
+}
+export function remoteValue(p){
+  if(p.wasThrown||p.exceptionDetails)throw new IosError('javascript_exception',p.result?.description||p.exceptionDetails?.text||'Page JavaScript threw.');
+  const r=p.result;
+  if(r&&Object.hasOwn(r,'value'))return r.value;
+  if(r?.type==='undefined')return {type:'undefined'};
+  return {type:r?.type||'unknown',description:r?.description||'',unserializableValue:r?.unserializableValue||''};
+}
+export function decodeImage(data){
+  if(typeof data!=='string'||!data.length||data.length>40*1024*1024)throw new IosError('invalid_image','Screenshot data is empty or exceeds the 30MiB decoded bound.');
+  const bytes=Buffer.from(data,'base64');let format,mime,ext;
+  if(bytes.subarray(0,8).equals(Buffer.from([137,80,78,71,13,10,26,10]))){format='png';mime='image/png';ext='.png';}
+  else if(bytes[0]===255&&bytes[1]===216&&bytes[2]===255){format='jpeg';mime='image/jpeg';ext='.jpg';}
+  else if(bytes.toString('ascii',0,4)==='RIFF'&&bytes.toString('ascii',8,12)==='WEBP'){format='webp';mime='image/webp';ext='.webp';}
+  else throw new IosError('invalid_image','Screenshot bytes are not PNG/JPEG/WebP.');
+  return {bytes,format,mime,ext,sha256:createHash('sha256').update(bytes).digest('hex')};
+}
+export class Cdp {
+  constructor(ws,signal,timeoutMs){
+    this.ws=ws;this.signal=signal;this.timeoutMs=timeoutMs;this.pending=new Map();this.seq=0;this.closed=false;this.transportClosed=false;this.closeWaiters=[];this.closePromise=null;
+    ws.addEventListener('message',e=>{let m;try{m=JSON.parse(String(e.data));}catch{return;}const p=this.pending.get(m.id);if(!p)return;clearTimeout(p.timer);this.pending.delete(m.id);if(m.error)p.reject(new IosError('cdp_error',m.error.message||'CDP failed.'));else p.resolve(m.result||{});});
+    ws.addEventListener('close',()=>{this.transportClosed=true;this.signal?.removeEventListener('abort',this.onAbort);this.rejectAll(new IosError('target_disconnected','Target disconnected; re-list before retry.'));for(const done of this.closeWaiters.splice(0))done();});
+    ws.addEventListener('error',()=>this.rejectAll(new IosError('websocket_error','Bridge socket error.')));
+    this.onAbort=()=>{this.rejectAll(new IosError('cancelled','Operation cancelled.'));void this.close().catch(()=>{});};
+    signal?.addEventListener('abort',this.onAbort,{once:true});
+  }
+  static async connect(url,{signal,timeoutMs=15000,factory=u=>new WebSocket(u)}={}){
+    signal?.throwIfAborted();const ws=factory(url),c=new Cdp(ws,signal,timeoutMs);
+    try{await new Promise((resolve,reject)=>{
+      const cleanup=()=>{clearTimeout(timer);signal?.removeEventListener('abort',abort);};
+      const abort=()=>{cleanup();reject(new IosError('cancelled','Connection cancelled.'));};
+      const timer=setTimeout(()=>{cleanup();reject(new IosError('connect_timeout','CDP connect timeout.'));},timeoutMs);
+      ws.addEventListener('open',()=>{cleanup();resolve();},{once:true});
+      ws.addEventListener('error',()=>{cleanup();reject(new IosError('websocket_error','Cannot connect CDP.'));},{once:true});
+      ws.addEventListener('close',()=>{cleanup();reject(new IosError('target_disconnected','Target closed while connecting.'));},{once:true});
+      signal?.addEventListener('abort',abort,{once:true});if(signal?.aborted)abort();
+    });return c;}catch(e){await c.close();throw e;}
+  }
+  rejectAll(e){for(const p of this.pending.values()){clearTimeout(p.timer);p.reject(e);}this.pending.clear();}
+  send(method,params={}){
+    this.signal?.throwIfAborted();if(this.closed||this.transportClosed)return Promise.reject(new IosError('client_closed','CDP client is closed.'));
+    return new Promise((resolve,reject)=>{const id=++this.seq;const timer=setTimeout(()=>{this.pending.delete(id);reject(new IosError('command_timeout','Timed out: '+method));},this.timeoutMs);this.pending.set(id,{resolve,reject,timer});try{this.ws.send(JSON.stringify({id,method,params}));}catch(e){clearTimeout(timer);this.pending.delete(id);reject(e);}});
+  }
+  async evaluate(expression){return remoteValue(await this.send('Runtime.evaluate',{expression,returnByValue:true,awaitPromise:true,userGesture:true}));}
+  async close(){
+    if(this.closePromise)return this.closePromise;
+    this.closed=true;this.signal?.removeEventListener('abort',this.onAbort);this.rejectAll(new IosError('client_closed','CDP client closed.'));
+    if(this.transportClosed)return;
+    this.closePromise=new Promise((resolve,reject)=>{
+      const timer=setTimeout(()=>reject(new IosError('socket_close_unknown','Socket close was not confirmed; keep device lock until owner verifies transport shutdown.',{retainDeviceLock:true})),Math.min(this.timeoutMs,3000));
+      const done=()=>{clearTimeout(timer);resolve();};this.closeWaiters.push(done);
+      try{this.ws.close();}catch(e){clearTimeout(timer);reject(new IosError('socket_close_unknown','Cannot confirm socket shutdown.',{retainDeviceLock:true}));}
+    });
+    return this.closePromise;
+  }
+}

package/lib/core/python.mjs

@@ -0,0 +1,47 @@
+import { spawn } from 'node:child_process';
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { IosError } from './protocol.mjs';
+
+export function isolatedPythonEnv(env=process.env){
+  const clean={};
+  for(const [key,value]of Object.entries(env)){
+    if(/^(PYTHON|PIP|VIRTUAL_ENV|CONDA|__PYVENV_LAUNCHER__)/i.test(key))continue;
+    clean[key]=value;
+  }
+  // Device discovery must never inherit a user's module injection settings or
+  // write the host Python's bytecode/cache. Setup uses its own stricter env.
+  return{...clean,PYTHONUTF8:'1',PYTHONIOENCODING:'utf-8',PYTHONDONTWRITEBYTECODE:'1',PYTHONNOUSERSITE:'1',PYTHONPYCACHEPREFIX:path.join(os.homedir(),'.dsh-ios-webview-app-control','runtime','pycache')};
+}
+export function pythonPath(config={}, {env=process.env,platform=process.platform}={}){
+  let candidate=config.pythonPath||env.DSH_IOS_PYTHON;
+  if(!candidate&&env.DSH_PRIMARY_RUNTIME){
+    if(!path.isAbsolute(env.DSH_PRIMARY_RUNTIME))throw new IosError('python_missing','DSH_PRIMARY_RUNTIME must be an absolute runtime payload directory.');
+    candidate=path.join(env.DSH_PRIMARY_RUNTIME,'dependencies','python',platform==='win32'?'python.exe':'bin/python3');
+  }
+  // Harness home/cache layout is not a public API. Never guess ~/.dsh paths,
+  // search PATH, launch a Store alias or install a runtime as a side effect.
+  let isFile=false;
+  if(typeof candidate==='string'&&path.isAbsolute(candidate)){
+    try{isFile=statSync(candidate).isFile();}catch{}
+  }
+  if(!isFile)throw new IosError('python_missing','Configure pythonPath or DSH_IOS_PYTHON as an absolute Python interpreter with pymobiledevice3 installed, or set DSH_PRIMARY_RUNTIME to an existing payload. Use load_workspace_dependencies when available to obtain its Python path, then configure pythonPath explicitly. No automatic install or Windows Store alias.');
+  return candidate;
+}
+export async function runPython(executable,args,{signal,timeoutMs=15000}={}){
+  signal?.throwIfAborted();
+  return new Promise((resolve,reject)=>{
+    const child=spawn(executable,args,{shell:false,windowsHide:true,stdio:['ignore','pipe','pipe'],env:isolatedPythonEnv()});
+    let stdout='',stderr='',failure=null;let settled=false;
+    const stop=e=>{if(!failure)failure=e;child.kill();};
+    const abort=()=>stop(new IosError('cancelled','Python discovery cancelled.'));
+    const timer=setTimeout(()=>stop(new IosError('process_timeout','Python discovery timed out; terminated only its owned child.')),timeoutMs);
+    signal?.addEventListener('abort',abort,{once:true});if(signal?.aborted)abort();
+    const cleanup=()=>{clearTimeout(timer);signal?.removeEventListener('abort',abort);};
+    child.stdout.on('data',b=>{stdout+=b.toString('utf8');if(Buffer.byteLength(stdout)>1024*1024)stop(new IosError('output_limit','Python discovery exceeded 1MiB.'));});
+    child.stderr.on('data',b=>{stderr+=b.toString('utf8');if(Buffer.byteLength(stderr)>1024*1024)stop(new IosError('output_limit','Python errors exceeded 1MiB.'));});
+    child.on('error',e=>{if(settled)return;settled=true;cleanup();reject(new IosError('process_error',e.message));});
+    child.on('close',code=>{if(settled)return;settled=true;cleanup();if(failure)reject(failure);else if(code!==0)reject(new IosError('python_error','Device discovery failed; check Apple service, USB, Trust and Web Inspector.',{exitCode:code}));else resolve(stdout);});
+  });
+}