@international-iot-association/plugin-template 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Loom Plugin SDK Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# __PLUGIN_ID__
+
+由 `@international-iot-association/plugin-cli new` 从 plugin-starter 生成的产测工位插件工程。
+
+**这是一个 unsigned 开发包，不是「官方 ZIP」**——「官方 ZIP」专指本仓 `plugins/*` 经五方对账与签名后的产物；仓外产出的包不管走什么路径打包，都只能叫 unsigned 开发包，产线放行与否取决于 MES 后台是否将其标记为 released。
+
+## 环境要求
+
+- Node.js >= 20.19
+- pnpm（由 `package.json` 的 `packageManager` 字段锁版本，勿用 npm/yarn 安装）
+
+## 大陆网络：npm 镜像配置
+
+clone 走 GitHub、装依赖走 npmjs 在大陆网络下容易同时卡住，先配置镜像：
+
+```bash
+npm config set registry https://registry.npmmirror.com
+```
+
+## 快速开始
+
+```bash
+pnpm install
+pnpm run dev
+pnpm run build && pnpm run pack
+```
+
+## 目录形态
+
+```
+manifest.json   插件清单：id / version / permissions / dependencies
+package.json    依赖声明 + loom 字段（见下）
+runtime/        产测流程主逻辑（独立 Node 子进程，禁止 import electron）
+ui/             操作员界面（React，沙箱 iframe，无网络）
+shared/         runtime 与 ui 共用的类型/契约
+test/           单元测试（不能是空壳）
+```
+
+## loom 字段
+
+`package.json` 里的 `loom` 字段供外壳工作台读取启动命令，避免猜测：
+
+```json
+{
+  "loom": {
+    "ui": { "dev": "...", "port": 5174 },
+    "runtime": { "build": "..." }
+  }
+}
+```
+
+## 插件间依赖不是 npm 依赖
+
+`manifest.json` 的 `dependencies` 字段引用的是别的插件（基座能力，如登录态、全局配置），由 Shell 底座（bundled-attested）或 MES 后台提供——**不要** `npm install` 它们，那些包名不在任何 npm registry 上。
+
+## 反馈
+
+发现问题请开 issue，不要提 PR——本仓不接受针对模板/SDK 的外部 PR。
+
+## 局限
+
+本 README 只验证过「照着做流程能跑通」，**未做真人可读性验收**（没有找一个没碰过本仓的人照文档从零走一遍）；如果卡住，请在 issue 里写清卡在哪一步。

package/manifest.json

