Project Structure

The directory structure of a widget project generated by the scaffolder is as follows (the vue-ts template additionally includes vite.config.ts and three .vue files):

my-widget/
├── patab.manifest.json            # 组件清单（固定文件名，工具链唯一配置来源）
├── schema/
│   └── patab.manifest.schema.json # Manifest JSON Schema 副本，供编辑器补全
├── package.json
├── tsconfig.json
├── src/
│   ├── env.d.ts
│   ├── widget.spec.ts             # 基于 Mock 宿主的单元测试示例
│   └── surfaces/
│       ├── widget.html            # 网格图块 surface（必须存在）
│       ├── widget.ts
│       ├── detail.html            # 详情弹层 surface（可选）
│       ├── detail.ts
│       ├── settings.html          # 设置弹层 surface（可选）
│       └── settings.ts
└── assets/
    ├── icon.png                   # 组件图标
    └── screenshots/
        └── preview.png            # 预览截图（可选，最多 5 张）

Key Conventions

patab.manifest.json is the only configuration file read by the toolchain; there is no additional CLI configuration file. For field details, see Manifest Configuration.
Surface source location: When surfaces.<name>.entry in the Manifest is declared as surfaces/<name>.html, the corresponding source must be located at src/surfaces/<name>.html. Each surface is an independent HTML entry, built separately by the project's own Vite configuration.
Asset paths are relative to the project root (e.g. assets/icon.png) and are only allowed under assets/.
package.json scripts: the scaffolder generates the following scripts, of which type-check is force-invoked by pack:

{
  "scripts": {
    "dev": "patab-widget dev",
    "check": "patab-widget check",
    "build": "patab-widget build",
    "pack": "patab-widget pack",
    "type-check": "tsc --noEmit",
    "test": "vitest run"
  }
}

Files Allowed in the Final Package

pack follows a whitelist policy: only files declared in the Manifest may appear in the package — one extra or one missing file causes rejection. Fixed contents:

patab.manifest.json (canonical JSON serialization)
One fully self-contained HTML per surface (JS/CSS/images/fonts all inlined as data URLs; external resources, dynamic import(), HMR client, and source maps are forbidden)
Assets declared in the Manifest: icon, screenshots, variant icons
integrity.json (SHA-256 integrity manifest)
signature.json (only for signed packaging)

Dependency Notes

Dependency	Purpose
`@patab/widget-sdk`	Widget runtime code (dependencies)
`@patab/widget-cli`	Development/validation/packaging toolchain (devDependencies), includes Vite
`vue` + `@vitejs/plugin-vue`	`vue-ts` template only

The vanilla-ts template has no vite.config.ts (zero configuration); the vue-ts template's vite.config.ts only registers the Vue plugin. The CLI only validates the final self-contained HTML, so you may add other Vite plugins as needed.

Key Conventions​

Files Allowed in the Final Package​

Dependency Notes​

Key Conventions

Files Allowed in the Final Package

Dependency Notes