create-aiaui-module 0.1.1-TEST → 0.2.0

package/README.md

@@ -7,8 +7,8 @@
 | 步骤 | 命令 | 说明 |
 | --- | --- | --- |
 | 查看可用模块 | `npx create-aiaui-module@latest --list` | 列出模块 ID 与 contractVersion |
-| 生成模块 | `npx create-aiaui-module@latest JobInformation` | 在实例根目录生成 `PyAIAUI/JobInformation` |
-| 机器可读 | `npx create-aiaui-module@latest JobInformation --json` | 生成结果输出 JSON（接 CI） |
+| 生成模块 | `npx create-aiaui-module@latest JobDashboard` | 在实例根目录生成 `PyAIAUI/JobDashboard` |
+| 机器可读 | `npx create-aiaui-module@latest JobDashboard --json` | 生成结果输出 JSON（接 CI） |
 
 ## 环境要求
 
@@ -20,10 +20,10 @@
 在 Instance 根目录（含 `Config/` 的目录）下执行：
 
 ```bash
-npx create-aiaui-module@latest JobInformation
+npx create-aiaui-module@latest JobDashboard
 ```
 
-生成后 `PyAIAUI/JobInformation/` 与 `PyAIAUI/_runtime/` 就位，`Config/AIAUIProtocol.json` 中登记该模块（默认 `enabled: false`、`port: null`）。
+生成后 `PyAIAUI/JobDashboard/` 与 `PyAIAUI/_runtime/` 就位，`Config/AIAUIProtocol.json` 中登记该模块（默认 `enabled: false`、`port: null`）。
 
 启用前需要调整的配置：
 
@@ -32,7 +32,7 @@ npx create-aiaui-module@latest JobInformation
   "schemaVersion": 1,
   "port": 18901,
   "modules": [
-    { "name": "JobInformation", "enabled": true }
+    { "name": "JobDashboard", "enabled": true }
   ]
 }
 ```
@@ -62,10 +62,11 @@ if aiaui is not None:
 ├── Config/AIAUIProtocol.json            # 运行协议：端口 + 模块启停（生成器只登记，不配置）
 └── PyAIAUI/
     ├── __init__.py                      # 入口：AIAUI 类（AIAUI.start / aiaui.stop）
-    ├── JobInformation/                  # 模块目录，目录名 == 模块 ID
-    │   ├── api.py                       # 后端契约：create_api(context) -> APIRouter
-    │   ├── resources/src/               # Vue 前端源码
-    │   ├── resources/dist/              # 预构建产物（开箱即跑，改源码后 npm run build 重出）
+    ├── JobDashboard/                   # 模块目录，目录名 == 模块 ID
+    │   ├── backend/api.py               # 后端契约：create_api(context) -> APIRouter
+    │   ├── backend/config.json          # 外观配置（可无：/config 端点读它）
+    │   ├── client/src/                  # Vue 前端源码
+    │   ├── client/dist/                 # 预构建产物（开箱即跑，改源码后 npm run build 重出）
     │   └── {README.md, CUSTOMIZATION.md}# 模块说明与定制手册
     └── _runtime/                        # 内嵌模块宿主（零外部依赖）
 ```
@@ -76,9 +77,9 @@ if aiaui is not None:
 
 | 模块 ID | 说明 | 组成 |
 | --- | --- | --- |
-| `JobInformation` | 工单 / 载具 / 工序信息面板 | FastAPI 后端 + Vue 前端；内置 `header`、`inputCarriers`、`outputCarriers`、`timeline`、`recipe` 五个可替换槽位；三级定制（默认 / 局部替换 / 全量自定义） |
+| `JobDashboard` | 工单 / 载具 / 工序信息面板 | FastAPI 后端（`backend/api.py` + `backend/config.json`）+ Vue 前端（`client/`）；实现 `GET /jobs`（工单数据）+ `GET /config`（显示开关 + 状态色/图标，config.json 读取）即可；分粒度槽位（`board`/`headerRegion`/`middleRegion`/`bottomRegion` + 叶子）可替换任意局部 |
 | `HelloWorld` | 最小前端模块示例 | 自定义元素；验证挂载链路，无后端 |
