@starci/eslint-canon-fe 8.4.43 → 9.1.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 9.1.0 - 2026-10-26
+- Added: universal CTA-6 button intent laws require `intent`, refuse app `variant`, contain destructive confirms in confirmation dialogs, keep one commit per render path and reserve commit for the view rather than collection items. Run `starci app codemod button-intent` to prepare migration and review its flagged cases.
+
+## 9.0.0 - 2026-10-26
+- Changed: concrete Grammar component, variant, token and vendor rules move to `@starci/eslint-grammar-starci` under the `starci-grammar` namespace. Consumers compose both flat-config factories for their selected family.
+- Added: explicit shared infrastructure exports under `@starci/eslint-canon-fe/lib/*`; family packages reuse these readers without copying them.
+- Kept universal: the R318 surface composition law (`nested-control-variant`, `no-list-panel-padding`, `no-app-surface-paint`) and the R65 `no-app-relative-clock`, now in `size-and-state-budget.mjs`.
+
+### Migrating from 8.x
+- What moved: twenty rules leave this package with their IDs, finding codes and severity unchanged; only the namespace changes from `starci-fe/` to `starci-grammar/`. They are `app-shell-frame`, `no-shell-bottom-tabs`, `navbar-control-size`, `navbar-cluster`, `no-navbar-create`, `no-raw-structural-element`, `no-heading-tag-outside-heading-component`, `status-text-uses-soft-foreground`, `vendor-primitive-has-named-owner`, `no-vendor-icon-outside-icon-leaf`, `heroicons-is-the-glyph-vendor`, `no-off-scale-glyph-size`, `no-icon-size-class`, `destructive-menu-entry-needs-danger-tone`, `no-decorative-icon-in-metric-cell`, `no-inline-svg-outside-brand-mark-leaf`, `no-fractional-step`, `no-hand-rolled-heading`, `no-unresolved-token-class` and `slot-status-through-slotview`. StarCi apps get them from `@starci/eslint-grammar-starci`; Offset Pop apps get the same implementations from `@starci/eslint-grammar-offset-pop`.
+- Select the family explicitly: set `sides.fe.grammar` to `starci` or `offset-pop` in `hfs.json`. No family is inferred.
+- Install the family package at its canon-pins version beside this one (app root `devDependencies`). `starci app check` refuses an app that selects a family and declares canon-fe 9 without that package (`FE_STACK_FAMILY_LINT_MISSING`, R288), so the twenty rules cannot be lost silently.
+- Flat config order: the universal factory first, then the family factory, both with the same HFS view: `export default [...starciFeConfig({ hfs }), ...starciGrammarConfig({ hfs })]` (Offset Pop: `offsetPopGrammarConfig`). `starci app sync` renders this managed `fe/eslint.config.mjs`.
+- Rename any reference to a moved rule from `starci-fe/<rule>` to `starci-grammar/<rule>`; the removed-vocabulary check refuses the old spelling.
+- NIVO moves in v0.3.7.
+
 ## 8.4.43 - 2026-10-26
 - Changed: the bundled canon pins follow back-end canon 3.4.43, hfs 4.7.34 and cli 1.7.34.
 
@@ -12,7 +28,7 @@
 - Fixed: `operations-only-in-swr-hooks` (FE_OP_OUTSIDE_SWR_HOOK) no longer reports named imports that all resolve, through relative re-exports, to a generated `__generated__/input-bounds` module (`INPUT_BOUNDS`, `inputBoundsIssues`): they are contract data, not API operations. Mixed, default and namespace imports of the barrel still report.
 - Added: the stream reader of server-sent events (`fe.transport.stream`, `modules/api/sse/clients/`) is part of the API layer, so it may call `fetch` (FE_TRANSPORT_OWNER); a stream operation (`sse/<area>/stream-<channel>.ts`) must import it.
 - Added: `useSWRSubscription` (`swr/subscription`) is an SWR request hook of the family (FE_SWR_OUTSIDE_FAMILY, FE_OP_OUTSIDE_SWR_HOOK, FE_HOOKS_ARE_HOOKS): a stream operation is consumed only by `hooks/swr/api/sse/subscriptions/useSubscribe<X>Swr.ts`.
-- Added: `nested-control-variant` (`FE_NESTED_VARIANT`) refuses explicit primary fields in Grammar surface subtrees and app-authored `bg-surface` paint. `no-list-panel-padding` (`FE_LIST_PANEL_PADDING`) refuses stacked horizontal wrapper padding around Grammar lists and section captions.
+- Changed: `nested-control-variant` (`FE_NESTED_VARIANT`) refuses static variants on layer-aware fields throughout app code and primary Tabs inside painted Grammar surfaces. R318 owns Grammar composition; `no-app-surface-paint` uses the separate layout-only code `FE_GRAMMAR_LAYOUT_ONLY`. `no-list-panel-padding` (`FE_LIST_PANEL_PADDING`) checks all horizontal padding forms only within the nearest painted surface.
 
 ## 8.4.40 - 2026-10-25
 - Changed: the bundled canon pins select @starci/stylelint-canon 2.0.11, @starci/hfs 4.7.33 and @starci/cli 1.7.33.

package/README.md

@@ -1,91 +1,48 @@
 # @starci/eslint-canon-fe
 