@@ -0,0 +1,17 @@
+{
+  "id": "__PLUGIN_ID__",
+  "name": "__PLUGIN_NAME__",
+  "version": "1.0.0",
+  "description": "由模板生成的插件。",
+  "stationTypes": [
+    "DUT"
+  ],
+  "models": [],
+  "agentApi": "3.0.0",
+  "uiEntry": "ui/index.html",
+  "runtimeEntry": "runtime/main.mjs",
+  "permissions": [],
+  "resultSchema": "schemas/result.schema.json",
+  "steps": [],
+  "checksum": ""
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@international-iot-association/plugin-template",
+  "version": "1.0.0-rc.1",
+  "description": "插件模板（React + Siemens iX（深色）+ Tailwind 布局 + rct-state + API-Bridge）。",
+  "type": "module",
+  "scripts": {
+    "build:runtime": "tsup --config tsup.runtime.config.ts",
+    "build:ui": "vite build",
+    "build": "pnpm run build:runtime && pnpm run build:ui",
+    "dev": "vite --host 127.0.0.1 --port 5174",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm run build:runtime && node --test test/*.test.mjs",
+    "clean": "rimraf ui-dist runtime-dist .turbo",
+    "pack": "plugin-cli pack . --out dist",
+    "preinstall": "npx only-allow pnpm"
+  },
+  "dependencies": {
+    "@international-iot-association/api-bridge": "3.0.0-rc.1",
+    "@international-iot-association/plugin-contracts": "3.0.0-rc.1",
+    "@international-iot-association/plugin-sdk": "3.0.0-rc.1",
+    "@international-iot-association/rct-state": "3.0.0-rc.1",
+    "@international-iot-association/ui": "1.0.0-rc.1",
+    "@siemens/ix": "~5.1.1",
+    "@siemens/ix-icons": "~3.4.0",
+    "@siemens/ix-react": "~5.1.1",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1"
+  },
+  "devDependencies": {
+    "@international-iot-association/tsconfig": "1.0.0-rc.1",
+    "@tailwindcss/vite": "^4.3.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "tailwindcss": "^4.3.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.6",
+    "vite-plugin-singlefile": "^2.2.0",
+    "rimraf": "^6.0.1",
+    "@international-iot-association/plugin-vite-config": "1.0.0-rc.1",
+    "@types/node": "^22.19.1",
+    "@international-iot-association/plugin-cli": "1.0.0-rc.1"
+  },
+  "pnpm": {
+    "overrides": {
+      "react": "19.2.7",
+      "react-dom": "19.2.7"
+    }
+  },
+  "loom": {
+    "ui": {
+      "dev": "vite --host 127.0.0.1 --port 5174",
+      "port": 5174
+    },
+    "runtime": {
+      "build": "tsup --config tsup.runtime.config.ts"
+    }
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "packageManager": "pnpm@10.14.0",
+  "x-internal-version": "1.0.0",
+  "x-source-revision": "410a2f3b85ef03b678f04f22ea0a47718f5ddae1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/International-IoT-Association/Loom-Plugin-Template.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/runtime/main.ts

@@ -0,0 +1,30 @@
+// __PLUGIN_NAME__ —— 插件运行时入口。
+//
+// 能力边界（重要）：运行在进程外的插件宿主中（纯 Node 子进程），只能使用受控的 `ctx`。
+// 绝不要 import serialport / fs / child_process / net。真实设备交互优先使用
+// createStationRuntime() 提供的 station.step / step.devices，底层仍由 Agent Device Broker 执行。
+
+import { createStationRuntime, definePluginRuntime } from "@international-iot-association/plugin-sdk/runtime";
+import type { TemplateApi } from "../shared/api";
+
+export const { activate } = definePluginRuntime<TemplateApi>((server, ctx) => {
+  const station = createStationRuntime(server, ctx);
+
+  ctx.logger.info("[__PLUGIN_ID__] runtime activated");
+
+  server.example.run.onRequest(async (input) => {
+    return station.step("example", async (step) => {
+      // —— 在这里写你的业务逻辑 ——
+      // 例如：const reply = await step.devices.dut.ask({ cmd: "ping" });
+      step.say("run", `note=${input?.note ?? ""}`);
+      station.sendEvent(server.example.progress, "progress", { pct: 100 });
+      return step.pass({ note: input?.note ?? null });
+    });
+  });
+
+  return {
+    deactivate() {
+      ctx.logger.info("[__PLUGIN_ID__] runtime deactivated");
+    },
+  };
+});

package/schemas/result.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "StationPluginStepResult",
+  "description": "受控的插件测试步骤结果结构。runtime 必须返回符合此结构的对象。",
+  "type": "object",
+  "required": ["ok", "stepKey", "startedAt", "finishedAt"],
+  "properties": {
+    "ok": { "type": "boolean" },
+    "stepKey": { "type": "string" },
+    "measurements": { "type": "object", "additionalProperties": true },
+    "raw": { "type": "string" },
+    "error": { "type": "string" },
+    "startedAt": { "type": "string", "format": "date-time" },
+    "finishedAt": { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}

package/shared/api.ts

@@ -0,0 +1,12 @@
+// 本插件的类型化 API-Bridge 接口。UI（usePluginClient<TemplateApi>）与 runtime
+// （definePluginRuntime）双方共同 import 它。把你自己的方法/事件加在这里。
+import type { ApiRoot, EventListener, FuncHandler, StepResult } from "@international-iot-association/plugin-sdk";
+
+export interface TemplateApi extends ApiRoot {
+  example: {
+    /** UI -> runtime：执行一次示例步骤。 */
+    run: FuncHandler<[{ note?: string }], StepResult>;
+    /** runtime -> UI：进度事件示例。 */
+    progress: EventListener<"progress", { pct: number }>;
+  };
+}