-自定义通过 `resources/src/customization.ts` 完成，槽位通信通过 `context.bus`（事件 / expose+peer），详见生成目录里的 `CUSTOMIZATION.md`。
+自定义通过 `client/src/customization.ts` 完成，槽位通信通过 `context.bus`（事件 / expose+peer），详见生成目录里的 `CUSTOMIZATION.md`。
 
 ## UIService 集成
 
@@ -97,6 +98,6 @@ export AIA_UI_MODULE_TEMPLATE_ROOT="$(npm root -g)/create-aiaui-module"
 
 ## 维护者（发布新模板）
 
-- 新增模块：在 `templates/<ModuleId>/` 下放实现（含 `contractVersion`、`README.md`、`resources/`）
+- 新增模块：在 `templates/<ModuleId>/` 下放实现（含 `contractVersion`、`README.md`、`backend/api.py`、`client/`）
 - 前端模板发布前在 `resources/` 跑 `npm install && npm run build`，把产物一起随包发布；发布自动执行 `verify-dist` 校验每个模板的 `contractVersion`、入口、`dist/` 产物
 - 发版流程：`npm test` → 改 `package.json` 版本号 → `npm publish`

package/bin/create-aiaui-module.js

@@ -35,7 +35,7 @@ function briefDescription(templateId) {
 
 function printTemplateList(entries) {
   console.log();
-  console.log("AIAUI 模块模板");
+  console.log("AIAUI module templates");
   console.log(DIVIDER);
   if (entries.length === 0) console.log("  (none)");
   for (const entry of entries) {
@@ -44,43 +44,35 @@ function printTemplateList(entries) {
       console.log(`     ${briefDescription(entry.id)}`);
   }
   console.log(DIVIDER);
-  console.log("生成: npx create-aiaui-module <模块名> [--list] [--json]");
+  console.log("usage: npx create-aiaui-module <ModuleId> [--list] [--json] [--instance-root <path>]");
 }
 
 function printSuccess(result) {
   console.log();
-  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
-  console.log("                  [AIAUI] 生成成功");
-  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+  console.log("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+  console.log("                    [AIAUI] module created");
+  console.log("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
   console.log();
-  console.log(`  ✅ 生成路径    ${result.path} (${result.filesCopied} 个文件)`);
-  console.log(`  ✅ 协议配置    ${result.configPath} (enabled: ${result.enabled})`);
+  console.log(`  done  module     ${result.moduleId}`);
+  console.log(`  done  path       ${result.path}`);
+  console.log(`  done  files      ${result.filesCopied}`);
+  console.log(`  done  protocol   ${result.configPath}`);
+  console.log(`                 enabled: ${result.enabled}, port: ${result.port ?? "unset"}`);
   console.log();
-  console.log("⚠️ 配置调整（需要你手动做）");
-  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
-  console.log("  📌 修改 port 字段为 18901（或你选择的其他空闲端口）");
-  console.log("  📌 将 enabled 改为 true");
-  console.log("  📌 模块接入 Instance 启动流程后再启用");
-  console.log();
-  console.log("🔧 接下来要做：");
-  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
-  console.log("  1. 配置端口");
-  console.log("     修改 AIAUIProtocol.json 中 port 字段为 18901（示例值）");
-  console.log("  2. 配置模块 enable");
-  console.log("     修改 AIAUIProtocol.json 中对应模块的 enabled 为 true");
-  console.log("  3. 接入 Instance 启动流程");
-  console.log("     · 启动时: aiaui = AIAUI.start(services={...})");
-  console.log("     · 关闭时: aiaui.stop()");
-  console.log("  4. 打开 UIClient 对应页面查看效果（JobInformation → /jobs）");
-  console.log();
-  console.log("❌ 没有做的（请确认）");
-  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
-  console.log("  · 未启动服务（由 Instance 生命周期调用 AIAUI.start）");
-  console.log("  · 未安装依赖（模块运行需要 pip install fastapi uvicorn）");
-  console.log("  · 未选择/配置端口");
-  console.log("  · 未手动启用任何模块");
-  console.log();
-  console.log("  初始化目录已就绪，按上面的顺序操作即可上线。");
+  console.log("next: edit your Config & wire the module (you must do this)");
+  console.log("\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501");
+  console.log('  1. Set a free loopback port in AIAUIProtocol.json ("port", e.g. 18900-18999 range)');
+  console.log('     and flip "enabled" to true for your module');
+  console.log("  2. Wire the module into your Instance lifecycle");
+  console.log("     from PyAIAUI import AIAUI");
+  console.log("     aiaui = AIAUI.start(services={...})   # at Instance startup");
+  console.log("     aiaui.stop()                            # at shutdown");
+  console.log('  3. Mount its data: backend/api.py implements create_api(context) -> APIRouter.');
+  console.log("     (many templates ship backend/config.json for appearance settings — see README)");
+
+  console.log("  4. Rebuild the frontend if you edited it:");
+  console.log("     npm install && npm run build        # from <module>/client");
+  console.log("  no  starting services, auto-required deps, or a running Instance is triggered");
   console.log();
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-aiaui-module",
-  "version": "0.1.1-TEST",
-  "description": "AIAUI Instance module scaffolder: generate editable module (FastAPI + Vue frontend) with one npx command",
+  "version": "0.2.0",
+  "description": "AIAUI Instance module scaffolder: npx generates an editable module",
   "keywords": [
     "aiaui",
     "scaffolding",
@@ -9,7 +9,8 @@
     "vue",
     "fastapi",
     "module",
-    "instance"
+    "instance",
+    "sharetek"
   ],
   "type": "module",
   "bin": {

package/runtime/_runtime/host.py

@@ -12,9 +12,6 @@ OWNER = "aiaui-proxy"
 
 class ProxyHost:
     def __init__(self, instance_root: Path, port: int, modules: list[ModuleDescriptor], context):
-        import fcntl
-        import os
-
         import uvicorn
         from fastapi import FastAPI
 
@@ -24,17 +21,13 @@ class ProxyHost:
         self.closed = False
         self.thread: threading.Thread | None = None
 
-        config_dir = self.root / "Config"
-        config_dir.mkdir(parents=True, exist_ok=True)
-        lock_path = config_dir / ".aiaui.host.lock"
-        descriptor = os.open(lock_path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
-        self._lock_file = os.fdopen(descriptor, "a")
-        try:
-            fcntl.flock(self._lock_file, fcntl.LOCK_EX | fcntl.LOCK_NB)
-        except BlockingIOError as error:
-            self._lock_file.close()
-            raise ValueError("Another process already hosts this Instance") from error
-
+        # No file lock: the loopback bind in `name:port` (the protocol's port)
+        # already enforces "one host per Instance". A second host for the
+        # same Instance fails fast with a uvicorn bind error. If two hosts
+        # for the same Instance ever end up on different ports, the second
+        # one silently serves alongside the first; this is an edge case the
+        # caller avoids by keeping AIAUIProtocol.json as the single source
+        # of truth.
         self._app = FastAPI(title=f"AIAUI modules for {self.root.name}")
         for module in modules:
             router = load_api(module, context)
@@ -85,4 +78,3 @@ class ProxyHost:
         if self.thread is not None:
             self.server.should_exit = True
             self.thread.join(timeout=5)
-        self._lock_file.close()

package/runtime/_runtime/registry.py

@@ -19,7 +19,10 @@ class ModuleDescriptor:
         self.id = module_id
         self.directory = directory
         self.api_file = directory / "api.py"
-        self.frontend_entry = directory / "resources" / "dist"
+        client_dist = directory / "client" / "dist"
+        self.frontend_entry = (
+            client_dist if client_dist.is_dir() else directory / "resources" / "dist"
+        )
 
     @property
     def has_backend(self) -> bool:

package/templates/JobDashboard/CUSTOMIZATION.md

@@ -0,0 +1,123 @@
+# JobDashboard customization
+
+This module ships a built-in job-information panel that reads two local
+endpoints and renders one card per job. Every part of a card can be replaced
+without touching the platform code; the host contract
+(`mount(container, context)` / `unmount()`) never changes.
+
+## Data contract (implement these two endpoints, get a working panel)
+
+`GET /jobs` — one entry per job (device + carriers + timeline + recipe):
+
+```json
+{
+  "items": [
+    {
+      "id": "job-001",
+      "name": "ASM3GM-PLUGIN-JOB-001",
+      "lot": "LOT-001",
+      "state": "Executing",
+      "carriers": { "input": [{"code": "CR-01"}], "output": [] },
+      "recipe": "RCP-CU-ETCH-O7",
+      "timeline": [
+        { "label": "Setup", "at": "2026-10-18T08:00:00", "state": "done" },
+        { "label": "Select", "at": "2026-10-18T08:01:05", "state": "done" },
+        { "label": "WaitingForStart", "at": "2026-10-18T08:02:30", "state": "active" },
+        { "label": "Executing", "at": "2026-10-18T08:05:12", "state": "pending" },
+        { "label": "Complete", "at": null, "state": "pending" }
+      ]
+    }
+  ],
+  "total": 1,
+  "page": 1,
+  "pageSize": 10
+}
+```
+
+- `{ id, name }` is the minimum; `lot/state/carriers/timeline/recipe` are all
+  optional and degrade to `—` / `No progress data`.
+- Durations between completed steps are computed on the frontend.
+- If `GET /jobs` fails, the module falls back to a built-in demo set.
+
+`GET /config` — the appearance contract:
+
+```json
+{
+  "display": {
+    "lotId": true,
+    "recipe": true,
+    "inputCarriers": true,
+    "outputCarriers": true,
+    "timeline": true
+  },
+  "states": [
+    { "name": "Executing", "color": "#1d4ed8", "icon": "activity" },
+    { "name": "Setup", "color": "#0369a1", "icon": "clock" },
+    { "name": "Complete", "color": "#166534", "icon": "flag" }
+  ]
+}
+```
+
+- Missing keys fall back to the built-in `config-defaults.ts` (all parts
+  visible, a sensible default state palette). Fields are merged shallowly, so
+  a backend may send only the fragments it wants to change.
+- The palette drives the status chip and the timeline step icons
+  (`clock / list / stop / activity / flag`). Unknown icons fall back to
+  `clock`.
+
+## Slots (what you can replace)
+
+Edit `client/src/customization.ts`. Keys per card:
+
+| Slot | Replaces | Renders inside |
+| --- | --- | --- |
+| `board` | the entire job card | (replaces header + middle + bottom) |
+| `headerRegion` | the job-name / lot-id / state row | each card |
+| `jobName` | job name (italic + leading dot) | `headerRegion` |
+| `lotId` | `Lot ID  <value>` | `headerRegion` |
+| `status` | the state chip | `headerRegion` |
+| `middleRegion` | the input-carrier / timeline / output-carrier row | each card |
+| `inputCarriers` | the input-cards list | `middleRegion` |
+| `timeline` | the Setup → … → Complete stepper | `middleRegion` |
+| `outputCarriers` | the output-cards list | `middleRegion` |
+| `bottomRegion` | the recipe sub-card + footer | each card |
+| `recipe` | the `Recipe` + name line | `bottomRegion` |
+
+Every slot component receives `{ context, job, config }` as props; leaf
+slots ignore the region around them (which stays platform-owned). Replacing
+`board` (or any `*Region`) replaces the whole region — including its
+sub-slots if set.
+
+```ts
+// client/src/customization.ts
+import MyJobName from "./custom/MyJobName.vue";
+import type { Customization } from "./contract";
+
+export const customization: Customization = {
+  slots: { jobName: MyJobName },
+};
+```
+
+Slot contract:
+
+```vue
+<script setup lang="ts">
+import type { ModuleSlotProps } from "../contract";
+
+defineProps<ModuleSlotProps>();
+</script>
+<template>
+  <span class="my-custom">— {{ job.state }} · {{ job.name }} —</span>
+</template>
+```
+
+## Rebuild
+
+```bash
+cd resources
+npm install
+npm run build
+```
+
+For quick iteration, `npm run dev` runs `vite build --watch` and keeps
+`dist/manifest.json` valid on every rebuild.

package/templates/{JobInformation → JobDashboard}/README.md

@@ -1,4 +1,4 @@
-# JobInformation module
+# JobDashboard module
 
 This template scaffolds an editable "job information" UI module. The
 generator only produces scaffolding plus an inlined runtime
@@ -19,7 +19,7 @@ def create_api(context) -> APIRouter:
 ```
 
 The generated host calls `create_api(context)` once and mounts the returned
-router at `/modules/JobInformation`. You receive:
+router at `/modules/JobDashboard`. You receive:
 
 - `context.instance_root` — the Instance root directory.
 - `context.services` — a dict of the live objects your Instance passes in at
@@ -28,25 +28,38 @@ router at `/modules/JobInformation`. You receive:
 
 Everything else about how to fetch or present data is yours to implement.
 
+## 前端契约（默认面板与数据）
+
+默认面板消费模块自带两个接口：`GET /jobs`（返回每张卡片的数据，任选可选
+字段，最少 `{id, name}`）和 `GET /config`（面板显示开关 + 状态颜色/图标；缺
+失字段回退内置 `config-defaults.ts`，后端失败则显示 demo 数据）。实现这两个
+接口 + `AIAUI.start()` 即可，无需改前端文件。
+
 ## Frontend
 
+
 The frontend is organized around a small customization contract:
 
-- `resources/src/index.ts` — the stable `mount` / `unmount` bridge the host loads.
-- `resources/src/contract.ts` — the shared types for the module context, bus, and customization.
-- `resources/src/customization.ts` — the only file you normally edit to customize.
-- `resources/src/bus.ts` — a per-mount communication bus shared by all slot components.
-- `resources/src/defaults/` — the built-in panel and its replaceable boxes.
+- `client/src/index.ts` — the stable `mount` / `unmount` bridge the host loads.
+- `client/src/contract.ts` — the shared types for the module context, bus, and customization.
+- `client/src/customization.ts` — the only file you normally edit to customize.
+- `client/src/bus.ts` — a per-mount communication bus shared by all slot components.
+- `client/src/defaults/` — the built-in panel and its replaceable boxes.
 
 Slot components also communicate through `context.bus` (events or imperative handles); see CUSTOMIZATION.md for the patterns.
 
+Slot components receive `{ context, job }`; the default layout only
+allows replacing individual regions (`header`, `inputCarriers`,
+`outputCarriers`, `timeline`, `bottom` [nested `recipe`]). Use `full` to
+replace the whole board.
+
 Three levels are supported without changing `index.ts`:
 
 1. **Default** — do nothing; the built-in panel renders.
 2. **Partial** — replace one or more named boxes:
 
    ```ts
-   // resources/src/customization.ts
+   // client/src/customization.ts
    import MyHeader from "./custom/MyHeader.vue";
    import type { Customization } from "./contract";
 
@@ -97,7 +110,7 @@ aiaui = AIAUI.start(services={
 aiaui.stop()
 ```
 
-`start()` returns `None` when `JobInformation` is disabled in
+`start()` returns `None` when `JobDashboard` is disabled in
 `Config/AIAUIProtocol.json`; otherwise it returns the running host.
 
 ## Dependencies (reminder, not installed automatically)

package/templates/JobDashboard/backend/api.py

@@ -0,0 +1,144 @@
+"""Editable JobDashboard example, mounted under /modules/JobDashboard."""
+
+import inspect
+
+import json
+from pathlib import Path
+
+from fastapi import APIRouter
+
+CONFIG_PATH = Path(__file__).resolve().parent / "config.json"
+
+DEFAULT_CONFIG = {
+    "display": {
+        "lotId": true,
+        "recipe": true,
+        "inputCarriers": true,
+        "outputCarriers": true,
+        "timeline": true
+    },
+    "states": [
+        {
+            "name": "Setup",
+            "color": "#0369a1",
+            "icon": "clock"
+        },
+        {
+            "name": "Select",
+            "color": "#526176",
+            "icon": "list"
+        },
+        {
+            "name": "WaitingForStart",
+            "color": "#8b95a5",
+            "icon": "stop"
+        },
+        {
+            "name": "Executing",
+            "color": "#1d4ed8",
+            "icon": "activity"
+        },
+        {
+            "name": "Running",
+            "color": "#1d4ed8",
+            "icon": "activity"
+        },
+        {
+            "name": "Complete",
+            "color": "#166534",
+            "icon": "flag"
+        },
+        {
+            "name": "Finished",
+            "color": "#166534",
+            "icon": "flag"
+        }
+    ]
+
+}
+
+
+def default_config() -> dict:
+    """Merge ``config.json`` over the shipped default palette."""
+    try:
+        raw = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    except OSError:
+        return DEFAULT_CONFIG
+    if not isinstance(raw, dict):
+        return DEFAULT_CONFIG
+    return {**DEFAULT_CONFIG, **raw}
+
+
+def create_api(context) -> APIRouter:
+    """Entry point invoked by the generated PyAIAUI host.
+
+    The Instance injects its live objects via ``PyAIAUI.AIAUI.start(services={...})``
+    and they arrive here through ``context.services``.
+    """
+    router = APIRouter()
+
+    @router.get("/jobs")
+    async def jobs(name: str = "", page: int = 1, pageSize: int = 20):
+        """Job list for the default panel.
+
+        Each item renders one job card:
+        ``{ name, lot, state, carriers.input[]/output[], timeline[], recipe }``.
+        ``state`` drives the chip colour from ``GET /config``'s state list;
+        durations between timeline steps are computed by the frontend.
+        """
+        repository = context.services.get("job_repository")
+        if repository is not None:
+            result = repository.list_jobs(name=name, page=page, page_size=pageSize)
+            return await result if inspect.isawaitable(result) else result
+
+        # Fixed demo data; replace when a real repository is injected.
+        items = [
+            {
+                "id": "job-001",
+                "name": "ASM3GM-PLUGIN-JOB-001",
+                "lot": "LOT-001",
+                "state": "Executing",
+                "carriers": {"input": [{"code": "CR-01"}, {"code": "CR-02"}], "output": []},
+                "recipe": "RCP-CU-ETCH-O7",
+                "timeline": [
+                    {"label": "Setup", "at": "2026-10-18T08:00:00", "state": "done"},
+                    {"label": "Select", "at": "2026-10-18T08:01:05", "state": "done"},
+                    {"label": "WaitingForStart", "at": "2026-10-18T08:02:30", "state": "active"},
+                    {"label": "Executing", "at": "2026-10-18T08:05:12", "state": "pending"},
+                    {"label": "Complete", "at": None, "state": "pending"},
+                ],
+            },
+            {
+                "id": "job-002",
+                "name": "ASM3GM-PLUGIN-JOB-002",
+                "lot": None,
+                "state": "Setup",
+                "carriers": {"input": [], "output": []},
+                "recipe": "RCP-CU-ETCH-O7",
+                "timeline": [
+                    {"label": "Setup", "at": "2026-10-18T08:00:00", "state": "active"},
+                    {"label": "Select", "at": None, "state": "pending"},
+                    {"label": "WaitingForStart", "at": None, "state": "pending"},
+                    {"label": "Executing", "at": None, "state": "pending"},
+                    {"label": "Complete", "at": None, "state": "pending"},
+                ],
+            },
+        ]
+        matched = [item for item in items if name.casefold() in item["name"].casefold()]
+        start = (page - 1) * pageSize
+        return {
+            "items": matched[start : start + pageSize],
+            "total": len(matched),
+            "page": page,
+            "pageSize": pageSize,
+        }
+
+    @router.get("/config")
+    async def config():
+        """Panel appearance contract, read from ``config.json`` (sitting next
+        to this file). Any missing key is merged over the built-in default
+        palette; unreadable/malformed content falls back to the default.
+        """
+        return default_config()
+
+    return router

package/templates/JobDashboard/backend/config.json

@@ -0,0 +1,46 @@
+{
+  "display": {
+    "lotId": true,
+    "recipe": true,
+    "inputCarriers": true,
+    "outputCarriers": true,
+    "timeline": true
+  },
+  "states": [
+    {
+      "name": "Setup",
+      "color": "#0369a1",
+      "icon": "clock"
+    },
+    {
+      "name": "Select",
+      "color": "#526176",
+      "icon": "list"
+    },
+    {
+      "name": "WaitingForStart",
+      "color": "#8b95a5",
+      "icon": "stop"
+    },
+    {
+      "name": "Executing",
+      "color": "#1d4ed8",
+      "icon": "activity"
+    },
+    {
+      "name": "Running",
+      "color": "#1d4ed8",
+      "icon": "activity"
+    },
+    {
+      "name": "Complete",
+      "color": "#166534",
+      "icon": "flag"
+    },
+    {
+      "name": "Finished",
+      "color": "#166534",
+      "icon": "flag"
+    }
+  ]
+}