@starci/eslint-canon-fe 8.4.40 → 8.4.41

package/CHANGELOG.md

@@ -1,6 +1,8 @@
 # Changelog
 
-## Unreleased
+## 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`.

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

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/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/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"
@@ -56,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 },

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