package/smoke.mjs

@@ -0,0 +1,12 @@
+// __PLUGIN_NAME__ —— 无头冒烟场景（由 tools/verify.mjs 经 tools/smoke-harness.mjs 执行）。
+// 要求：activate → 至少一次 API 往返 → 至少一条 ctx.report.result。
+// 写你自己的业务后，把这里改成能覆盖主流程的真实场景。
+export default async function smoke(toolkit) {
+  const { ctx, client, results } = toolkit.createHarness();
+  await toolkit.activate(ctx);
+
+  const response = await client.example.run.call({ note: "smoke" });
+  toolkit.assert.equal(response.result.ok, true, "example.run 应 PASS");
+  toolkit.assert.equal(response.result.measurements.note, "smoke");
+  toolkit.assert.equal(results.length, 1, "应产生一条 report.result");
+}

package/test/runtime.test.mjs

@@ -0,0 +1,68 @@
+// __PLUGIN_NAME__ —— runtime 单元测试（node --test）。
+// 脚手架自带：新插件生成后 `pnpm --filter __PLUGIN_ID__ test` 必须直接全绿。
+// 写你自己的步骤逻辑时，请同步把用例改成真实断言（不要留空壳测试）。
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { createAPIClient } from "@international-iot-association/api-bridge";
+
+/** 最小 stub ctx：形状对齐外壳 plugin-host/runner.ts 注入的 PluginRuntimeContext。 */
+function makeStubCtx() {
+  const reports = [];
+  const stepEvents = [];
+  let runtimeOnMessage = null;
+
+  const ctx = {
+    logger: { info() {}, warn() {}, error() {}, debug() {} },
+    channels: {
+      async writeReadMock(logicalName, payload) {
+        return { logicalName, request: payload, response: `MOCK<${logicalName}>:${payload}:OK`, latencyMs: 1 };
+      },
+      async writeRead() {
+        throw new Error("no device configured");
+      },
+      async control() {
+        throw new Error("no device configured");
+      },
+      subscribe() {},
+    },
+    report: {
+      stepEvent: (e) => stepEvents.push(e),
+      result: (r) => reports.push(r),
+    },
+    ui: {
+      postMessage: (env) => {
+        if (env.type === "response") clientMessageHandler(env);
+        else if (env.type === "event") serverEventHandler(env);
+      },
+      onMessage: (h) => {
+        runtimeOnMessage = h;
+      },
+    },
+    bus: { postMessage() {}, onMessage() {} },
+  };
+
+  const { client, clientMessageHandler, serverEventHandler } = createAPIClient({
+    requestServerFunc: async (req) => {
+      runtimeOnMessage?.(req);
+    },
+  });
+
+  return { ctx, client, reports, stepEvents };
+}
+
+test("example.run：回传 PASS、携带输入 note、上报 result 并推送 progress 事件", async () => {
+  const { ctx, client, reports } = makeStubCtx();
+  const { activate } = await import("../runtime-dist/main.mjs");
+  await activate(ctx);
+
+  const progressEvents = [];
+  client.example.progress.on("progress", (data) => progressEvents.push(data));
+
+  const response = await client.example.run.call({ note: "hello" });
+  assert.equal(response.result.ok, true);
+  assert.equal(response.result.stepKey, "example");
+  assert.equal(response.result.measurements.note, "hello");
+  assert.equal(reports.length, 1);
+  assert.equal(reports[0].ok, true);
+  assert.deepEqual(progressEvents, [{ pct: 100 }]);
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "@international-iot-association/tsconfig/react.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "ui",
+    "runtime",
+    "shared"
+  ]
+}

