snice 7.2.0 → 7.3.0

package/.agents/skills/snice/SKILL.md

@@ -8,9 +8,32 @@ description: Build, modify, debug, or review applications and components that us
 Use the documentation shipped with the exact installed Snice version. Do not
 reconstruct Snice APIs from Lit or generic web-component conventions.
 
-If a consuming project does not yet contain `.agents/skills/snice/SKILL.md`,
-run `npx snice init-ai` from that project root before writing Snice code. This
-installs version-matched guidance plus `AGENTS.md` and `CLAUDE.md` pointers.
+## Choose the owner before the API
+
+Make this decision before creating files or choosing decorators:
+
+- **Visual behavior belongs in the element.** Rendering, internal DOM, focus,
+  keyboard behavior, visual state, and translation of internal-part events into
+  the element's semantic events stay in the `@element` class.
+- **Application behavior specific to a set of elements belongs in a
+  controller.** API/storage access, business rules, and app-specific reactions
+  that exist for those elements stay in an `@controller` class.
+- **Element orchestration belongs in the page.** A `@page` composes elements,
+  passes properties, handles their events, binds their controllers, and
+  coordinates the screen. Routing is one page concern; it is not the definition
+  of the page's role.
+
+Do not attach a controller to the page host or move orchestration into a “page
+controller.” Do not move visual behavior into a controller merely to make an
+element smaller. A host-free reusable function may stay a plain module wherever
+the project convention puts it. State plus lifecycle belongs in an explicitly
+constructed `@daemon`, not a singleton.
+
+Examples: focus/internal buttons → element; element-specific API behavior → controller;
+coordinating search, results, and dialog elements → page; state plus lifecycle → daemon.
+
+If `.agents/skills/snice/SKILL.md` is absent, run `npx snice init-ai` from the
+project root before writing code; it installs version-matched agent guidance.
 
 ## Locate the reference
 
@@ -19,18 +42,23 @@ Use the first directory that exists:
 1. `docs/ai/` in a Snice source checkout.
 2. `node_modules/snice/docs/ai/` in a consuming application.
 
+Every reference below is relative to that AI-doc root. Never substitute the
+parallel human-facing files under `docs/`.
+
 If neither exists, install the project dependencies before writing Snice code.
 
-## Load only relevant context
+## Documentation gate (mandatory)
+
+The agent doing the work must complete this gate itself before editing. Do not
+delegate the reading, rely on memory, or substitute another agent's summary.
 
-1. Read `README.md` for the framework contract and documentation map.
-2. Read the specific topical reference needed:
-   - `decorators.md` for decorator signatures.
-   - `rendering.md` and `bindings.md` for templates and reactivity.
-   - `react-integration.md` for React adapters.
-   - `theme.md` for tokens and theming.
-   - `patterns.md` for architecture and composition.
-3. Read only `components/<name>.md` for components actually used.
+1. Read the AI-doc root's `README.md` for its contract and documentation map.
+2. Before touching code that uses a Snice decorator, or introducing one, read
+   `decorators.md` and that decorator's complete topical AI reference. The
+   general decorator index alone does not satisfy this gate.
+3. Before touching code that uses a built-in Snice element, or introducing one,
+   read that element's complete `components/<name>.md` reference.
+4. Read the applicable template, binding, routing, controller, daemon, React, theme, accessibility, or lifecycle reference before using that feature.
 
 Treat those versioned files and the runtime TypeScript declarations as
 authoritative. If they conflict, inspect the installed declarations/source and
@@ -47,7 +75,6 @@ type-checks with `npx tsc -p references/tsconfig.kitchen-sink.json` after
 - Import built-in elements through their documented deep side-effect path.
 - Import React wrappers from `snice/react`; also register each underlying
   custom element through its documented deep side-effect import.
-- Keep application data and orchestration in pages, controllers, or services.
 - Pass objects and arrays through property bindings, not string attributes.
 - Preserve native form, keyboard, focus, and accessibility behavior.
 - Use the project compiler configuration for TC39 decorators.

package/README.md

@@ -591,11 +591,12 @@ elements in `src/components/`, attached behavior in `src/controllers/`, and
 app-owned services in `src/daemons/`. `src/router.ts` constructs and exports the
 router pieces; `src/main.ts` imports page modules and calls `initialize()`.
 
-Pages orchestrate a route. When several storage/server/timer operations collect
-inside one page, or substantial non-visual logic is repeated across pages, move
-that behavior into a controller. `snice check` reports folder and extraction
-guidance as non-blocking suggestions while treating broken Router construction
-as an error.
+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 in the project's chosen location. `snice check` reports
+page-host controllers, manual URL parsing, and decomposition opportunities while
+treating broken Router construction as an error.
 
 ## Template Syntax
 

package/adapters/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/adapters/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/adapters/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/adapters/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/adapters/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/adapters/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/adapters/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/adapters/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/bin/analyzer-contracts.js

@@ -21,7 +21,7 @@ export const ANALYZER_CONTRACTS = {
     "componentModules": 188,
     "componentUtilityModules": 31,
     "reactWrappers": 193,
-    "rootExports": 115
+    "rootExports": 116
   },
   "rootExports": [
     "AdoptedOptions",
@@ -48,6 +48,7 @@ export const ANALYZER_CONTRACTS = {
     "OnOptions",
     "OnScope",
     "PageOptions",
+    "PageRouteOptions",
     "PartOptions",
     "Placard",
     "PropertyConverter",