@fui-org/fui-cli 1.3.2 → 2.1.0

package/skills/fui-skill/references/module-json-anatomy.md

@@ -1,35 +1,31 @@
-# module.json Anatomy — 4 thành phần: data · watch · controls · set
+# module.json Anatomy — data · watch · controls · set
 
-> File này sở hữu: **4 thành phần `module.json` (data/watch/controls/set) — vai trò và cách chúng tương tác, checklist cấu trúc**. Cú pháp action/control chi tiết xem [controls-patterns.md](controls-patterns.md).
+> Owns: **the 4 `module.json` blocks (data/watch/controls/set) — roles, interaction, structure checklist**. Action/control syntax: [controls-patterns.md](controls-patterns.md).
 
-`module.json` mô tả một trang FUI. Nó có đúng **4 khối cấp 1**. File này giải thích *vai trò, cách cấu hình, tác động* và *tương tác* giữa chúng, rồi trỏ tới file chuyên sâu cho từng loại pattern.
-
-> Cơ chế nền tảng (runtime đọc module.json thế nào): [platform-architecture.md](platform-architecture.md). Pattern UI thực tế (ưu tiên cao, đã tinh chỉnh qua thực chiến): [ui-patterns.md](ui-patterns.md).
+`module.json` describes one FUI page with exactly **4 top-level blocks**. Runtime internals: [platform-architecture.md](platform-architecture.md). Battle-tested UI patterns (high priority): [ui-patterns.md](ui-patterns.md).
 
 ```json
 {
-  "data":     [ /* state + action */ ],
-  "watch":    { /* observer → action */ },
-  "controls": [ /* layout UI: container > rows > cols */ ],
-  "set":      { /* override config trang (tùy chọn) */ }
+  "data": [/* state + action */],
+  "watch": {/* observer → action */},
+  "controls": [/* layout UI: container > rows > cols */],
+  "set": {/* override config trang (tùy chọn) */}
 }
 ```
 
-Runtime chạy: `runAction(data)` → `buildModuleUI(controls)` → gắn `watch` → merge `set` vào config trang. Tất cả state sống trong `vueData`.
+Runtime order: `runAction(data)` → `buildModuleUI(controls)` → attach `watch` → merge `set` into page config. All state lives in `vueData`.
 
 ---
 
-## 1. `data` — Mảng khởi tạo state + định nghĩa Action
-
-**Là gì:** một **mảng**. FUI xử lý tuần tự từ trên xuống khi trang load.
+## 1. `data` — state init + action definitions
 
-**Ba loại phần tử trong `data[]`:**
+An **array**, processed top to bottom on page load. Three element kinds:
 
