snice 7.2.0 → 7.4.0

package/dist/react/SniceProvider.js

@@ -1,5 +1,5 @@
 /*!
- * snice v7.1.1
+ * snice v7.3.0
  * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.

package/dist/react/SniceRouter.d.ts

@@ -2,6 +2,8 @@ import { type ReactNode, type ReactElement, type ComponentType } from 'react';
 import type { Placard } from './SniceProvider';
 export interface RouteProps {
     path: string;
+    /** Lower values win when route specificity ties. Declaration order is the fallback. */
+    order?: number;
     /** React component OR Snice element tag name (string) */
     page: ComponentType<any> | string;
     /** Single guard function */

package/dist/react/SniceRouter.js

@@ -1,5 +1,5 @@
 /*!
- * snice v7.1.1
+ * snice v7.3.0
  * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.
@@ -83,6 +83,7 @@ function SniceRouter({ mode, context = {}, layout: defaultLayout, loading, fallb
                 guards.push(...props.guards);
             result.push({
                 path: props.path,
+                order: props.order,
                 page: props.page,
                 guards,
                 guardRedirect: props.guardRedirect,
@@ -99,7 +100,7 @@ function SniceRouter({ mode, context = {}, layout: defaultLayout, loading, fallb
             .map((r) => r.placard);
     }, [parsedRoutes]);
     // Build route configs for matching
-    const routeConfigs = useMemo(() => parsedRoutes.map((r, i) => ({ path: r.path, index: i })), [parsedRoutes]);
+    const routeConfigs = useMemo(() => parsedRoutes.map((r, i) => ({ path: r.path, index: i, order: r.order })), [parsedRoutes]);
     // Navigate function
     const navigate = useCallback((path) => {
         if (mode === 'hash') {

package/dist/react/SniceRouter.js.map

@@ -1 +1 @@
-{"version":3,"file":"SniceRouter.js","sources":["../../src/react/SniceRouter.tsx"],"sourcesContent":["import {\n  useState,\n  useEffect,\n  useCallback,\n  useMemo,\n  useRef,\n  type ReactNode,\n  type ReactElement,\n  type ComponentType,\n  Children,\n  isValidElement,\n  createElement,\n} from 'react';\nimport { SniceProvider } from './SniceProvider';\nimport { matchRoutes, type RouteConfig } from './matchRoute';\nimport type { Placard } from './SniceProvider';\n\n// ─── Route component (declarative config) ───\n\nexport interface RouteProps {\n  path: string;\n  /** React component OR Snice element tag name (string) */\n  page: ComponentType<any> | string;\n  /** Single guard function */\n  guard?: (context: Record<string, any>, params: Record<string, string>) => boolean | Promise<boolean>;\n  /** Multiple guards (AND logic) */\n  guards?: Array<(context: Record<string, any>, params: Record<string, string>) => boolean | Promise<boolean>>;\n  /** Redirect path if guard rejects */\n  guardRedirect?: string;\n  /** Layout override. Component, string (Snice tag), or false (no layout) */\n  layout?: ComponentType<{ children: ReactNode }> | string | false;\n  /** Page metadata for layouts */\n  placard?: Placard;\n}\n\n/**\n * Route definition component. Child of <SniceRouter>.\n * Does not render anything — SniceRouter reads its props.\n */\nexport function Route(_props: RouteProps): ReactElement | null {\n  return null;\n}\n\n// ─── SniceRouter ───\n\nexport interface SniceRouterProps {\n  /** URL strategy */\n  mode: 'hash' | 'history';\n  /** Application context passed to guards, pages, layouts */\n  context?: Record<string, any>;\n  /** Default layout component or Snice tag name */\n  layout?: ComponentType<{ children: ReactNode }> | string;\n  /** Loading component shown during async guards. Component, string (Snice tag), or JSX. */\n  loading?: ComponentType | string | ReactNode;\n  /** Fallback when no route matches. Component, string (Snice tag), or JSX. */\n  fallback?: ComponentType | string | ReactNode;\n  children: ReactNode;\n}\n\ninterface ParsedRoute {\n  path: string;\n  page: ComponentType<any> | string;\n  guards: Array<(ctx: Record<string, any>, params: Record<string, string>) => boolean | Promise<boolean>>;\n  guardRedirect?: string;\n  layout?: ComponentType<{ children: ReactNode }> | string | false;\n  placard?: Placard;\n}\n\nfunction getPath(mode: 'hash' | 'history'): string {\n  if (mode === 'hash') {\n    return window.location.hash.slice(1) || '/';\n  }\n  return window.location.pathname;\n}\n\nfunction DefaultLoading() {\n  return createElement('div', {\n    style: {\n      display: 'flex',\n      alignItems: 'center',\n      justifyContent: 'center',\n      height: '100%',\n      minHeight: '200px',\n    },\n  },\n    createElement('style', null, '@keyframes snice-spin{to{transform:rotate(360deg)}}'),\n    createElement('div', {\n      style: {\n        width: '32px',\n        height: '32px',\n        border: '3px solid rgba(128,128,128,0.3)',\n        borderTopColor: 'rgba(128,128,128,0.8)',\n        borderRadius: '50%',\n        animation: 'snice-spin 0.6s linear infinite',\n      },\n    }),\n  );\n}\n\n/** Render a page/layout/loading/fallback prop that can be component, string tag, or JSX */\nfunction renderFlexible(\n  value: ComponentType<any> | string | ReactNode | undefined,\n  props?: Record<string, any>,\n): ReactNode {\n  if (value === undefined || value === null) return null;\n\n  // String = Snice web component tag name\n  if (typeof value === 'string') {\n    return createElement(value, props);\n  }\n\n  // Function = React component\n  if (typeof value === 'function') {\n    return createElement(value as ComponentType<any>, props);\n  }\n\n  // Already JSX/ReactNode\n  return value;\n}\n\n/**\n * Root provider component. Manages URL state, route matching,\n * guard execution, layout selection, and context propagation.\n */\nexport function SniceRouter({\n  mode,\n  context = {},\n  layout: defaultLayout,\n  loading,\n  fallback,\n  children,\n}: SniceRouterProps) {\n  const [currentPath, setCurrentPath] = useState(() => getPath(mode));\n  const [guardState, setGuardState] = useState<'idle' | 'checking' | 'passed' | 'failed'>('idle');\n  const contextRef = useRef(context);\n  contextRef.current = context;\n\n  // Parse Route children into config\n  const parsedRoutes = useMemo<ParsedRoute[]>(() => {\n    const result: ParsedRoute[] = [];\n    Children.forEach(children, (child) => {\n      if (!isValidElement(child) || child.type !== Route) return;\n      const props = child.props as RouteProps;\n      const guards: ParsedRoute['guards'] = [];\n      if (props.guard) guards.push(props.guard);\n      if (props.guards) guards.push(...props.guards);\n      result.push({\n        path: props.path,\n        page: props.page,\n        guards,\n        guardRedirect: props.guardRedirect,\n        layout: props.layout,\n        placard: props.placard,\n      });\n    });\n    return result;\n  }, [children]);\n\n  // Collect placards\n  const placards = useMemo<Placard[]>(() => {\n    return parsedRoutes\n      .filter((r) => r.placard)\n      .map((r) => r.placard!);\n  }, [parsedRoutes]);\n\n  // Build route configs for matching\n  const routeConfigs = useMemo<RouteConfig[]>(\n    () => parsedRoutes.map((r, i) => ({ path: r.path, index: i })),\n    [parsedRoutes],\n  );\n\n  // Navigate function\n  const navigate = useCallback(\n    (path: string) => {\n      if (mode === 'hash') {\n        window.location.hash = path;\n      } else {\n        window.history.pushState(null, '', path);\n        setCurrentPath(path);\n      }\n    },\n    [mode],\n  );\n\n  // Listen for URL changes\n  useEffect(() => {\n    const handler = () => setCurrentPath(getPath(mode));\n    const event = mode === 'hash' ? 'hashchange' : 'popstate';\n    window.addEventListener(event, handler);\n    return () => window.removeEventListener(event, handler);\n  }, [mode]);\n\n  // Match current path\n  const match = useMemo(\n    () => matchRoutes(routeConfigs, currentPath),\n    [routeConfigs, currentPath],\n  );\n\n  const matchedRoute = match ? parsedRoutes[match.index] : null;\n  // Stable params reference across renders so downstream `useMemo` deps\n  // (SniceProvider value, guard effect) don't churn on every render when\n  // nothing actually changed.\n  const params = useMemo(\n    () => match?.params ?? {},\n    // Re-create only when the param content actually changes\n    [JSON.stringify(match?.params ?? {})],\n  );\n\n  // Run guards\n  useEffect(() => {\n    if (!matchedRoute) {\n      setGuardState('idle');\n      return;\n    }\n\n    if (matchedRoute.guards.length === 0) {\n      setGuardState('passed');\n      return;\n    }\n\n    let cancelled = false;\n    setGuardState('checking');\n\n    (async () => {\n      try {\n        for (const guard of matchedRoute.guards) {\n          const result = await guard(contextRef.current, params);\n          if (cancelled) return;\n          if (!result) {\n            setGuardState('failed');\n            if (matchedRoute.guardRedirect) {\n              navigate(matchedRoute.guardRedirect);\n            }\n            return;\n          }\n        }\n        if (!cancelled) setGuardState('passed');\n      } catch {\n        if (!cancelled) {\n          setGuardState('failed');\n          if (matchedRoute.guardRedirect) {\n            navigate(matchedRoute.guardRedirect);\n          }\n        }\n      }\n    })();\n\n    return () => { cancelled = true; };\n  }, [matchedRoute, currentPath]); // eslint-disable-line react-hooks/exhaustive-deps\n\n  // Determine what to render\n  let content: ReactNode;\n\n  if (!matchedRoute) {\n    // No route match → fallback\n    content = renderFlexible(fallback) ?? createElement('div', null, '404 — Page not found');\n  } else if (guardState === 'checking') {\n    // Async guards running → show loading\n    content = renderFlexible(loading) ?? createElement(DefaultLoading);\n  } else if (guardState === 'failed') {\n    // Guard rejected (redirect may have fired) — render nothing\n    content = null;\n  } else {\n    // Guard passed or no guards → render page\n    content = renderFlexible(matchedRoute.page, params);\n  }\n\n  // Apply layout\n  const layoutCandidate = matchedRoute?.layout !== undefined ? matchedRoute.layout : defaultLayout;\n  const layoutToUse = layoutCandidate === false ? undefined : layoutCandidate;\n  if (layoutToUse && content !== null) {\n    content = renderFlexible(\n      layoutToUse as ComponentType<{ children: ReactNode }> | string,\n      { children: content },\n    );\n  }\n\n  return (\n    <SniceProvider\n      context={context}\n      navigate={navigate}\n      route={match?.path ?? ''}\n      params={params}\n      placards={placards}\n    >\n      {content}\n    </SniceProvider>\n  );\n}\n"],"names":["_jsx"],"mappings":"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"}
+{"version":3,"file":"SniceRouter.js","sources":["../../src/react/SniceRouter.tsx"],"sourcesContent":["import {\n  useState,\n  useEffect,\n  useCallback,\n  useMemo,\n  useRef,\n  type ReactNode,\n  type ReactElement,\n  type ComponentType,\n  Children,\n  isValidElement,\n  createElement,\n} from 'react';\nimport { SniceProvider } from './SniceProvider';\nimport { matchRoutes, type RouteConfig } from './matchRoute';\nimport type { Placard } from './SniceProvider';\n\n// ─── Route component (declarative config) ───\n\nexport interface RouteProps {\n  path: string;\n  /** Lower values win when route specificity ties. Declaration order is the fallback. */\n  order?: number;\n  /** React component OR Snice element tag name (string) */\n  page: ComponentType<any> | string;\n  /** Single guard function */\n  guard?: (context: Record<string, any>, params: Record<string, string>) => boolean | Promise<boolean>;\n  /** Multiple guards (AND logic) */\n  guards?: Array<(context: Record<string, any>, params: Record<string, string>) => boolean | Promise<boolean>>;\n  /** Redirect path if guard rejects */\n  guardRedirect?: string;\n  /** Layout override. Component, string (Snice tag), or false (no layout) */\n  layout?: ComponentType<{ children: ReactNode }> | string | false;\n  /** Page metadata for layouts */\n  placard?: Placard;\n}\n\n/**\n * Route definition component. Child of <SniceRouter>.\n * Does not render anything — SniceRouter reads its props.\n */\nexport function Route(_props: RouteProps): ReactElement | null {\n  return null;\n}\n\n// ─── SniceRouter ───\n\nexport interface SniceRouterProps {\n  /** URL strategy */\n  mode: 'hash' | 'history';\n  /** Application context passed to guards, pages, layouts */\n  context?: Record<string, any>;\n  /** Default layout component or Snice tag name */\n  layout?: ComponentType<{ children: ReactNode }> | string;\n  /** Loading component shown during async guards. Component, string (Snice tag), or JSX. */\n  loading?: ComponentType | string | ReactNode;\n  /** Fallback when no route matches. Component, string (Snice tag), or JSX. */\n  fallback?: ComponentType | string | ReactNode;\n  children: ReactNode;\n}\n\ninterface ParsedRoute {\n  path: string;\n  order?: number;\n  page: ComponentType<any> | string;\n  guards: Array<(ctx: Record<string, any>, params: Record<string, string>) => boolean | Promise<boolean>>;\n  guardRedirect?: string;\n  layout?: ComponentType<{ children: ReactNode }> | string | false;\n  placard?: Placard;\n}\n\nfunction getPath(mode: 'hash' | 'history'): string {\n  if (mode === 'hash') {\n    return window.location.hash.slice(1) || '/';\n  }\n  return window.location.pathname;\n}\n\nfunction DefaultLoading() {\n  return createElement('div', {\n    style: {\n      display: 'flex',\n      alignItems: 'center',\n      justifyContent: 'center',\n      height: '100%',\n      minHeight: '200px',\n    },\n  },\n    createElement('style', null, '@keyframes snice-spin{to{transform:rotate(360deg)}}'),\n    createElement('div', {\n      style: {\n        width: '32px',\n        height: '32px',\n        border: '3px solid rgba(128,128,128,0.3)',\n        borderTopColor: 'rgba(128,128,128,0.8)',\n        borderRadius: '50%',\n        animation: 'snice-spin 0.6s linear infinite',\n      },\n    }),\n  );\n}\n\n/** Render a page/layout/loading/fallback prop that can be component, string tag, or JSX */\nfunction renderFlexible(\n  value: ComponentType<any> | string | ReactNode | undefined,\n  props?: Record<string, any>,\n): ReactNode {\n  if (value === undefined || value === null) return null;\n\n  // String = Snice web component tag name\n  if (typeof value === 'string') {\n    return createElement(value, props);\n  }\n\n  // Function = React component\n  if (typeof value === 'function') {\n    return createElement(value as ComponentType<any>, props);\n  }\n\n  // Already JSX/ReactNode\n  return value;\n}\n\n/**\n * Root provider component. Manages URL state, route matching,\n * guard execution, layout selection, and context propagation.\n */\nexport function SniceRouter({\n  mode,\n  context = {},\n  layout: defaultLayout,\n  loading,\n  fallback,\n  children,\n}: SniceRouterProps) {\n  const [currentPath, setCurrentPath] = useState(() => getPath(mode));\n  const [guardState, setGuardState] = useState<'idle' | 'checking' | 'passed' | 'failed'>('idle');\n  const contextRef = useRef(context);\n  contextRef.current = context;\n\n  // Parse Route children into config\n  const parsedRoutes = useMemo<ParsedRoute[]>(() => {\n    const result: ParsedRoute[] = [];\n    Children.forEach(children, (child) => {\n      if (!isValidElement(child) || child.type !== Route) return;\n      const props = child.props as RouteProps;\n      const guards: ParsedRoute['guards'] = [];\n      if (props.guard) guards.push(props.guard);\n      if (props.guards) guards.push(...props.guards);\n      result.push({\n        path: props.path,\n        order: props.order,\n        page: props.page,\n        guards,\n        guardRedirect: props.guardRedirect,\n        layout: props.layout,\n        placard: props.placard,\n      });\n    });\n    return result;\n  }, [children]);\n\n  // Collect placards\n  const placards = useMemo<Placard[]>(() => {\n    return parsedRoutes\n      .filter((r) => r.placard)\n      .map((r) => r.placard!);\n  }, [parsedRoutes]);\n\n  // Build route configs for matching\n  const routeConfigs = useMemo<RouteConfig[]>(\n    () => parsedRoutes.map((r, i) => ({ path: r.path, index: i, order: r.order })),\n    [parsedRoutes],\n  );\n\n  // Navigate function\n  const navigate = useCallback(\n    (path: string) => {\n      if (mode === 'hash') {\n        window.location.hash = path;\n      } else {\n        window.history.pushState(null, '', path);\n        setCurrentPath(path);\n      }\n    },\n    [mode],\n  );\n\n  // Listen for URL changes\n  useEffect(() => {\n    const handler = () => setCurrentPath(getPath(mode));\n    const event = mode === 'hash' ? 'hashchange' : 'popstate';\n    window.addEventListener(event, handler);\n    return () => window.removeEventListener(event, handler);\n  }, [mode]);\n\n  // Match current path\n  const match = useMemo(\n    () => matchRoutes(routeConfigs, currentPath),\n    [routeConfigs, currentPath],\n  );\n\n  const matchedRoute = match ? parsedRoutes[match.index] : null;\n  // Stable params reference across renders so downstream `useMemo` deps\n  // (SniceProvider value, guard effect) don't churn on every render when\n  // nothing actually changed.\n  const params = useMemo(\n    () => match?.params ?? {},\n    // Re-create only when the param content actually changes\n    [JSON.stringify(match?.params ?? {})],\n  );\n\n  // Run guards\n  useEffect(() => {\n    if (!matchedRoute) {\n      setGuardState('idle');\n      return;\n    }\n\n    if (matchedRoute.guards.length === 0) {\n      setGuardState('passed');\n      return;\n    }\n\n    let cancelled = false;\n    setGuardState('checking');\n\n    (async () => {\n      try {\n        for (const guard of matchedRoute.guards) {\n          const result = await guard(contextRef.current, params);\n          if (cancelled) return;\n          if (!result) {\n            setGuardState('failed');\n            if (matchedRoute.guardRedirect) {\n              navigate(matchedRoute.guardRedirect);\n            }\n            return;\n          }\n        }\n        if (!cancelled) setGuardState('passed');\n      } catch {\n        if (!cancelled) {\n          setGuardState('failed');\n          if (matchedRoute.guardRedirect) {\n            navigate(matchedRoute.guardRedirect);\n          }\n        }\n      }\n    })();\n\n    return () => { cancelled = true; };\n  }, [matchedRoute, currentPath]); // eslint-disable-line react-hooks/exhaustive-deps\n\n  // Determine what to render\n  let content: ReactNode;\n\n  if (!matchedRoute) {\n    // No route match → fallback\n    content = renderFlexible(fallback) ?? createElement('div', null, '404 — Page not found');\n  } else if (guardState === 'checking') {\n    // Async guards running → show loading\n    content = renderFlexible(loading) ?? createElement(DefaultLoading);\n  } else if (guardState === 'failed') {\n    // Guard rejected (redirect may have fired) — render nothing\n    content = null;\n  } else {\n    // Guard passed or no guards → render page\n    content = renderFlexible(matchedRoute.page, params);\n  }\n\n  // Apply layout\n  const layoutCandidate = matchedRoute?.layout !== undefined ? matchedRoute.layout : defaultLayout;\n  const layoutToUse = layoutCandidate === false ? undefined : layoutCandidate;\n  if (layoutToUse && content !== null) {\n    content = renderFlexible(\n      layoutToUse as ComponentType<{ children: ReactNode }> | string,\n      { children: content },\n    );\n  }\n\n  return (\n    <SniceProvider\n      context={context}\n      navigate={navigate}\n      route={match?.path ?? ''}\n      params={params}\n      placards={placards}\n    >\n      {content}\n    </SniceProvider>\n  );\n}\n"],"names":["_jsx"],"mappings":"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"}

