@starci/hfs 4.9.3 → 4.9.5

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 4.9.5 - 2026-10-28
+
+- Added: the bundled rule catalog carries R324 (`FE_PAGE_TABS_OUTSIDE_HEADER`, `page-tabs-in-header`) and R325 (`FE_ROUTE_PAGE_OUTSIDE_PAGE`, `route-page-is-one-page`), both enforced by `@starci/eslint-grammar-core`, and their failure-code guidance.
+- Changed: the bundled canon pins follow release G (Grammar family 0.15.4, hfs 4.9.5, canon-fe 9.4.4, canon-be 3.6.4, ai-router 0.3.0); the mermaid pin names Grammar's MermaidDiagram as its owner.
+
+## 4.9.4 - 2026-10-28
+
+- Added: the bundled rule catalog carries R323 (`FE_PAGE_HEADER_HAND_ROLLED`, enforced by `@starci/eslint-grammar-core` `no-hand-rolled-page-header`) and its failure-code guidance.
+- Changed: the bundled canon pins follow release F (Grammar family 0.15.3, hfs 4.9.4, canon-fe 9.4.3, canon-be 3.6.3, ai-router 0.3.0).
+
 ## 4.9.3 - 2026-10-28
 
 - Changed: the bundled canon pins no longer pin the command line. An app's `starci-harness` is judged and scaffolded at the version of the CLI that runs this package: `main(argv, { harness: { version } })` takes it, and `runtime/scripts/hfs/canon-pins.mjs` (`canonPins`, the one reader of `knowledge/hfs/canon-pins.yaml`) adds the `starci-harness` row from it for HFS_CANON_PIN_DRIFT, HFS_CI_MISSING_CANON and the scaffold's root devDependencies. The CLI depends on this package exactly, so a bundled pin of the CLI tied every CLI release to a new hfs and back. Run without a CLI, nothing judges the app's `starci-harness` and `scaffoldApp` refuses HFS_SCAFFOLD_PIN_MISSING before `git init`. Spec: `src/canon-pins.spec.mjs` (also: every `source:` pin at its folder's version, the five runtime copies byte-identical, `contexts/stack/pins.yaml` in step).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.9.3",
+  "version": "4.9.5",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,35 +31,35 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.15.2
+    version: 0.15.4
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.6.2
+    version: 3.6.4
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.4.2
+    version: 9.4.4
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.15.2
+    version: 0.15.4
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.15.2
+    version: 0.15.4
     group: starci
     install: registry
     side: fe
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 4.9.3
+    version: 4.9.5
     group: starci
     install: registry
     side: both
@@ -487,7 +487,7 @@ pins:
     version: 11.16.0
     group: ui
     side: fe
-    why: 'diagrams (fe-stack diagrams); version read from the starci-academy package-lock on 2026-10-13.'
+    why: 'runtime dependency of @starci/grammar for MermaidDiagram (fe-stack diagrams), imported lazily on the first diagram and themed from the grammar root; apps render diagrams through MermaidDiagram and never import mermaid.'
   'react-dropzone':
     version: 15.0.0
     group: ui

package/runtime/knowledge/hfs/rules.yaml

@@ -5687,3 +5687,72 @@ rules:
         source: owner
         quote: "A chip label starts uppercase."
         ruling: "The label of a status chip starts with an uppercase letter (owner ruling chip-label-uppercase); StatusDot capitalises a text label it renders, and the lint refuses a lowercase literal label at its source."
+  - id: R323
+    code: "FE_PAGE_HEADER_HAND_ROLLED"
+    law: "A page is headed by Grammar's PageHeader; a Breadcrumbs trail followed by a SectionHeader in one parent is a page head composed by hand, with no band, no top inset and no separator."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_PAGE_HEADER_HAND_ROLLED"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: no-hand-rolled-page-header}
+    editions: [lite, full]
+    docs: [knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP]
+    templateNa: "A template states no page head; the pages are the app's."
+    proves:
+      - packages/eslint-grammar-core/src/page-header.spec.ts
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/page-header.spec.ts, editions: [lite, full], codes: [FE_PAGE_HEADER_HAND_ROLLED]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/page-header.spec.ts, editions: [lite, full], codes: [FE_PAGE_HEADER_HAND_ROLLED]}
+    cases:
+      - id: case-1
+        date: "2026-10-28"
+        source: owner
+        quote: "Publish Grammar 0.15.3 with PageHeader now, then move all 18 pages to it before deploying. (translated from Vietnamese)"
+        ruling: "A page is headed by Grammar's PageHeader (owner ruling page-header-band): a surface band whose content shares the page content's edges and which ends in its own full-width separator, page tabs standing on it; the lint refuses a page head composed by hand from Breadcrumbs and SectionHeader."
+  - id: R324
+    code: "FE_PAGE_TABS_OUTSIDE_HEADER"
+    law: "Page tabs are the header's tabs; a Tabs that is the first element of a Page body or the next element after a PageHeader is a page tab bar drawn outside the band."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_PAGE_TABS_OUTSIDE_HEADER"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: page-tabs-in-header}
+    editions: [lite, full]
+    docs: [knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP]
+    templateNa: "A template states no page; the pages are the app's."
+    proves:
+      - packages/eslint-grammar-core/src/page.spec.ts
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/page.spec.ts, editions: [lite, full], codes: [FE_PAGE_TABS_OUTSIDE_HEADER]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/page.spec.ts, editions: [lite, full], codes: [FE_PAGE_TABS_OUTSIDE_HEADER]}
+    cases:
+      - id: case-1
+        date: "2026-10-28"
+        source: owner
+        quote: "ok trò"
+        ruling: "A route page is one Grammar Page (owner ruling page-frame); page tabs are its header's tabs, and the lint refuses a Tabs at the top of the Page body or right after a PageHeader."
+  - id: R325
+    code: "FE_ROUTE_PAGE_OUTSIDE_PAGE"
+    law: "A page owner draws one Grammar Page with nothing beside it; a sibling of the Page, or a bare PageHeader or PageContainer in the page owner, re-decides the inset and rhythm Page owns."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_ROUTE_PAGE_OUTSIDE_PAGE"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: route-page-is-one-page}
+    editions: [lite, full]
+    docs: [knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP]
+    templateNa: "A template states no page; the pages are the app's."
+    proves:
+      - packages/eslint-grammar-core/src/page.spec.ts
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/page.spec.ts, editions: [lite, full], codes: [FE_ROUTE_PAGE_OUTSIDE_PAGE]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/page.spec.ts, editions: [lite, full], codes: [FE_ROUTE_PAGE_OUTSIDE_PAGE]}
+    cases:
+      - id: case-1
+        date: "2026-10-28"
+        source: owner
+        quote: "ok trò"
+        ruling: "A route page is one Grammar Page (owner ruling page-frame): the single owner of the page inset and rhythm; the lint refuses a sibling beside the Page and a bare PageHeader or PageContainer in a page owner."

