refactor(nav): use M3eMaterialIcon for rail items; keep Theme.Icon elsewhere

Navbar and NavItem icon slots now render Material-only M3eMaterialIcon
(Lit name sync for React 19), not Theme.Icon sprite dispatch.
Theme.Icon delegates its Material branch to M3eMaterialIcon for one sync implementation.

Made-with: Cursor

Author: soyaaroncervantes

src/features/navigation/components/navbar/NavbarItems.tsx

@@ -1,6 +1,6 @@
 import { useNavigate } from '@tanstack/react-router'
 import { Fragment, type ReactNode } from 'react'
-import { Theme } from '@/features/theme/components'
+import { M3eMaterialIcon } from '@/features/theme/components/icon/M3eMaterialIcon'
 import { Nav } from '@/features/theme/components/nav/Nav'
 import type { NavItemProps } from '@/features/theme/components/nav/NavItem'
 import type { NavItemModel } from '../../models/NavItemModel'
@@ -24,7 +24,7 @@ const Item = ({ model, selected, ...props }: ItemProps) => {
       onClick={(event) => model.onClick(event.nativeEvent, { navigate, onActivate })}
       {...model.toAnchorAttrs()}
     >
-      <Theme.Icon slot="icon" name={model.icon} aria-label={model.id} />
+      <M3eMaterialIcon slot="icon" name={model.icon} aria-label={model.id} />
     </Nav.Item>
   )
 }

src/features/theme/components/icon/AGENTS.md

@@ -30,17 +30,20 @@ The renderer choice (Material vs sprite) is an implementation detail and must st
 ## Internal dispatch pattern
 
 - `Icon.tsx` receives `name`.
-- `registry.ts` decides whether the name is a sprite icon.
+- `registry.ts` decides whether the name is a sprite icon; ids must match `public/icons.svg` (see `__tests__/registry.test.ts`).
 - If sprite: render `<svg><use href="...#id" /></svg>`.
-- Otherwise: render `<M3eIcon name={...} />` (with a `useLayoutEffect` sync for React 19 / Lit).
+- Otherwise: render `M3eMaterialIcon` (wraps `M3eIcon` with Lit `name` sync for React 19).
 
-- `registry.ts` lists sprite symbol ids (`SPRITE_ICON_IDS`) that must match `<symbol id="…">` in `public/icons.svg` (see `__tests__/registry.test.ts`).
+## M3E navigation (nav rail / nav bar)
+
+- **`NavbarItems`** and **`NavItem`** (`icon` prop) use **`M3eMaterialIcon`** only — Material Symbols, no sprite registry. Consumers of the navbar should keep `model.icon` / `icon` as Material icon names.
 
 ---
 
 ## Rules
 
-- Keep `Theme.Icon` as the only semantic API.
-- Never branch icon renderer in consumer components.
+- Keep **`Theme.Icon`** as the only **public** icon API for pages, cards, and buttons.
+- Never branch icon renderer in those consumers.
 - Never reintroduce `Icon.Svg` as public API.
 - When you add a symbol to `public/icons.svg`, append its id to `SPRITE_ICON_IDS` in `registry.ts`.
+- Do not use `Theme.Icon` inside **`NavbarItems`** / nav item icon slots until we add explicit sprite support there.

src/features/theme/components/icon/Icon.tsx

@@ -1,6 +1,6 @@
-import { M3eIcon } from '@m3e/react/icon'
+import type { M3eIcon } from '@m3e/react/icon'
 import type { ComponentProps } from 'react'
-import { useLayoutEffect, useRef } from 'react'
+import { M3eMaterialIcon } from './M3eMaterialIcon'
 import { isSpriteIcon } from './registry'
 
 export type ThemeIconProps = Omit<ComponentProps<typeof M3eIcon>, 'name'> & {
@@ -15,16 +15,6 @@ export const ThemeIcon = ({
   color,
   ...props
 }: ThemeIconProps) => {
-  const materialRef = useRef<HTMLElement | null>(null)
-
-  useLayoutEffect(() => {
-    const el = materialRef.current
-    if (!el) return
-    // `m3e-icon` paints from the Lit `name` property inside its shadow tree, not from light-DOM children.
-    // With React 19, @lit/react can leave `name` unset on the element; sync after mount/updates.
-    Object.assign(el, { name })
-  }, [name])
-
   if (isSpriteIcon(name)) {
     const href = `${spriteHref}#${name}`
     return (
@@ -42,5 +32,5 @@ export const ThemeIcon = ({
     )
   }
 
-  return <M3eIcon ref={materialRef} {...props} name={name} />
+  return <M3eMaterialIcon {...props} name={name} />
 }

src/features/theme/components/icon/M3eMaterialIcon.tsx

@@ -0,0 +1,25 @@
+import { M3eIcon } from '@m3e/react/icon'
+import type { ComponentProps } from 'react'
+import { useLayoutEffect, useRef } from 'react'
+
+/**
+ * Material-only icon for M3E nav slots. Bypasses `Theme.Icon` sprite dispatch.
+ *
+ * `m3e-icon` paints from the Lit `name` property in shadow DOM; @lit/react can
+ * leave it unset with React 19 — sync after mount/update.
+ */
+export type M3eMaterialIconProps = Omit<ComponentProps<typeof M3eIcon>, 'name'> & {
+  name: string
+}
+
+export const M3eMaterialIcon = ({ name, ...props }: M3eMaterialIconProps) => {
+  const ref = useRef<HTMLElement | null>(null)
+
+  useLayoutEffect(() => {
+    const el = ref.current
+    if (!el) return
+    Object.assign(el, { name })
+  }, [name])
+
+  return <M3eIcon ref={ref} {...props} name={name} />
+}

src/features/theme/components/nav/AGENTS.md

@@ -188,7 +188,7 @@ export const NavItem = ({ children, className, ...props }: Props) => {
 
   return (
     <M3eNavItem {...props} selected={isSelected} ref={m3eNavItemRef} onChange={onChangeHandler} className={resolvedClassName}>
-      {props.icon && <Theme.Icon slot="icon" name={props.icon} />}
+      {props.icon && <M3eMaterialIcon slot="icon" name={props.icon} />}
       {children}
     </M3eNavItem>
   )

src/features/theme/components/nav/NavItem.tsx

@@ -1,7 +1,7 @@
 import { M3eNavItem } from '@m3e/react/nav-bar'
 import type { ComponentProps, PropsWithChildren } from 'react'
 import { useNavItemController } from '../../hooks/useNavItemController'
-import { ThemeIcon } from '../icon/Icon'
+import { M3eMaterialIcon } from '../icon/M3eMaterialIcon'
 import styles from './nav.module.css'
 
 export type NavItemProps = PropsWithChildren &
@@ -22,7 +22,7 @@ export const NavItem = ({ children, className, ...props }: NavItemProps) => {
       onChange={onChangeHandler}
       className={resolvedClassName}
     >
-      {props.icon && <ThemeIcon slot="icon" name={props.icon} />}
+      {props.icon && <M3eMaterialIcon slot="icon" name={props.icon} />}
       {children}
     </M3eNavItem>
   )