snice 7.2.0 → 7.3.0

package/dist/react/SniceProvider.js

@@ -1,5 +1,5 @@
 /*!
- * snice v7.1.1
+ * snice v7.2.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.2.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.2.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.2.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.2.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.2.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.2.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.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v7.1.1
+ * snice v7.2.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.2.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/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/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

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
 

package/docs/ai/cli.md

@@ -52,7 +52,10 @@ Non-blocking architecture suggestions:
 - `@element` -> `src/components/`
 - `@controller` -> `src/controllers/`
 - `@daemon` -> `src/daemons/`
-- several external-effect methods or substantial logic repeated across pages -> extract a controller
+- visual behavior -> element
+- application behavior specific to a set of elements -> controller
+- element orchestration -> page; do not attach a controller to the page host
+- host-free reusable function -> plain module in the project's chosen location
 
 Both `doctor` and `validate` accept `--json`.
 

package/docs/ai/controllers.md

@@ -2,7 +2,15 @@
 
 Mirrors `docs/controllers.md`.
 
-Controllers handle data fetching, business logic, and server communication separately from visual components. Attach to any HTML element, including native elements.
+Controllers hold application behavior specific to a set of elements, including
+their data fetching, business rules, and server communication. Attach to any
+HTML element, including native elements.
+
+Visual behavior belongs in elements, application behavior specific to a set of
+elements belongs in a controller, and element orchestration belongs in pages.
+Do not attach a controller to the page host. A host-free reusable function may
+stay a plain module wherever the project keeps it. URL/query parsing belongs in
+`@page({ routes })`, not in a controller.
 
 ## Basic Usage
 
@@ -79,6 +87,8 @@ Exception to step 4: `await attachController(this, ControllerClass)` inside the
 host's own `@ready` handler attaches immediately because initial render is
 already complete. Awaiting that same host's `ready` would self-deadlock. An
 attachment targeting any other element still waits for the target's `ready`.
+This runtime safeguard does not make attaching a controller to a routed page a
+good architecture; pages should orchestrate directly.
 
 **Detachment flow:**
 1. `detach()` called

package/docs/ai/decorators.md

@@ -2,7 +2,7 @@
 
 ## Class
 - `@element('tag-name', options?)` - Custom element. Options: `{ formAssociated?, renderRoot?: 'shadow'|'light', shadow?: 'open'|'closed'|false, delegatesFocus? }`
-- `@page({ tag, routes, guards?, placard? })` - Routable page
+- `@page({ tag, routes, guards?, placard? })` - Routable page. `routes` normally uses ordered strings; optional `{ path, order? }` entries explicitly break specificity ties.
 - `@controller('name')` - Swappable behavior. Required on every controller class. Attach by class (preferred): `controller=${MyController}` in templates, `attachController(el, MyController)`, or `el.controller = MyController`; by string in raw HTML: `controller="name"`. A class attachment reflects this name in the DOM as a diagnostic marker without attaching through the registry.
 - `@daemon` - Marks an explicitly constructed app-context daemon. No name argument; context key is address. Never constructs/registers globally.
 - `@layout('tag-name')` - Page wrapper for routing system

package/docs/ai/react-integration.md

@@ -33,6 +33,7 @@ Deep import: `import { useRequestHandler } from 'snice/react/useRequestHandler'`
 ## Route Props
 
 - `path`: Route pattern (e.g., `/users/:id`)
+- `order`: Optional numeric specificity tie-break; lower values match first. Equal/omitted values preserve declaration order.
 - `page`: React component (receives params as props) OR Snice tag name string (params set as attributes)
 - `guard`: `(ctx, params) => boolean | Promise<boolean>`
 - `guards`: Array of guard functions (AND logic, sequential, short-circuit)

package/docs/ai/routing.md

@@ -144,7 +144,10 @@ changeTheme(theme: 'light' | 'dark') {
 ```typescript
 interface PageOptions {
   tag: string;                       // custom element tag name
-  routes: string[];                  // route patterns
+  routes: Array<string | {           // strings are the normal form
+    path: string;
+    order?: number;                  // lower wins on a specificity tie
+  }>;
   transition?: Transition;           // page-specific transition
   guards?: Guard | Guard[];          // route guards
   layout?: string | false;           // layout tag, or false to disable
@@ -154,6 +157,25 @@ interface PageOptions {
 
 - Multiple routes: `routes: ['/user', '/users', '/profile']` — all resolve to the same page.
 - Route params: `:name` segments inside a route pattern (see Route Parameters below).
+- Routes are sorted by specificity first. When specificity ties, string entries
+  keep registration order, including their order in one `routes` array.
+- Object notation is optional. Use `{ path, order }` only for an explicit tie-break
+  across registrations; lower `order` values match first. Equal or omitted values
+  still preserve registration order.
+
+```typescript
+@page({
+  tag: 'work-orders-page',
+  routes: ['/work-orders?status=:status', '/work-orders']
+})
+class WorkOrdersPage extends HTMLElement {}
+
+@page({
+  tag: 'override-page',
+  routes: [{ path: '/:section/:item', order: -10 }]
+})
+class OverridePage extends HTMLElement {}
+```
 
 ## Navigation
 
@@ -183,7 +205,7 @@ function Router(options: RouterOptions): {
   page: (pageOptions: PageOptions) => ClassDecorator;
   initialize: () => void;
   navigate: (path: string) => Promise<void>;
-  register: (route: string, tag: string, transition?: Transition, guards?: Guard | Guard[]) => void;
+  register: (route: string, tag: string, transition?: Transition, guards?: Guard | Guard[], layout?: string | false, placard?: Placard | ((ctx: AppContext) => Placard), order?: number) => void;
 }
 ```
 
@@ -191,4 +213,4 @@ function Router(options: RouterOptions): {
 - `initialize(): void` — starts listening for route changes; must be called after all pages are defined.
 - Do not add `@element` to an `@page` class. The Router-returned page decorator
   already registers the custom element and applies Snice element behavior.
-- `register(route: string, tag: string, transition?: Transition, guards?: Guard | Guard[], layout?: string | false, placard?: Placard | ((ctx: AppContext) => Placard)): void` — manually registers a route without the `@page` decorator. Note: the return-type shape above lists `register` with 4 params; this fuller 6-param signature (adding `layout`, `placard`) is documented separately in the source.
+- `register(route, tag, transition?, guards?, layout?, placard?, order?): void` — manually registers a route without `@page`. Lower `order` values win only after specificity ties; omitted/equal order preserves registration order.

package/docs/cli.md

@@ -55,8 +55,10 @@ npx snice validate    # source analyzer only
 
 It also gives non-blocking architecture suggestions: keep `@page`, `@element`,
 `@controller`, and `@daemon` classes under `src/pages`, `src/components`,
-`src/controllers`, and `src/daemons`; extract clearly service-heavy or repeated
-page logic into a controller. Small route orchestration remains valid page code.
+`src/controllers`, and `src/daemons`; keep visual behavior in elements,
+application behavior specific to a set of elements in controllers, and element
+orchestration in pages. A host-free reusable function may remain a plain module
+wherever the project convention places it.
 
 Both accept `--json` for CI.
 

package/docs/controllers.md

@@ -1,7 +1,15 @@
 <!-- AI: For the AI-optimized version of this doc, see docs/ai/api.md -->
 # Controllers API Documentation
 
-Controllers handle data fetching, business logic, and server communication separately from visual components. They can be attached to any HTML element, including native elements.
+Controllers hold application behavior specific to a set of elements, including
+their data fetching, business rules, and server communication. They can be
+attached to any HTML element, including native elements.
+
+Visual behavior belongs in elements, application behavior specific to a set of
+elements belongs in a controller, and element orchestration belongs in pages.
+Do not attach a controller to the page host. A host-free reusable function may
+stay a plain module wherever the project keeps it. URL/query parsing belongs in
+`@page({ routes })`, not in a controller.
 
 ## Table of Contents
 - [Basic Usage](#basic-usage)
@@ -125,6 +133,8 @@ Snice attaches immediately. Initial rendering has already completed at that
 point, and waiting for `ready` would otherwise create a self-deadlock because
 `ready` cannot settle until the current handler returns. Attaching to any
 other element still awaits that element's `ready` promise.
+This runtime safeguard does not make attaching a controller to a routed page a
+good architecture; pages should orchestrate directly.
 
 ### Detachment Flow
 
@@ -355,9 +365,11 @@ class FormValidationController implements IController<HTMLFormElement> {
 
 ### Data Fetching Controller
 
-Controllers own data fetching. Pass state through the element's public API and
-dispatch outcome events — do not manipulate its rendered DOM. A production
-controller should also prevent an older response from overwriting a newer one:
+A data-fetching controller is appropriate when the fetch is application behavior
+specific to the elements it controls. Pass state through the element's public
+API and dispatch outcome events — do not manipulate its rendered DOM. A
+production controller should also prevent an older response from overwriting a
+newer one:
 
 ```typescript
 interface Order { id: string; total: number }

package/docs/react-integration.md

@@ -147,6 +147,7 @@ Defines a route within `<SniceRouter>`. The `<Route>` component itself renders n
 | Prop | Type | Description |
 |------|------|-------------|
 | `path` | `string` | URL pattern. Supports dynamic segments: `/users/:id`, `/posts/:slug`. |
+| `order` | `number` | Optional specificity tie-break. Lower values match first; equal or omitted values preserve declaration order. |
 | `page` | `Component \| string` | What to render. React component receives route params as props. String = Snice web component tag name (params set as attributes). |
 | `guard` | `(ctx, params) => boolean \| Promise<boolean>` | Single guard function. |
 | `guards` | `function[]` | Multiple guards — all must pass (AND logic). |

package/docs/routing.md

@@ -294,7 +294,10 @@ class SettingsPage extends HTMLElement {
 ```typescript
 interface PageOptions {
   tag: string;                       // Custom element tag name
-  routes: string[];                  // Route patterns
+  routes: Array<string | {           // Strings are the normal form
+    path: string;
+    order?: number;                  // Lower wins on a specificity tie
+  }>;
   transition?: Transition;           // Page-specific transition
   guards?: Guard | Guard[];          // Route guards
   layout?: string | false;           // Layout tag, or false to disable
@@ -317,6 +320,30 @@ class UserPage extends HTMLElement {
 }
 ```
 
+Routes are sorted by specificity first. If specificity ties, registration
+order wins, including the order of plain strings in one `routes` array. Keep
+that compact syntax for normal pages:
+
+```typescript
+@page({
+  tag: 'work-orders-page',
+  routes: ['/work-orders?status=:status', '/work-orders']
+})
+class WorkOrdersPage extends HTMLElement {}
+```
+
+Object notation is optional. Use it only when a route needs an explicit
+tie-break across registrations; lower `order` values match first. Equal or
+omitted values still preserve registration order.
+
+```typescript
+@page({
+  tag: 'override-page',
+  routes: [{ path: '/:section/:item', order: -10 }]
+})
+class OverridePage extends HTMLElement {}
+```
+
 ### Route with Parameters
 
 ```typescript
@@ -815,7 +842,7 @@ function Router(options: RouterOptions): {
   page: (pageOptions: PageOptions) => ClassDecorator;
   initialize: () => void;
   navigate: (path: string) => Promise<void>;
-  register: (route: string, tag: string, transition?: Transition, guards?: Guard | Guard[]) => void;
+  register: (route: string, tag: string, transition?: Transition, guards?: Guard | Guard[], layout?: string | false, placard?: Placard | ((ctx: AppContext) => Placard), order?: number) => void;
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snice",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "type": "module",
   "description": "A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.",
   "main": "dist/index.cjs",