@starci/eslint-canon-fe 8.4.39 → 8.4.41

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 8.4.41 - 2026-10-26
+
+- Enforce the app-shell canon through fixed WorkspaceShell frames, drawer navigation, ordered navbar controls, control sizing and page-owned creation, with full and lite regression coverage.
+- 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.
 

package/README.md

@@ -32,6 +32,10 @@ exported; `why[rule]` is `{ code, vi, fixVi }`, the finding code and the Vietnam
 
 ## 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.
+
 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),
@@ -76,6 +80,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/app-shell.mjs

@@ -0,0 +1,161 @@
+/** FE-APP-SHELL-1..5: static app-frame and visible navbar composition from the UI canon. */
+import { isProductSource } from "./lib/scope.mjs"
+import { grammarName, isBarControl, propOf, resolveLocal, semanticText, textProp } from "./lib/app-shell.mjs"
+import { appBarOpenings, isAppBar, isAppShell, isNavigationDrawer, ownsAppFrame } from "./lib/app-shell-scope.mjs"
+import { visitVisible } from "./lib/app-shell-visible.mjs"
+import { clusterAlternatives } from "./lib/app-shell-cluster.mjs"
+import { isCreateAction, menuHasCreate } from "./lib/app-shell-create.mjs"
+import { provesImportedBar } from "./lib/app-shell-owner.mjs"
+import { variableOf } from "./lib/bindings.mjs"
+
+const CANON = "knowledge/ui/composition/app-shell.yaml"
+const BOTTOM_TABS = /^(?:BottomNav|BottomNavigation|BottomTabBar|MobileBottomNav|MobileTabBar)$/
+const EXPECTED_CLUSTER = ["language:IconButton", "theme:Switch", "notifications:IconButton", "account:AvatarButton"]
+
+const meta = (code, description, messages) => ({
+  type: "problem",
+  docs: { description: `${code}: ${description}`, url: CANON },
+  schema: [],
+  messages,
+})
+
+/** The app frame is the fixed-viewport Grammar shell; hand-written frame landmarks are rejected. */
+export const appShellFrame = {
+  meta: meta("FE_APP_SHELL_FRAME", "FE-APP-SHELL-1 uses WorkspaceShell viewport=fixed.", {
+    frame: "FE_APP_SHELL_FRAME: compose the app frame with WorkspaceShell viewport=\"fixed\"; Grammar owns its header, navigation and independent scroll regions.",
+  }),
+  create(context) {
+    if (!isProductSource(context)) return {}
+    return { JSXOpeningElement(node) {
+      const wrongViewport = isAppShell(context, node) && textProp(context, node, "viewport") !== "fixed"
+      const handFrame = ownsAppFrame(context, node) && (node.name.type === "JSXIdentifier" && ["header", "nav", "main"].includes(node.name.name) || isAppBar(context, node) && !appBarOpenings(context).has(node))
+      if (wrongViewport || handFrame) {
+        context.report({ node, messageId: "frame" })
+      }
+    } }
+  },
+}
+
+/** Bottom navigation is not an alternative compact app-shell frame. */
+export const noShellBottomTabs = {
+  meta: meta("FE_APP_SHELL_BOTTOM_TABS", "FE-APP-SHELL-4 keeps mobile navigation in the sidebar drawer.", {
+    bottom: "FE_APP_SHELL_BOTTOM_TABS: the app shell uses a mobile subnav opener and Sidebar drawer. Remove bottom tab navigation and WorkspaceShell compactNavigation.",
+  }),
+  create(context) {
+    if (!isProductSource(context)) return {}
+    return { JSXOpeningElement(node) {
+      const name = grammarName(context, node)
+      const compact = name === "WorkspaceShell" && propOf(context, node, "compactNavigation")
+      const value = compact && resolveLocal(context, compact.value)
+      const absent = value?.type === "Identifier" && value.name === "undefined" && !variableOf(context, value)?.defs.length
+      if (BOTTOM_TABS.test(name ?? "") || compact && !absent && (!compact.known || compact.value !== null || compact.present)) context.report({ node, messageId: "bottom" })
+    } }
+  },
+}
+
+const visitBar = (context, node, visit) => {
+  const name = grammarName(context, node)
+  if (name === "WorkspaceShell" && isAppShell(context, node)) {
+    for (const slot of ["header", "compactHeader"]) visitVisible(context, propOf(context, node, slot).value, visit)
+  } else if (isAppBar(context, node)) {
+    visitVisible(context, node.parent, visit)
+  } else if (isNavigationDrawer(context, node)) {
+    visitVisible(context, propOf(context, node, "trigger").value, visit)
+  }
+}
+
+const delegatesImportedBar = (context, expression) => {
+  let imported = false
+  let controls = false
+  let unknown = false
+  visitVisible(context, expression, (opening, name) => {
+    if (isBarControl(context, opening, name)) controls = true
+    if (name !== null) return
+    const proof = provesImportedBar(context, opening)
+    if (proof === true) imported = true
+    if (proof === false) unknown = true
+  })
+  return imported && !controls && !unknown
+}
+
+/** Every visible control in a navbar band uses the shared control size. */
+export const navbarControlSize = {
+  meta: meta("FE_NAVBAR_CONTROL_SIZE", "FE-APP-SHELL-2 requires size=control on bar controls.", {
+    control: "FE_NAVBAR_CONTROL_SIZE: {{name}} in the navbar band needs size=\"control\" so every bar control shares Grammar's control height.",
+  }),
+  create(context) {
+    if (!isProductSource(context)) return {}
+    const reported = new Set()
+    return { JSXOpeningElement(node) {
+      visitBar(context, node, (control, name) => {
+        if (!isBarControl(context, control, name) || textProp(context, control, "size") === "control" || reported.has(control)) return
+        reported.add(control)
+        context.report({ node: control, messageId: "control", data: { name } })
+      })
+    } }
+  },
+}
+
+/** The right cluster is checked at the bar's actions composition, in visual source order. */
+export const navbarCluster = {
+  meta: meta("FE_NAVBAR_CLUSTER", "FE-APP-SHELL-3 fixes navbar action kinds and order.", {
+    cluster: "FE_NAVBAR_CLUSTER: navbar actions must be a tertiary Language IconButton in DropdownMenu, theme Switch, notification IconButton in Popover, account AvatarButton in DropdownMenu, in that order. Mobile retains notifications then account and moves language/theme into the drawer.",
+  }),
+  create(context) {
+    if (!isProductSource(context)) return {}
+    return { JSXOpeningElement(node) {
+      const name = grammarName(context, node)
+      if (!isAppShell(context, node) && !isAppBar(context, node)) return
+      const shellHeader = name === "WorkspaceShell"
+      const actions = propOf(context, node, shellHeader ? "header" : "actions")
+      const { alternatives, ownsBar } = clusterAlternatives(context, actions.value, shellHeader)
+      if (ownsBar) return
+      if (shellHeader && delegatesImportedBar(context, actions.value)) return
+      const desktop = EXPECTED_CLUSTER.join("|")
+      const mobile = EXPECTED_CLUSTER.slice(2).join("|")
+      const sequences = alternatives.map((sequence) => sequence.join("|"))
+      if (!sequences.includes(desktop) || sequences.some((sequence) => sequence !== desktop && sequence !== mobile)) context.report({ node, messageId: "cluster" })
+    } }
+  },
+}
+
+/** Creation belongs to its page, never to the global app bar. */
+export const noNavbarCreate = {
+  meta: meta("FE_NAVBAR_CREATE", "FE-APP-SHELL-5 keeps create actions on pages.", {
+    create: "FE_NAVBAR_CREATE: move this create action from the navbar to its page.",
+  }),
+  create(context) {
+    if (!isProductSource(context)) return {}
+    const reported = new Set()
+    const report = (node) => {
+      if (reported.has(node)) return
+      reported.add(node)
+      context.report({ node, messageId: "create" })
+    }
+    const inspect = (control, name) => {
+      if (name === "DropdownMenu" || name === "Popover") {
+        if (["entries", "items", "sections"].some((slot) => menuHasCreate(context, propOf(context, control, slot).value))) report(control)
+        visitVisible(context, propOf(context, control, "content").value, inspect)
+        for (const child of control.parent.children) visitVisible(context, child, inspect)
+      }
+      if (!isBarControl(context, control, name) || reported.has(control)) return
+      const text = `${semanticText(context, control)} ${control.parent.children.map((child) => context.sourceCode.getText(child)).join(" ")}`
+      if (isCreateAction(text)) report(control)
+    }
+    return { JSXOpeningElement(node) {
+      visitBar(context, node, inspect)
+    } }
+  },
+}
+
+/** Every app-shell enforcer is gathered into the ordinary FE lint and gate path. */
+export const rules = {
+  "app-shell-frame": appShellFrame,
+  "no-shell-bottom-tabs": noShellBottomTabs,
+  "navbar-control-size": navbarControlSize,
+  "navbar-cluster": navbarCluster,
+  "no-navbar-create": noNavbarCreate,
+}
+
+/** Every rule is mandatory. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

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/app-shell.md

@@ -0,0 +1,50 @@
+# App shell
+
+Owner: knowledge/ui/composition/app-shell.yaml
+
+The application composes `WorkspaceShell viewport="fixed"`. The `app-shell-frame` rule identifies
+workspace chrome from a fixed shell, sidebar/navigation slot, workspace identity, HFS layout owner,
+or a shell owner combining a bar and sidebar. It rejects hand-written app-frame landmarks and
+workspace shells without the fixed viewport. Generic flow-based site chrome stays in its own scope.
+`no-shell-bottom-tabs` rejects bottom navigation components and the shell's `compactNavigation` slot.
+
+The `navbar-cluster` rule reads the visible `TopBar` or `NavigationFeatureNav` actions in source order:
+tertiary Language `IconButton` triggering `DropdownMenu`, theme `Switch`, notification `IconButton`
+triggering `Popover`, account `AvatarButton` triggering `DropdownMenu`. It follows
+local JSX constants and components, constant object members, imported Grammar aliases, and namespace imports. Translated
+labels may be dynamic; icon sources identify language and notifications. Menu contents and popover
+content belong to their overlays and are outside the bar's control sequence. Conditional render
+branches are checked separately. Grammar `TopBar` and `NavigationFeatureNav` compositions are app
+bars by default. A proven `WorkspaceShell viewport="flow"` with no workspace/sidebar evidence owns
+generic site chrome. A shell hosting an imported navbar delegates only after its owned public
+export and rendered Base chain prove a `TopBar` or `NavigationFeatureNav` in every alternative.
+Workspace exports resolve back to source. Raw or unknown imported headers are red; the actual
+bar's own actions are checked where composed. Each lint source snapshot has fresh dependency proofs.
+
+`navbar-control-size` requires `size="control"` on each bar control. Unknown trailing prop spreads
+cannot prove a size; put the explicit size after a spread. A left `Drawer` containing
+`Sidebar presentation="drawer"` also identifies a mobile bar opener when composed in a separate
+client owner. Its trigger is checked; drawer bodies and footers retain their normal field sizes.
+`no-navbar-create` places creation on its
+own page and rejects create controls in the navbar and its attached menus or popovers. Static
+evidence includes literal labels, translated keys with create semantics, and conventional create
+handlers. Runtime-generated labels and arbitrary handler behavior need semantic review; the rule
+does not execute application code.
+
+| Rule | Invalid composition | Valid composition |
+| --- | --- | --- |
+| `app-shell-frame` | An app `Shell` returns a hand-written `<header>` and `<nav>`. | `WorkspaceShell viewport="fixed"` owns the app frame. |
+| `no-shell-bottom-tabs` | The shell supplies `compactNavigation={<BottomNav />}`. | The shell supplies `navigationDrawer` with a drawer `Sidebar`. |
+| `navbar-control-size` | A navbar `IconButton` uses `size="md"`. | The same control uses `size="control"`. |
+| `navbar-cluster` | Account precedes notifications, or a language trigger uses a regular `Button`. | Language menu, theme switch, notification popover, account menu use their stated Grammar trigger kinds in that order. |
+| `no-navbar-create` | A navbar button or attached menu item creates a record. | The page owns its create action. |
+
+```tsx
+// Invalid: the navbar action creates a page record and has a different height.
+<TopBar actions={<Button onPress={on.create}>Create</Button>} />
+
+// Valid: a page action belongs to page content.
+<SurfaceCard><Button onPress={on.create}>Create</Button></SurfaceCard>
+```
+
+All five rules are errors in the gathered FE canon and run through the ordinary application gate.

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,
 }