-The StarCi front-end lint canon for Next.js and TypeScript applications. It keeps
-component ownership, accessibility, loading behavior, vendor boundaries, translations, naming,
-and colocated class-name composition consistent without prescribing a custom rendering protocol.
-
-```bash
-npm i -D @starci/eslint-canon-fe eslint-plugin-react-hooks typescript
-```
-
-A repository's `eslint.config.mjs` is the managed one-liner `starci app sync` renders (and `starci app check` compares, R05/R17):
+Universal front-end laws for TypeScript and Next.js applications, classified by
+[FE-RULE-OWNERSHIP](../../../knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP).
+The canon owns composition, data and effect boundaries, translations, accessibility, source
+structure, typed contracts, token discipline and check integrity across Grammar families.
 
 ```js
 import { loadHfs, starciFeConfig } from "@starci/eslint-canon-fe"
-export default starciFeConfig({ hfs: loadHfs(import.meta.url) })
-```
-
-`loadHfs` reads the repository's `hfs.json` and the slot manifest shipped in `runtime/`. The factory returns two
-flat-config blocks and owns everything about the law: which files are linted (from the HFS profile), which rules are on
-(every one, at `error` - nothing is off and nothing is a warning), the React Hooks rules (`eslint-plugin-react-hooks` 7, its
-recommended set lifted to `error`), typed linting, and the inline-directive fence (`noInlineConfig` plus
-`reportUnusedDisableDirectives`). The repository states nothing.
-
-- The **Sonar parity** law (R235): the smells SonarCloud measures that a lint rule can decide, `no-await-in-loop`, `prefer-code-point`, `prefer-string-raw`, `no-nested-conditional`, `no-void-operator`, `no-unused-import`, `prefer-export-from` and `no-unused-prop-types`, plus the typescript-eslint rules `no-deprecated`, `no-base-to-string` and `require-await` the factory turns on (they read types, so the source block is typed). A Next `matcher` string keeps its escapes (the segment config is read statically); `*.spec.ts` and `*.e2e-spec.ts` are outside the scan, so outside these rules.
-- The **fe-stack** law: `fe-stack-import` refuses an import of a library the front-end stack catalog forbids (one canonical library per concern, read from `runtime/knowledge/hfs/fe-stack.yaml`) and `@supabase/*` outside `modules/auth`.
-- The **ignore** block: `node_modules`, `.next`, `dist`, `coverage`, `__generated__` and `.starci/`.
-- The **source** block governs `apps/*/src/**` and `packages/*/src/**` with types (`parserOptions.projectService`) and
-  `settings.starci.hfs`, the slot view path-scoped rules ask (`lib/hfs.mjs` `hfsOf`), never a path pattern.
-
-`recommended`, `why`, `loadHfs`, `linterOptions` and the plugin itself are also
-exported; `why[rule]` is `{ code, vi, fixVi }`, the finding code and the Vietnamese why the harness quotes.
-
-## Rules
-
-The [app-shell](docs/app-shell.md) law holds the fixed `WorkspaceShell` frame, mobile drawer navigation,
-navbar action kinds and order, shared bar control size, and page ownership of create actions. Its
-rules are gathered into the normal FE lint and application gate.
+import { starciGrammarConfig } from "@starci/eslint-grammar-starci"
 