package/runtime/modules/kernel/failure-codes.yaml

@@ -2714,6 +2714,16 @@ FE_PACKAGE_SHAPE:
   owner: op-retry
   kind: check-finding
 
+FE_PAGE_HEADER_HAND_ROLLED:
+  title: "A page head is composed by hand instead of PageHeader"
+  title_vi: "Phần đầu trang được ghép tay thay vì dùng PageHeader"
+  meaning_vi: "Tại <file>, một Breadcrumbs theo sau là một SectionHeader trong cùng một phần tử cha: phần đầu trang ghép tay không có dải nền, không có khoảng đệm trên và không có đường phân cách, nên mỗi trang tự quyết khoảng cách riêng."
+  causes_vi:
+    - "Đặt Breadcrumbs rồi SectionHeader level={1} ở đầu trang hoặc layout."
+  nextStep_vi: "Dùng PageHeader của Grammar với breadcrumbs, title và các khe cần thiết (description, meta, status, mark, actions, tabs) (quy định page-header-band)."
+  owner: op-retry
+  kind: check-finding
+
 FE_PAGE_METADATA_MISSING:
   title: "Every page exports metadata"
   title_vi: "Trang không khai báo metadata"
@@ -2724,6 +2734,16 @@ FE_PAGE_METADATA_MISSING:
   owner: op-retry
   kind: check-finding
 
+FE_PAGE_TABS_OUTSIDE_HEADER:
+  title: "Page tabs are drawn outside the page header band"
+  title_vi: "Tab của trang nằm ngoài dải đầu trang"
+  meaning_vi: "Tại <file>, một Tabs đứng đầu thân Page hoặc ngay sau PageHeader: thanh tab của trang không đứng trên đường phân cách của dải đầu trang mà lấy khoảng đệm và khoảng cách của thân trang."
+  causes_vi:
+    - "Đặt Tabs làm phần tử đầu tiên trong Page hoặc ngay sau PageHeader."
+  nextStep_vi: "Truyền tab qua header.tabs của Page (hoặc tabs của PageHeader): { label, items, selectedKey, onSelect } (quy định page-frame)."
+  owner: op-retry
+  kind: check-finding
+
 FE_PROPS_MUTABLE:
   title: "Component props can be written"
   title_vi: "Props của component có thể bị ghi"
@@ -2864,6 +2884,17 @@ FE_ROUTE_ONE_PAGE:
   owner: other-op:interface.implement
   kind: check-finding
 
+FE_ROUTE_PAGE_OUTSIDE_PAGE:
+  title: "A page owner draws something outside its Page"
+  title_vi: "Trang vẽ nội dung nằm ngoài Page"
+  meaning_vi: "Tại <file>, page owner vẽ một phần tử bên cạnh Page, hoặc tự dùng PageHeader hay PageContainer: khoảng đệm và nhịp dọc của trang bị quyết định lại ngoài Page."
+  causes_vi:
+    - "Đặt banner, footer hay khối khác cạnh Page trong page owner."
+    - "Ghép PageHeader và PageContainer bằng tay thay vì dùng Page."
+  nextStep_vi: "Vẽ đúng một Page: dải đầu trang là header, mọi thứ khác trong thân, measure là measure của Page (quy định page-frame)."
+  owner: op-retry
+  kind: check-finding
+
 FE_SERVER_ACTION_FORBIDDEN:
   title: "A front-end file carries a `\"use server\"` directive"
   title_vi: "Front end có Server Action (\"use server\")"