@starci/eslint-canon-fe 8.4.38 → 8.4.40

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Unreleased
+- 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.
+
+## 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.
+
+## 8.4.39 - 2026-10-25
+- Changed: the bundled canon pins select @starci/grammar 0.11.0, @starci/hfs 4.7.32 and @starci/cli 1.7.32.
+
 ## 8.4.38 - 2026-10-24
 - Changed: the bundled runtime copies and canon pins carry the alpha.30 canon (the `zod` pin is `side: both`) and select @starci/hfs 4.7.31 and @starci/cli 1.7.31.
 

package/README.md

@@ -76,6 +76,12 @@ The one locale pattern everywhere is `next-intl`, a `[locale]` segment, default
 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
 
 ESLint 9+ (flat config), `eslint-plugin-react-hooks` 7+, and Node.js 20.9+.

package/callback-shape.mjs

@@ -7,6 +7,7 @@
  * This syntax check follows lexical bindings and local aliases rather than trusting a method's spelling.
  */
 import { stringOf, walk } from "./lib/ast.mjs"
+import { patternPath } from "./lib/bindings.mjs"
 import { normalizePath } from "./lib/path.mjs"
 import { ownerExportKind } from "./lib/pure-owner-helper.mjs"
 import { classifyImport, inSlot, resolveImport } from "./lib/scope.mjs"