package/dist/react/index.js

@@ -1,5 +1,5 @@
 /*!
- * snice v7.1.1
+ * snice v7.3.0
  * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.

package/dist/react/matchRoute.d.ts

@@ -2,6 +2,8 @@ import { type RouteParams } from 'pica-route';
 export interface RouteConfig {
     path: string;
     index: number;
+    /** Lower values win when route specificity ties. Defaults to 0. */
+    order?: number;
 }
 export interface MatchResult {
     index: number;
@@ -11,6 +13,7 @@ export interface MatchResult {
 /**
  * Match a URL path against an array of route configs.
  * Uses pica-route — same matching as vanilla Snice's Router.
- * Routes are sorted by per-segment specificity (static > dynamic > wildcard).
+ * Routes are sorted by per-segment specificity (static > dynamic > wildcard),
+ * then optional lower-first order, then declaration order.
  */
 export declare function matchRoutes(routes: RouteConfig[], pathname: string): MatchResult | null;

package/dist/react/matchRoute.js

@@ -1,5 +1,5 @@
 /*!
- * snice v7.1.1
+ * snice v7.3.0
  * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.
@@ -45,11 +45,21 @@ function routeSpecificity(spec) {
 /**
  * Match a URL path against an array of route configs.
  * Uses pica-route — same matching as vanilla Snice's Router.
- * Routes are sorted by per-segment specificity (static > dynamic > wildcard).
+ * Routes are sorted by per-segment specificity (static > dynamic > wildcard),
+ * then optional lower-first order, then declaration order.
  */
 function matchRoutes(routes, pathname) {
+    for (const route of routes) {
+        if (route.order !== undefined && !Number.isFinite(route.order)) {
+            throw new TypeError(`Route order for "${route.path}" must be a finite number.`);
+        }
+    }
     // Sort by specificity (most specific first), same model as the vanilla Router.
-    const sorted = [...routes].sort((a, b) => routeSpecificity(b.path) - routeSpecificity(a.path));
+    const sorted = routes
+        .map((route, registrationOrder) => ({ ...route, registrationOrder }))
+        .sort((a, b) => routeSpecificity(b.path) - routeSpecificity(a.path)
+        || (a.order ?? 0) - (b.order ?? 0)
+        || a.registrationOrder - b.registrationOrder);
     for (const route of sorted) {
         const matcher = new Route(route.path);
         const params = matcher.match(pathname);

package/dist/react/matchRoute.js.map

@@ -1 +1 @@
-{"version":3,"file":"matchRoute.js","sources":["../../src/react/route-specificity.ts","../../src/react/matchRoute.ts"],"sourcesContent":["/**\n * Route specificity scorer for the React binding.\n *\n * IMPORTANT: keep this in exact sync with `src/route-specificity.ts`. The React\n * integration is bundled in isolation (rootDir: src/react) and cannot import\n * across that boundary, so the scorer is mirrored here. The `matchRoutes`\n * resolution tests exercise this copy, so behavioral drift is caught.\n *\n * Scoring is per-segment by ROLE, not string length: a static segment outweighs\n * a dynamic (`:param`) segment, which outweighs a wildcard (`*` / `*name`). So\n * `/post/new` beats `/post/:id`, and a splat always ranks last. Sort callers\n * descending by this score (highest = most specific = first).\n */\nconst STATIC_SEGMENT = 10;\nconst DYNAMIC_SEGMENT = 3;\nconst WILDCARD_SEGMENT = -2;\n\nexport function routeSpecificity(spec: string): number {\n  const segments = spec.split('/').filter(Boolean);\n  // Base on segment count so a deeper path outranks a shallower one on ties.\n  let score = segments.length;\n\n  for (const segment of segments) {\n    if (segment.startsWith('*')) {\n      score += WILDCARD_SEGMENT;\n    } else if (segment.startsWith(':')) {\n      score += DYNAMIC_SEGMENT;\n    } else {\n      score += STATIC_SEGMENT;\n    }\n  }\n\n  return score;\n}\n","import { Route, type RouteParams } from 'pica-route';\nimport { routeSpecificity } from './route-specificity';\n\nexport interface RouteConfig {\n  path: string;\n  index: number;\n}\n\nexport interface MatchResult {\n  index: number;\n  params: RouteParams;\n  path: string;\n}\n\n/**\n * Match a URL path against an array of route configs.\n * Uses pica-route — same matching as vanilla Snice's Router.\n * Routes are sorted by per-segment specificity (static > dynamic > wildcard).\n */\nexport function matchRoutes(routes: RouteConfig[], pathname: string): MatchResult | null {\n  // Sort by specificity (most specific first), same model as the vanilla Router.\n  const sorted = [...routes].sort((a, b) => routeSpecificity(b.path) - routeSpecificity(a.path));\n\n  for (const route of sorted) {\n    const matcher = new Route(route.path);\n    const params = matcher.match(pathname);\n    if (params !== false) {\n      return {\n        index: route.index,\n        params: params as RouteParams,\n        path: route.path,\n      };\n    }\n  }\n\n  return null;\n}\n"],"names":[],"mappings":";;;;;;;;;;AAAA;;;;;;;;;;;;AAYG;AACH,MAAM,cAAc,GAAG,EAAE;AACzB,MAAM,eAAe,GAAG,CAAC;AACzB,MAAM,gBAAgB,GAAG,EAAE;AAErB,SAAU,gBAAgB,CAAC,IAAY,EAAA;AAC3C,IAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;;AAEhD,IAAA,IAAI,KAAK,GAAG,QAAQ,CAAC,MAAM;AAE3B,IAAA,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE;AAC9B,QAAA,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE;YAC3B,KAAK,IAAI,gBAAgB;QAC3B;AAAO,aAAA,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE;YAClC,KAAK,IAAI,eAAe;QAC1B;aAAO;YACL,KAAK,IAAI,cAAc;QACzB;IACF;AAEA,IAAA,OAAO,KAAK;AACd;;ACnBA;;;;AAIG;AACG,SAAU,WAAW,CAAC,MAAqB,EAAE,QAAgB,EAAA;;AAEjE,IAAA,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAE9F,IAAA,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE;QAC1B,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC;QACrC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC;AACtC,QAAA,IAAI,MAAM,KAAK,KAAK,EAAE;YACpB,OAAO;gBACL,KAAK,EAAE,KAAK,CAAC,KAAK;AAClB,gBAAA,MAAM,EAAE,MAAqB;gBAC7B,IAAI,EAAE,KAAK,CAAC,IAAI;aACjB;QACH;IACF;AAEA,IAAA,OAAO,IAAI;AACb;;;;"}
+{"version":3,"file":"matchRoute.js","sources":["../../src/react/route-specificity.ts","../../src/react/matchRoute.ts"],"sourcesContent":["/**\n * Route specificity scorer for the React binding.\n *\n * IMPORTANT: keep this in exact sync with `src/route-specificity.ts`. The React\n * integration is bundled in isolation (rootDir: src/react) and cannot import\n * across that boundary, so the scorer is mirrored here. The `matchRoutes`\n * resolution tests exercise this copy, so behavioral drift is caught.\n *\n * Scoring is per-segment by ROLE, not string length: a static segment outweighs\n * a dynamic (`:param`) segment, which outweighs a wildcard (`*` / `*name`). So\n * `/post/new` beats `/post/:id`, and a splat always ranks last. Sort callers\n * descending by this score (highest = most specific = first).\n */\nconst STATIC_SEGMENT = 10;\nconst DYNAMIC_SEGMENT = 3;\nconst WILDCARD_SEGMENT = -2;\n\nexport function routeSpecificity(spec: string): number {\n  const segments = spec.split('/').filter(Boolean);\n  // Base on segment count so a deeper path outranks a shallower one on ties.\n  let score = segments.length;\n\n  for (const segment of segments) {\n    if (segment.startsWith('*')) {\n      score += WILDCARD_SEGMENT;\n    } else if (segment.startsWith(':')) {\n      score += DYNAMIC_SEGMENT;\n    } else {\n      score += STATIC_SEGMENT;\n    }\n  }\n\n  return score;\n}\n","import { Route, type RouteParams } from 'pica-route';\nimport { routeSpecificity } from './route-specificity';\n\nexport interface RouteConfig {\n  path: string;\n  index: number;\n  /** Lower values win when route specificity ties. Defaults to 0. */\n  order?: number;\n}\n\nexport interface MatchResult {\n  index: number;\n  params: RouteParams;\n  path: string;\n}\n\n/**\n * Match a URL path against an array of route configs.\n * Uses pica-route — same matching as vanilla Snice's Router.\n * Routes are sorted by per-segment specificity (static > dynamic > wildcard),\n * then optional lower-first order, then declaration order.\n */\nexport function matchRoutes(routes: RouteConfig[], pathname: string): MatchResult | null {\n  for (const route of routes) {\n    if (route.order !== undefined && !Number.isFinite(route.order)) {\n      throw new TypeError(`Route order for \"${route.path}\" must be a finite number.`);\n    }\n  }\n  // Sort by specificity (most specific first), same model as the vanilla Router.\n  const sorted = routes\n    .map((route, registrationOrder) => ({ ...route, registrationOrder }))\n    .sort((a, b) =>\n      routeSpecificity(b.path) - routeSpecificity(a.path)\n      || (a.order ?? 0) - (b.order ?? 0)\n      || a.registrationOrder - b.registrationOrder\n    );\n\n  for (const route of sorted) {\n    const matcher = new Route(route.path);\n    const params = matcher.match(pathname);\n    if (params !== false) {\n      return {\n        index: route.index,\n        params: params as RouteParams,\n        path: route.path,\n      };\n    }\n  }\n\n  return null;\n}\n"],"names":[],"mappings":";;;;;;;;;;AAAA;;;;;;;;;;;;AAYG;AACH,MAAM,cAAc,GAAG,EAAE;AACzB,MAAM,eAAe,GAAG,CAAC;AACzB,MAAM,gBAAgB,GAAG,EAAE;AAErB,SAAU,gBAAgB,CAAC,IAAY,EAAA;AAC3C,IAAA,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;;AAEhD,IAAA,IAAI,KAAK,GAAG,QAAQ,CAAC,MAAM;AAE3B,IAAA,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE;AAC9B,QAAA,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE;YAC3B,KAAK,IAAI,gBAAgB;QAC3B;AAAO,aAAA,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE;YAClC,KAAK,IAAI,eAAe;QAC1B;aAAO;YACL,KAAK,IAAI,cAAc;QACzB;IACF;AAEA,IAAA,OAAO,KAAK;AACd;;ACjBA;;;;;AAKG;AACG,SAAU,WAAW,CAAC,MAAqB,EAAE,QAAgB,EAAA;AACjE,IAAA,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE;AAC1B,QAAA,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;YAC9D,MAAM,IAAI,SAAS,CAAC,CAAA,iBAAA,EAAoB,KAAK,CAAC,IAAI,CAAA,0BAAA,CAA4B,CAAC;QACjF;IACF;;IAEA,MAAM,MAAM,GAAG;AACZ,SAAA,GAAG,CAAC,CAAC,KAAK,EAAE,iBAAiB,MAAM,EAAE,GAAG,KAAK,EAAE,iBAAiB,EAAE,CAAC;SACnE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KACT,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,IAAI;AAC/C,WAAA,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAAC;AAC9B,WAAA,CAAC,CAAC,iBAAiB,GAAG,CAAC,CAAC,iBAAiB,CAC7C;AAEH,IAAA,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE;QAC1B,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC;QACrC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC;AACtC,QAAA,IAAI,MAAM,KAAK,KAAK,EAAE;YACpB,OAAO;gBACL,KAAK,EAAE,KAAK,CAAC,KAAK;AAClB,gBAAA,MAAM,EAAE,MAAqB;gBAC7B,IAAI,EAAE,KAAK,CAAC,IAAI;aACjB;QACH;IACF;AAEA,IAAA,OAAO,IAAI;AACb;;;;"}

package/dist/react/useRequestHandler.js

@@ -1,5 +1,5 @@
 /*!
- * snice v7.1.1
+ * snice v7.3.0
  * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.

package/dist/symbols.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v7.1.1
+ * snice v7.3.0
  * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.

package/dist/symbols.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v7.1.1
+ * snice v7.3.0
  * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.

package/dist/testing-dom.cjs

@@ -0,0 +1,48 @@
+/*!
+ * snice v7.3.0
+ * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
+ * (c) 2024
+ * Released under the MIT License.
+ *
+ * GENERATED FILE — DO NOT EDIT. Source: src/. Rebuild: npm run build:core
+ */
+'use strict';
+
+/**
+ * Standards-shaped DOM compatibility for non-browser test runners.
+ *
+ * This module only fills missing IDL surface. It never replaces an existing
+ * implementation and does not attempt to simulate layout, paint, or browser
+ * focus navigation.
+ */
+/**
+ * Fill proven DOM-runner IDL gaps without replacing native implementations.
+ * Safe to call more than once.
+ */
+function installDOMTestingCompatibility(scope = globalThis) {
+    const installed = [];
+    const HTMLElementConstructor = scope.HTMLElement;
+    if (!HTMLElementConstructor)
+        return { installed };
+    const prototype = HTMLElementConstructor.prototype;
+    if (!('autofocus' in prototype)) {
+        Object.defineProperty(prototype, 'autofocus', {
+            configurable: true,
+            enumerable: true,
+            get() {
+                return this.hasAttribute('autofocus');
+            },
+            set(value) {
+                this.toggleAttribute('autofocus', Boolean(value));
+            },
+        });
+        installed.push('HTMLElement.autofocus');
+    }
+    return { installed };
+}
+/** Result of the side-effect installation performed by `snice/testing/dom`. */
+const domTestingCompatibility = installDOMTestingCompatibility();
+
+exports.domTestingCompatibility = domTestingCompatibility;
+exports.installDOMTestingCompatibility = installDOMTestingCompatibility;
+//# sourceMappingURL=testing-dom.cjs.map

package/dist/testing-dom.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing-dom.cjs","sources":["../src/testing-dom.ts"],"sourcesContent":["/**\n * Standards-shaped DOM compatibility for non-browser test runners.\n *\n * This module only fills missing IDL surface. It never replaces an existing\n * implementation and does not attempt to simulate layout, paint, or browser\n * focus navigation.\n */\n\nexport type DOMTestingCompatibilityFeature = 'HTMLElement.autofocus';\n\nexport interface DOMTestingCompatibilityReport {\n  /** Standards features installed because the current DOM omitted them. */\n  installed: readonly DOMTestingCompatibilityFeature[];\n}\n\ninterface DOMTestingGlobal {\n  HTMLElement?: typeof HTMLElement;\n}\n\n/**\n * Fill proven DOM-runner IDL gaps without replacing native implementations.\n * Safe to call more than once.\n */\nexport function installDOMTestingCompatibility(\n  scope: DOMTestingGlobal = globalThis as DOMTestingGlobal\n): DOMTestingCompatibilityReport {\n  const installed: DOMTestingCompatibilityFeature[] = [];\n  const HTMLElementConstructor = scope.HTMLElement;\n  if (!HTMLElementConstructor) return { installed };\n\n  const prototype = HTMLElementConstructor.prototype;\n  if (!('autofocus' in prototype)) {\n    Object.defineProperty(prototype, 'autofocus', {\n      configurable: true,\n      enumerable: true,\n      get(this: HTMLElement): boolean {\n        return this.hasAttribute('autofocus');\n      },\n      set(this: HTMLElement, value: boolean) {\n        this.toggleAttribute('autofocus', Boolean(value));\n      },\n    });\n    installed.push('HTMLElement.autofocus');\n  }\n\n  return { installed };\n}\n\n/** Result of the side-effect installation performed by `snice/testing/dom`. */\nexport const domTestingCompatibility = installDOMTestingCompatibility();\n"],"names":[],"mappings":";;;;;;;;;;AAAA;;;;;;AAMG;AAaH;;;AAGG;AACG,SAAU,8BAA8B,CAC5C,KAAA,GAA0B,UAA8B,EAAA;IAExD,MAAM,SAAS,GAAqC,EAAE;AACtD,IAAA,MAAM,sBAAsB,GAAG,KAAK,CAAC,WAAW;AAChD,IAAA,IAAI,CAAC,sBAAsB;QAAE,OAAO,EAAE,SAAS,EAAE;AAEjD,IAAA,MAAM,SAAS,GAAG,sBAAsB,CAAC,SAAS;AAClD,IAAA,IAAI,EAAE,WAAW,IAAI,SAAS,CAAC,EAAE;AAC/B,QAAA,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,WAAW,EAAE;AAC5C,YAAA,YAAY,EAAE,IAAI;AAClB,YAAA,UAAU,EAAE,IAAI;YAChB,GAAG,GAAA;AACD,gBAAA,OAAO,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC;YACvC,CAAC;AACD,YAAA,GAAG,CAAoB,KAAc,EAAA;gBACnC,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;YACnD,CAAC;AACF,SAAA,CAAC;AACF,QAAA,SAAS,CAAC,IAAI,CAAC,uBAAuB,CAAC;IACzC;IAEA,OAAO,EAAE,SAAS,EAAE;AACtB;AAEA;AACO,MAAM,uBAAuB,GAAG,8BAA8B;;;;;"}

package/dist/testing-dom.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Standards-shaped DOM compatibility for non-browser test runners.
+ *
+ * This module only fills missing IDL surface. It never replaces an existing
+ * implementation and does not attempt to simulate layout, paint, or browser
+ * focus navigation.
+ */
+export type DOMTestingCompatibilityFeature = 'HTMLElement.autofocus';
+export interface DOMTestingCompatibilityReport {
+    /** Standards features installed because the current DOM omitted them. */
+    installed: readonly DOMTestingCompatibilityFeature[];
+}
+interface DOMTestingGlobal {
+    HTMLElement?: typeof HTMLElement;
+}
+/**
+ * Fill proven DOM-runner IDL gaps without replacing native implementations.
+ * Safe to call more than once.
+ */
+export declare function installDOMTestingCompatibility(scope?: DOMTestingGlobal): DOMTestingCompatibilityReport;
+/** Result of the side-effect installation performed by `snice/testing/dom`. */
+export declare const domTestingCompatibility: DOMTestingCompatibilityReport;
+export {};

package/dist/testing-dom.esm.js

@@ -0,0 +1,45 @@
+/*!
+ * snice v7.3.0
+ * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
+ * (c) 2024
+ * Released under the MIT License.
+ *
+ * GENERATED FILE — DO NOT EDIT. Source: src/. Rebuild: npm run build:core
+ */
+/**
+ * Standards-shaped DOM compatibility for non-browser test runners.
+ *
+ * This module only fills missing IDL surface. It never replaces an existing
+ * implementation and does not attempt to simulate layout, paint, or browser
+ * focus navigation.
+ */
+/**
+ * Fill proven DOM-runner IDL gaps without replacing native implementations.
+ * Safe to call more than once.
+ */
+function installDOMTestingCompatibility(scope = globalThis) {
+    const installed = [];
+    const HTMLElementConstructor = scope.HTMLElement;
+    if (!HTMLElementConstructor)
+        return { installed };
+    const prototype = HTMLElementConstructor.prototype;
+    if (!('autofocus' in prototype)) {
+        Object.defineProperty(prototype, 'autofocus', {
+            configurable: true,
+            enumerable: true,
+            get() {
+                return this.hasAttribute('autofocus');
+            },
+            set(value) {
+                this.toggleAttribute('autofocus', Boolean(value));
+            },
+        });
+        installed.push('HTMLElement.autofocus');
+    }
+    return { installed };
+}
+/** Result of the side-effect installation performed by `snice/testing/dom`. */
+const domTestingCompatibility = installDOMTestingCompatibility();
+
+export { domTestingCompatibility, installDOMTestingCompatibility };
+//# sourceMappingURL=testing-dom.esm.js.map

package/dist/testing-dom.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing-dom.esm.js","sources":["../src/testing-dom.ts"],"sourcesContent":["/**\n * Standards-shaped DOM compatibility for non-browser test runners.\n *\n * This module only fills missing IDL surface. It never replaces an existing\n * implementation and does not attempt to simulate layout, paint, or browser\n * focus navigation.\n */\n\nexport type DOMTestingCompatibilityFeature = 'HTMLElement.autofocus';\n\nexport interface DOMTestingCompatibilityReport {\n  /** Standards features installed because the current DOM omitted them. */\n  installed: readonly DOMTestingCompatibilityFeature[];\n}\n\ninterface DOMTestingGlobal {\n  HTMLElement?: typeof HTMLElement;\n}\n\n/**\n * Fill proven DOM-runner IDL gaps without replacing native implementations.\n * Safe to call more than once.\n */\nexport function installDOMTestingCompatibility(\n  scope: DOMTestingGlobal = globalThis as DOMTestingGlobal\n): DOMTestingCompatibilityReport {\n  const installed: DOMTestingCompatibilityFeature[] = [];\n  const HTMLElementConstructor = scope.HTMLElement;\n  if (!HTMLElementConstructor) return { installed };\n\n  const prototype = HTMLElementConstructor.prototype;\n  if (!('autofocus' in prototype)) {\n    Object.defineProperty(prototype, 'autofocus', {\n      configurable: true,\n      enumerable: true,\n      get(this: HTMLElement): boolean {\n        return this.hasAttribute('autofocus');\n      },\n      set(this: HTMLElement, value: boolean) {\n        this.toggleAttribute('autofocus', Boolean(value));\n      },\n    });\n    installed.push('HTMLElement.autofocus');\n  }\n\n  return { installed };\n}\n\n/** Result of the side-effect installation performed by `snice/testing/dom`. */\nexport const domTestingCompatibility = installDOMTestingCompatibility();\n"],"names":[],"mappings":";;;;;;;;AAAA;;;;;;AAMG;AAaH;;;AAGG;AACG,SAAU,8BAA8B,CAC5C,KAAA,GAA0B,UAA8B,EAAA;IAExD,MAAM,SAAS,GAAqC,EAAE;AACtD,IAAA,MAAM,sBAAsB,GAAG,KAAK,CAAC,WAAW;AAChD,IAAA,IAAI,CAAC,sBAAsB;QAAE,OAAO,EAAE,SAAS,EAAE;AAEjD,IAAA,MAAM,SAAS,GAAG,sBAAsB,CAAC,SAAS;AAClD,IAAA,IAAI,EAAE,WAAW,IAAI,SAAS,CAAC,EAAE;AAC/B,QAAA,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,WAAW,EAAE;AAC5C,YAAA,YAAY,EAAE,IAAI;AAClB,YAAA,UAAU,EAAE,IAAI;YAChB,GAAG,GAAA;AACD,gBAAA,OAAO,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC;YACvC,CAAC;AACD,YAAA,GAAG,CAAoB,KAAc,EAAA;gBACnC,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;YACnD,CAAC;AACF,SAAA,CAAC;AACF,QAAA,SAAS,CAAC,IAAI,CAAC,uBAAuB,CAAC;IACzC;IAEA,OAAO,EAAE,SAAS,EAAE;AACtB;AAEA;AACO,MAAM,uBAAuB,GAAG,8BAA8B;;;;"}

package/dist/transitions.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v7.1.1
+ * snice v7.3.0
  * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v7.1.1
+ * snice v7.3.0
  * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.

package/dist/types/context.d.ts

@@ -9,21 +9,21 @@ declare const REGISTERED_ELEMENTS_SET: unique symbol;
  * Represents the bundled router state that can notify registered elements of changes
  */
 export declare class Context {
-    [REGISTERED_ELEMENTS]: WeakMap<HTMLElement, Set<string>>;
+    [REGISTERED_ELEMENTS]: WeakMap<object, Set<string>>;
     [IS_UPDATING]: boolean;
     /**
-     * Register an element to receive context updates
+     * Register an element or controller to receive context updates
      * @internal Used by @context decorator
      */
-    [CONTEXT_REGISTER]: (element: HTMLElement, methodName: string) => void;
+    [CONTEXT_REGISTER]: (element: object, methodName: string) => void;
     /**
-     * Unregister an element from receiving context updates. With a methodName,
+     * Unregister a subscriber from context updates. With a methodName,
      * removes only that one handler (so a `once` handler tearing itself down
      * doesn't kill the element's other @context handlers); without one, removes
-     * the element entirely (used on disconnect).
+     * the subscriber entirely (used on disconnect/detach).
      * @internal Used by @context decorator cleanup
      */
-    [CONTEXT_UNREGISTER]: (element: HTMLElement, methodName?: string) => void;
+    [CONTEXT_UNREGISTER]: (element: object, methodName?: string) => void;
     /**
      * Update the context and notify all registered elements
      * Prevents infinite loops by tracking update state
@@ -31,10 +31,10 @@ export declare class Context {
      */
     [CONTEXT_UPDATE]: (context: AppContext, placards: Placard[], currentRoute: string, routeParams: RouteParams) => void;
     /**
-     * Notify a specific element of the current context state
+     * Notify a specific subscriber of the current context state
      * @internal Used by @context decorator
      */
-    [CONTEXT_NOTIFY_ELEMENT]: (element: HTMLElement) => void;
+    [CONTEXT_NOTIFY_ELEMENT]: (element: object) => void;
     private [REGISTERED_ELEMENTS_SET];
     /**
      * Unique immutable identifier for this context instance

package/dist/types/page-options.d.ts

@@ -2,6 +2,16 @@ import { Transition } from './transition';
 import { Placard } from './placard';
 import { Guard } from './guard';
 import { AppContext } from './app-context';
+export interface PageRouteOptions {
+    /** Route pattern matched by the router. */
+    path: string;
+    /**
+     * Optional priority used only when route specificity ties.
+     * Lower numbers match first. Equal or omitted values preserve registration
+     * order, including the order of entries in PageOptions.routes.
+     */
+    order?: number;
+}
 export interface PageOptions {
     /**
      * The tag name of the custom element.
@@ -11,9 +21,13 @@ export interface PageOptions {
     tag: string;
     /**
      * The routes that will trigger the page element.
+     * String entries are the normal form. Their array order breaks specificity
+     * ties. Use an object entry only when an explicit order is needed across
+     * registrations.
      * @example { routes: ['/login', '/login/:id'] }
+     * @example { routes: [{ path: '/login', order: 10 }] }
      */
-    routes: string[];
+    routes: Array<string | PageRouteOptions>;
     /**
      * Optional per-page transition override
      */

package/dist/types/router-instance.d.ts

@@ -2,11 +2,12 @@ import { PageOptions } from './page-options';
 import { Guard } from './guard';
 import { Transition } from './transition';
 import { AppContext } from './app-context';
+import { Placard } from './placard';
 export interface RouterInstance {
     page: (pageOptions: PageOptions) => <C extends {
         new (...args: any[]): HTMLElement;
     }>(constructor: C, context: ClassDecoratorContext) => C;
     initialize: () => void;
     navigate: (path: string) => Promise<void>;
-    register: (route: string, tag: string, transition?: Transition, guards?: Guard<AppContext> | Guard<AppContext>[]) => void;
+    register: (route: string, tag: string, transition?: Transition, guards?: Guard<AppContext> | Guard<AppContext>[], layout?: string | false, placard?: Placard | ((context: AppContext) => Placard), order?: number) => void;
 }

package/dist/utils.d.ts

@@ -101,7 +101,9 @@ export declare function invokeImmediateWatchers(instance: any, constructor: any)
 /**
  * Create a debounced version of a function
  */
-export declare function createDebounced<T extends (...args: any[]) => any>(fn: T, delay: number): T;
+export declare function createDebounced<T extends (...args: any[]) => any>(fn: T, delay: number): T & {
+    cancel(): void;
+};
 /**
  * Create a throttled version of a function (leading + trailing edge)
  */

package/docs/ai/README.md

@@ -101,13 +101,15 @@ Runtime first, then one bundle per component (any order after runtime):
 - Components re-render on any property change (decorated or not)
 
 **Architecture:**
-- **Elements are purely visual** - no fetch(), no API calls, no backend logic
+- **Elements own visual behavior** - no fetch(), no API calls, no backend logic
 - Elements receive data via properties, emit events for actions
-- **Pages orchestrate** - handle routing, call APIs, coordinate elements
-- **Controllers add behavior** - attach to elements for reusable non-visual logic; bind by class in templates (`controller=${MyController}`, preferred) or by name in raw HTML (`controller="name"`)
+- **Controllers own application behavior specific to a set of elements** - data, APIs, storage, business rules, and app-specific reactions that exist for those elements; bind by class in templates (`controller=${MyController}`, preferred) or by name in raw HTML (`controller="name"`)
+- **Pages own element orchestration** - compose elements, pass properties, handle events, bind controllers, and coordinate the screen; routing is one concern, not the definition of the role
 - **Daemons hold app-owned state/lifecycle** - construct explicitly, provide through `context.daemons`, communicate by address without importing implementations
 - Conventional folders: `src/pages`, `src/components`, `src/controllers`, `src/daemons`; construct the Router in `src/router.ts` and initialize it from `src/main.ts`
-- Several server/storage/timer operations in one page, or substantial logic copied across pages, belongs in a controller; `snice check` suggests the extraction conservatively
+- Do not attach a controller to a page host; keep the ownership rules distinct: visual behavior in elements, element-specific application behavior in controllers, element orchestration in pages
+- A host-free reusable function may stay a plain module wherever the project keeps it; state plus lifecycle belongs in a daemon
+- Declare query parameters in `@page({ routes: ['/search?q=:query'] })`; do not build a URL-parsing controller for a page
 - Put API calls in pages/controllers/services, not in elements
 
 **Properties:**

package/docs/ai/api.md

@@ -9,7 +9,7 @@
   shadow?: 'open' | 'closed' | false,
   delegatesFocus?: boolean
 }) // Define custom element
-@page({ tag, routes, guards?, placard? }) // Define routable page
+@page({ tag, routes, guards?, placard? }) // Ordered string routes; optional { path, order? } tie-break entries
 @controller('name') // Define behavior module (required on every controller class)
 // Attach: html`<x-el controller=${MyController}></x-el>` (class, preferred; custom + native els)
 //         attachController(el, MyController) | el.controller = MyController
@@ -122,7 +122,7 @@ html`
 @dispatch(eventName: string, options?: { debounce?, throttle?, dispatchOnUndefined?, scope?, daemon?, ...EventInit })
 // Fires CustomEvent after method, detail = return value
 // Supports async methods (dispatches after promise resolves)
-// dispatchOnUndefined: false (default) — skips dispatch if method returns undefined
+// dispatchOnUndefined: false — skips when return is undefined; omitted/true still dispatches
 // scope: 'global' | selector | EventTarget | () => EventTarget | null — redirects dispatch target
 ```
 
@@ -178,6 +178,8 @@ html`
 // Example:
 //   @respond('fetch-user')
 //   async handleFetchUser(payload: { id: string }) {
+//     const fetch = getContextFetch(this);
+//     if (!fetch) throw new Error('Controller requires context fetch');
 //     const user = await fetch(`/api/users/${payload.id}`).then(r => r.json());
 //     return user;
 //   }
@@ -191,6 +193,14 @@ const context = getContext(elementOrController);
 // Provide before connect/attach. Call release() during app/test teardown.
 ```
 
+Context transport:
+```typescript
+const release = provideContext(appRoot, appContext, { fetch: appFetch });
+const fetch = getContextFetch(elementOrController);
+// Router supplies its ContextAwareFetcher-bound Context.fetch automatically.
+// AppContext is not mutated with a reserved transport key.
+```
+
 ## Observers
 
 ```typescript
@@ -222,6 +232,7 @@ const context = getContext(elementOrController);
 
 @context(options?: { debounce?, throttle?, once? })
 // Method decorator: receives Context on navigation and ctx.update() calls
+// Supported on pages, descendant elements, and attached controllers.
 // Called on: initial load, route change, ctx.update()
 // Example:
 //   @context() handleContext(ctx: Context) {

package/docs/ai/architecture.md

@@ -4,11 +4,17 @@
 
 **Separation of concerns:**
 - **Cross-cutting:** Router + global context
-- **Pages:** Orchestrate elements, handle URLs
-- **Elements:** Generic visual building blocks — no fetch(), no API calls, no business logic
-- **Controllers:** Specific behavior (data, APIs, business rules) — swappable per element
+- **Elements:** Visual behavior and semantic UI contracts — rendering, internal DOM, focus, keyboard behavior, and visual state
+- **Controllers:** Application behavior specific to a set of elements — data, APIs, storage, business rules, and app-specific reactions that exist for those elements
+- **Pages:** Element orchestration — compose elements, pass properties, handle events, bind controllers, and coordinate the screen
+- **Plain modules:** Host-free reusable functions with explicit inputs; use the project's own folder convention
 - **Daemons:** Explicitly constructed app-owned state/lifecycle objects — addressable through context, never global singletons
 
+These are ownership rules, not synonyms: visual behavior belongs in the element,
+application behavior specific to a set of elements belongs in a controller, and
+element orchestration belongs in the page. Routing is a page concern, but it does
+not define the page role.
+
 **Generic vs Specific:** Elements say *what* they need, controllers decide *how*.
 Swap controllers to change behavior without touching the component.
 Mock controller for tests, real API controller in production — same element.
@@ -27,16 +33,23 @@ Conventional application layout:
 src/
   main.ts
   router.ts
-  pages/          # @page classes; route orchestration and presentation
+  pages/          # @page classes; element orchestration and routing
   components/     # reusable @element visual components
   controllers/    # @controller data, API, and reusable business behavior
   daemons/        # explicitly constructed @daemon state/lifecycle services
 ```
 
-Pages may coordinate a route and perform a small one-off load. Move behavior to
-a controller when a page owns several storage/server/timer operations or when
-substantial non-visual logic is copied across pages. `snice check` reports these
-as architecture suggestions, not errors.
+Pages orchestrate elements. Do not call `attachController(this, ...)` or assign
+`this.controller` on a page; that creates a second owner instead of preserving
+the page's orchestration role. Keep visual behavior in the element. Put
+application behavior specific to a set of elements in a controller and bind it
+where the page composes those elements. A host-free reusable function may stay a
+plain module in the project's chosen location.
+
+Declare route and query state in `@page({ routes })` rather than giving a
+controller `URLSearchParams`, `location`, or `history` responsibilities.
+`snice check` reports these architecture mistakes and conservative page
+decomposition suggestions.
 
 ## Rendering System
 
@@ -90,8 +103,9 @@ as architecture suggestions, not errors.
 2. ControllerPart commit / attributeChangedCallback detects change
 3. Detach old controller (if any)
 4. Attach new controller (class refs skip the registry; reference-deduped)
-5. setupEventHandlers for controller
-6. On detach: cleanupEventHandlers
+5. Register `@context` and catch up with the current Router context
+6. Set up `@observe`, `@respond`, and `@on` handlers
+7. On detach: clean up every managed decorator
 - Class bindings own the element; their decorator name is reflected as a diagnostic-only `controller="name"` marker
 - Native elements: class bindings attach via ControllerPart; string attrs via MutationObserver
 
@@ -171,9 +185,12 @@ async *fetchData(): Response<Data> {
 }
 
 // Controller responds (receives payload, returns result directly)
+private ctx!: Context;
+@context() receiveContext(ctx: Context) { this.ctx = ctx; }
+
 @respond('fetch-data')
 async handleFetch(payload: { id: string }) {
-  return await fetch(`/api/${payload.id}`).then(r => r.json());
+  return await this.ctx.fetch(`/api/${payload.id}`).then(r => r.json());
 }
 // Wiring: html`<my-element controller=${MyController}></my-element>` (or controller="my-controller" in raw HTML)
 ```