package/tsup.runtime.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from "tsup";
+
+// 将 runtime/main.ts 构建为一个自包含的 ESM 模块，外壳可以从一个没有 node_modules 的
+// 安装目录中动态 import 它。
+//
+// 因此我们把 SDK + api-bridge 及其依赖（rxjs、nanoid）一并打包进来。我们从不 import
+// electron/serialport/fs，所以它们绝不会进入产物——runtime 始终是一个纯 node 的能力沙箱客户端。
+export default defineConfig({
+  entry: { main: "runtime/main.ts" },
+  outDir: "runtime-dist",
+  format: ["esm"],
+  platform: "node",
+  target: "node18",
+  bundle: true,
+  noExternal: [/^@international-iot-association\//, "rxjs", "nanoid"],
+  outExtension: () => ({ js: ".mjs" }),
+  clean: true,
+  dts: false,
+  sourcemap: false,
+  minify: false,
+});

package/ui/App.tsx

@@ -0,0 +1,116 @@
+import { useEffect } from "react";
+import { usePluginClient, useDisplayScale } from "@international-iot-association/plugin-sdk/ui";
+import { IxChip, IxTypography } from "@siemens/ix-react";
+import type { TemplateApi } from "../shared/api";
+import { ui$ } from "./state";
+import { OperatorButton, OperatorToggleButton } from "./components/operator-controls";
+
+// 状态 → 文案/语义色集中映射；禁止在 JSX 里散落颜色判断或硬编码 hex（约定 §8.3/§11.5）。
+const STATUS_WORD = { idle: "待机", running: "运行中", done: "完成" } as const;
+const STATUS_CHIP = { idle: "neutral", running: "info", done: "success" } as const;
+
+export function App(): React.JSX.Element {
+  // 类型化的 API-Bridge 客户端：直接调用插件 runtime，卸载时自动清理监听。
+  const client = usePluginClient<TemplateApi>();
+  // 显示缩放：根字号 = Shell 校准基准 ×（普通 1.0 / 超大 1.5），组件内只写 rem（约定 §7）。
+  const scale = useDisplayScale();
+
+  // rct-state：值变化时自动重渲染。
+  const status = ui$.status.use();
+  const count = ui$.count.use();
+  const lastError = ui$.lastError.use();
+
+  // runtime -> UI 的事件示例。
+  useEffect(() => {
+    const off = client.example.progress.on("progress", (d) => {
+      ui$.status.set(d.pct >= 100 ? "done" : "running");
+    });
+    return () => off();
+  }, [client]);
+
+  const handleRunExample = async (): Promise<void> => {
+    // UI 层防重复（busy + 状态检查）；runtime 侧仍需幂等校验（约定 §13.2）。
+    if (ui$.status.peek() === "running") return;
+    ui$.batch(() => {
+      ui$.status.set("running");
+      ui$.lastError.set("");
+      ui$.count.set(ui$.count.peek() + 1);
+    });
+    try {
+      // invoke：resolve StepResult 本体；失败以 ApiBridgeError reject（约定 §18.1）。
+      const result = await client.example.run.invoke({ note: `run #${ui$.count.peek()}` });
+      ui$.batch(() => {
+        ui$.status.set(result.ok ? "done" : "idle");
+        ui$.lastError.set(result.ok ? "" : (result.error ?? "示例步骤失败"));
+      });
+    } catch (cause) {
+      // 失败必须显式呈现；真实插件请给出影响、下一步操作与故障代码（约定 §15）。
+      ui$.batch(() => {
+        ui$.status.set("idle");
+        ui$.lastError.set(cause instanceof Error ? cause.message : String(cause));
+      });
+    }
+  };
+
+  // 布局约定（§9）：全宽填满显示区（禁止 max-w-* 限宽），统一页面内边距 1.25rem。
+  return (
+    <div className="flex min-h-full w-full flex-col gap-[1rem] p-[1.25rem]">
+      <header className="flex flex-wrap items-center gap-[1rem]">
+        <div className="min-w-0 flex-1">
+          <IxTypography format="h3">__PLUGIN_NAME__</IxTypography>
+          <IxTypography format="body-sm" textColor="soft">
+            __PLUGIN_ID__ · 校准 {scale.basePercent}% ×{" "}
+            {scale.mode === "xl" ? "超大 ×1.5" : "普通 ×1.0"}
+          </IxTypography>
+        </div>
+
+        {/* 普通/超大显示模式：面向产线的插件必须提供（约定 §7.1）。 */}
+        <div className="flex items-center gap-[0.5rem]" role="group" aria-label="显示尺寸">
+          <OperatorToggleButton
+            pressed={scale.mode === "normal"}
+            onPressedChange={() => scale.setMode("normal")}
+          >
+            普通
+          </OperatorToggleButton>
+          <OperatorToggleButton
+            pressed={scale.mode === "xl"}
+            onPressedChange={() => scale.setMode("xl")}
+          >
+            超大
+          </OperatorToggleButton>
+        </div>
+      </header>
+
+      <section className="flex flex-col gap-[1rem] rounded-lg border border-border bg-card p-[1.25rem]">
+        <IxTypography format="body" textColor="soft">
+          这是插件模板：UI 用 rct-state 管理状态、经 API-Bridge 的 invoke 调用 runtime。
+          界面按 docs/ui-conventions.md 实现（iX 组件、深色唯一、rem 尺寸、全宽布局）。
+          把业务逻辑写在 runtime/main.ts 与本文件即可。
+        </IxTypography>
+
+        <div className="flex flex-wrap items-center gap-[1rem]">
+          <OperatorButton
+            physicalSize="primary"
+            busy={status === "running"}
+            onClick={() => void handleRunExample()}
+          >
+            {status === "running" ? "正在运行示例步骤…" : "运行示例步骤"}
+          </OperatorButton>
+          {/* 状态同时有文字 + 语义色，且经 aria-live 播报（约定 §11.5/§20）。 */}
+          <span className="flex items-center gap-[0.5rem]" role="status" aria-live="polite">
+            <IxChip variant={STATUS_CHIP[status]}>{STATUS_WORD[status]}</IxChip>
+            <IxTypography format="body-sm" textColor="soft">
+              已运行 {count} 次
+            </IxTypography>
+          </span>
+        </div>
+
+        {lastError !== "" ? (
+          <IxTypography format="body-sm" textColor="alarm">
+            上次运行失败：{lastError}
+          </IxTypography>
+        ) : null}
+      </section>
+    </div>
+  );
+}

package/ui/components/operator-controls.tsx

@@ -0,0 +1,66 @@
+import type { ComponentProps } from "react";
+import { IxButton, IxToggleButton } from "@siemens/ix-react";
+
+// 产线触摸尺寸包装（docs/ui-conventions.md §7.2/§7.3）：
+// iX 5.x 按钮宿主固定 height: 2rem、内核 height: 100%，低于产线普通模式 2.75rem 触摸基线。
+// 在宿主元素上覆盖高度即可整体拉伸。所有操作员可触控件统一经这里，不要在页面里散落覆盖。
+
+const TOUCH_STANDARD = "2.75rem"; // 普通触摸目标（校准后约 11.6mm）
+const TOUCH_PRIMARY = "3rem"; // 高频主操作（校准后约 12.7mm）
+
+type OperatorButtonProps = ComponentProps<typeof IxButton> & {
+  /** primary = 高频主操作（3rem 高）；standard = 普通触摸目标（2.75rem 高）。 */
+  physicalSize?: "standard" | "primary";
+  /** 异步进行中：loading + 禁点。仅 UI 层防重复不够，runtime 仍需幂等（约定 §13.2）。 */
+  busy?: boolean;
+};
+
+export function OperatorButton({
+  physicalSize = "standard",
+  busy = false,
+  disabled,
+  loading,
+  style,
+  children,
+  ...props
+}: OperatorButtonProps): React.JSX.Element {
+  return (
+    <IxButton
+      {...props}
+      disabled={disabled || busy}
+      loading={loading || busy}
+      aria-busy={busy || undefined}
+      style={{
+        blockSize: physicalSize === "primary" ? TOUCH_PRIMARY : TOUCH_STANDARD,
+        minInlineSize: TOUCH_STANDARD,
+        fontSize: "1rem",
+        ...style,
+      }}
+    >
+      {children}
+    </IxButton>
+  );
+}
+
+type OperatorToggleButtonProps = ComponentProps<typeof IxToggleButton>;
+
+/** 触摸尺寸达标的 iX ToggleButton（用于"普通/超大"显示模式等分段选择）。 */
+export function OperatorToggleButton({
+  style,
+  children,
+  ...props
+}: OperatorToggleButtonProps): React.JSX.Element {
+  return (
+    <IxToggleButton
+      {...props}
+      style={{
+        blockSize: TOUCH_STANDARD,
+        minInlineSize: "4.5rem",
+        fontSize: "1rem",
+        ...style,
+      }}
+    >
+      {children}
+    </IxToggleButton>
+  );
+}

package/ui/index.css

@@ -0,0 +1,10 @@
+@import "tailwindcss";
+@import "@international-iot-association/ui/styles.css";
+
+/* 扫描本插件自身的 UI 源码以及下面这行 @import 引入的共享 UI 组件库源码，以便 Tailwind
+   生成所有用到的工具类（在 monorepo 内相对路径是确定的，不受 pnpm 提升策略影响）。
+   注意：这里刻意不写死具体包名——gen-starter.mjs 生成 plugin-starter/ 时只做结构化
+   改写（import specifier / JSON 字段 / CSS 精确子串），不做全文替换，写死包名的说明性
+   文字不会被自动改写，会在投影里变成过时/错误的提及。 */
+@source "./";
+@source "../node_modules/@international-iot-association/ui/dist";

package/ui/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<!-- iX 5.x 主题经属性选择器挂载：[data-ix-theme=classic][data-ix-color-schema=dark]。
+     深色是唯一默认（docs/ui-conventions.md §8），不要在业务组件中切换主题。 -->
+<html lang="zh" class="dark" data-ix-theme="classic" data-ix-color-schema="dark">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <!--
+      运行在沙箱、opaque-origin 的 iframe 中，无网络、无 Node。UI 是单个自包含文件
+      （JS + CSS 由 viteSingleFile 内联），因此 'unsafe-inline' 是务实的 CSP 选择。
+      不允许任何远程来源；font-src/img-src 的 data: 用于内联的 iX 字体与图形资产。
+    -->
+    <meta
+      http-equiv="Content-Security-Policy"
+      content="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:; connect-src 'none'"
+    />
+    <title>__PLUGIN_NAME__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

package/ui/main.tsx

@@ -0,0 +1,20 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { applyInitialDisplayScale } from "@international-iot-association/plugin-sdk/ui";
+import { App } from "./App";
+// Siemens iX 核心样式 + 深色主题（深色是唯一默认，见 docs/ui-conventions.md §8）。
+// 单文件构建会把 iX 样式内嵌的字体/图形资产全部内联（CSP 无网络，见 vite.config.ts）。
+import "@siemens/ix/dist/siemens-ix/siemens-ix.css";
+import "@siemens/ix/dist/siemens-ix/theme/classic-dark.css";
+import "./index.css";
+
+// 渲染前应用外壳注入的校准基准（?displayScale=），消除首帧错误字号。
+applyInitialDisplayScale();
+
+const el = document.getElementById("root");
+if (!el) throw new Error("root element missing");
+createRoot(el).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/ui/state.ts

@@ -0,0 +1,14 @@
+import { observable } from "@international-iot-association/rct-state";
+
+// 插件 UI 的响应式状态（rct-state）。
+//   读取：const x = ui$.x.use()   —— 值变化时组件自动重渲染
+//   更新：ui$.x.set(v)            —— 同步写入并通知订阅者
+//   快照：ui$.x.peek() / ui$.peek()
+//   批量：ui$.batch(() => { ... }) —— 多次 set 只通知一次
+// 主状态用互斥的字面量联合表达；真实插件请扩展为判别联合/状态机
+// （禁止用多个独立布尔拼装，见 docs/ui-conventions.md §10）。
+export const ui$ = observable({
+  status: "idle" as "idle" | "running" | "done",
+  count: 0,
+  lastError: "",
+});

package/vite.config.ts

@@ -0,0 +1,3 @@
+import { definePluginUiViteConfig } from "@international-iot-association/plugin-vite-config";
+
+export default definePluginUiViteConfig(import.meta.url);