@@ -32,19 +33,6 @@ const bindingOf = (sourceCode, node) => {
 /** Whether an identifier refers to the actual unshadowed platform global. */
 const isGlobal = (sourceCode, node, name) => node?.type === "Identifier" && node.name === name && !(bindingOf(sourceCode, node)?.defs.length)
 
-/** The property path that a destructured binding selects from its initializer. */
-const patternPath = (pattern, name) => {
-  if (pattern.type === "Identifier") return pattern.name === name ? [] : null
-  if (pattern.type === "AssignmentPattern") return patternPath(pattern.left, name)
-  if (pattern.type !== "ObjectPattern") return null
-  for (const property of pattern.properties) {
-    if (property.type !== "Property") continue
-    const nested = patternPath(property.value, name)
-    if (nested !== null) return [property.computed ? stringOf(property.key) : property.key.name ?? property.key.value, ...nested]
-  }
-  return null
-}
-
 /** Route configuration is inert; a second HTTP door or an exported helper is not. */
 const CONFIG_EXPORTS = new Set(["runtime", "dynamic", "revalidate", "fetchCache", "preferredRegion", "maxDuration"])
 const FUNCTIONS = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"])

package/docs/grammar-boundary.md

@@ -1,6 +1,6 @@
 # Grammar boundary
 
-Law module: `grammar-boundary.mjs`. Catalogue: R62 FE_NATIVE_FORM_CONTROL (the grammar owns the element).
+Law module: `grammar-boundary.mjs`. Catalogue: R62 FE_NATIVE_FORM_CONTROL (the grammar owns the element), R65 FE_SIZE_AND_STATE_BUDGET (timer ownership).
 
 Page structure and text are composed from `@starci/grammar` (or the repository's `<family>-ui` package), not drawn as raw HTML.
 
@@ -14,6 +14,8 @@ Applies to app source that composes the grammar (slots `fe.feature`, `fe.compone
 
 The refused tags are exactly those `@starci/grammar` has a component for (the twin test reads the package source): `h1-h6` (`Heading`), `p` and `span` (`Text`), `hr` (`Divider`), `label` (`Label`), `form` (`Form`), `fieldset` (`Fieldset`), `dl` `dt` `dd` (`DescriptionList`), `table` `thead` `tbody` `tr` `td` `th` (`DataTable`), `ul` `ol` `li` (`List` and `ListItem` for a plain semantic list, `SurfaceListCard`, `StaticStateRow`), `header` (`SectionHeader`, `TopBar`), `footer` (`Footer`), `nav` (`NavLandmark` for a named row of links, `Subnav`, `Breadcrumbs`, `NavigationFeatureNav`), `section` (`Region` for a named non-card region, `SurfaceCard`), `main` (`WorkspaceShell`), `figure` and `figcaption` (`MediaFrame`). `div`, `br`, `aside` and `article` are not refused: the grammar has no component for them.
 
+Native `<time>` remains available for an absolute timestamp. Live relative time and countdown labels use `RelativeTime`.
+
 **Invalid** (`src/features/pages/home/component.tsx`)
 
 ```ts
@@ -31,3 +33,25 @@ export const Home = () => <SurfaceCard><Text>{t("intro")}</Text></SurfaceCard>
 **Why:** Raw `<tag>` in `<file>`. Page structure and text are composed from grammar components, not written as raw HTML.
 
 **Fix:** Replace it with the matching grammar component (`Heading`, `Text`, `SurfaceCard`, ...); if the grammar lacks one, add it to the grammar or the ui package instead of drawing it in place.
+
+## `starci-fe/no-app-relative-clock`
+
+Grammar owns the shared clock for live relative time and countdowns. App components, hooks, modules and shared packages, including a product UI package, pass `dateTime`, `locale` and `mode` to `RelativeTime`.
+
+The rule rejects a recurring `setInterval` or self-scheduling `setTimeout` whose callback or same-file helper reads `Date.now()`, `Date()`, zero-argument `new Date()` or `performance.now()`. It follows local aliases and destructured platform methods. Static reads, one-shot delays and timers that do not read the clock remain available. Indirect external clock helpers and counters that only decrement state need semantic review.
+
+**Invalid** (`src/hooks/time/useNow.ts`)
+
+```ts
+const timer = setInterval(() => update(Date.now()), 1000)
+```
+
+**Valid** (`src/components/leaves/UpdatedAt/index.tsx`)
+
+```tsx
+const UpdatedAt = () => <RelativeTime dateTime={instant} locale={locale} mode="relative" />
+```
+
+**Finding code:** `FE_SIZE_AND_STATE_BUDGET`
+
+**Fix:** Render the Grammar primitive and pass the instant; its single shared ticker owns updates and its deterministic fallback owns the server render.

package/docs/surface-rules.md

@@ -0,0 +1,41 @@
+# Grammar surface composition
+
+Law module: `surface-rules.mjs`. Canon: ANATOMY-2 and PADDING-0.
+
+## `starci-fe/nested-control-variant`
+
+Finding code: `FE_NESTED_VARIANT`. Grammar surfaces supply the secondary field default through their nesting context. An explicit primary field inside a surface subtree in the same component is refused. Named import aliases and namespace imports preserve Grammar ownership. A different component owns a separate static subtree; overlay triggers belong outside the overlay content.
+
+App `className` values carry layout. A raw `bg-surface` utility paints a surface and is refused, including conditional classes, class builders, responsive variants, important modifiers and opacity suffixes. Static props spreads keep the same obligations. Typed app lint follows imported colocated class declarations as well as local constants.
+
+Invalid:
+
+```tsx
+import { SurfaceCard, SearchField } from "@starci/grammar/core"
+const Panel = () => <SurfaceCard><SearchField variant="primary" /></SurfaceCard>
+```
+
+Valid:
+
+```tsx
+import { SurfaceCard, SearchField } from "@starci/grammar/core"
+const Panel = () => <SurfaceCard><SearchField /></SurfaceCard>
+```
+
+## `starci-fe/no-list-panel-padding`
+
+Finding code: `FE_LIST_PANEL_PADDING`. A wrapper around Grammar `ListBox` or its section caption cannot add `px-*`, `ps-*` or `pe-*`. These insets add to the list's own padding. Grammar's panel inset aligns rows, section captions and the surface header to one content edge.
+
+Invalid:
+
+```tsx
+import { SurfaceCard, ListBox } from "@starci/grammar/core"
+const Panel = () => <SurfaceCard><div className="px-2"><ListBox label="Members" items={members} /></div></SurfaceCard>
+```
+
+Valid:
+
+```tsx
+import { SurfaceCard, ListBox } from "@starci/grammar/core"
+const Panel = () => <SurfaceCard><ListBox inset="panel" label="Members" items={members} /></SurfaceCard>
+```

package/grammar-boundary.mjs

@@ -17,7 +17,10 @@
  * rule refuses to guess a scope.
  */
 
+import { walk } from "./lib/ast.mjs"
+import { functionOf, isFn, unwrap, variableOf } from "./lib/bindings.mjs"
 import { hfsOf } from "./lib/hfs.mjs"
+import { isProductSource } from "./lib/scope.mjs"
 
 /**
  * The intrinsic elements of page structure and text, each with the grammar components that render it.
@@ -82,9 +85,118 @@ export const noRawStructuralElement = {
   },
 }
 
+/** The static property name of an access or destructured property. */
+const propertyName = (node) => {
+  const key = node.property ?? node.key
+  if (!node.computed && key?.type === "Identifier") return key.name
+  return key?.type === "Literal" && typeof key.value === "string" ? key.value : null
+}
+
+/** The platform member a local destructured binding selects. */
+const destructuredPath = (context, declarator, local, seen) => {
+  if (declarator.id.type !== "ObjectPattern") return null
+  const property = declarator.id.properties.find((entry) => entry.type === "Property" && entry.value.type === "Identifier" && entry.value.name === local)
+  const name = property && propertyName(property)
+  const object = platformPath(context, declarator.init, seen)
+  return object && name ? [...object, name] : null
+}
+
+/** A platform path, following local aliases and destructuring while refusing shadowed globals. */
+const platformPath = (context, node, seen = new Set()) => {
+  const inner = unwrap(node)
+  if (!inner || seen.has(inner)) return null
+  seen.add(inner)
+  if (inner.type === "MemberExpression") {
+    const object = platformPath(context, inner.object, seen)
+    const name = propertyName(inner)
+    return object && name ? [...object, name] : null
+  }
+  if (inner.type !== "Identifier") return null
+  const variable = variableOf(context, inner)
+  if (!variable || variable.defs.length === 0) return [inner.name]
+  for (const definition of variable.defs) {
+    if (definition.type !== "Variable" || !definition.node.init) continue
+    const declarator = definition.node
+    if (declarator.id.type === "Identifier") return platformPath(context, declarator.init, seen)
+    return destructuredPath(context, declarator, inner.name, seen)
+  }
+  return null
+}
+
+/** A platform API spelling with the optional global-object prefix removed. */
+const platformName = (context, node) => {
+  const parts = platformPath(context, node)
+  if (!parts) return null
+  if (["window", "globalThis", "self"].includes(parts[0])) parts.shift()
+  return parts.join(".")
+}
+
+/** A wall-clock read: Date.now(), Date(), zero-argument new Date(), or performance.now(). */
+const readsClock = (context, root, seen = new Set()) => {
+  if (!root || seen.has(root)) return false
+  seen.add(root)
+  let found = false
+  walk(context.sourceCode, root, (node) => {
+    if (found) return false
+    if (node.type === "NewExpression" && node.arguments.length === 0 && platformName(context, node.callee) === "Date") found = true
+    if (node.type !== "CallExpression") return undefined
+    if (["Date", "Date.now", "performance.now"].includes(platformName(context, node.callee))) found = true
+    const helper = functionOf(context, node.callee)
+    if (helper && readsClock(context, helper.body, seen)) found = true
+    return undefined
+  })
+  return found
+}
+
+/** Whether a timer callback runs its enclosing function again, directly or through a same-file helper. */
+const callsFunction = (context, root, target, seen = new Set()) => {
+  if (!root || seen.has(root)) return false
+  if (root === target) return true
+  seen.add(root)
+  let found = false
+  walk(context.sourceCode, root.body ?? root, (node) => {
+    if (found) return false
+    if (node.type !== "CallExpression") return undefined
+    const called = functionOf(context, node.callee)
+    if (called === target || called && callsFunction(context, called, target, seen)) found = true
+    return undefined
+  })
+  return found
+}
+
+/** Grammar owns the shared clock for live time labels; product components and hooks only pass instants. */
+export const noAppRelativeClock = {
+  meta: {
+    type: "problem",
+    docs: { description: "Live relative time and countdowns use Grammar's shared clock rather than a product-owned ticker." },
+    schema: [],
+    messages: {
+      clock: "This recurring timer reads the clock. Render RelativeTime with dateTime, locale and mode; Grammar owns its single shared ticker and its server-safe first render. Product components and hooks pass the target instant and never start another clock for time labels.",
+    },
+  },
+  create(context) {
+    if (!isProductSource(context)) return {}
+    return {
+      CallExpression(node) {
+        const timer = platformName(context, node.callee)
+        if (timer !== "setInterval" && timer !== "setTimeout") return
+        const callback = functionOf(context, node.arguments[0])
+        if (!callback) return
+        let owner = node.parent
+        while (owner && !isFn(owner)) owner = owner.parent
+        const repeats = timer === "setInterval" || owner && callsFunction(context, callback, owner)
+        if (repeats && (readsClock(context, callback.body) || timer === "setTimeout" && readsClock(context, owner.body))) {
+          context.report({ node, messageId: "clock" })
+        }
+      },
+    }
+  },
+}
+
 /** The rules this law contributes to the plugin. */
 export const rules = {
   "no-raw-structural-element": noRawStructuralElement,
+  "no-app-relative-clock": noAppRelativeClock,
 }
 
 /** Every rule is an error. */

package/hooks-folder.mjs

@@ -7,6 +7,7 @@
  * saying where the non-hook code goes. It now does, per family of the front-end stack (each its own slot):
  *
  *   hooks/swr/api/{graphql,rest}/{queries,mutations}/use{Query,Mutate,Get,Post,Put,Patch,Delete}<X>Swr.ts
+ *   hooks/swr/api/sse/subscriptions/useSubscribe<X>Swr.ts
  *                                     one SWR hook per modules/api operation (fe.hooks.swr), plus SwrSideEffects.tsx
  *   hooks/rhf/use<X>Form.ts           one form (fe.hooks.rhf)
  *   hooks/zustand/<store>/store.ts    one local store and its use*.ts selectors (fe.hooks.zustand)
@@ -37,7 +38,7 @@ import { rules as swrFamilyRules } from "./swr-family.mjs"
 const isHookName = (name) => /^use[A-Z0-9]/.test(name)
 
 /**
- * The SWR key of a hook (`QUERY_<X>_SWR_KEY`, `MUTATE_<X>_SWR_KEY`, fe-stack data): the one constant a hook file exports beside its
+ * The SWR key of a hook (`QUERY_<X>_SWR_KEY`, `MUTATE_<X>_SWR_KEY`, `SUBSCRIBE_<X>_SWR_KEY`, fe-stack data): the one constant a hook file exports beside its
  * hook, so a mutation or a socket message revalidates exactly that cache entry.
  */
 const isSwrKeyName = (name) => /^[A-Z][A-Z0-9_]*_SWR_KEY$/.test(name)
@@ -85,8 +86,9 @@ const SWR_HOOKS = new Map([
   ["swr/immutable", new Set(["useSWRImmutable"])],
   ["swr/infinite", new Set(["useSWRInfinite"])],
   ["swr/mutation", new Set(["useSWRMutation"])],
+  ["swr/subscription", new Set(["useSWRSubscription"])],
 ])
-const SWR_DEFAULTS = new Map([["swr", "useSWR"], ["swr/immutable", "useSWRImmutable"], ["swr/infinite", "useSWRInfinite"], ["swr/mutation", "useSWRMutation"]])
+const SWR_DEFAULTS = new Map([["swr", "useSWR"], ["swr/immutable", "useSWRImmutable"], ["swr/infinite", "useSWRInfinite"], ["swr/mutation", "useSWRMutation"], ["swr/subscription", "useSWRSubscription"]])
 /**
  * The library hooks a composite hook may stand on (an explicit list, owner ruling 2026-10-16): next-intl, next/navigation,
  * react-hook-form and zustand's React entry points. A name outside the list is not a hook by its spelling.
@@ -205,7 +207,8 @@ const hookFileOf = (context) => {
     const stray = Boolean(verdict) && !verdict.allowed
     const allows = (verdict?.allows ?? hfs.slot(found.slot)?.allows ?? []).join("`, `")
     // A role the slot names (`entry`, `effects`, `store`) or a non-hook file it allows (sockets.ts, enums/, types/, barrels) is no hook file.
-    return { stray, directlyInHooks: false, hookFile: !stray && !found.role && isHookFileName(name), sharedFile: false, family: found.slot, allows }
+    const subscriptions = ["/api/sse/subscriptions/", "/api/graphql/subscriptions/"].some((folder) => file.split(String.fromCharCode(92)).join("/").includes(folder))
+    return { stray, directlyInHooks: false, hookFile: !stray && !found.role && isHookFileName(name), sharedFile: false, family: found.slot, allows, subscriptions }
   }
   if (!inSlot(context, "fe.hooks")) return null
   // A file directly in `hooks/` is its own root: the slot binds the file name as the `domain`.
@@ -232,6 +235,8 @@ export const hooksFolderHoldsHooksOnly = {
         "`{{name}}` is in `hooks/` but is not a React hook. Hooks are `use<Name>.ts`; the domain's non-hook helpers go in `<domain>.shared.ts`; a call to the back end is an operation of `modules/api`, wrapped by an SWR hook in `hooks/swr/`.",
       family:
         "`{{name}}` is not a file `{{family}}` names. This family holds `{{allows}}`: an SWR hook is `use{Query,Mutate}<X>Swr.ts` (GraphQL) or `use{Get,Post,Put,Patch,Delete}<X>Swr.ts` (REST) in its `api/<protocol>/<queries|mutations>/` folder, a form is `use<X>Form.ts`. A name outside the list is a hook nobody finds by its family, or code that is not a hook.",
+      subscription:
+        "`{{name}}` is not a file `{{family}}` names in a subscriptions folder. A stream or GraphQL subscription hook is `useSubscribe<X>Swr.ts` in `api/sse/subscriptions/` or `api/graphql/subscriptions/`, one hook per file, exporting at most its `SUBSCRIBE_<X>_SWR_KEY`.",
       export:
         "`{{name}}` is exported from a hook file but is not a hook. A hook file exports the hook (a function named `use...`) and at most its SWR key (`QUERY_<X>_SWR_KEY`, `MUTATE_<X>_SWR_KEY`); a helper belongs in `<domain>.shared.ts`.",
       many:
@@ -256,6 +261,7 @@ export const hooksFolderHoldsHooksOnly = {
       Program(program) {
         if (judged.directlyInHooks) return context.report({ node: program, messageId: "domain" })
         if (!judged.stray) return
+        if (judged.family && judged.subscriptions) return context.report({ node: program, messageId: "subscription", data: { name, family: judged.family } })
         if (judged.family) context.report({ node: program, messageId: "family", data: { name, family: judged.family, allows: judged.allows } })
         else context.report({ node: program, messageId: "notHook", data: { name } })
       },

package/icon.mjs

@@ -12,7 +12,7 @@
  * generalises on its own, and the gap between them is exactly where a third step gets invented.
  */
 
-import { isClassAttribute, staticText } from "./lib/ast.mjs"
+import { attribute, isClassAttribute, staticText, tagName } from "./lib/ast.mjs"
 import { canonicalPackages } from "./lib/fe-stack.mjs"
 import { hfsOf } from "./lib/hfs.mjs"
 import { fileOf, inSlot, isComponentFile, isProductSource, kindOfFile, roleOfFile } from "./lib/scope.mjs"
@@ -171,6 +171,35 @@ export const noOffScaleGlyphSize = {
   },
 }
 
+// -- ICON-1 (call site) ----------------------------------------------------------------------------
+
+/** A size utility on the class of a glyph: `size-5`, `w-4`, `h-6`, `min-w-4`. */
+const SIZE_UTILITY = /(?:^|\s)(?:size|w|h|min-w|min-h|max-w|max-h)-\S+/
+
+/** The icon's size is its usage's: the call site passes the glyph and never a size class. */
+export const noIconSizeClass = {
+  meta: {
+    type: "problem",
+    docs: { description: "A glyph component takes its size from its usage (the 20px leading step is size-5), never from a size class at the call site." },
+    schema: [],
+    messages: {
+      size:
+        "`{{cls}}` sizes a glyph at the call site. The size of a glyph is its usage's (`Icon` and the Grammar components that draw one: 24px heading, 20px leading = size-5, 16px chip), so the app passes the glyph and no size class; a size written here is a third step nobody applies the same way twice.",
+    },
+  },
+  create(context) {
+    if (!isProductSource(context) || isIconLeafFile(context)) return {}
+    return {
+      JSXOpeningElement(node) {
+        const name = tagName(node)
+        if (name === null || !/Icon$/.test(name)) return
+        const hit = SIZE_UTILITY.exec(staticText(attribute(node, "className")?.value) ?? "")
+        if (hit) context.report({ node, messageId: "size", data: { cls: hit[0].trim() } })
+      },
+    }
+  },
+}
+
 // -- ICON-10 ---------------------------------------------------------------------------------------
 
 /** A repeated metric cell does not invent a feature glyph absent from the reference. */
@@ -266,6 +295,7 @@ export const rules = {
   "no-vendor-icon-outside-icon-leaf": noVendorIconOutsideIconLeaf,
   "heroicons-is-the-glyph-vendor": heroiconsIsTheGlyphVendor,
   "no-off-scale-glyph-size": noOffScaleGlyphSize,
+  "no-icon-size-class": noIconSizeClass,
   "no-decorative-icon-in-metric-cell": noDecorativeIconInMetricCell,
   "no-inline-svg-outside-brand-mark-leaf": noInlineSvgOutsideBrandMarkLeaf,
 }

package/index.mjs

@@ -31,6 +31,7 @@ import { recommended as landmarkRecommended, rules as landmarkRules } from "./la
 import { recommended as listsRecommended, rules as listsRules } from "./lists.mjs"
 import { recommended as loadingRecommended, rules as loadingRules } from "./loading.mjs"
 import { recommended as lintEscapeRecommended, rules as lintEscapeRules } from "./lint-escape-hatch.mjs"
+import { recommended as menuEntriesRecommended, rules as menuEntriesRules } from "./menu-entries.mjs"
 import { recommended as namingRecommended, rules as namingRules } from "./naming.mjs"
 import { recommended as nativeControlsRecommended, rules as nativeControlsRules } from "./native-controls.mjs"
 import { recommended as nextConventionsRecommended, rules as nextConventionsRules } from "./next-conventions.mjs"
@@ -40,6 +41,7 @@ import { recommended as drawingRecommended, rules as drawingRules } from "./draw
 import { recommended as sizeBudgetRecommended, rules as sizeBudgetRules } from "./size-and-state-budget.mjs"
 import { recommended as sizeGrowthRecommended, rules as sizeGrowthRules } from "./size-growth.mjs"
 import { recommended as statusColorsRecommended, rules as statusColorsRules } from "./status-colors.mjs"
+import { recommended as surfaceRulesRecommended, rules as surfaceRules } from "./surface-rules.mjs"
 import { recommended as splitRecommended, rules as splitRules } from "./the-split.mjs"
 import { recommended as tokensRecommended, rules as tokensRules } from "./tokens.mjs"
 import { recommended as transportRecommended, rules as transportRules } from "./transport.mjs"
@@ -75,6 +77,7 @@ const CONTRIBUTIONS = [
   { law: "lists", rules: listsRules, recommended: listsRecommended },
   { law: "loading", rules: loadingRules, recommended: loadingRecommended },
   { law: "lint-escape-hatch", rules: lintEscapeRules, recommended: lintEscapeRecommended },
+  { law: "menu-entries", rules: menuEntriesRules, recommended: menuEntriesRecommended },
   { law: "naming", rules: namingRules, recommended: namingRecommended },
   { law: "native-controls", rules: nativeControlsRules, recommended: nativeControlsRecommended },
   { law: "next-conventions", rules: nextConventionsRules, recommended: nextConventionsRecommended },
@@ -84,6 +87,7 @@ const CONTRIBUTIONS = [
   { law: "size-and-state-budget", rules: sizeBudgetRules, recommended: sizeBudgetRecommended },
   { law: "size-growth", rules: sizeGrowthRules, recommended: sizeGrowthRecommended },
   { law: "status-colors", rules: statusColorsRules, recommended: statusColorsRecommended },
+  { law: "surface-rules", rules: surfaceRules, recommended: surfaceRulesRecommended },
   { law: "the-split", rules: splitRules, recommended: splitRecommended },
   { law: "tokens", rules: tokensRules, recommended: tokensRecommended },
   { law: "translation", rules: translationRules, recommended: translationRecommended },

package/lib/bindings.mjs

@@ -6,6 +6,8 @@
  * written.
  */
 
+import { stringOf } from "./ast.mjs"
+
 /** The globals that all name the browser's global object. */
 const GLOBAL_OBJECT = new Set(["window", "globalThis", "self"])
 
@@ -72,6 +74,19 @@ export const importOf = (context, identifier) => {
   return { source, imported: null }
 }
 
+/** The property path a destructured binding selects from its initializer; null for an unselected or rest binding. */
+export const patternPath = (pattern, name) => {
+  if (pattern.type === "Identifier") return pattern.name === name ? [] : null
+  if (pattern.type === "AssignmentPattern") return patternPath(pattern.left, name)
+  if (pattern.type !== "ObjectPattern") return null
+  for (const property of pattern.properties) {
+    if (property.type !== "Property") continue
+    const nested = patternPath(property.value, name)
+    if (nested !== null) return [property.computed ? stringOf(property.key) : property.key.name ?? property.key.value, ...nested]
+  }
+  return null
+}
+
 /**
  * The function an expression stands for: the function itself, or the function a same-file variable or declaration holds.
  *

package/lib/config.mjs

@@ -100,6 +100,7 @@ export const SLOT_FREE_RULES = Object.freeze([
   "no-native-anchor", "no-inline-parameter-type", "no-hand-rolled-polling", "status-text-uses-soft-foreground", "no-copy-in-call", "no-alert", "no-failure-collapse",
   "outcome-kinds-exhaustive", "no-await-in-loop", "prefer-code-point", "prefer-string-raw", "no-nested-conditional", "no-void-operator", "no-unused-import",
   "prefer-export-from", "no-unused-prop-types", "media-has-caption", "max-params",
+  "nested-control-variant", "no-list-panel-padding",
 ])
 
 /** The source of a plain front-end tree: its `src/`. */

package/lib/fe-stack.mjs

@@ -11,16 +11,17 @@ import { readFileSync } from "node:fs"
 import { dirname, join } from "node:path"
 import { fileURLToPath } from "node:url"
 import { parseYaml } from "../runtime/engine/yaml.mjs"
+import { globExpression } from "../runtime/scripts/lib/glob.mjs"
 
 const CATALOG = join(dirname(fileURLToPath(import.meta.url)), "..", "runtime", "knowledge", "hfs", "fe-stack.yaml")
 
-/** @type {{ concerns: ReadonlyArray<object>, forbidden: ReadonlyMap<string, object> } | null} */
+/** @type {{ concerns: ReadonlyArray<object>, forbidden: ReadonlyMap<string, object>, patterns: ReadonlyArray<object> } | null} */
 let loaded = null
 
 /**
  * The parsed catalog: its concerns, and every forbidden package mapped to the concern that forbids it.
  *
- * @returns {{ concerns: ReadonlyArray<object>, forbidden: ReadonlyMap<string, object> }} The catalog.
+ * @returns {{ concerns: ReadonlyArray<object>, forbidden: ReadonlyMap<string, object>, patterns: ReadonlyArray<object> }} The catalog.
  */
 export const feStack = () => {
   if (loaded) return loaded
@@ -34,7 +35,8 @@ export const feStack = () => {
   if (!Array.isArray(concerns) || concerns.length === 0) throw new Error("runtime/knowledge/hfs/fe-stack.yaml declares no concerns: the fe-stack catalog is malformed")
   const forbidden = new Map()
   for (const concern of concerns) for (const name of concern.forbids ?? []) forbidden.set(String(name), concern)
-  loaded = Object.freeze({ concerns: Object.freeze(concerns), forbidden })
+  const patterns = [...forbidden].filter(([name]) => name.includes("*")).map(([name, concern]) => ({ expression: globExpression(name), concern }))
+  loaded = Object.freeze({ concerns: Object.freeze(concerns), forbidden, patterns: Object.freeze(patterns) })
   return loaded
 }
 
@@ -61,7 +63,9 @@ export const packageNameOf = (specifier) => {
  */
 export const forbiddingConcern = (specifier) => {
   const name = packageNameOf(specifier)
-  return name === null ? null : feStack().forbidden.get(name) ?? null
+  if (name === null) return null
+  const { forbidden, patterns } = feStack()
+  return forbidden.get(name) ?? patterns.find(({ expression }) => expression.test(name))?.concern ?? null
 }
 
 /**

package/lib/scope.mjs

@@ -67,8 +67,8 @@ export const isConfigModule = (context) => inSlot(context, "fe.modules.config")
  */
 export const isApiClient = (context) => inSlot(context, "fe.transport.client", "fe.package.api.client")
 
-/** The slots of the API layer: the app's `modules/api` (with its clients folder and its GraphQLResponse file) and the shared api package. */
-const API_LAYER_SLOTS = Object.freeze(["fe.modules.api", "fe.transport.client", "fe.transport.outcome", "fe.package.api", "fe.package.api.client", "fe.package.api.outcome"])
+/** The slots of the API layer: the app's `modules/api` (with its clients folder, its stream reader and its GraphQLResponse file) and the shared api package. */
+const API_LAYER_SLOTS = Object.freeze(["fe.modules.api", "fe.transport.client", "fe.transport.stream", "fe.transport.outcome", "fe.package.api", "fe.package.api.client", "fe.package.api.outcome"])
 
 /** True when the linted file sits in the API layer: the only place that talks to the back end (Apollo, axios, `fetch`). */
 export const isApiLayer = (context) => inSlot(context, ...API_LAYER_SLOTS)

package/lib/typed-class-values.mjs

@@ -0,0 +1,72 @@
+/** Static class declarations in imported colocated modules, resolved by the consuming TypeScript program. */
+import ts from "typescript"
+
+/** The expression's literal fragments, following imported const/property declarations without executing code. */
+const fragments = (checker, node, seen, mode) => {
+  if (!node || seen.has(node)) return []
+  seen.add(node)
+  if (ts.isStringLiteralLike(node) || ts.isTemplateHead(node) || ts.isTemplateMiddle(node) || ts.isTemplateTail(node)) return [node.text]
+  if (ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) || ts.isSatisfiesExpression(node) || ts.isParenthesizedExpression(node) || ts.isNonNullExpression(node)) return fragments(checker, node.expression, seen, mode)
+  if (ts.isIdentifier(node) || ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+    const symbol = ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)
+      ? checker.getTypeAtLocation(node.expression).getProperty(node.argumentExpression.text)
+      : checker.getSymbolAtLocation(ts.isPropertyAccessExpression(node) ? node.name : node)
+    return symbolFragments(checker, symbol, seen, mode)
+  }
+  return fragmentChildren(node, mode).flatMap((child) => fragments(checker, child, seen, mode))
+}
+
+/** An object binding reads only its selected property's symbol, including aliases and nested patterns. */
+const bindingProperty = (checker, declaration) => {
+  const source = declaration.parent.parent
+  const owner = ts.isBindingElement(source) ? bindingProperty(checker, source) : null
+  const type = owner ? checker.getTypeOfSymbolAtLocation(owner, source) : source.initializer ? checker.getTypeAtLocation(source.initializer) : null
+  const name = declaration.propertyName ?? declaration.name
+  return ts.isIdentifier(name) || ts.isStringLiteralLike(name) ? type?.getProperty(name.text) : null
+}
+
+/** Alias and destructuring symbols retain their declaration values without reading sibling properties. */
+const symbolFragments = (checker, input, seen, mode) => {
+  let symbol = input
+  if (symbol && (symbol.flags & ts.SymbolFlags.Alias) !== 0) symbol = checker.getAliasedSymbol(symbol)
+  return (symbol?.declarations ?? []).flatMap((declaration) => {
+    const selected = ts.isBindingElement(declaration) ? bindingProperty(checker, declaration) : null
+    return selected ? symbolFragments(checker, selected, seen, mode) : fragments(checker, declaration.initializer, seen, mode)
+  })
+}
+
+/** Class-producing positions inside a declaration, including cn dictionaries and conditional recipes. */
+const fragmentChildren = (node, mode) => {
+  if (ts.isCallExpression(node)) return mode === "classes" ? node.arguments : []
+  if (ts.isArrayLiteralExpression(node)) return node.elements
+  if (ts.isConditionalExpression(node)) return [node.whenTrue, node.whenFalse]
+  if (ts.isBinaryExpression(node)) {
+    if (node.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) return [node.right]
+    return [ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(node.operatorToken.kind) ? [node.left, node.right] : []
+  }
+  if (ts.isObjectLiteralExpression(node)) return node.properties.flatMap((property) => ts.isPropertyAssignment(property) ? [property.name, property.initializer] : [])
+  if (ts.isTemplateExpression(node) && mode === "classes") return [node.head, ...node.templateSpans.flatMap((span) => [span.expression, span.literal])]
+  return []
+}
+
+/**
+ * Imported class values are reported at their use in the linted file, while their text comes from the typed declaration.
+ * Syntax-only rule consumers have no imported-file program and retain same-file inspection.
+ */
+export const typedClassStrings = (context, node, mode) => {
+  const services = context.sourceCode.parserServices
+  if (!services?.program || !services.esTreeNodeToTSNodeMap) return []
+  const source = services.esTreeNodeToTSNodeMap.get(node)
+  const checker = services.program.getTypeChecker()
+  return fragments(checker, source, new Set(), mode).map((text) => ({ node, text }))
+}
+
+/** Known imported props spreads expose the same static property values as named JSX attributes. */
+export const typedPropertyStrings = (context, node, key, mode) => {
+  const services = context.sourceCode.parserServices
+  if (!services?.program || !services.esTreeNodeToTSNodeMap) return []
+  const source = services.esTreeNodeToTSNodeMap.get(node)
+  const checker = services.program.getTypeChecker()
+  const symbol = checker.getTypeAtLocation(source).getProperty(key)
+  return symbolFragments(checker, symbol, new Set(), mode).map((text) => ({ node, text }))
+}

package/lib/why.mjs

@@ -19,6 +19,16 @@
 
 /** @type {Record<string, Why>} */
 export const why = {
+  "nested-control-variant": {
+    code: "FE_NESTED_VARIANT",
+    en: "`<file>` forces a primary field inside a Grammar surface, or paints a raw bg-surface in app CSS.",
+    fix: "Compose a Grammar surface and omit the nested field variant so its surface context supplies secondary.",
+  },
+  "no-list-panel-padding": {
+    code: "FE_LIST_PANEL_PADDING",
+    en: "`<file>` adds horizontal wrapper padding to a Grammar list or its section caption, stacking the content inset.",
+    fix: "Remove the wrapper padding and use ListBox inset=\"panel\" so headers, captions and rows share the panel content edge.",
+  },
   "no-env-outside-config": {
     code: "FE_ENV_OWNER",
     en: "`<file>` reads an environment variable. Only `modules/config` may read env.",
@@ -279,10 +289,15 @@ export const why = {
     en: "Raw `<tag>` in `<file>`. Page structure and text are composed from grammar components, not hand-written HTML.",
     fix: "Replace it with the matching grammar component (`Heading`, `Text`, `SurfaceCard`, ...); if grammar lacks it, add it to grammar or the ui package instead of drawing it in place.",
   },
+  "no-app-relative-clock": {
+    code: "FE_SIZE_AND_STATE_BUDGET",
+    en: "`<file>` starts a recurring timer that reads the wall clock for live time labels.",
+    fix: "Render Grammar RelativeTime with the target dateTime, locale and mode; its shared ticker owns live relative time and countdown updates.",
+  },
   "fe-stack-import": {
     code: "FE_STACK_FORBIDDEN",
-    en: "`<file>` imports `<what>`, a library the front-end stack forbids (a second library for a concern that has one), or a Supabase package outside `modules/auth`.",
-    fix: "Use the concern's canonical library from `knowledge/hfs/fe-stack.yaml` (the message names it); Supabase on the front end is the auth client in `modules/auth` only, data goes through `modules/api`.",
+    en: "`<file>` imports `<what>`, a package or scoped package family the front-end stack forbids, or a Supabase package outside `modules/auth`.",
+    fix: "Use the concern's canonical library from `knowledge/hfs/fe-stack.yaml` (the message names it). For @dicebear/*, pass the identity id as seed on Grammar Avatar, AvatarButton or AvatarGroup members. Supabase on the front end is the auth client in `modules/auth` only, data goes through `modules/api`.",
   },
   "file-size-growth": {
     code: "HFS_SIZE_GROWTH",

package/lint-escape-hatch.mjs

@@ -7,7 +7,7 @@
  *
  *   eslint-disable / -next-line / -line / -enable / -env, and `/* eslint rule: "off" *\/`
  *   @ts-ignore, @ts-expect-error, @ts-nocheck
- *   NOSONAR, @sonar-ignore                        - Sonar's own switches
+ *   the no-sonar word, @sonar-ignore              - Sonar's own switches
  *   istanbul ignore, c8 ignore, v8 ignore         - a line taken out of the coverage the gate reads
  *   prettier-ignore                               - a region taken out of the formatter
  *   stylelint-disable / -enable                   - a stylelint switch that reached a TS file
@@ -39,7 +39,7 @@ const ESLINT_DIRECTIVE = /^\s*eslint-(?:disable(?:-next-line|-line)?|enable|env)
 const TS_DIRECTIVE = /^\s*(?:\/\s*)?@ts-(?:ignore|expect-error|nocheck)\b/
 
 /**
- * A quality-tool switch other than ESLint's: Sonar honours `NOSONAR` anywhere in a comment (case-insensitively), so it is
+ * A quality-tool switch other than ESLint's: Sonar honours its no-sonar word anywhere in a comment (case-insensitively), so it is
  * matched anywhere; the others are read by their tool from the start of the comment, so they are anchored there too.
  */
 const TOOL_DIRECTIVE =