-| Loại object | Nhận biết | Tác động |
-|---|---|---|
-| Khởi tạo state | Không có key action (`API`/`CALL`/`IF`...) | Tạo biến reactive trong `vueData` |
-| Named action | Key là tên hàm, value là object action | Định nghĩa action tái sử dụng (gọi qua `CALL`) |
-| Auto-startup | `{ "API": ... }` hoặc `{ "CALL": ... }` đứng riêng | **Tự chạy** ngay khi load |
+| Object kind  | Recognized by                                    | Effect                              |
+| ------------ | ------------------------------------------------ | ----------------------------------- |
+| State init   | No action key (`API`/`CALL`/`IF`...)             | Creates reactive var in `vueData`   |
+| Named action | Key = function name, value = action object       | Reusable action (invoke via `CALL`) |
+| Auto-startup | Standalone `{ "API": ... }` or `{ "CALL": ... }` | **Runs immediately** on load        |
 
 ```json
 "data": [
@@ -41,15 +37,15 @@ Runtime chạy: `runAction(data)` → `buildModuleUI(controls)` → gắn `watch
 ]
 ```
 
-**Tác động:** mọi biến khai báo ở đây thành reactive state; action đặt tên ở đây gọi được từ `watch`, `controls`, hay action khác. Auto-startup ở cuối = dữ liệu ban đầu của trang.
+Named actions are callable from `watch`, `controls` or other actions; trailing auto-startup = initial page data.
 
-**Chi tiết:** khai báo `data[]` + value resolution (chuỗi/biến/backtick/`{{ }}`/deep key, action tự chạy, named action, `v_old`) → **[module-data-patterns.md](module-data-patterns.md)**; engine action → [controls-patterns.md](controls-patterns.md); tổ chức data thực tế → [ui-patterns.md](ui-patterns.md) §1–2.
+Details: `data[]` declaration + value resolution (string/var/backtick/`{{ }}`/deep key, auto-run, named action, `v_old`) → **[module-data-patterns.md](module-data-patterns.md)**; action engine → [controls-patterns.md](controls-patterns.md); real-world data layout → [ui-patterns.md](ui-patterns.md) §1–2.
 
 ---
 
-## 2. `watch` — Observer: state đổi → chạy action
+## 2. `watch` — state change → run action
 
-**Là gì:** một **object** `{ "tênBiến": action }`. Khi biến đổi giá trị, action chạy.
+An **object** `{ "varName": action }`; action runs when the var changes.
 
 ```json
 "watch": {
@@ -59,18 +55,17 @@ Runtime chạy: `runAction(data)` → `buildModuleUI(controls)` → gắn `watch
 }
 ```
 
-**Tác động & mẫu dùng:**
-- **Cascading filter**: mỗi dropdown lọc có một watch → tự reload bảng khi đổi.
-- Nhiều action cho một biến → dùng **mảng**.
-- **`deep-watch`**: theo dõi thay đổi sâu bên trong object/array (runtime hỗ trợ key `deep-watch`).
+- **Cascading filter**: one watch per filter dropdown → table reloads on change.
+- Multiple actions for one var → use an **array**.
+- **`deep-watch`**: tracks nested changes inside object/array (runtime supports the `deep-watch` key).
 
-**Chi tiết:** [watcher-patterns.md](watcher-patterns.md) (v_old, deep-watch, cascading), [ui-patterns.md](ui-patterns.md) §3.
+Details: [watcher-patterns.md](watcher-patterns.md) (v_old, deep-watch, cascading), [ui-patterns.md](ui-patterns.md) §3.
 
 ---
 
-## 3. `controls` — Layout UI (bắt buộc grid container > rows > cols)
+## 3. `controls` — UI layout (mandatory grid container > rows > cols)
 
-**Là gì:** một **mảng** container. Runtime dựng: `container (v-container)` → `rows (v-layout)` → `cols` → mỗi phần tử là một **Control Object**.
+An **array** of containers. Runtime builds `container (v-container)` → `rows (v-layout)` → `cols` → each item is a **Control Object**.
 
 ```json
 "controls": [
@@ -83,25 +78,25 @@ Runtime chạy: `runAction(data)` → `buildModuleUI(controls)` → gắn `watch
 ]
 ```
 
-**Control Object** — các key chính:
+Control Object keys:
 
-| Key | Vai trò |
-|---|---|
-| `el` | Tag/component: `div`, `v-*` (Vuetify), `f-*`/`t-*` (FUI), `uc-*` (custom) |
-| `attr` | Thuộc tính/directive (`class`, `style`, `v-model`, `v-on:click`) — **dùng `v-on:click`, KHÔNG `@click`** |
-| `w` | Bề rộng cột: `1–12` (grid) hoặc `>= 25` (px, **bắt buộc kèm `col: { "class": "shrink" }`**). Không dùng 13–24. Bắt buộc cho item trong `cols` |
-| `col` | Cấu hình cột grid bao ngoài (`class`, `style`, `v-if`) |
-| `innerHTML` | Nội dung: string (hỗ trợ `{{ }}`) hoặc mảng Control Object lồng nhau |
+| Key         | Role                                                                                                                                   |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `el`        | Tag/component: `div`, `v-*` (Vuetify), `f-*`/`t-*` (FUI), `uc-*` (custom)                                                              |
+| `attr`      | Attributes/directives (`class`, `style`, `v-model`, `v-on:click`) — **use `v-on:click`, NOT `@click`**                                 |
+| `w`         | Column width: `1–12` (grid) or `>= 25` (px, **requires `col: { "class": "shrink" }`**). Never 13–24. Required for every item in `cols` |
+| `col`       | Wrapping grid column config (`class`, `style`, `v-if`)                                                                                 |
+| `innerHTML` | Content: string (supports `{{ }}`) or array of nested Control Objects                                                                  |
 
-**Tác động:** đây là toàn bộ giao diện trang. Quy tắc bắt buộc: luôn bắt đầu bằng grid wrapper; dùng `innerHTML` (mảng) để lồng, không dùng `children`; dialog đặt trong container `prop: "hidden-container"`.
+Mandatory: always start with the grid wrapper; nest via `innerHTML` (array), never `children`; put dialogs in a container with `prop: "hidden-container"`.
 
-**Chi tiết:** cấu trúc & grid → [controls-patterns.md](controls-patterns.md) §6; **class/prop/style được dùng (đừng tự thêm style)** → [controls-styling-vocabulary.md](controls-styling-vocabulary.md); chọn component → [component-quickref.md](component-quickref.md); pattern layout/table/dialog → [ui-patterns.md](ui-patterns.md), [ui-table-cell-patterns.md](ui-table-cell-patterns.md), [ui-dialog-patterns.md](ui-dialog-patterns.md), [ui-layout-patterns.md](ui-layout-patterns.md).
+Details: structure & grid → [controls-patterns.md](controls-patterns.md) §6; **allowed class/prop/style (don't invent styles)** → [controls-styling-vocabulary.md](controls-styling-vocabulary.md); picking components → [component-quickref.md](component-quickref.md); layout/table/dialog patterns → [ui-patterns.md](ui-patterns.md), [ui-table-cell-patterns.md](ui-table-cell-patterns.md), [ui-dialog-patterns.md](ui-dialog-patterns.md), [ui-layout-patterns.md](ui-layout-patterns.md).
 
 ---
 
-## 4. `set` — Override config cho riêng trang (tùy chọn)
+## 4. `set` — per-page config override (optional)
 
-**Là gì:** một **object** override config cấp project cho trang này. Runtime trộn `project.json` rồi `set` (module thắng) — xem [platform-architecture.md](platform-architecture.md) §2.1.
+An **object** overriding project config for this page. Runtime merges `project.json` then `set` (module wins) — see [platform-architecture.md](platform-architecture.md) §2.1.
 
 ```json
 "set": {
@@ -110,13 +105,13 @@ Runtime chạy: `runAction(data)` → `buildModuleUI(controls)` → gắn `watch
 }
 ```
 
-**Tác động:** chỉ khai báo field khác với project. Thường dùng: `title` (tiêu đề trang), `menu: false` (ẩn header — sub-window/landing), `menuLeft` (sidebar riêng), `apiDomain` (đổi backend trang đó). Trang bình thường **không cần `set`** (kế thừa hết project).
+Declare only fields differing from the project. Common: `title`, `menu: false` (hide header — sub-window/landing), `menuLeft` (own sidebar), `apiDomain` (different backend for this page). Normal pages **need no `set`**.
 
-**Chi tiết & danh mục thuộc tính đầy đủ:** [project-config.md](project-config.md).
+Full property list: [project-config.md](project-config.md).
 
 ---
 
-## Tương tác giữa 4 thành phần
+## How the 4 blocks interact
 
 ```
 URL ?param  ──►  vueData[param]         (inject trước khi data chạy)
@@ -126,12 +121,12 @@ watch       ──►  state đổi → chạy action → cập nhật state kh
 set         ──►  quyết định khung trang (title/menu/apiDomain) bao quanh controls
 ```
 
-Vòng lặp điển hình: user thao tác trên `controls` → đổi state → `watch` bắt → gọi `API` action trong `data` → `OUT` cập nhật state → `controls` render lại.
+Typical loop: user acts on `controls` → state changes → `watch` fires → `API` action in `data` → `OUT` updates state → `controls` re-render.
 
-## Checklist khi viết module.json
+## Checklist
 
-1. `data[]`: state trước → named action → `{ "CALL": ... }` auto-startup cuối
-2. `watch`: mọi filter/dropdown đều có watch → reload
-3. `controls`: bắt đầu bằng grid wrapper; `w` cho mọi item; dialog trong `hidden-container`; `v-on:click` không `@click`
-4. `set`: chỉ khai báo khi trang khác project default
-5. Tham chiếu state bằng `vueData.` trong controls/attr; JSON hợp lệ (không trailing comma)
+1. `data[]`: state first → named actions → `{ "CALL": ... }` auto-startup last
+2. `watch`: every filter/dropdown has a watch → reload
+3. `controls`: start with grid wrapper; `w` on every item; dialogs in `hidden-container`; `v-on:click` not `@click`
+4. `set`: only when the page differs from project defaults
+5. Reference state as `vueData.` in controls/attr; valid JSON (no trailing commas)

package/skills/fui-skill/references/module-structure.md

@@ -1,17 +1,12 @@
-# Module Structure (Canonical for Workspace and Chat)
+# Module Structure
 
-> File này sở hữu: **cây thư mục project/module, trách nhiệm từng file, `_moduleInfo.json`/`mTitle`, chế độ `HTMLOnly`, meta tag mặc định**. Quy tắc viết `uc-*.vue` xem [component-design.md](component-design.md); nội dung bên trong `module.json` xem [controls-patterns.md](controls-patterns.md). *(Tier A — luôn nạp cùng `skill_get`.)*
+> Owns: project/module tree, per-file duties, `_moduleInfo.json`/`mTitle`, `HTMLOnly`, default meta tags. `uc-*.vue` rules: [component-design.md](component-design.md); `module.json` content: [controls-patterns.md](controls-patterns.md). _(Tier A — loaded with `fui skill get`.)_
 
-Use this structure when creating, refactoring, or reviewing a FUI module.
+Use when creating, refactoring or reviewing a module. With workspace access it is the real folder layout; in chat, use it to organize the response without assuming files exist.
 
-- In editor or extension contexts with workspace access, apply it as the real local folder structure.
-- In chat or agent-chat contexts, use it to virtualize the same module structure and organize the response, without assuming the files already exist on disk.
+## Local Structure
 
-## Canonical Local Structure
-
-The workspace is organized at two levels: **project** and **module**.
-
-### Project-level (root of a checked-out project)
+### Project-level
 
 ```text
 {projectId}/
@@ -22,20 +17,23 @@ The workspace is organized at two levels: **project** and **module**.
 |-- components/                   # Project-scope Vue components
 |   |-- _components.json          # Component registry
 |   `-- uc-*.vue                  # Project-level custom components
+|-- _db/                          # Local DB workspace (see db-workflow.md)
+|   |-- _connections.json         # v2 registry; key = friendly connectionName/folder
+|   `-- {connectionName}/         # schema.json + stored-procedure .sql files
 |-- modules/                      # All modules in this project
 |   |-- _modules.json             # Module list metadata
 |   `-- {moduleId}/               # One folder per module (see module-level below)
 `-- skills/                       # FUI skill files (auto-copied on checkout)
 ```
 
-### Module-level (inside `modules/{moduleId}/`)
+### Module-level (`modules/{moduleId}/`)
 
 ```text
 {moduleId}/
 |-- _moduleInfo.json              # Required: module metadata + mTitle (page title) + HTMLOnly
 |-- module.json                   # Required: data/watch/controls/set (unused when HTMLOnly=true)
 |-- script.js                     # Recommended: helper logic for FUN/EXE/chart/transform
-|-- style.css                     # Optional: module-wide CSS (published via module_publish_css)
+|-- style.css                     # Optional: module-wide CSS (published via fui module publish css)
 |-- header.html                   # Full <head> content: <link>, <style>, <script> tags
 |-- body.html                     # HTMLOnly=false: supplementary body HTML
 |                                 # HTMLOnly=true: entire page content (custom HTML/Vue app)
@@ -46,215 +44,101 @@ The workspace is organized at two levels: **project** and **module**.
     `-- uc-*.vue                  # Custom components (prefix uc-)
 ```
 
-## Chat-Safe Usage
-
-When working without local workspace access:
-
-1. Present this tree as the canonical module layout, not as a claimed filesystem state.
-2. Return file contents in separate code blocks or clearly labeled sections.
-3. Ask the user to paste `_moduleInfo.json`, `module.json`, `script.js`, or component files when a review or patch depends on existing code.
-4. Scope recommendations to the files actually provided instead of inventing unseen surrounding files.
-
-## Required vs Optional
-
-1. Required (module-level):
-- `_moduleInfo.json`
-- `module.json`
-
-2. Recommended:
-- `script.js`
-- `imports/_imports.json`
-
-3. Optional by use-case:
-- `header.html`
-- `body.html`
-- `style.css`
-- `components/` (with `_components.json` and `uc-*.vue`)
-
-## File Responsibilities
-
-### module.json (core)
-- Keep all runtime config in `data`, `watch`, `controls`, `set`.
-- Keep `controls` under FUI grid wrapper (`container > rows > cols`).
-- Keep business actions in `data` and trigger with `CALL`.
-- **When `HTMLOnly=true`: leave this file empty (`data:[], watch:{}, controls:[], set:{}`). The FUI runtime does not use it.**
-- **JSON content patterns** (data[], watch, controls, actions, dialogs, navigation): see [`examples/module-patterns.json`](../examples/module-patterns.json)
-- **f-table props and header types**: see [`examples/f-table-patterns.json`](../examples/f-table-patterns.json)
-
-### script.js (helper logic)
-- Move complex transforms, chart builders, debounce helpers, parsing logic here.
-- Expose functions for `FUN` actions or template helpers.
-- Avoid large inline `EXE` blocks in `module.json` when reusable function is possible.
-
-### style.css (module-wide CSS)
-- CSS not tied to a single component — shared/global rules for the module.
-- Published via `module_publish_css` (mirrors `script.js`/`module_publish_script`); does not auto-clear on `module_publish_html` if left empty.
-- Component-local CSS belongs in the component's own `<style scoped>` (see [component-design.md](component-design.md)), not here.
-
-### _moduleInfo.json (metadata)
-- Keep `ProjectID`, `ModuleID`, `ModuleName`, `Framework` accurate.
-- Contains `mTitle` (page title). To update the module's page title, edit the `mTitle` field in `_moduleInfo.json`. This value is sent to the server as `title` when publishing via `module_publish_html`.
-- Contains `HTMLOnly` (boolean). **Read this first before deciding how to structure the module.**
-
-### header.html (head content)
-- Contains everything that goes **inside** the `<head>` tag — do NOT include the `<head>` wrapper itself.
-- Can contain: `<link>` CSS imports, `<style>` blocks, `<script>` imports, `<meta>` tags.
-- Do NOT put a `<title>` tag here — page title is managed via `mTitle` in `_moduleInfo.json`.
-- **Default meta tags — already present on every FUI page, do NOT repeat them in header.html:**
-  ```html
-  <meta charset="UTF-8"/>
-  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover"/>
-  ```
-  These defaults affect UI design decisions: `user-scalable=no, maximum-scale=1` means users **cannot pinch-zoom** — fonts/buttons must be readable and tappable at natural size on mobile; `width=device-width, initial-scale=1` makes Vuetify breakpoints behave per real device CSS pixels; `viewport-fit=cover` lets the page extend into the iOS notch/home-indicator area — fullscreen/`HTMLOnly` layouts touching top/bottom edges need `env(safe-area-inset-*)` padding.
-- For `HTMLOnly=false`: typically only CSS (`<link>` and `<style>`). Framework and project-level scripts are injected automatically by the server.
-- For `HTMLOnly=true`: **you must bring your own runtime** — see [HTMLOnly=true: KHÔNG có thư viện nào được nhúng sẵn](#htmlonlytrue-không-có-thư-viện-nào-được-nhúng-sẵn) below before writing a single tag.
-
-### body.html (body content)
-- Contains everything that goes **inside** the `<body>` tag — do NOT include the `<body>` wrapper itself.
-- **When `HTMLOnly=false`**: supplementary HTML rendered alongside the FUI Vue runtime. Usually empty or minimal.
-- **When `HTMLOnly=true`**: the **entire page content**. Can be plain HTML or a fully custom Vue app (own `<div id="app">`, own `<v-app>`, etc.). The FUI default Vue mount point is hidden in this mode.
-- Both `header.html` and `body.html` store only the **inner content** (no wrapper tags). The server strips wrappers automatically on save, and the publish tool does the same preprocessing.
-
-### imports/_imports.json (module imports)
-- Declares module-scope JS/CSS import files.
-- Each entry: `{ name, type, contentType, fileID, scope, sort }`.
-- `sort` — thứ tự load. **Khi thêm import mới: đặt `sort` từ 40 trở lên** (40, 50, 60...). Giá trị nhỏ (1–39) dành cho import hệ thống/framework được load trước — không dùng để tránh xung đột.
-- Only module-scope imports are stored here (project-scope imports are at `{projectId}/imports/_imports.json`).
-
-### components/_components.json
-- Register `uc-*` components.
-- Follow upsert rule:
-  - Before publish: may only have `comName`.
-  - After publish/sync: `comID` is server-managed.
-- Do not handcraft random `comID`.
-
-### components/uc-*.vue
-- Use `uc-` prefix for custom components.
-- Keep component-specific UI complexity here instead of bloating `module.json`.
-- Prefer reusable component contracts: props for input, emits for output, slots for extensibility.
-- Avoid baking page-specific API calls or route logic into the component unless that coupling is intentional and unavoidable.
-- `<style scoped>` blocks are allowed, but `scoped` has no real scoping effect — every selector must be manually prefixed with a unique class matching the component name. See [component-design.md](component-design.md) for the full rule and example.
-- Never use backtick template strings inside the component `<template>`.
-
-### _projectInfo.json (project metadata)
-- Saved at project root on checkout (`{projectId}/_projectInfo.json`).
-- Contains `ProjectID`, `ProjectName`, `GroupName`, `Framework`, `pDomain`, `fetchedAt`.
-- Read-only for module editing — do not modify.
-
-### project.json (project config)
-- Contains a single `data` object — project-level defaults for all modules: `apiDomain`, `login`, `userInfo`, `menu`, `menuLeft`, `menuStyle`, `menuComponent`, `domainSetting`, etc.
-- **Relationship with `module.json` `set`**: runtime merges `project.json data` + `module.json set`, with module values taking priority. A module only needs to declare fields that differ from the project default.
-- See [project-config.md](project-config.md) for full field reference, menu item structure, and `right` permission rules.
-
-## Naming and Prefix Rules
-
-1. Module folder name:
-- Use the same module ID naming used by project conventions.
-
-2. Custom component file:
-- Use `uc-*.vue` kebab-case.
-
-3. Component usage in `module.json`:
-- Use `el: "uc-..."` for custom components.
-- Keep prop binding in `attr` with kebab-case prop names.
+Required: `_moduleInfo.json`, `module.json`. Recommended: `script.js`, `imports/_imports.json`. Optional: `header.html`, `body.html`, `style.css`, `components/`.
 
-## HTMLOnly Mode
+## Chat Without Workspace
 
-`HTMLOnly` is a boolean flag in `_moduleInfo.json`. **Always check this first** before editing a module.
+- Present the tree as canonical layout, not actual disk state; return each file in its own labeled code block.
+- Ask the user to paste `_moduleInfo.json`, `module.json`, `script.js` or components when a review/patch depends on them. Scope advice to provided files; never invent unseen ones.
 
-### HTMLOnly=false (default — FUI Vue module)
+## File Duties
 
-- `module.json` is the core: FUI runtime reads `data`, `watch`, `controls`, `set` and bootstraps a Vue app.
-- `body.html` is supplementary HTML rendered in the body alongside the Vue controls (often empty).
-- `header.html` typically contains CSS only (`<link>`, `<style>`). Framework and project-level scripts are auto-injected by the server.
-- Vue components (`uc-*.vue`) are fully supported.
-- `script.js` exposes helper functions used by `FUN`/`EXE` actions.
+**module.json** — all runtime config in `data`, `watch`, `controls`, `set`; `controls` inside grid wrapper (`container > rows > cols`); business actions in `data`, triggered by `CALL`. Patterns: [`examples/module-patterns.json`](../examples/module-patterns.json); f-table props/header types: [`examples/f-table-patterns.json`](../examples/f-table-patterns.json).
 
-### HTMLOnly=true (custom HTML/Vue page)
+**script.js** — complex transforms, chart builders, debounce, parsing; expose functions for `FUN`/`EXE` and template helpers. Prefer a reusable function over large inline `EXE`.
 
-- `module.json` is **ignored** at runtime — keep it empty (`data:[], watch:{}, controls:[], set:{}`).
-- `body.html` is the **entire page content**. The developer has full control — can write plain HTML or a completely custom Vue app (own `<div id="app">`, own `<v-app>`, own Vue instance).
-- Do NOT attempt to use FUI's `controls`/`data`/`watch` JSON system — it has no effect.
-- Use this mode for: standalone tools, custom editors, pages that need their own runtime or layout that doesn't fit the FUI grid system.
-- **Full-height layout**: nếu trang có `menu` hiển thị (không phải `set.menu: false`), thanh menu chiếm 48px cố định — mọi CSS `height: 100vh` hay `calc(100vh - Npx)` trên container gốc phải cộng thêm 48px vào phần trừ. Xem [project-config.md](project-config.md) §menu.
+**style.css** — module-wide CSS not tied to one component. Publish with `fui module publish css`; an empty file is not auto-cleared by `fui module publish html`. Component-local CSS goes in the component's `<style scoped>`.
 
-#### HTMLOnly=true: KHÔNG có thư viện nào được nhúng sẵn
+**\_moduleInfo.json** — keep `ProjectID`, `ModuleID`, `ModuleName`, `Framework` accurate. `mTitle` is the page title (edit it here; sent as `title` by `fui module publish html`). Read `HTMLOnly` before structuring anything.
+
+**header.html** — inner `<head>` content only (`<link>`, `<style>`, `<script>`, `<meta>`); no wrapper, no `<title>` (use `mTitle`). `HTMLOnly=false`: usually CSS only; server injects framework and project scripts. `HTMLOnly=true`: bring your own runtime — read [HTMLOnly=true: no library is embedded](#htmlonlytrue-no-library-is-embedded) first. These meta tags are on every page — never repeat them:
+
+```html
+<meta charset="UTF-8" />
+<meta
+  name="viewport"
+  content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover"
+/>
+```
 
-Đây là điều hay bị hiểu sai nhất về chế độ này, và hiểu sai thì **không có lỗi nào nổi lên lúc
-viết** — chỉ là trang trắng sau khi deploy.
+- No pinch-zoom → fonts/buttons must be readable and tappable at natural size on mobile.
+- Vuetify breakpoints follow real device CSS pixels.
+- `viewport-fit=cover` → fullscreen/`HTMLOnly` layouts touching top/bottom need `env(safe-area-inset-*)` padding (iOS notch/home indicator).
 
-Với `HTMLOnly=true`, server chỉ phát ra **ba** thứ:
+**body.html** — inner `<body>` content only. `HTMLOnly=false`: supplementary HTML beside the Vue runtime, usually empty. `HTMLOnly=true`: the whole page (plain HTML or own Vue app with own `<div id="app">`/`<v-app>`); FUI's default mount point is hidden. Server and publish command strip `<head>`/`<body>` wrappers.
 
-1. import **của chính module này** (`{moduleId}/imports/_imports.json`),
-2. StyleCSS **cấp module** (`style.css` + `<style>` của `uc-*.vue` cấp module),
-3. bundle `moduledata` (`$moduleUI` + `script.js` + component cấp module).
+**imports/\_imports.json** — module-scope JS/CSS imports; entry `{ name, type, contentType, fileID, scope, sort }`. `sort` = load order: new imports use **>= 40** (40, 50, 60…); 1–39 is reserved for system/framework. Project-scope imports live in `{projectId}/imports/_imports.json`.
 
-Tất cả những thứ sau **KHÔNG** được nhúng — kể cả khi project đang khai chúng:
+**components/\_components.json** — registers `uc-*`. Before publish an entry may hold only `comName`; `comID` is server-managed after publish/sync. Never invent `comID`.
 
-| Không có | Hệ quả nếu bạn cứ giả định là có |
-|---|---|
-| Framework V2/V3 — `vue.global.min.js`, `vuetify*.js/css`, `fastproject*.js`, `component*.js`, `defaultfunction*.js` | `Vue is not defined`, `<v-btn>` không render, `f-*`/`t-*` không tồn tại |
-| jQuery, lodash (`_`), `moment`/`dayjs`, `numeral`, `jquery-confirm` | `$ is not defined`, `_ is not defined` |
-| Roboto, Material Design Icons (`mdi-*`) | chữ sai font, icon thành ô vuông trống |
-| `projectdata` bundle — `$projectData`, `$projectGroupSetting`, component cấp **project** | `apiDomain`/`menu`/`login` đều undefined; `uc-*` cấp project là unknown element |
-| StyleCSS cấp **project**, `projectdefaultstyle.css` | mất toàn bộ class dùng chung của project (kể cả `.shrink`) |
-| `<div id="fastProjectAPP">` | không có mount point sẵn — bạn phải tự dựng gốc trong `body.html` |
+**components/uc-\*.vue** — `uc-` prefix, kebab-case. Hold component UI complexity here, not in `module.json`. Contract: props in, emits out, slots to extend. No page-specific API/route logic unless the coupling is intentional and unavoidable. `scoped` does not really scope: prefix every selector with a unique class matching the component name ([component-design.md](component-design.md)). No backtick template strings in `<template>`.
 
-**Quy tắc:** cần thư viện nào thì tự khai thư viện đó, **cho từng module HTMLOnly một** — khai ở
-cấp project không giúp gì cả. Hai cách, dùng cách nào cũng được:
+**\_projectInfo.json** — written on checkout (`ProjectID`, `ProjectName`, `GroupName`, `Framework`, `pDomain`, `fetchedAt`). Read-only.
+
+**project.json** — one `data` object of project defaults (`apiDomain`, `login`, `userInfo`, `menu`, `menuLeft`, `menuStyle`, `menuComponent`, `domainSetting`, …). Runtime merges it with `module.json` `set`; module wins, so declare only differences. Fields, menu items, `right` rules: [project-config.md](project-config.md).
+
+## Naming
+
+- Module folder: project's module ID convention.
+- Use a component in `module.json` via `el: "uc-..."`, props in `attr` with kebab-case names.
+
+## HTMLOnly Mode
 
-- khai vào `imports/_imports.json` của module (`file_import_new`, `sort >= 40`) — nên dùng, vì
-  nó hiện ra trong `file_import_list` và trong báo cáo `module_simulate({renderUI:true})`;
-- hoặc viết thẳng `<link>`/`<script>` vào `header.html` — tự do hơn, nhưng không tool nào liệt kê
-  được cho bạn.
+Boolean in `_moduleInfo.json`. **Check it first.**
 
-Hệ quả bị bỏ sót thường xuyên: **[script-map.md](script-map.md) không áp dụng ở chế độ này.** File
-đó liệt kê thư viện "đã bundle sẵn, cấm thêm CDN trùng" — điều đó chỉ đúng với `HTMLOnly=false`.
-Ở HTMLOnly, thêm CDN không phải là trùng lặp, mà là **điều kiện để trang chạy**.
+- **false (default)**: runtime reads `module.json` and bootstraps Vue; `uc-*.vue` and `script.js` helpers fully supported.
+- **true**: `module.json` ignored — keep it `data:[], watch:{}, controls:[], set:{}`; FUI `controls`/`data`/`watch` have no effect. `body.html` is the entire page. Use for standalone tools, custom editors, pages needing their own runtime or a non-grid layout.
+- **Full-height**: if the menu shows (not `set.menu: false`) it takes a fixed 48px — subtract 48px more from any root `height: 100vh` / `calc(100vh - Npx)`. See [project-config.md](project-config.md) §menu.
 
-`module_simulate({ renderUI: true })` dựng trang **đúng như production** cho module HTMLOnly (bỏ
-framework, bỏ projectdata, bỏ `#fastProjectAPP`) và in một dòng cảnh báo nói rõ điều đó — nên nếu
-bạn quên khai một thư viện, ảnh render sẽ hỏng y hệt trang thật thay vì đẹp giả tạo.
+#### HTMLOnly=true: no library is embedded
 
-## Practical Patterns
+Most common mistake; it shows **no error while writing**, only a blank page after deploy. The server emits just three things:
 
-### Pattern A: Simple module (no custom component)
+1. this module's imports (`{moduleId}/imports/_imports.json`),
+2. module-level StyleCSS (`style.css` + `<style>` of module-level `uc-*.vue`),
+3. the `moduledata` bundle (`$moduleUI` + `script.js` + module-level components).
 
-Use:
-- `_moduleInfo.json`
-- `module.json`
-- `script.js`
-- `imports/_imports.json`
+Not embedded, even if the project declares them:
 
-Skip `components/` unless needed.
+| Missing                                                                                                             | Symptom                                                      |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Framework V2/V3 — `vue.global.min.js`, `vuetify*.js/css`, `fastproject*.js`, `component*.js`, `defaultfunction*.js` | `Vue is not defined`, `<v-btn>` not rendered, no `f-*`/`t-*` |
+| jQuery, lodash (`_`), `moment`/`dayjs`, `numeral`, `jquery-confirm`                                                 | `$ is not defined`, `_ is not defined`                       |
+| Roboto, Material Design Icons (`mdi-*`)                                                                             | wrong font, icons as empty boxes                             |
+| `projectdata` bundle — `$projectData`, `$projectGroupSetting`, project-level components                             | `apiDomain`/`menu`/`login` undefined; project `uc-*` unknown |
+| Project-level StyleCSS, `projectdefaultstyle.css`                                                                   | shared project classes gone (incl. `.shrink`)                |
+| `<div id="fastProjectAPP">`                                                                                         | no mount point — build your own root in `body.html`          |
 
-### Pattern B: Dashboard/report module (recommended split)
+**Declare every needed library in each HTMLOnly module**; project-level declarations do not help. Either:
 
-Use:
-- `module.json` for filters + action orchestration
-- `script.js` for conversion/chart utilities
-- `components/uc-*.vue` for chart/table dashboard presentation
-- `header.html` for module-scoped and component-scoped CSS
+- `fui import new` into the module's `imports/_imports.json` with `--sort` >= 40 (see `fui import new --help`) — preferred: visible in `fui import list` and the `fui module simulate --render` report; or
+- raw `<link>`/`<script>` in `header.html` — flexible, but no command lists them.
 
-This pattern matches large report modules and keeps `module.json` maintainable.
+**[script-map.md](script-map.md) does not apply here**: its "already bundled, no duplicate CDN" list is for `HTMLOnly=false` only. In HTMLOnly the CDN is required, not a duplicate.
 
-### Pattern C: HTMLOnly custom page
+`fui module simulate --render` renders HTMLOnly modules exactly like production (no framework, projectdata or `#fastProjectAPP`) and warns so; a missing library breaks the screenshot like the real page.
 
-Use:
-- `_moduleInfo.json` (with `HTMLOnly: true`)
-- `module.json` (empty skeleton only)
-- `header.html` for all CSS + JS library imports
-- `body.html` for the entire page — plain HTML or a self-contained Vue app
+## Patterns
 
-Skip `components/` and `script.js` unless the custom app needs them.
+- **A — simple**: `_moduleInfo.json`, `module.json`, `script.js`, `imports/_imports.json`; no `components/` unless needed.
+- **B — dashboard/report (recommended)**: `module.json` filters + action orchestration; `script.js` conversion/chart utils; `components/uc-*.vue` chart/table presentation; `header.html` module/component CSS. Keeps large `module.json` maintainable.
+- **C — HTMLOnly page**: `_moduleInfo.json` (`HTMLOnly: true`), empty `module.json` skeleton, `header.html` all CSS + JS libraries, `body.html` whole page (plain HTML or self-contained Vue app); `components/`/`script.js` only if needed.
 
-## Review Checklist (Structure)
+## Review Checklist
 
-1. Check `HTMLOnly` in `_moduleInfo.json` first — it determines which files matter.
-2. If `HTMLOnly=false`: does `module.json` have valid `data/watch/controls/set`?
-3. If `HTMLOnly=true`: is `module.json` empty? Is all content in `body.html`?
-4. Is heavy logic moved to `script.js` instead of oversized `EXE`?
-5. If custom UI exists, is it moved to `components/uc-*.vue`?
-6. If `components/` exists, does `_components.json` register them correctly?
-7. Are imports declared in `imports/_imports.json`?
-8. Do `header.html` and `body.html` contain only inner content (no `<head>`/`<body>` wrapper tags)?
+1. `HTMLOnly` checked first (decides which files matter).
+2. false: valid `data/watch/controls/set`? true: `module.json` empty, all content in `body.html`?
+3. Heavy logic in `script.js`, not oversized `EXE`?
+4. Custom UI in `components/uc-*.vue`, registered in `_components.json`?
+5. Imports in `imports/_imports.json`?
+6. `header.html`/`body.html` inner content only (no `<head>`/`<body>`)?