@starci/eslint-canon-fe 8.4.39 → 8.4.41

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,41 @@
 
 /** @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.",
+  },
+  "app-shell-frame": {
+    code: "FE_APP_SHELL_FRAME",
+    en: "The app frame must use Grammar WorkspaceShell with its fixed viewport.",
+    fix: "Compose WorkspaceShell viewport=\"fixed\" and supply its header, navigation and primary slots.",
+  },
+  "no-shell-bottom-tabs": {
+    code: "FE_APP_SHELL_BOTTOM_TABS",
+    en: "Bottom tab navigation replaces the required mobile sidebar drawer.",
+    fix: "Use WorkspaceShell navigationDrawer and Sidebar presentation=\"drawer\".",
+  },
+  "navbar-control-size": {
+    code: "FE_NAVBAR_CONTROL_SIZE",
+    en: "A navbar control does not use Grammar's shared control height.",
+    fix: "Set size=\"control\" on every visible bar control.",
+  },
+  "navbar-cluster": {
+    code: "FE_NAVBAR_CLUSTER",
+    en: "Navbar action component kinds or order differ from the app-shell canon.",
+    fix: "Compose Language IconButton, theme Switch, notification IconButton and account AvatarButton in that order.",
+  },
+  "no-navbar-create": {
+    code: "FE_NAVBAR_CREATE",
+    en: "A create action is composed into the global navbar.",
+    fix: "Move the create action to the page that owns it.",
+  },
   "no-env-outside-config": {
     code: "FE_ENV_OWNER",
     en: "`<file>` reads an environment variable. Only `modules/config` may read env.",
@@ -279,10 +314,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 =

package/menu-entries.mjs

@@ -0,0 +1,133 @@
+/**
+ * The menu entries a product hands to Grammar's `DropdownMenu`.
+ *
+ * HeroUI colours a destructive menu item through its `danger` variant, which Grammar exposes as `tone: "danger"`. An entry the app
+ * forgets to tone reads like any other command: sign out and delete sit beside "Settings" in the same ink, and the one click that
+ * cannot be taken back gets no mark. The decision is the entry's meaning, so it is checked where the entry is written: an entry whose
+ * id or label says it signs out, deletes, removes, leaves or revokes carries `tone: "danger"`.
+ *
+ * The terms are this canon's own list, English and Vietnamese. They are compared as whole words after the text is lower-cased, split
+ * at `-`, `_` and camelCase, and stripped of diacritics (the Vietnamese for "sign out" with its tone marks is `dang xuat`), so `signOut`, `sign-out`,
+ * `Sign out` and the tone-marked Vietnamese spelling are one term.
+ *
+ * WHERE IT LOOKS. A menu entry is an object literal in the `entries` attribute of a `DropdownMenu`, or in a declaration typed as
+ * `DropdownMenuEntry`, `DropdownMenuItem` or `DropdownMenuSection` (an array of them too), including the `items` of a section and the
+ * `submenu` of an item. Anything it cannot see through (a spread, a call) it leaves alone: the rule refuses to guess.
+ */
+
+import { stringOf } from "./lib/ast.mjs"
+import { isProductSource } from "./lib/scope.mjs"
+
+/** The English terms of a destructive entry. */
+const DESTRUCTIVE_TERMS_EN = Object.freeze([
+  "sign out", "log out", "logout", "signout",
+  "delete", "remove", "erase", "destroy", "discard", "purge",
+  "leave workspace", "leave team", "leave group", "leave organization", "leave project", "leave channel", "leave course", "revoke", "deactivate", "disconnect", "unlink", "unsubscribe", "terminate",
+  "close account", "cancel subscription", "cancel plan",
+])
+
+/** The Vietnamese terms, written without diacritics (the text is compared after the diacritics are stripped). */
+const DESTRUCTIVE_TERMS_VI = Object.freeze([
+  "dang xuat", "xoa", "xoa bo", "go bo", "loai bo", "roi khoi", "roi nhom", "thu hoi",
+  "vo hieu hoa", "ngat ket noi", "huy dang ky", "huy goi", "cham dut", "dong tai khoan",
+])
+
+/** A destructive term as a whole word or phrase of the normalized text. */
+const DESTRUCTIVE_PATTERN = new RegExp(String.raw`(?:^|\s)(?:${[...DESTRUCTIVE_TERMS_EN, ...DESTRUCTIVE_TERMS_VI].map((term) => term.replaceAll(" ", String.raw`\s+`)).join("|")})(?=\s|$)`)
+
+/** The text lower-cased, split at separators and camelCase, with diacritics stripped. */
+export const normalizeText = (text) =>
+  text
+    .replaceAll(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replaceAll(/[-_./:]+/g, " ")
+    .toLowerCase()
+    .replaceAll("\u0111", "d")
+    .normalize("NFD")
+    .replaceAll(/\p{M}+/gu, "")
+    .replaceAll(/\s+/g, " ")
+    .trim()
+
+/** True when the id or label text names a destructive command. */
+export const isDestructiveText = (text) => DESTRUCTIVE_PATTERN.test(normalizeText(text))
+
+const MENU_TYPES = new Set(["DropdownMenuEntry", "DropdownMenuItem", "DropdownMenuSection"])
+
+/** The value node of the property called `name` in an object literal, or null. */
+const propertyValue = (object, name) =>
+  object.properties.find((entry) => entry.type === "Property" && !entry.computed && (entry.key.name === name || entry.key.value === name))?.value ?? null
+
+/** The element type of an array type (`T[]`, `readonly T[]`, `ReadonlyArray<T>`), else the type itself. */
+const elementTypeOf = (type) => {
+  if (type.type === "TSTypeOperator") return elementTypeOf(type.typeAnnotation)
+  if (type.type === "TSArrayType") return type.elementType
+  const isArrayName = type.type === "TSTypeReference" && type.typeName.type === "Identifier" && (type.typeName.name === "ReadonlyArray" || type.typeName.name === "Array")
+  return isArrayName ? (type.typeArguments ?? type.typeParameters)?.params[0] ?? type : type
+}
+
+/** True when the type annotation names a menu entry type or an array of one. */
+const isMenuType = (annotation) => {
+  const type = annotation?.typeAnnotation
+  if (!type) return false
+  const element = elementTypeOf(type)
+  return element.type === "TSTypeReference" && element.typeName.type === "Identifier" && MENU_TYPES.has(element.typeName.name)
+}
+
+/** Report an entry (an object literal), then walk the `items` of a section and the `submenu` of an item. */
+function visitEntries(node, report) {
+  if (!node) return
+  if (node.type === "ArrayExpression") {
+    for (const element of node.elements) visitEntries(element, report)
+    return
+  }
+  if (node.type === "TSAsExpression" || node.type === "TSSatisfiesExpression") {
+    visitEntries(node.expression, report)
+    return
+  }
+  if (node.type !== "ObjectExpression") return
+  const kind = stringOf(propertyValue(node, "kind"))
+  if (kind === "section") {
+    visitEntries(propertyValue(node, "items"), report)
+    return
+  }
+  const text = [stringOf(propertyValue(node, "id")), stringOf(propertyValue(node, "label"))].filter((value) => value !== null)
+  const tone = propertyValue(node, "tone")
+  const toned = tone !== null && (stringOf(tone) === "danger" || stringOf(tone) === null)
+  if (!toned && text.some(isDestructiveText)) report(node, text.find(isDestructiveText))
+  visitEntries(propertyValue(node, "submenu"), report)
+}
+
+/** A destructive menu entry carries `tone: "danger"`. */
+export const destructiveMenuEntryNeedsDangerTone = {
+  meta: {
+    type: "problem",
+    docs: { description: "A menu entry whose id or label signs out, deletes, removes, leaves or revokes carries `tone: \"danger\"`." },
+    schema: [],
+    messages: {
+      tone:
+        "The menu entry `{{text}}` is destructive but has no `tone: \"danger\"`. HeroUI colours the label and glyph of a danger item so the one click that cannot be taken back is marked; without the tone it reads like \"Settings\". Add `tone: \"danger\"` to the entry.",
+    },
+  },
+  create(context) {
+    if (!isProductSource(context)) return {}
+    const report = (node, text) => context.report({ node, messageId: "tone", data: { text } })
+    return {
+      JSXAttribute(node) {
+        if (node.name.type !== "JSXIdentifier" || node.name.name !== "entries") return
+        const element = node.parent?.name
+        if (element?.type !== "JSXIdentifier" || element.name !== "DropdownMenu") return
+        visitEntries(node.value?.type === "JSXExpressionContainer" ? node.value.expression : null, report)
+      },
+      VariableDeclarator(node) {
+        if (isMenuType(node.id.typeAnnotation)) visitEntries(node.init, report)
+      },
+    }
+  },
+}
+
+/** The rules this law contributes to the plugin. */
+export const rules = {
+  "destructive-menu-entry-needs-danger-tone": destructiveMenuEntryNeedsDangerTone,
+}
+
+/** Every rule is an error. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "8.4.39",
+  "version": "8.4.41",
   "description": "The StarCi front-end lint canon: every rule its laws publish, gathered as one flat-config plugin and attached by one factory.",
   "type": "module",
   "license": "MIT",

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

@@ -1,6 +1,6 @@
 schema: starci/canon-pins@1
 purpose: >-
-  The exact version of every dependency a StarCi product repository pins. One version per dependency for the whole
+  The exact version of every shared dependency in the StarCi family, including package-owned runtime dependencies. One version per dependency for the whole
   family. Raising a version is a change to this file first (with the package bump when it is a @starci package),
   then the repositories' own upgrade lane (each sets the exact version and reinstalls; nothing else installs a @starci package). Read on 2026-09-29 from the packages under
   .claude/packages and from the installed node_modules of the six product repositories; where they disagreed the
@@ -10,7 +10,8 @@ purpose: >-
   two, pinned here with a why (2026-10-01: every such conflict but graphql was already pinned). The runtime's example apps
   merged the same way on 2026-10-01: no dependency outside this file was declared at two versions across their sides, so
   every choice is a pin (each side's older @starci pins and graphql moved to the version here). `side` names the side whose code uses
-  the dependency; the app root package.json carries the pins of both.
+  the dependency; the app root package.json declares the direct dependencies and tools its sides need. Package-owned
+  runtime dependencies are declared by their package, not by the app.
 pins:
   # --- @starci packages. Every @starci package is a PUBLISHED npm package (install: registry): a product repository
   # installs the exact pinned version from the npm registry in the root and every workspace package.json, never `file:`.
@@ -22,28 +23,28 @@ pins:
     source: packages/heroicons/package.json
     why: 'StarCi custom Heroicons-compatible cuts; eslint-canon-fe (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
   '@starci/grammar':
-    version: 0.11.0
+    version: 0.12.1
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.40
+    version: 3.4.41
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.39
+    version: 8.4.41
     group: starci
     install: registry
     side: fe
     source: packages/eslint/fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/stylelint-canon':
-    version: 2.0.10
+    version: 2.0.11
     group: starci
     install: registry
     side: fe
@@ -62,7 +63,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.3.5
+    version: 2.3.6
     group: starci
     install: registry
     side: be
@@ -76,14 +77,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.32
+    version: 1.7.33
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.32
+    version: 4.7.33
     group: starci
     install: registry
     side: both
@@ -238,6 +239,11 @@ pins:
     group: framework
     side: be
     why: 'the Postgres driver behind TypeORM; the reference app declares ^8.12.0 and resolves 8.23.1.'
+  bullmq:
+    version: 6.3.11
+    group: framework
+    side: be
+    why: 'the queue transport of both editions behind platform/queue (ruling:R212/case-10); starci app add queue|job declares it in a lite app together with its Redis, and both example apps resolve this version.'
   reflect-metadata:
     version: 0.2.2
     group: framework
@@ -305,6 +311,11 @@ pins:
     group: framework
     side: fe
     why: 'the GraphQL client of every front end (fe-stack graphql): auth and no-auth clients with the link chain in modules/api/graphql; version read from the starci-academy package-lock on 2026-10-13.'
+  graphql-ws:
+    version: 6.2.1
+    group: framework
+    side: both
+    why: 'the subscription transport: the front end opens it only in the Apollo clients folder (fe-stack graphql, GraphQLWsLink of @apollo/client/link/subscriptions) and the back end serves it only from platform/realtime; the version resolved by the full-app lockfile on 2026-10-24.'
   '@graphql-codegen/cli':
     version: 7.4.6
     group: tooling
@@ -370,6 +381,16 @@ pins:
     group: ui
     side: fe
     why: 'the base of the one application icon set (fe-stack icons, with @starci/heroicons for the glyphs it lacks); eslint-canon-fe (icon.mjs) admits @heroicons/react/24/outline and /16/solid.'
+  '@dicebear/core':
+    version: 10.4.0
+    group: ui
+    side: fe
+    why: 'runtime dependency of @starci/grammar for its seeded circle avatars; apps use the Avatar seed prop and never declare or import @dicebear/*; pinned with @dicebear/styles.'
+  '@dicebear/styles':
+    version: 10.4.0
+    group: ui
+    side: fe
+    why: 'runtime dependency of @starci/grammar supplying its fixed avatar DNA style; apps use the Avatar seed prop and never declare or import @dicebear/*; pinned with @dicebear/core.'
   'next-themes':
     version: 0.4.6
     group: ui
@@ -481,6 +502,16 @@ pins:
     group: framework
     side: be
     why: 'the Apollo driver of @nestjs/graphql; the full-app resolution on 2026-10-13. Stays on 13.x with @nestjs/graphql (accepted advisory, major deferred to alpha.19).'
+  '@aws-sdk/client-s3':
+    version: 3.1150.0
+    group: framework
+    side: be
+    why: 'the S3 transport of integrations/object-storage, the one ObjectStorage adapter of both editions (MinIO, S3, Spaces, Supabase Storage); 3.1150.0 is the release of 2026-10-12, chosen over newer ones that had not aged two weeks.'
+  '@aws-sdk/s3-request-presigner':
+    version: 3.1150.0
+    group: framework
+    side: be
+    why: 'signs the presigned PUT and GET of integrations/object-storage locally, the same release as client-s3.'
   '@apollo/server':
     version: 5.5.1
     group: framework
@@ -496,6 +527,31 @@ pins:
     group: framework
     side: be
     why: 'the socket.io platform of @nestjs/websockets; the @nestjs/core pin line.'
+  socket.io:
+    version: 4.8.3
+    group: framework
+    side: be
+    why: 'the socket.io server the IoAdapter of platform/realtime builds (types and the adapter contract); the exact version @nestjs/platform-socket.io 11.2.5 depends on, so the workspace keeps one copy (4.8.4 is the latest on 2026-10-24).'
+  '@socket.io/postgres-adapter':
+    version: 0.5.0
+    group: framework
+    side: be
+    why: 'the stateless socket.io adapter of a back end without Redis that runs several api replicas (LISTEN/NOTIFY, no sticky sessions, websocket only), imported only by platform/realtime (knowledge/patterns/be/realtime.yaml BE-REALTIME-7); the latest registry version on 2026-10-24.'
+  '@socket.io/redis-adapter':
+    version: 8.3.0
+    group: framework
+    side: be
+    why: 'the sharded Redis adapter (createShardedAdapter, Redis 7 or later) of a back end with Redis declared that runs several api replicas, imported only by platform/realtime; the latest registry version on 2026-10-24.'
+  ioredis:
+    version: 5.11.1
+    group: framework
+    side: be
+    why: 'the one Redis client of a back end: the cache, the optional peer bullmq loads for the queue of platform/queue, and the Redis hub and sharded socket.io adapter of platform/realtime (its docs recommend ioredis over redis); the latest 5.x on 2026-10-24, because typeorm 0.3.31 declares ioredis ^5.0.4 as a peer and ioredis 6.0.0 (the latest) does not satisfy it.'
+  '@types/pg':
+    version: 8.23.1
+    group: framework
+    side: be
+    why: 'the types of the pg driver the Postgres hub of platform/realtime opens a LISTEN connection with; the pg pin line, the latest registry version on 2026-10-24.'
   '@as-integrations/express5':
     version: 1.1.2
     group: framework

package/runtime/knowledge/hfs/fe-stack.yaml

@@ -19,7 +19,14 @@ concerns:
     home: [fe.modules.api, fe.transport.client, fe.transport.outcome]
     pattern: FE-API-GRAPHQL
     forbids: [urql, graphql-request, '@urql/core', graphql-hooks, apollo-boost]
-    why: one file per operation under modules/api/graphql/{queries,mutations}, run by the auth or no-auth Apollo client with the link chain.
+    why: one file per operation under modules/api/graphql/{queries,mutations,subscriptions}, run by the auth or no-auth Apollo client with the link chain.
+  - id: graphql-subscriptions
+    tier: opt
+    packages: [graphql-ws]
+    home: [fe.transport.client, fe.package.api.client]
+    pattern: FE-REALTIME
+    forbids: []
+    why: the subscription transport of a GraphQL subscription door (be.feature.realtime.graphql); only the Apollo clients folder imports it (GraphQLWsLink of @apollo/client/link/subscriptions), a subscription operation runs on that client and a useSubscribe hook of hooks/swr reads it.
   - id: codegen
     tier: core
     packages: ['@graphql-codegen/cli', '@graphql-codegen/client-preset']
@@ -74,8 +81,8 @@ concerns:
     packages: [socket.io-client, eventemitter2]
     home: [fe.hooks.socketio]
     pattern: FE-REALTIME
-    forbids: [graphql-ws, subscriptions-transport-ws, '@supabase/realtime-js', pusher-js, ably]
-    why: one socket.io-client singleton per namespace and one side-effect component that dispatches to redux and SWR; lite runs the gateway in the be api process. A one-way channel served as server-sent events needs no package, only a fetch reader in modules/api/sse and a use<Channel>Stream hook (FE-REALTIME).
+    forbids: [subscriptions-transport-ws, '@supabase/realtime-js', pusher-js, ably]
+    why: one socket.io-client singleton per namespace and one side-effect component that dispatches to redux and SWR; both editions run the gateway in the be api process. A one-way channel served as server-sent events needs no package, only a stream reader in modules/api/sse/clients, a stream operation in modules/api/sse and a useSubscribe<Channel>Swr hook (FE-REALTIME).
   - id: auth
     tier: core
     packages: []
@@ -89,7 +96,7 @@ concerns:
     home: [fe.modules.i18n]
     pattern: FE-I18N
     forbids: [i18next, react-i18next, next-i18next, react-intl, '@lingui/react']
-    why: useTranslations for copy and the next-intl formatter for numbers, dates and currency.
+    why: useTranslations for copy and the next-intl formatter for numbers, fixed dates and currency; FE-DATE owns live time display.
   - id: ui
     tier: core
     packages: ['@heroui/react', '@heroui/styles', tailwindcss, '@starci/grammar']
@@ -107,6 +114,17 @@ concerns:
       one application icon set, the heroicons family (owner ruling 2026-10-13), on the 24/outline and 16/solid cuts. @heroicons/react
       is the base set and is used first; @starci/heroicons holds only the glyphs heroicons lacks (brand or domain glyphs drawn in
       heroicons style), never duplicates a heroicons glyph, and a missing glyph is added to it.
+  - id: avatar-illustration
+    tier: opt
+    packages: ['@starci/grammar']
+    home: [fe.components]
+    pattern: FE-UI
+    forbids: ['@dicebear/*', boring-avatars, 'react-nice-avatar', multiavatar]
+    why: >-
+      Grammar owns circle avatars: pass the uploaded avatar as src, otherwise pass the user or identity id as seed on
+      Avatar, AvatarButton or AvatarGroup members. Grammar renders deterministic DiceBear images with its fixed DNA style;
+      @dicebear/core and @dicebear/styles are Grammar runtime dependencies pinned in canon-pins.yaml. Apps declare and
+      import @starci/grammar, never @dicebear/*, and draw no avatar visuals. With neither src nor seed, initials remain.
   - id: theme
     tier: core
     packages: [next-themes]
@@ -127,7 +145,7 @@ concerns:
     home: [fe.modules]
     pattern: FE-DATE
     forbids: [moment, moment-timezone, date-fns, luxon]
-    why: dayjs (modules/dayjs) for date math and parsing; display through the next-intl formatter.
+    why: FE-DATE owns application date math, fixed date formatting and Grammar's live time display.
   - id: numbers
     tier: opt
     packages: [decimal.js]