-Each law has a page under [`docs/`](docs) with, for every rule, an invalid and a valid example and
-its Vietnamese why. New in 5.0: [env-owner](docs/env-owner.md), [transport](docs/transport.md),
-[client-boundary](docs/client-boundary.md), [hooks-folder](docs/hooks-folder.md),
-[next-conventions](docs/next-conventions.md), [translation](docs/translation.md) (no literal copy at any
-tier), [brand-values](docs/brand-values.md), [native-controls](docs/native-controls.md),
-[size-and-state-budget](docs/size-and-state-budget.md) and [lint-escape-hatch](docs/lint-escape-hatch.md). New in 5.1: [lists](docs/lists.md), [hygiene](docs/hygiene.md), [formatting](docs/formatting.md) and [type-safety](docs/type-safety.md), plus rules added to next-conventions, client-boundary, native-controls and transport. New in 6.1: `no-vietnamese-in-source` (English-only identifiers, strings, comments and test titles; the i18n fixtures slot `e2e/fixtures/i18n/` is the one exemption). New in 6.0: `effect-subscription-needs-cleanup` (timers, frames, listeners, observers, sockets and subscriptions are released against the same handle), `server-module-marks-server-only` ([client-boundary](docs/client-boundary.md)), `no-data-fetch-in-effect` sees indirect loads, `no-hardcoded-copy` reads templates and sentence values, `no-inline-lint-config` refuses `NOSONAR` and the coverage/formatter switches. Also new in 6.0: [grammar-boundary](docs/grammar-boundary.md) (`no-raw-structural-element`), `one-outcome-union` ([transport](docs/transport.md)), `i18n-stack-in-one-module` ([next-conventions](docs/next-conventions.md)), [size-growth](docs/size-growth.md) (`file-size-growth`: a file over the manifest's line budget is not born large and does not grow; the budget is `ruleParams.fe.fileLines`, read from the manifest copy in `runtime/`).
-
-Older laws cover comments, file layout, icons and vendor ownership, landmarks, loading states,
-naming, props, served locales, component splits, design tokens, type safety, typography, and
-class-name ownership. Reusable class names belong in a colocated `classNames.ts` module and should
-be composed with HeroUI `cn` using one utility token per argument.
-
-The `drawing` law holds the split surfaces (blocks, pages, layouts, overlays under `components/`
-or `features/`): the pure `XBase` takes `{ state, props, on }` of atoms, with named `render`/`renderX`
-callbacks in feature `props` for block composition (`base-props-atom`), only its
-sibling `index.tsx` imports it and never re-exports it (`base-import-pair`), `XState` names drawn
-shapes and never a data status (`no-data-status-shape`), and a block renders each slot's
-loading/forbidden/error/empty through `SlotView` (`slot-status-through-slotview`). The law's name is
-the `drawing` slot role of `component.tsx`; a split-surface reference tree lives under
-`.claude/examples/`.
-
-Page and layout owners in `features/{pages,layouts}/<Name>/index.tsx` may compose overlay and block public entries. A server
-page may import and render a client overlay entry while remaining a server component: `FE_CLIENT_BOUNDARY` accepts the
-overlay entry, and `FE_CLIENT_SERVER_IMPORT` / `FE_CLIENT_REACHES_SERVER` reject server-only imports from its client closure.
-The only feature-to-feature edge is pages or layouts to overlays; layouts never import pages, overlays never import other
-overlays, components never import overlays, and blocks never import another block. For a client list, a server page mounts an overlay whose connected entry reads list
-identities and supplies a block renderer to its pure Base. A pure component or branch may render that keyed list by
-calling the supplied render prop; it imports no block and fetches no data. The supplied renderer composes blocks only,
-with no intrinsic markup or hook calls, and each connected item block still renders its exact sibling `XBase`.
-
-A layout-level overlay host passes rendered overlay candidates into a client `features/overlays/OverlayRouteHost` entry.
-Its hook under `hooks/overlays` reads `usePathname()` and `useSearchParams()` and supplies scalar selection to the pure
-`components/branches/OverlayHost` branch. The layout imports the candidate overlay entries; the host and branch only
-receive rendered nodes. No callback crosses the server-to-client boundary, and pages stay server components. This
-composition-only host renders an existing public pure branch without a forwarding private Base; connected blocks still
-require their exact sibling Base. The worked tree is in
-[`knowledge/patterns/fe/boundaries.yaml`](../../../knowledge/patterns/fe/boundaries.yaml), `FE-BOUNDARY-5`.
-
-The one locale pattern everywhere is `next-intl`, a `[locale]` segment, default `vi`,
-`localePrefix: "as-needed"`, and `proxy.ts` instead of `middleware.ts`.
-
-Grammar is a business-neutral HeroUI-backed component package. Its components accept ordinary
-typed React props and children.
-
-The [surface composition law](docs/surface-rules.md) holds ANATOMY-2 and PADDING-0:
-`nested-control-variant` refuses explicit primary fields inside Grammar surfaces and raw app
-`bg-surface` paint (`FE_NESTED_VARIANT`); `no-list-panel-padding` refuses horizontal padding
-wrappers around Grammar lists and section captions (`FE_LIST_PANEL_PADDING`). Grammar supplies
-the nested secondary default and owns the list's panel inset.
-
-## Requirements
+const hfs = loadHfs(import.meta.url)
+export default [...starciFeConfig({ hfs }), ...starciGrammarConfig({ hfs })]
+```
 
-ESLint 9+ (flat config), `eslint-plugin-react-hooks` 7+, and Node.js 20.9+.
+`starci app sync` renders the selected family's managed flat config. Both factories cover every
+app and workspace package's source. Universal rules, React Hooks rules, type-aware rules and
+Sonar rules run at error; the factory sets typed parsing and refuses inline lint directives.
+Generated wire types, dependencies and build outputs follow the shared source-scope contract.
+
+Concrete Grammar component names, props, variants, scales and vendor recipes belong to
+`@starci/eslint-grammar-starci` or the selected family's package. The family rules keep their
+bare IDs under the `starci-grammar` namespace. This package exports shared AST, binding, type,
+slot and configuration infrastructure through `@starci/eslint-canon-fe/lib/*`; family packages
+import those readers without copying them.
+
+Every universal law remains gathered by `index.mjs`; its recommendation enables every rule.
+The `docs/` directory carries the detailed behavior of the documented laws. `why` supplies
+failure codes and English guidance for the catalogued rules.
+
+`starciPlainSourceConfig({ root })` applies slot-free universal rules to a TypeScript `src/`
+tree. `starciTypedSourceConfig({ root })` provides the shared typed, React Hooks and Sonar
+configuration for source that has not adopted the product composition laws.
+
+The [surface composition law](docs/surface-rules.md) (R318) holds ANATOMY-2 and PADDING-0 for every
+family that publishes the shared HeroUI surface and field API: `nested-control-variant` refuses static
+variants on layer-aware fields and primary Tabs inside painted Grammar surfaces (`FE_NESTED_VARIANT`),
+`no-app-surface-paint` keeps surface paint in Grammar (`FE_GRAMMAR_LAYOUT_ONLY`) and
+`no-list-panel-padding` refuses horizontal padding wrappers around Grammar lists and section captions
+within the nearest painted surface (`FE_LIST_PANEL_PADDING`). The R65 budget law's
+`no-app-relative-clock` leaves live relative time and countdowns to Grammar's shared clock.
+
+The [button intent law](docs/button-intent.md) (CTA-6) requires every app Button and IconButton to
+declare intent and leave variants to Grammar. It contains destructive confirms in their same-file
+dialog, counts mutually exclusive render paths separately and reserves commit for the view's
+decision rather than repeated collection items.
+
+Regression specs belong to this package. Application front ends and Grammar libraries have no specs.

package/brand-values.mjs

@@ -13,7 +13,7 @@
  * breakpoint. Spacing and sizing come from the grammar's utility tokens.
  *
  * WHAT IT DELIBERATELY LEAVES ALONE: a fragment identifier (`href="#top"`, `id`, `htmlFor`), a
- * `data:` URI, a component's `color="primary"` prop (that is a variant name, not a colour), and
+ * `data:` URI, a component's semantic appearance prop (a named role rather than a raw colour), and
  * Tailwind arbitrary values (`w-[12px]`), which `no-arbitrary-value` already reports - two rules
  * for one span would be two findings for one fix.
  */

package/button-intent.mjs

@@ -0,0 +1,320 @@
+/** CTA-6: app buttons declare consequences; Grammar owns their visual variants. */
+import { attributeValue, stringOf, walk } from "./lib/ast.mjs"
+import { functionOf, importOf, isFn, patternPath, unwrap, variableOf } from "./lib/bindings.mjs"
+import { typedPropertyStrings } from "./lib/typed-class-values.mjs"
+import ts from "typescript"
+
+const GRAMMAR_ENTRY = /^@starci\/grammar(?:\/(?:common|core|heritage|offset-pop))?$/
+const BUTTONS = new Set(["Button", "IconButton"])
+const DIALOGS = new Set(["AlertDialog", "ConfirmDialog"])
+const ITEMS = new Set(["CollectionItem", "ItemActions", "ListItem", "ListRow", "ListBox.Item", "GridList.Item", "Table.Row", "TableRow"])
+
+/** The consuming TypeScript program exposes literal intents and spread properties without executing app code. */
+const typedInfo = (context, node, key) => {
+  const services = context.sourceCode.parserServices
+  if (!services?.program || !services.esTreeNodeToTSNodeMap || !node) return null
+  const checker = services.program.getTypeChecker()
+  const source = services.esTreeNodeToTSNodeMap.get(node)
+  const owner = checker.getTypeAtLocation(source)
+  const symbol = key === undefined ? null : owner.getProperty(key)
+  if (key !== undefined && !symbol) return null
+  const type = symbol ? checker.getTypeOfSymbolAtLocation(symbol, source) : owner
+  const members = type.isUnion() ? type.types : [type]
+  return { values: members.filter((member) => member.isStringLiteral()).map((member) => member.value), optional: Boolean(symbol && (symbol.flags & ts.SymbolFlags.Optional) !== 0) }
+}
+
+/** Resolve the imported Grammar role without confusing a shadowed local component with its namesake. */
+const roleOf = (context, name) => {
+  const parts = []
+  let root = name
+  while (root.type === "JSXMemberExpression") {
+    parts.unshift(root.property.name)
+    root = root.object
+  }
+  if (root.type !== "JSXIdentifier") return null
+  const imported = importOf(context, root)
+  if (!imported || !GRAMMAR_ENTRY.test(imported.source)) return null
+  if (imported.imported) parts.unshift(imported.imported)
+  else if (!variableOf(context, root)?.defs.some((definition) => definition.node.type === "ImportNamespaceSpecifier")) return null
+  return parts.join(".")
+}
+
+/** Static object properties, including aliases and spreads, retain their button obligations. */
+const objectProperty = (context, input, key, seen = new Set()) => {
+  const node = unwrap(input)
+  if (!node || seen.has(node)) return []
+  const next = new Set(seen).add(node)
+  if (node.type === "ObjectExpression") return node.properties.flatMap((property) => {
+    if (property.type === "SpreadElement") return objectProperty(context, property.argument, key, next)
+    const name = property.computed ? stringOf(property.key) : property.key.name ?? property.key.value
+    return name === key ? [property.value] : []
+  })
+  if (node.type === "ConditionalExpression") return [node.consequent, node.alternate].flatMap((branch) => objectProperty(context, branch, key, next))
+  if (node.type === "MemberExpression") {
+    const member = node.computed ? stringOf(node.property) : node.property.name
+    return objectProperty(context, node.object, member, next).flatMap((value) => objectProperty(context, value, key, next))
+  }
+  if (node.type !== "Identifier") return []
+  const definition = variableOf(context, node)?.defs.find((entry) => entry.type === "Variable")
+  if (!definition) return []
+  const path = patternPath(definition.node.id, node.name)
+  if (path === null) return []
+  const values = path.reduce((entries, name) => entries.flatMap((entry) => objectProperty(context, entry, name, next)), [definition.node.init])
+  return values.flatMap((value) => objectProperty(context, value, key, next))
+}
+
+/** Possible statically authored values of an intent or step; dynamic values remain TypeScript's responsibility. */
+const valuesOf = (context, input, seen = new Set()) => {
+  const node = unwrap(input)
+  if (!node || seen.has(node)) return []
+  const next = new Set(seen).add(node)
+  const text = stringOf(node)
+  if (text !== null) return [text]
+  if (node.type === "ConditionalExpression") return [node.consequent, node.alternate].flatMap((branch) => valuesOf(context, branch, next))
+  if (node.type === "LogicalExpression") return valuesOf(context, node.right, next)
+  if (node.type === "MemberExpression") {
+    const name = node.computed ? stringOf(node.property) : node.property.name
+    const values = objectProperty(context, node.object, name, next).flatMap((value) => valuesOf(context, value, next))
+    return values.length ? values : typedInfo(context, node)?.values ?? []
+  }
+  if (node.type !== "Identifier") return typedInfo(context, node)?.values ?? []
+  const definition = variableOf(context, node)?.defs.find((entry) => entry.type === "Variable")
+  if (!definition) return typedInfo(context, node)?.values ?? []
+  const path = patternPath(definition.node.id, node.name)
+  if (path === null) return []
+  const values = path.reduce((entries, name) => entries.flatMap((entry) => objectProperty(context, entry, name, next)), [definition.node.init])
+  return values.flatMap((value) => valuesOf(context, value, next))
+}
+
+/** An explicit attribute or statically resolved spread exposing a prop. */
+const propsOf = (context, opening, key) => opening.attributes.flatMap((entry) => {
+  if (entry.type === "JSXAttribute") return entry.name.name === key ? [{ node: entry, value: attributeValue(entry) }] : []
+  const values = objectProperty(context, entry.argument, key)
+  if (values.length) return values.map((value) => ({ node: entry, value }))
+  const authored = typedPropertyStrings(context, entry.argument, key, "variant")
+  if (authored.length) return authored.map((value) => ({ node: entry, text: value.text }))
+  const typed = typedInfo(context, entry.argument, key)
+  return typed ? [{ node: entry, texts: typed.values }] : []
+})
+
+const hasValue = (context, opening, key, value) => propsOf(context, opening, key).some((prop) => prop.text === value || prop.texts?.includes(value) || valuesOf(context, prop.value).includes(value))
+const isButton = (context, opening) => BUTTONS.has(roleOf(context, opening.name))
+
+/** A conditional props spread supplies intent only when every branch supplies it. */
+const suppliesIntent = (context, input, seen = new Set()) => {
+  const node = unwrap(input)
+  if (!node || seen.has(node)) return false
+  const next = new Set(seen).add(node)
+  if (node.type === "ConditionalExpression") return [node.consequent, node.alternate].every((branch) => suppliesIntent(context, branch, next))
+  if (node.type === "Identifier") {
+    const definition = variableOf(context, node)?.defs.find((entry) => entry.type === "Variable")
+    if (definition?.node.id.type === "Identifier") return suppliesIntent(context, definition.node.init, next)
+    const typed = typedInfo(context, node, "intent")
+    return Boolean(typed && !typed.optional)
+  }
+  return objectProperty(context, node, "intent").length > 0 || typedPropertyStrings(context, node, "intent", "variant").length > 0
+}
+
+const hasIntent = (context, opening) => opening.attributes.some((entry) => {
+  if (entry.type === "JSXSpreadAttribute") return suppliesIntent(context, entry.argument)
+  if (entry.name.name !== "intent") return false
+  const value = unwrap(attributeValue(entry))
+  return Boolean(value) && !(value.type === "Literal" && value.value === null) && !(value.type === "Identifier" && value.name === "undefined")
+})
+
+/** JSX child render callbacks contribute content to their enclosing component render. */
+const inlineRenderCallback = (node) => node.parent?.type === "JSXExpressionContainer" && node.parent.parent?.type !== "JSXAttribute"
+
+const lexicalFunction = (node) => {
+  for (let current = node.parent; current; current = current.parent) if (isFn(current)) return current
+  return null
+}
+
+/** The nearest function owns a render; a component defined in a dialog is still its own subtree. */
+const functionOwner = (node) => {
+  for (let current = node.parent; current; current = current.parent) if (isFn(current) && !inlineRenderCallback(current)) return current
+  return null
+}
+
+/** A trigger opens a dialog and is outside its confirmation subtree. */
+const insideDialog = (context, opening) => {
+  const triggers = new Set()
+  for (let current = opening.parent; current; current = current.parent) {
+    if (isFn(current) && !inlineRenderCallback(current)) return false
+    if (current.type === "JSXAttribute" && current.name.name === "trigger") triggers.add(current.parent)
+    if (current.type === "JSXElement" && !triggers.has(current.openingElement) && DIALOGS.has(roleOf(context, current.openingElement.name))) return true
+  }
+  return false
+}
+
+/** Normalize a condition so `ready` and `!ready` select opposite render paths. */
+const guardOf = (context, input, positive) => {
+  const node = unwrap(input)
+  if (node.type === "UnaryExpression" && node.operator === "!") return guardOf(context, node.argument, !positive)
+  if (node.type === "BinaryExpression" && ["===", "==", "!==", "!="].includes(node.operator)) {
+    const literal = node.right.type === "Literal" ? node.right : node.left.type === "Literal" ? node.left : null
+    if (literal) {
+      const selector = context.sourceCode.getText(literal === node.right ? node.left : node.right).replace(/\s+/g, "")
+      const choice = JSON.stringify(literal.value)
+      const value = node.operator.startsWith("!") ? !positive : positive
+      return { key: `${selector}===${choice}`, value, selector, choice }
+    }
+  }
+  return { key: context.sourceCode.getText(node).replace(/\s+/g, ""), value: positive }
+}
+
+const constrainPath = (context, path, test, positive) => {
+  const guard = guardOf(context, test, positive)
+  path.guards.set(guard.key, guard.value)
+  if (guard.selector && guard.value) path.choices.set(guard.selector, guard.choice)
+  return path
+}
+
+/** Conditional intent values retain the guards selecting commit instead of flattening both alternatives. */
+const valuePaths = (context, input, seen = new Set()) => {
+  const node = unwrap(input)
+  if (!node || seen.has(node)) return []
+  const next = new Set(seen).add(node)
+  if (node.type === "ConditionalExpression") return [node.consequent, node.alternate].flatMap((branch, index) => valuePaths(context, branch, next).map((path) => constrainPath(context, path, node.test, index === 0)))
+  if (node.type === "Identifier") {
+    const definition = variableOf(context, node)?.defs.find((entry) => entry.type === "Variable")
+    if (definition?.node.id.type === "Identifier") return valuePaths(context, definition.node.init, next)
+  }
+  return valuesOf(context, node).includes("commit") ? [{ guards: new Map(), choices: new Map() }] : []
+}
+
+/** Branch guards and return ownership identify mutually exclusive render paths. */
+const renderPath = (context, opening, owner) => {
+  const guards = new Map()
+  const choices = new Map()
+  const path = { guards, choices }
+  let returned = null
+  let child = opening
+  for (let current = opening.parent; current && current !== owner; current = current.parent) {
+    if (current.type === "ReturnStatement" && lexicalFunction(current) === owner) returned = current
+    if (current.type === "ConditionalExpression" && child !== current.test) constrainPath(context, path, current.test, child === current.consequent)
+    if (current.type === "IfStatement" && child !== current.test) constrainPath(context, path, current.test, child === current.consequent)
+    if (current.type === "LogicalExpression" && child === current.right && current.operator !== "??") constrainPath(context, path, current.left, current.operator === "&&")
+    child = current
+  }
+  return { guards, choices, returned }
+}
+
+const canCoexist = (left, right) => {
+  if (left.returned && right.returned && left.returned !== right.returned) return false
+  if ([...left.choices].some(([selector, choice]) => right.choices.has(selector) && right.choices.get(selector) !== choice)) return false
+  return [...left.guards].every(([condition, value]) => !right.guards.has(condition) || right.guards.get(condition) === value)
+}
+
+/** No explicit visual prop: any authored variant, including a known props spread, is an app bypass. */
+const buttonNoVariant = {
+  meta: { type: "problem", docs: { description: "CTA-6: app buttons never choose a variant." }, schema: [], messages: {
+    FE_BUTTON_NO_VARIANT: "FE_BUTTON_NO_VARIANT: declare Button intent instead of variant; Grammar resolves the variant from intent and placement.",
+  } },
+  create(context) {
+    return { JSXOpeningElement(opening) {
+      if (!isButton(context, opening)) return
+      for (const node of new Set(propsOf(context, opening, "variant").map((prop) => prop.node))) context.report({ node, messageId: "FE_BUTTON_NO_VARIANT" })
+    } }
+  },
+}
+
+/** Every app button states its command's intent explicitly. */
+const buttonIntentRequired = {
+  meta: { type: "problem", docs: { description: "CTA-6: every app Button and IconButton declares intent." }, schema: [], messages: {
+    FE_BUTTON_INTENT_REQUIRED: "FE_BUTTON_INTENT_REQUIRED: Button and IconButton require intent (commit, alternative, dismiss, neutral or destructive). Choose it from the command's consequence and rank.",
+  } },
+  create(context) {
+    return { JSXOpeningElement(opening) {
+      if (isButton(context, opening) && !hasIntent(context, opening)) context.report({ node: opening, messageId: "FE_BUTTON_INTENT_REQUIRED" })
+    } }
+  },
+}
+
+/** A destructive final press is contained by its same-file confirmation dialog. */
+const destructiveConfirmInDialog = {
+  meta: { type: "problem", docs: { description: "CTA-6: destructive confirm buttons stay inside AlertDialog or ConfirmDialog." }, schema: [], messages: {
+    FE_DESTRUCTIVE_CONFIRM_IN_DIALOG: "FE_DESTRUCTIVE_CONFIRM_IN_DIALOG: a destructive confirm belongs inside the same-file AlertDialog or ConfirmDialog subtree. The trigger uses step=\"entry\".",
+  } },
+  create(context) {
+    return { JSXOpeningElement(opening) {
+      if (!isButton(context, opening) || !hasValue(context, opening, "intent", "destructive") || !hasValue(context, opening, "step", "confirm")) return
+      if (!insideDialog(context, opening)) context.report({ node: opening, messageId: "FE_DESTRUCTIVE_CONFIRM_IN_DIALOG" })
+    } }
+  },
+}
+
+/** A component render exposes one next action, with exclusive branches counted separately. */
+const singleCommitPerRender = {
+  meta: { type: "problem", docs: { description: "CTA-6: at most one commit is visible in a component render." }, schema: [], messages: {
+    FE_SINGLE_COMMIT_PER_RENDER: "FE_SINGLE_COMMIT_PER_RENDER: this render contains another commit action. Keep the one next action as commit and classify its alternatives by consequence.",
+  } },
+  create(context) {
+    const owners = new Map()
+    return { JSXOpeningElement(opening) {
+      if (!isButton(context, opening) || !hasValue(context, opening, "intent", "commit")) return
+      const owner = functionOwner(opening) ?? context.sourceCode.ast
+      const base = renderPath(context, opening, owner)
+      const paths = propsOf(context, opening, "intent").flatMap((prop) => prop.value ? valuePaths(context, prop.value) : prop.text === "commit" || prop.texts?.includes("commit") ? [{ guards: new Map(), choices: new Map() }] : [])
+        .map((path) => ({ returned: base.returned, guards: new Map([...base.guards, ...path.guards]), choices: new Map([...base.choices, ...path.choices]) }))
+      const prior = owners.get(owner) ?? []
+      if (paths.some((path) => prior.some((entry) => canCoexist(entry, path)))) context.report({ node: opening, messageId: "FE_SINGLE_COMMIT_PER_RENDER" })
+      prior.push(...paths)
+      owners.set(owner, prior)
+    } }
+  },
+}
+
+/** A repeated row's next action is alternative; the enclosing view keeps the commit. */
+const noCommitInCollectionItem = {
+  meta: { type: "problem", docs: { description: "CTA-6: collection item renders cannot expose commit actions." }, schema: [], messages: {
+    FE_NO_COMMIT_IN_COLLECTION_ITEM: "FE_NO_COMMIT_IN_COLLECTION_ITEM: collection items cannot use commit. Use alternative for an item's next action and reserve commit for the view's decision.",
+  } },
+  create(context) {
+    const reported = new Set()
+    const report = (opening) => {
+      if (!reported.has(opening) && isButton(context, opening) && hasValue(context, opening, "intent", "commit")) {
+        reported.add(opening)
+        context.report({ node: opening, messageId: "FE_NO_COMMIT_IN_COLLECTION_ITEM" })
+      }
+    }
+    const scanCallback = (callback) => {
+      if (!callback) return
+      walk(context.sourceCode, callback.body, (node) => {
+        if (isFn(node) && !inlineRenderCallback(node)) return false
+        if (node.type === "JSXOpeningElement") report(node)
+        return undefined
+      })
+    }
+    return {
+      JSXAttribute(attribute) {
+        if (attribute.name.name === "renderCell" && roleOf(context, attribute.parent.name) === "DataTable") scanCallback(functionOf(context, attributeValue(attribute)))
+      },
+      JSXOpeningElement(opening) {
+        for (let current = opening.parent; current; current = current.parent) {
+          if (isFn(current) && !inlineRenderCallback(current)) return
+          if (current.type === "JSXElement" && ITEMS.has(roleOf(context, current.openingElement.name))) return report(opening)
+        }
+      },
+      CallExpression(call) {
+        const callee = unwrap(call.callee)
+        if (callee.type !== "MemberExpression") return
+        const name = callee.computed ? stringOf(callee.property) : callee.property.name
+        if (name !== "map") return
+        scanCallback(functionOf(context, call.arguments[0]))
+      },
+    }
+  },
+}
+
+/** Every intent law is universal across Grammar families and app editions. */
+export const rules = {
+  "button-intent-required": buttonIntentRequired,
+  "button-no-variant": buttonNoVariant,
+  "destructive-confirm-in-dialog": destructiveConfirmInDialog,
+  "single-commit-per-render": singleCommitPerRender,
+  "no-commit-in-collection-item": noCommitInCollectionItem,
+}
+
+/** All five laws reach consumers at error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/docs/button-intent.md

@@ -0,0 +1,22 @@
+# Button intent (CTA-6)
+
+Owner: knowledge/ui/composition/cta.yaml
+
+App `Button` and `IconButton` commands declare `intent`. Grammar derives their variant from that intent and its placement context. These laws apply to every Grammar family in both app editions; aliases and namespace imports retain the same obligations.
+
+| Rule | Finding code | Required behavior |
+| --- | --- | --- |
+| `starci-fe/button-intent-required` | `FE_BUTTON_INTENT_REQUIRED` | Pass the command's `intent`. A known props spread may supply it. |
+| `starci-fe/button-no-variant` | `FE_BUTTON_NO_VARIANT` | Omit `variant`, including variants in known props spreads. |
+| `starci-fe/destructive-confirm-in-dialog` | `FE_DESTRUCTIVE_CONFIRM_IN_DIALOG` | Put `intent="destructive" step="confirm"` inside the same-file `AlertDialog` or `ConfirmDialog` content subtree. Its trigger uses `step="entry"`. A separate component's definition does not inherit its caller's JSX ancestry. |
+| `starci-fe/single-commit-per-render` | `FE_SINGLE_COMMIT_PER_RENDER` | Render at most one commit per component path. Different return paths, opposite conditional arms and opposite guards are mutually exclusive. |
+| `starci-fe/no-commit-in-collection-item` | `FE_NO_COMMIT_IN_COLLECTION_ITEM` | Use `alternative` for an item's next action. A `.map` callback or explicit Grammar collection item context cannot expose commit. |
+
+```tsx
+<AlertDialog>
+  <Button intent="dismiss">Cancel</Button>
+  <Button intent="destructive" step="confirm">Delete record</Button>
+</AlertDialog>
+```
+
+`starci app codemod button-intent` defaults to a dry run. Use `--write` to apply deterministic mappings, then resolve every case in its JSON and Markdown report from the command's actual consequence. A destructive-looking label is a review signal rather than authority to choose an intent.

package/docs/hooks-folder.md

@@ -8,7 +8,7 @@ Every rule below is an error in `starciFeConfig`; none can be switched off or su
 
 ## `starci-fe/hooks-folder-holds-hooks-only`
 
-`hooks/` holds `use*.ts` hooks under the names their family slot gives and, per domain, one `<domain>.shared.ts`; nothing else. A hook file exports one hook; `server-only` and `next/headers` are never imported there. A hook is a function that calls a hook: a React, SWR or Redux hook, a `use*` imported from the app's own `hooks/` folders (a `hooks/swr` wrapper or a sibling domain hook, resolved by TypeScript symbol resolution through barrels; that hook's own file is judged when it is linted), or a library hook from an explicit list (`next-intl` `useTranslations`/`useLocale`/`useFormatter`/`useNow`/`useTimeZone`/`useMessages`, `next/navigation`, `react-hook-form`, `zustand`). A `use*` from outside every `hooks/` folder or an unlisted library is not a hook by its spelling, and a file that exports a helper, a constant or a component still fails (owner ruling 2026-10-16).
+`hooks/` holds `use*.ts` hooks under the names their family slot gives and, per domain, one `<domain>.shared.ts`; nothing else. A hook file exports one hook; `server-only` and `next/headers` are never imported there. A hook is a function that calls a hook: a React, SWR or Redux hook, a `use*` imported from the app's own `hooks/` folders (a `hooks/swr` wrapper or a sibling domain hook, resolved by TypeScript symbol resolution through barrels; that hook's own file is judged when it is linted), or a library hook from an explicit list (`next-intl` `useTranslations`/`useLocale`/`useFormatter`/`useNow`/`useTimeZone`/`useMessages`, `next/navigation`, `next-themes` `useTheme`, `react-hook-form`, `zustand`). A `use*` from outside every `hooks/` folder or an unlisted library is not a hook by its spelling, and a file that exports a helper, a constant or a component still fails (owner ruling 2026-10-16).
 
 **Invalid** (`src/hooks/course/readCourse.ts`)
 
@@ -19,7 +19,8 @@ export const readCourse = () => 1
 **Valid** (`src/hooks/course/useCourse.ts`)
 
 ```ts
-export const useCourse = () => 1
+import { useState } from "react"
+export const useCourse = () => useState(1)
 ```
 
 **Finding code:** `FE_HOOKS_ARE_HOOKS`
@@ -33,7 +34,8 @@ export const useGetCourseSwr = () => 1
 **Valid** (`src/hooks/swr/api/graphql/queries/useQueryCourseSwr.ts`)
 
 ```ts
-export const useQueryCourseSwr = () => 1
+import { useState } from "react"
+export const useQueryCourseSwr = () => useState(1)
 ```
 
 **Why:** `<file>` inside `hooks/` is not a React hook, or is not a file its hooks family names. A call to the back end goes to `modules/api`, a helper to `<domain>.shared.ts`.

package/docs/native-controls.md

@@ -16,11 +16,7 @@ Use the grammar's renderers; never a bare select, input, textarea or button.
 <button onClick={go} />
 ```
 
-**Valid** (`src/components/blocks/Feed/index.tsx`)
-
-```ts
-<Button onPress={go}>{t("go")}</Button>
-```
+**Valid:** Compose the selected grammar's published control with its supported event props and a translated label.
 
 **Finding code:** `FE_NATIVE_FORM_CONTROL`
 

package/docs/next-conventions.md

@@ -141,7 +141,7 @@ export default function Page() { return <CoursesPage /> }
 
 ## `starci-fe/navigation-from-intl`
 
-`Link`, `useRouter`, `usePathname` and `redirect` come from `modules/i18n/navigation`, not from Next (catalogue R59, sub-check `FE_I18N_NAVIGATION`).
+`Link`, `useRouter`, `usePathname` and `redirect` come from `modules/routes`, not from Next (catalogue R59, sub-check `FE_I18N_NAVIGATION`).
 
 **Invalid** (`src/components/blocks/Feed/component.tsx`)
 
@@ -152,18 +152,18 @@ import { useRouter } from "next/navigation"
 **Valid** (`src/components/blocks/Feed/component.tsx`)
 
 ```tsx
-import { useRouter } from "@/modules/i18n/navigation"
+import { useRouter } from "@/modules/routes"
 ```
 
 **Finding code:** `FE_I18N_NAVIGATION`
 
 **Why:** `<file>` imports `Link`, `useRouter`, `usePathname` or `redirect` from Next, which is unaware of the locale: paths lose the `[locale]` prefix.
 
-**Fix:** Import from `modules/i18n/navigation`, which next-intl builds from `routing.ts`.
+**Fix:** Import from `modules/routes`, which next-intl builds from `routing.ts`.
 
 ## `starci-fe/no-native-anchor`
 
-An internal link is `Link` from `modules/i18n/navigation`; an external `_blank` link carries `rel` (catalogue R59, sub-check `FE_I18N_NAVIGATION`).
+An internal link is `Link` from `modules/routes`; an external `_blank` link carries `rel` (catalogue R59, sub-check `FE_I18N_NAVIGATION`).
 
 **Invalid** (`src/components/blocks/Feed/component.tsx`)
 
@@ -181,7 +181,7 @@ An internal link is `Link` from `modules/i18n/navigation`; an external `_blank`
 
 **Why:** `<a>` in `<file>` points at an internal route (reloads the whole page, loses the locale, loses prefetch) or opens a new tab without `rel`.
 
-**Fix:** Use `Link` from `modules/i18n/navigation` with an href built by `modules/routes`; for `_blank` links add `rel="noopener noreferrer"`.
+**Fix:** Use `Link` from `modules/routes` with an href built by `modules/routes`; for `_blank` links add `rel="noopener noreferrer"`.
 
 ## `starci-fe/no-hardcoded-route`
 
@@ -207,9 +207,9 @@ router.push(routes.newWorkspace())
 
 ## `starci-fe/i18n-stack-in-one-module`
 
-next-intl's routing, navigation, request config and middleware factories are called only in the i18n package (or the only app's `modules/i18n`).
+The shared i18n package owns a multi-app stack. A single app keeps routing/request config in `modules/i18n` and navigation in the `modules/routes` public entry.
 
-`defineRouting` (`next-intl/routing`), `createNavigation` (`next-intl/navigation`), `getRequestConfig` (`next-intl/server`) and `createMiddleware` (`next-intl/middleware`), resolved by the import that binds the called name (a renamed import or a namespace member counts), are called only in a file of slot `fe.package.i18n` (`packages/<family>-i18n`, exporting `createAppI18n`), or in a `fe.modules.i18n` file of a repository that declares exactly one app. In a multi-app repository each app's `modules/i18n` calls the package factory. It sits beside `no-second-i18n-stack`, which refuses another i18n library at its import; this rule refuses a second copy of next-intl's own stack.
+`defineRouting` and `getRequestConfig` remain in the i18n owner. `createNavigation` belongs to a shared `fe.package.i18n` owner or the single app's `fe.modules.routes` owner. A single app's proxy mounts locale middleware using the routing-only public i18n entry. A shared package exposes its routing-only proxy entry as a declared package export. The proxy does not import `next-intl/navigation` or the app's routes/navigation barrel. Named import aliases and namespace imports keep their factory identity.
 
 **Invalid** (`apps/web/src/modules/i18n/request.ts`, a repository with two apps)
 
@@ -229,4 +229,4 @@ export const i18n = createAppI18n({ locales: ["vi"] })
 
 **Why:** `<file>` builds a layer of the next-intl stack itself (`defineRouting`, `createNavigation`, `getRequestConfig`, `createMiddleware`). The stack may be written only once per repo.
 
-**Fix:** Call the `createAppI18n` factory of the shared i18n package in `modules/i18n/index.ts` and import the result; in a single-app repo, write the stack only in that app's `modules/i18n`.
+**Fix:** Use the shared i18n factory, or keep routing/request configuration in the single app's i18n module and navigation in its public routes entry. Keep navigation imports out of the proxy.