feat: use selected Agent Trace brand icon

README.md

@@ -66,6 +66,17 @@ state cleanly. Page unmount and plugin deactivation own their disposers.
 
 ## Development and packaging
 
+The plugin-owned brand artwork is `assets/agent-trace.png` (256 × 256). The
+module exports the public `CordisXPluginBrandIcon` declaration as `icon`; Host
+plugin lists render its inline PNG without a network request. Run
+`npm run icon:generate` after replacing the asset; `npm run check` verifies that
+the generated declaration still matches. The package includes both the source
+PNG and its compiled declaration. Session actions keep their Host semantic icons.
+
+Distribution remains source-based `explicit-local-v1` at the canonical GitHub
+repository; this private package has no npm publication or release-tag workflow.
+The tracked PNG can be referenced by a commit-pinned raw GitHub URL for catalogs.
+
 ```sh
 npm ci
 npm run check

README.zh-Hans.md

@@ -1,5 +1,13 @@
 # CordisX Agent Trace Showcase
 
+插件品牌图为 `assets/agent-trace.png`（256 × 256），通过公开的
+`CordisXPluginBrandIcon` 顶层 `icon` 导出供 Host 插件列表使用，运行时无需请求网络。
+替换图片后运行 `npm run icon:generate`；`npm run check` 会检查生成声明与 PNG
+是否一致。包内同时保留原始 PNG 和编译后的声明，会话操作继续使用 Host 语义图标。
+
+分发方式保持为正式 GitHub 仓库上的 `explicit-local-v1` 源码安装；当前私有包没有 npm
+发布或 release-tag 工作流。商店可引用固定 commit 的原始 PNG URL。
+
 Agent Trace Showcase 是独立、只读的 CordisX 插件仓库。插件只负责 Timeline
 业务投影与正文组合；会话 chrome、路由行为、共享控件、无障碍、权限 UI 与
 native lifecycle authority 均由 Host 负责。

package.json

@@ -8,6 +8,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
+    "assets/agent-trace.png",
     "dist",
     "README.md",
     "README.zh-Hans.md",
@@ -16,11 +17,13 @@
     "legal"
   ],
   "scripts": {
+    "icon:generate": "node scripts/generate-brand-icon.mjs",
+    "icon:check": "node scripts/generate-brand-icon.mjs --check",
     "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "naming:check": "node scripts/check-public-naming.mjs",
-    "check": "npm run naming:check && npm run typecheck && npm run build && npm test && npm run naming:check && npm run pack:check",
+    "check": "npm run icon:check && npm run naming:check && npm run typecheck && npm run build && npm test && npm run naming:check && npm run pack:check",
     "pack:check": "npm pack --dry-run",
     "format": "dprint fmt",
     "format:check": "dprint check",

scripts/generate-brand-icon.mjs

@@ -0,0 +1,19 @@
+import { readFile, writeFile } from 'node:fs/promises'
+
+const asset = new URL('../assets/agent-trace.png', import.meta.url)
+const target = new URL('../src/brand-icon.ts', import.meta.url)
+const data = (await readFile(asset)).toString('base64')
+const source = `// Generated by scripts/generate-brand-icon.mjs from assets/agent-trace.png.\n`
+  + `import type { CordisXPluginBrandIcon } from 'cordisx/contracts'\n\n`
+  + `export const icon = Object.freeze(\n  {\n`
+  + `    mediaType: 'image/png',\n`
+  + `    data:\n      '${data}',\n`
+  + `  } satisfies CordisXPluginBrandIcon,\n)\n`
+
+if (process.argv.includes('--check')) {
+  if (await readFile(target, 'utf8') !== source) {
+    throw new Error('Brand icon is stale; run npm run icon:generate')
+  }
+} else {
+  await writeFile(target, source)
+}

src/index.ts

@@ -20,6 +20,7 @@ import { createTraceReactPage } from './react-view.js'
 import type { TraceShowcaseStore } from './types.js'
 
 export const name = 'agent-trace-showcase'
+export { icon } from './brand-icon.js'
 export const inject = ['i18n', 'pages', 'routes', 'slots', 'sessions']
 
 function text(key: string, fallback: string) {

test/brand-icon.test.ts

@@ -0,0 +1,16 @@
+import { createHash } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { expect, it } from 'vitest'
+import { icon } from '../src/index.js'
+
+it('exports the selected 256px PNG through the public plugin brand declaration', async () => {
+  const source = await readFile(new URL('../assets/agent-trace.png', import.meta.url))
+  expect(icon.mediaType).toBe('image/png')
+  expect(Buffer.from(icon.data, 'base64')).toEqual(source)
+  expect(createHash('sha256').update(source).digest('hex')).toBe(
+    'c5ea34e2d791d9647f3adc49bf1a5c03cb88f12d7ddd400468b02c42292a490b',
+  )
+  expect(source.subarray(0, 8)).toEqual(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+  expect(source.readUInt32BE(16)).toBe(256)
+  expect(source.readUInt32BE(20)).toBe(256)
+})