@starci/eslint-canon-fe 8.4.39 → 8.4.41

package/index.mjs

@@ -13,6 +13,7 @@
  * would leave two names for one rule and no way to tell which a message came from.
  */
 import { createRequire } from "node:module"
+import { recommended as appShellRecommended, rules as appShellRules } from "./app-shell.mjs"
 import { join } from "node:path"
 import { pathToFileURL } from "node:url"
 import { recommended as brandValuesRecommended, rules as brandValuesRules } from "./brand-values.mjs"
@@ -31,6 +32,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 +42,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"
@@ -54,6 +57,7 @@ import { why } from "./lib/why.mjs"
 
 /** Each law's contribution, kept separate so a duplicate name is detectable rather than silent. */
 const CONTRIBUTIONS = [
+  { law: "app-shell", rules: appShellRules, recommended: appShellRecommended },
     { law: "project-graph", rules: projectGraphRules, recommended: projectGraphRecommended },
   { law: "brand-values", rules: brandValuesRules, recommended: brandValuesRecommended },
   { law: "client-boundary", rules: clientBoundaryRules, recommended: clientBoundaryRecommended },
@@ -75,6 +79,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 +89,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/app-shell-cluster.mjs

@@ -0,0 +1,66 @@
+/** The static alternatives of the app bar's right cluster, preserving conditional branches. */
+import { clusterRole, grammarName, isBarControl, propOf, textProp } from "./app-shell.mjs"
+import { visitVisible } from "./app-shell-visible.mjs"
+
+const controlsOf = (context, expression, choices, shellHeader = false) => {
+  const controls = []
+  const branches = []
+  let ownsBar = false
+  visitVisible(context, expression, (opening, name, ancestors) => {
+    if (shellHeader && ["TopBar", "NavigationFeatureNav"].includes(name)) { ownsBar = true; return false }
+    if (!isBarControl(context, opening, name)) return
+    const role = clusterRole(context, opening, name)
+    controls.push(controlSignature(context, opening, name, role, ancestors))
+    return false
+  }, new Set(), (node) => {
+    if (!choices.has(node)) branches.push(node)
+    return choices.get(node) ?? "consequent"
+  })
+  return { controls, branches, ownsBar }
+}
+
+const controlSignature = (context, opening, name, role, ancestors) => {
+  const signature = `${role ?? "unknown"}:${name}`
+  const expected = { language: "DropdownMenu", notifications: "Popover", account: "DropdownMenu" }[role]
+  const disclosure = [...ancestors].reverse().map((ancestor) => grammarName(context, ancestor)).find((parent) => parent === "DropdownMenu" || parent === "Popover")
+  if (expected && disclosure !== expected) return `${signature}:wrong-disclosure`
+  if (role === "language") {
+    const variant = propOf(context, opening, "variant")
+    if (!variant.known || variant.value !== null && textProp(context, opening, "variant") !== "tertiary") return `${signature}:wrong-variant`
+  }
+  return signature
+}
+
+const rightGroup = (context, expression, choices) => {
+  let group = null
+  let count = Number.POSITIVE_INFINITY
+  const roles = controlsOf(context, expression, choices).controls.filter((role) => !role.startsWith("unknown:"))
+  visitVisible(context, expression, (opening, name) => {
+    if (isBarControl(context, opening, name)) return false
+    const result = controlsOf(context, opening.parent, choices)
+    const known = result.controls.filter((role) => !role.startsWith("unknown:"))
+    if (roles.length > 0 && known.length === roles.length && roles.every((role) => known.includes(role)) && result.controls.length < count) {
+      group = opening.parent
+      count = result.controls.length
+    }
+  }, new Set(), (node) => choices.get(node) ?? "consequent")
+  return group ?? expression
+}
+
+/** Every reachable branch yields its own sequence; shell headers select the narrowest right-hand group. */
+export const clusterAlternatives = (context, expression, shellHeader) => {
+  const pending = [new Map()]
+  const alternatives = []
+  while (pending.length) {
+    const choices = pending.pop()
+    const initial = controlsOf(context, expression, choices, shellHeader)
+    if (initial.ownsBar) return { alternatives: [], ownsBar: true }
+    const group = shellHeader ? rightGroup(context, expression, choices) : expression
+    const result = controlsOf(context, group, choices)
+    const unknown = [...initial.branches, ...result.branches].find((node) => !choices.has(node))
+    if (unknown) {
+      pending.push(new Map([...choices, [unknown, "alternate"]]), new Map([...choices, [unknown, "consequent"]]))
+    } else alternatives.push(result.controls)
+  }
+  return { alternatives, ownsBar: false }
+}

package/lib/app-shell-create.mjs

@@ -0,0 +1,33 @@
+/** Static create-action semantics in a bar's controls and its attached menu declarations. */
+import { fileURLToPath } from "node:url"
+import { phrasesOf } from "../runtime/scripts/lib/source-phrases.mjs"
+import { escapeRegExp } from "../runtime/scripts/lib/regex.mjs"
+import { resolveLocal } from "./app-shell.mjs"
+
+const runtimeRoot = fileURLToPath(new URL("../runtime/", import.meta.url))
+const localizedLabels = phrasesOf("appShell.product", runtimeRoot)
+if (localizedLabels.length === 0) throw new Error("The FE canon's app-shell create-action phrase catalog is missing: regenerate the runtime bundle.")
+const localizedCreate = localizedLabels.map((label) => escapeRegExp(label).replace(/\s+/g, String.raw`\s*`)).join("|")
+const CREATE_WORDS = new RegExp(String.raw`\bcreate\b|\bnew\s+(?:item|record|project|task)|${localizedCreate}`, "i")
+
+/** Literal create labels and conventional create handlers are executable static evidence. */
+export const isCreateAction = (text) => CREATE_WORDS.test(text.normalize("NFC")) || /\bcreate[A-Z]|\bnew[A-Z]|\bonCreate|\bhandleCreate/.test(text)
+
+const ACTION_FIELDS = new Set(["id", "key", "label", "title", "textValue", "onAction", "onPress", "onClick", "action"])
+
+/** Follow static item/section arrays; inspect labels and handlers where a menu action is declared. */
+export const menuHasCreate = (context, expression, seen = new Set()) => {
+  const node = resolveLocal(context, expression)
+  if (!node || seen.has(node)) return false
+  seen.add(node)
+  if (node.type === "SpreadElement") return menuHasCreate(context, node.argument, seen)
+  if (node.type === "ArrayExpression") return node.elements.some((item) => menuHasCreate(context, item, seen))
+  if (node.type !== "ObjectExpression") return false
+  return node.properties.some((property) => {
+    if (property.type === "SpreadElement") return menuHasCreate(context, property.argument, seen)
+    const name = property.key.name ?? property.key.value
+    const value = resolveLocal(context, property.value)
+    if (ACTION_FIELDS.has(name) && value?.range && isCreateAction(context.sourceCode.getText(value))) return true
+    return menuHasCreate(context, property.value, seen)
+  })
+}

package/lib/app-shell-owner-source.mjs

@@ -0,0 +1,124 @@
+/** Resolve only an imported header's owned source and selected public export. */
+import fs from "node:fs"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import ts from "typescript"
+import parser from "@typescript-eslint/parser"
+import { SourceCode } from "eslint"
+import { importOf, variableOf } from "./bindings.mjs"
+import { resolveImport } from "./scope.mjs"
+import { hfsOf } from "./hfs.mjs"
+import { walk } from "./ast.mjs"
+import { loadArchitectureConfig } from "../runtime/scripts/hfs/architecture/config.mjs"
+import { workspaceSourceEntry } from "../runtime/scripts/hfs/architecture/typescript.mjs"
+import { openHfs } from "../runtime/scripts/hfs/slots.mjs"
+
+const RUNTIME = fileURLToPath(new URL("../runtime/", import.meta.url))
+const roots = new WeakMap()
+const origins = new WeakMap()
+
+const stateOf = (context) => {
+  const root = hfsOf(context).repoRoot
+  const snapshot = origins.get(context.sourceCode) ?? context.sourceCode
+  if (!roots.has(snapshot)) roots.set(snapshot, { root, files: new Map(), proofs: new Map(), workspaces: null })
+  return roots.get(snapshot)
+}
+
+const workspaceFile = (context, source) => {
+  const state = stateOf(context)
+  if (!state.workspaces) {
+    const hfs = openHfs({ root: RUNTIME, repoRoot: state.root })
+    const config = loadArchitectureConfig(state.root, { hfs })
+    state.workspaces = config.workspaces.map((relative) => {
+      const root = path.join(state.root, relative)
+      const manifest = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"))
+      return { root, workspace: true, name: manifest.name, manifest, exports: manifest.exports }
+    })
+  }
+  const workspace = state.workspaces.find((entry) => entry.name && (source === entry.name || source.startsWith(`${entry.name}/`)))
+  return workspace ? workspaceSourceEntry(ts, workspace, source) : null
+}
+
+const sourceFile = (context, source) => {
+  const target = resolveImport(context, source) ?? workspaceFile(context, source)
+  if (!target) return null
+  const hfs = hfsOf(context)
+  return [target, `${target}.tsx`, `${target}.ts`, `${target}/index.tsx`, `${target}/index.ts`]
+    .find((file) => /\.[cm]?[jt]sx?$/i.test(file) && !/\.d\.[cm]?ts$/i.test(file) && ts.sys.fileExists(file) && hfs.classify(file).status === "owned") ?? null
+}
+
+const sourceContext = (context, filename) => {
+  const state = stateOf(context)
+  if (state.files.has(filename)) return state.files.get(filename)
+  const text = fs.readFileSync(filename, "utf8")
+  const parsed = parser.parseForESLint(text, { filePath: filename, sourceType: "module", ecmaFeatures: { jsx: true }, range: true, loc: true, tokens: true, comment: true })
+  const sourceCode = new SourceCode({ text, ast: parsed.ast, scopeManager: parsed.scopeManager, visitorKeys: parsed.visitorKeys, parserServices: parsed.services })
+  walk(sourceCode, parsed.ast, (node) => {
+    for (const key of sourceCode.visitorKeys[node.type] ?? []) {
+      const values = Array.isArray(node[key]) ? node[key] : [node[key]]
+      for (const child of values) if (child?.type) child.parent = node
+    }
+  })
+  const owned = { filename, sourceCode, settings: context.settings }
+  origins.set(sourceCode, origins.get(context.sourceCode) ?? context.sourceCode)
+  state.files.set(filename, owned)
+  return owned
+}
+
+const moduleContext = (context, source) => {
+  const filename = sourceFile(context, source)
+  return filename ? sourceContext(context, filename) : null
+}
+
+const namedDeclaration = (declaration, name) => {
+  if (declaration?.type === "FunctionDeclaration") return declaration.id?.name === name ? declaration : null
+  if (declaration?.type !== "VariableDeclaration") return null
+  return declaration.declarations.find((entry) => entry.id.type === "Identifier" && entry.id.name === name)?.init ?? null
+}
+
+const namedExport = (context, statement, name, visited) => {
+  const value = namedDeclaration(statement.declaration, name)
+  if (value) return { matched: true, owner: { context, value } }
+  const specifier = statement.specifiers.find((entry) => (entry.exported.name ?? entry.exported.value) === name)
+  if (!specifier) return { matched: false }
+  if (!statement.source) return { matched: true, owner: { context, value: specifier.local } }
+  const target = moduleContext(context, String(statement.source.value))
+  return { matched: true, owner: target ? headerExport(target, specifier.local.name ?? specifier.local.value, visited) : null }
+}
+
+/** The selected exported value, following public barrels without scanning unrelated imported implementations. */
+const headerExport = (context, name, seen = new Set()) => {
+  const key = `${context.filename}:${name}`
+  if (seen.has(key)) return null
+  const visited = new Set(seen).add(key)
+  for (const statement of context.sourceCode.ast.body) {
+    if (statement.type === "ExportDefaultDeclaration" && name === "default") return { context, value: statement.declaration }
+    if (statement.type === "ExportNamedDeclaration") {
+      const found = namedExport(context, statement, name, visited)
+      if (found.matched) return found.owner
+    }
+    if (statement.type === "ExportAllDeclaration") {
+      const target = moduleContext(context, String(statement.source.value))
+      const found = target && headerExport(target, name, visited)
+      if (found) return found
+    }
+  }
+  return null
+}
+
+/** An imported JSX owner, or null when its implementation cannot be proved from owned source. */
+export const importedHeader = (context, opening) => {
+  const name = opening.name
+  const identifier = name.type === "JSXIdentifier" ? name : name.object
+  if (identifier?.type !== "JSXIdentifier") return null
+  const imported = importOf(context, identifier)
+  if (!imported) return null
+  const definition = variableOf(context, identifier)?.defs.find((entry) => entry.type === "ImportBinding")
+  if (name.type === "JSXMemberExpression" && definition?.node.type !== "ImportNamespaceSpecifier") return null
+  const target = moduleContext(context, imported.source)
+  const exported = name.type === "JSXMemberExpression" ? name.property.name : imported.imported ?? "default"
+  return target ? headerExport(target, exported) : null
+}
+
+/** The per-repository proof cache shares the same lifetime as parsed header source. */
+export const headerProofs = (context) => stateOf(context).proofs

package/lib/app-shell-owner.mjs

@@ -0,0 +1,65 @@
+/** Imported header delegation requires an actual canonical bar in every visible source alternative. */
+import { functionOf, importOf } from "./bindings.mjs"
+import { isBarControl, resolveLocal } from "./app-shell.mjs"
+import { visitFunction } from "./app-shell-visible.mjs"
+import { headerProofs, importedHeader } from "./app-shell-owner-source.mjs"
+
+const OVERLAYS = new Set(["Dialog", "AlertDialog", "Drawer", "Popover", "DropdownMenu", "Tooltip"])
+
+const importBinding = (context, opening) => {
+  const name = opening.name.type === "JSXMemberExpression" ? opening.name.object : opening.name
+  return name.type === "JSXIdentifier" ? importOf(context, name) : null
+}
+
+const reactFragment = (context, opening) => {
+  const imported = importBinding(context, opening)
+  return imported?.source === "react" && (imported.imported === "Fragment" || opening.name.type === "JSXMemberExpression" && opening.name.property.name === "Fragment")
+}
+
+const proveOwner = (owner, seen) => {
+  if (!owner) return false
+  const { context, value } = owner
+  const key = `${context.filename}:${value.range?.join(":")}`
+  const proofs = headerProofs(context)
+  if (proofs.has(key)) return proofs.get(key)
+  if (seen.has(key)) return false
+  const fn = functionOf(context, resolveLocal(context, value))
+  const valid = Boolean(fn) && proveReturns(context, fn, new Set(seen).add(key))
+  proofs.set(key, valid)
+  return valid
+}
+
+const proveReturns = (context, fn, seen) => {
+  const pending = [new Map()]
+  while (pending.length) {
+    const choices = pending.pop()
+    const branch = []
+    let bar = false
+    let unknown = false
+    visitFunction(context, fn, (opening, name) => {
+      if (reactFragment(context, opening)) return
+      if (["TopBar", "NavigationFeatureNav"].includes(name)) { bar = true; return false }
+      if (OVERLAYS.has(name)) return false
+      if (["header", "nav", "main"].includes(name) || isBarControl(context, opening, name)) { unknown = true; return false }
+      if (name === null && importBinding(context, opening)) {
+        if (proveOwner(importedHeader(context, opening), seen)) bar = true
+        else unknown = true
+        return false
+      }
+    }, new Set(), (node) => {
+      if (!choices.has(node)) branch.push(node)
+      return choices.get(node) ?? "consequent"
+    }, [])
+    const missing = branch.find((node) => !choices.has(node))
+    if (missing) pending.push(new Map([...choices, [missing, "alternate"]]), new Map([...choices, [missing, "consequent"]]))
+    else if (!bar || unknown) return false
+  }
+  return true
+}
+
+/** True only for an imported JSX header whose owned implementation reaches a canonical Grammar bar. */
+export const provesImportedBar = (context, opening) => {
+  if (reactFragment(context, opening)) return null
+  if (!importBinding(context, opening)) return null
+  return proveOwner(importedHeader(context, opening), new Set())
+}

package/lib/app-shell-scope.mjs

@@ -0,0 +1,79 @@
+/** Structural app-shell ownership, distinct from generic flow-based site chrome. */
+import { walk } from "./ast.mjs"
+import { kindOfFile, roleOfFile } from "./scope.mjs"
+import { grammarName, propOf, textProp } from "./app-shell.mjs"
+import { visitVisible } from "./app-shell-visible.mjs"
+
+/** A workspace identity or a sidebar/navigation slot identifies an application shell structurally. */
+export const isAppShell = (context, opening) => {
+  if (grammarName(context, opening) !== "WorkspaceShell") return false
+  const viewport = textProp(context, opening, "viewport")
+  if (viewport === "fixed" || viewport !== "flow" && ownsAppFrame(context, opening)) return true
+  const navigation = propOf(context, opening, "navigation")
+  if (navigation.value !== null || !navigation.known) return true
+  let identity = false
+  visitVisible(context, propOf(context, opening, "header").value, (_node, name) => {
+    if (name === "IdentityLockup") identity = true
+  })
+  return identity
+}
+
+/** A left Drawer containing a drawer Sidebar is the mobile navigation opener, including an extracted client owner. */
+export const isNavigationDrawer = (context, opening) => {
+  if (grammarName(context, opening) !== "Drawer" || textProp(context, opening, "placement") !== "left") return false
+  let sidebar = false
+  const inspect = (node, name) => {
+    if (name === "Sidebar" && textProp(context, node, "presentation") === "drawer") sidebar = true
+  }
+  for (const child of opening.parent.children) visitVisible(context, child, inspect)
+  visitVisible(context, propOf(context, opening, "children").value, inspect)
+  return sidebar
+}
+
+/** Shell-named React owners and the HFS layout kind compose an app frame, rather than page-local navigation. */
+export const ownsAppFrame = (context, node) => {
+  if (kindOfFile(context) === "layouts" || roleOfFile(context) === "layout") return true
+  let rendered = null
+  let shellName = false
+  for (let current = node.parent; current; current = current.parent) {
+    if (current.type === "ReturnStatement") rendered = current.argument
+    if (current.type === "FunctionDeclaration") { shellName = /Shell(?:Base)?$/.test(current.id?.name ?? ""); break }
+    if (current.type === "ArrowFunctionExpression" || current.type === "FunctionExpression") {
+      rendered ??= current.body
+      shellName = current.parent?.type === "VariableDeclarator" && /Shell(?:Base)?$/.test(current.parent.id.name ?? "")
+      break
+    }
+  }
+  if (shellName) return true
+  let sidebar = false
+  visitVisible(context, rendered, (_opening, name) => { if (name === "Sidebar") sidebar = true })
+  return sidebar
+}
+
+const APP_BAR_CACHE = new WeakMap()
+
+/** Every visible opening hosted by a structurally identified app shell in this source file. */
+export const appBarOpenings = (context) => {
+  const source = context.sourceCode
+  if (APP_BAR_CACHE.has(source)) return APP_BAR_CACHE.get(source)
+  const openings = new Set()
+  walk(source, source.ast, (node) => {
+    if (node.type !== "JSXOpeningElement" || !isAppShell(context, node)) return
+    for (const slot of ["header", "compactHeader"]) {
+      visitVisible(context, propOf(context, node, slot).value, (opening) => { openings.add(opening) })
+    }
+  })
+  APP_BAR_CACHE.set(source, openings)
+  return openings
+}
+
+/** Grammar bars are app bars unless an explicit generic flow shell establishes site-chrome ownership. */
+export const isAppBar = (context, opening) => {
+  if (!["TopBar", "NavigationFeatureNav"].includes(grammarName(context, opening))) return false
+  for (let current = opening.parent; current; current = current.parent) {
+    if (current.type !== "JSXElement") continue
+    const shell = current.openingElement
+    if (grammarName(context, shell) === "WorkspaceShell" && textProp(context, shell, "viewport") === "flow" && !isAppShell(context, shell)) return false
+  }
+  return true
+}

package/lib/app-shell-visible.mjs

@@ -0,0 +1,92 @@
+/** Traverse only the visible bar composition and its local React owners. */
+import { functionOf, variableOf } from "./bindings.mjs"
+import { grammarName, propOf, resolveLocal } from "./app-shell.mjs"
+
+const BAR_SLOTS = {
+  WorkspaceShell: ["header", "compactHeader"],
+  TopBar: ["brand", "navigation", "actions"],
+  NavigationFeatureNav: ["identity", "navigation", "actions", "compactNavigationTrigger"],
+  DropdownMenu: ["trigger"],
+  Popover: ["trigger"],
+  Drawer: ["trigger"],
+}
+
+/** Visible JSX composition only: menu, popover and drawer bodies are outside the navbar band. */
+export const visitVisible = (context, expression, visit, seen = new Set(), branch = () => "both", ancestors = []) => {
+  const node = resolveLocal(context, expression)
+  if (!node || seen.has(node)) return
+  const visited = new Set(seen).add(node)
+  const next = (child) => visitVisible(context, child, visit, visited, branch, ancestors)
+  switch (node.type) {
+    case "JSXExpressionContainer": next(node.expression); break
+    case "JSXFragment": for (const child of node.children) next(child); break
+    case "ConditionalExpression": visitConditional(node, next, branch); break
+    case "LogicalExpression": visitLogical(context, node, next, branch); break
+    case "ArrayExpression": for (const item of node.elements) next(item); break
+    case "JSXElement": visitElement(context, node, visit, visited, branch, ancestors); break
+  }
+}
+
+const visitConditional = (node, next, branch) => {
+  const choice = branch(node)
+  if (choice !== "alternate") next(node.consequent)
+  if (choice !== "consequent") next(node.alternate)
+}
+
+const visitLogical = (context, node, next, branch) => {
+  const left = resolveLocal(context, node.left)
+  const known = left?.type === "Literal"
+  let right = node.operator === "&&" ? Boolean(left?.value) : !left?.value
+  if (node.operator === "??") right = left?.value === null
+  if (!known) {
+    const choice = branch(node)
+    if (choice === "both") { next(node.left); next(node.right); return }
+    right = choice === "consequent"
+  }
+  next(right ? node.right : node.left)
+}
+
+const visitElement = (context, node, visit, seen, branch, ancestors) => {
+  const opening = node.openingElement
+  const name = grammarName(context, opening)
+  if (visit(opening, name, ancestors) === false) return
+  const inside = [...ancestors, opening]
+  const next = (child) => visitVisible(context, child, visit, seen, branch, inside)
+  if (name === null && opening.name.type === "JSXIdentifier") {
+    const fn = functionOf(context, resolveLocal(context, opening.name)) ?? variableOf(context, opening.name)?.defs.find((definition) => definition.type === "FunctionName")?.node
+    if (fn) visitFunction(context, fn, visit, seen, branch, inside)
+  }
+  const slots = BAR_SLOTS[name]
+  if (slots) for (const slot of slots) next(propOf(context, opening, slot).value)
+  if (["DropdownMenu", "Popover", "Drawer"].includes(name)) return
+  for (const child of node.children) next(child)
+}
+
+/** Visit a rendered owner's returns with the same branch, overlay and local-binding semantics as inline JSX. */
+export const visitFunction = (context, fn, visit, seen, branch, ancestors) => {
+  if (fn.body.type !== "BlockStatement") return visitVisible(context, fn.body, visit, seen, branch, ancestors)
+  visitStatements(context, fn.body.body, visit, seen, branch, ancestors)
+}
+
+const visitStatements = (context, statements, visit, seen, branch, ancestors) => {
+  for (const statement of statements) {
+    if (statement.type === "ReturnStatement") {
+      visitVisible(context, statement.argument, visit, seen, branch, ancestors)
+      return true
+    }
+    if (statement.type === "BlockStatement" && visitStatements(context, statement.body, visit, seen, branch, ancestors)) return true
+    if (statement.type === "IfStatement") {
+      if (visitIf(context, statement, visit, seen, branch, ancestors)) return true
+    }
+  }
+  return false
+}
+
+const visitIf = (context, statement, visit, seen, branch, ancestors) => {
+  const condition = resolveLocal(context, statement.test)
+  let choice = branch(statement)
+  if (condition?.type === "Literal") choice = condition.value ? "consequent" : "alternate"
+  const consequent = choice !== "alternate" && visitStatements(context, [statement.consequent], visit, seen, branch, ancestors)
+  const alternate = choice !== "consequent" && statement.alternate && visitStatements(context, [statement.alternate], visit, seen, branch, ancestors)
+  return choice === "consequent" && consequent || choice === "alternate" && alternate || consequent && alternate
+}

package/lib/app-shell.mjs

@@ -0,0 +1,148 @@
+/** Static readers for the visible Grammar app-bar composition, including local JSX owners. */
+import { attributeValue, stringOf } from "./ast.mjs"
+import { functionOf, importOf, unwrap, variableOf } from "./bindings.mjs"
+
+const GRAMMAR_SOURCE = /^@starci\/grammar(?:\/|$)/
+/** Grammar controls whose visible hit target belongs to the navbar band's size contract. */
+const BAR_CONTROLS = new Set(["Button", "IconButton", "Switch", "AvatarButton", "PlainPressable", "IdentityLockup", "SearchField", "Input", "TextField", "Select", "TextAction"])
+const BAR_WRAPPERS = new Set(["GrammarRoot", "WorkspaceShell", "TopBar", "NavigationFeatureNav", "Region", "PageContainer", "NavLandmark", "Form", "Fieldset", "Field", "ButtonGroup", "DropdownMenu", "Popover", "Drawer", "Tooltip"])
+const ACTION_PROPS = ["onPress", "onClick", "onAction", "onValueChange", "onSelectionChange", "onSelectedChange", "onChange", "onInputChange"]
+const INTERACTION_PROPS = new Set(["label", "value", "defaultValue", "selectedKey", "selectedKeys", "selectionMode", "href", ...ACTION_PROPS])
+
+/** Bar policy also counts labelled/value/selection/action field owners, so an extra control cannot vanish from the cluster. */
+export const isBarControl = (context, opening, name) => {
+  if (BAR_CONTROLS.has(name)) return true
+  if (!name || !/^[A-Z]/.test(name) || BAR_WRAPPERS.has(name)) return false
+  if (opening.attributes.some((entry) => entry.type === "JSXAttribute" && INTERACTION_PROPS.has(entry.name.name))) return true
+  return [...INTERACTION_PROPS].some((prop) => propOf(context, opening, prop).value !== null)
+}
+/** A literal or constant's initializer, without type-only wrappers. */
+export const resolveLocal = (context, expression, seen = new Set()) => {
+  const node = unwrap(expression)
+  if (node?.type === "MemberExpression") return resolveMember(context, node, seen)
+  if (node?.type === "CallExpression") return resolveCall(context, node, seen)
+  if (!["Identifier", "JSXIdentifier"].includes(node?.type) || seen.has(node)) return node
+  const definition = variableOf(context, node)?.defs.find((entry) => entry.type === "Variable")
+  if (!definition || definition.parent?.kind !== "const") return node
+  seen.add(node)
+  return resolveLocal(context, initializerOf(definition.node, node), seen)
+}
+
+const resolveCall = (context, node, seen) => {
+  if (seen.has(node)) return node
+  seen.add(node)
+  const fn = functionOf(context, resolveLocal(context, node.callee, seen))
+  if (!fn) return node
+  if (fn.body.type !== "BlockStatement") return resolveLocal(context, fn.body, seen)
+  if (fn.body.body.some((statement) => !["VariableDeclaration", "ReturnStatement"].includes(statement.type))) return node
+  const returned = fn.body.body.find((statement) => statement.type === "ReturnStatement")
+  return returned ? resolveLocal(context, returned.argument, seen) : node
+}
+
+const resolveMember = (context, node, seen) => {
+  const key = node.computed ? stringOf(node.property) : node.property.name
+  if (!key) return node
+  const property = objectValue(context, node.object, key, seen)
+  return property.known && property.value !== null ? resolveLocal(context, property.value, seen) : node
+}
+
+const initializerOf = (declaration, node) => {
+  if (declaration.id.type === "ObjectPattern") {
+    const property = declaration.id.properties.find((entry) => entry.type === "Property" && entry.value.name === node.name)
+    if (!property) return node
+    return { type: "MemberExpression", object: declaration.init, property: property.key, computed: property.computed }
+  }
+  return declaration.init
+}
+
+/** The imported Grammar component's name; aliases and namespace imports keep their identity. */
+export const grammarName = (context, opening) => {
+  const name = opening.name
+  if (name.type === "JSXIdentifier") {
+    const canonical = expressionName(context, name)
+    if (canonical) return canonical
+    return variableOf(context, name)?.defs.length ? null : name.name
+  }
+  if (name.type !== "JSXMemberExpression" || name.object.type !== "JSXIdentifier") return null
+  return expressionName(context, { type: "MemberExpression", object: name.object, property: name.property, computed: false })
+}
+
+const expressionName = (context, expression) => {
+  const resolved = resolveLocal(context, expression)
+  if (resolved?.type === "MemberExpression") {
+    return namespaceName(context, resolved.object, resolved.computed ? stringOf(resolved.property) : resolved.property.name)
+  }
+  if (!["Identifier", "JSXIdentifier"].includes(resolved?.type)) return null
+  const imported = importOf(context, resolved)
+  return imported && GRAMMAR_SOURCE.test(imported.source) ? imported.imported : null
+}
+
+const namespaceName = (context, expression, property) => {
+  const object = resolveLocal(context, expression)
+  if (!["Identifier", "JSXIdentifier"].includes(object?.type)) return null
+  const imported = importOf(context, object)
+  return imported && GRAMMAR_SOURCE.test(imported.source) ? property : null
+}
+
+const objectValue = (context, expression, name, seen = new Set()) => {
+  const node = resolveLocal(context, expression)
+  if (node?.type === "ConditionalExpression") return conditionalObjectValue(context, node, name, seen)
+  if (node?.type !== "ObjectExpression" || seen.has(node)) return { known: false, value: null }
+  seen.add(node)
+  let result = { known: true, value: null }
+  for (const property of node.properties) {
+    if (property.type === "SpreadElement") {
+      const spread = objectValue(context, property.argument, name, seen)
+      if (!spread.known || spread.value !== null) result = spread
+    } else if (!property.computed && (property.key.name ?? property.key.value) === name) {
+      result = { known: true, value: property.value }
+    }
+  }
+  return result
+}
+
+const conditionalObjectValue = (context, node, name, seen) => {
+  if (seen.has(node)) return { known: false, value: null }
+  const visited = new Set(seen).add(node)
+  const values = [node.consequent, node.alternate].map((branch) => objectValue(context, branch, name, new Set(visited)))
+  return { known: values.every((value) => value.known && value.value === null), value: null }
+}
+
+/** The effective prop, respecting JSX spread order; unknown later spreads cannot prove a value. */
+export const propOf = (context, opening, name) => {
+  let result = { known: true, value: null }
+  for (const entry of opening.attributes) {
+    if (entry.type === "JSXSpreadAttribute") {
+      const spread = objectValue(context, entry.argument, name)
+      if (!spread.known || spread.value !== null) result = spread
+    } else if (entry.name.name === name) result = { known: true, value: attributeValue(entry), present: true }
+  }
+  return result
+}
+
+/** A statically proven string prop, or null for missing/unknown values. */
+export const textProp = (context, opening, name) => {
+  const prop = propOf(context, opening, name)
+  return prop.known ? stringOf(resolveLocal(context, prop.value)) : null
+}
+
+/** The source spelling is semantic evidence for an icon or action whose translated label is dynamic. */
+export const semanticText = (context, opening) => {
+  const values = ["source", "icon", "label", "aria-label", "id", ...ACTION_PROPS].map((name) => {
+    const prop = propOf(context, opening, name)
+    return prop.value ? context.sourceCode.getText(prop.value) : ""
+  })
+  return values.join(" ")
+}
+
+/** The right-cluster role and the Grammar kind that must draw it. */
+export const clusterRole = (context, opening, name) => {
+  if (name === "Switch") return "theme"
+  if (name === "AvatarButton") return "account"
+  const text = semanticText(context, opening)
+  if (/language|locale|translate/i.test(text)) return "language"
+  if (/notification|bell/i.test(text)) return "notifications"
+  if (/account|avatar|profile/i.test(text)) return "account"
+  if (/theme|darkmode|color.?mode/i.test(text)) return "theme"
+  return null
+}