@agent-native/core 0.36.0 → 0.37.0

package/dist/client/route-state.js

@@ -0,0 +1,205 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useLocation, useNavigate, } from "react-router";
+import { deleteClientAppState, readClientAppState, setClientAppState, } from "./application-state.js";
+const SAFE_BROWSER_TAB_ID_RE = /^[A-Za-z0-9_-]{1,96}$/;
+function normalizeBrowserTabId(browserTabId) {
+    if (typeof browserTabId !== "string")
+        return undefined;
+    const trimmed = browserTabId.trim();
+    return SAFE_BROWSER_TAB_ID_RE.test(trimmed) ? trimmed : undefined;
+}
+function appStateKeyForBrowserTab(key, browserTabId) {
+    return browserTabId ? `${key}:${browserTabId}` : key;
+}
+function routeLocationFromReactRouter(location) {
+    return {
+        pathname: location.pathname,
+        search: location.search,
+        hash: location.hash,
+        searchParams: new URLSearchParams(location.search),
+        location,
+    };
+}
+function uniqueKeys(keys) {
+    return Array.from(new Set(keys));
+}
+function defaultCommandDedupKey(command) {
+    if (command && typeof command === "object" && "_writeId" in command) {
+        const writeId = command._writeId;
+        if (typeof writeId === "string" && writeId)
+            return writeId;
+    }
+    return JSON.stringify(command);
+}
+function currentRouterPath(location) {
+    return `${location.pathname}${location.search}${location.hash}`;
+}
+function stringifyForWriteDedup(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Keeps semantic UI state agent-visible and consumes agent-authored one-shot
+ * commands. This is the framework primitive behind route/navigation sync; it
+ * intentionally knows nothing about app-specific route shapes.
+ */
+export function useSemanticNavigationState(options) {
+    const { requestSource, commandRefetchInterval = 2_000, enabled = true, keepalive = true, writeDebounceMs = 0, } = options;
+    const queryClient = useQueryClient();
+    const navigationKeys = useMemo(() => uniqueKeys(options.navigationKeys ?? ["navigation"]), [options.navigationKeys]);
+    const commandKeys = useMemo(() => uniqueKeys(options.commandKeys ?? ["navigate"]), [options.commandKeys]);
+    const commandQueryKey = useMemo(() => options.commandQueryKey ?? ["navigate-command"], [options.commandQueryKey]);
+    const navigationState = options.state ?? null;
+    const navigationWriteDedup = stringifyForWriteDedup({
+        keys: navigationKeys,
+        state: navigationState,
+    });
+    const getCommandDedupKeyRef = useRef(options.getCommandDedupKey);
+    const onCommandRef = useRef(options.onCommand);
+    const onErrorRef = useRef(options.onError);
+    getCommandDedupKeyRef.current = options.getCommandDedupKey;
+    onCommandRef.current = options.onCommand;
+    onErrorRef.current = options.onError;
+    const lastNavigationWriteRef = useRef(null);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        if (lastNavigationWriteRef.current === navigationWriteDedup)
+            return;
+        lastNavigationWriteRef.current = navigationWriteDedup;
+        const write = () => {
+            for (const key of navigationKeys) {
+                setClientAppState(key, navigationState, {
+                    keepalive,
+                    requestSource,
+                }).catch((error) => onErrorRef.current?.(error));
+            }
+        };
+        if (writeDebounceMs > 0) {
+            const timer = setTimeout(write, writeDebounceMs);
+            return () => clearTimeout(timer);
+        }
+        write();
+    }, [
+        enabled,
+        keepalive,
+        navigationKeys,
+        navigationState,
+        navigationWriteDedup,
+        requestSource,
+        writeDebounceMs,
+    ]);
+    const commandQuery = useQuery({
+        queryKey: commandQueryKey,
+        enabled,
+        retry: false,
+        refetchInterval: commandRefetchInterval,
+        queryFn: async () => {
+            for (const key of commandKeys) {
+                const command = await readClientAppState(key);
+                if (command !== null && command !== undefined) {
+                    return { key, command };
+                }
+            }
+            return null;
+        },
+    });
+    const clearCommand = useCallback(async () => {
+        await Promise.all(commandKeys.map((key) => deleteClientAppState(key, { requestSource }).catch((error) => {
+            onErrorRef.current?.(error);
+        })));
+        queryClient.setQueryData(commandQueryKey, null);
+    }, [commandKeys, commandQueryKey, queryClient, requestSource]);
+    const lastProcessedDedupKeyRef = useRef(null);
+    useEffect(() => {
+        const envelope = commandQuery.data;
+        if (!enabled || !envelope)
+            return;
+        const dedupKey = getCommandDedupKeyRef.current?.(envelope.command) ??
+            defaultCommandDedupKey(envelope.command);
+        const consume = () => {
+            deleteClientAppState(envelope.key, { requestSource }).catch((error) => onErrorRef.current?.(error));
+            queryClient.setQueryData(commandQueryKey, null);
+        };
+        if (lastProcessedDedupKeyRef.current === dedupKey) {
+            consume();
+            return;
+        }
+        lastProcessedDedupKeyRef.current = dedupKey;
+        consume();
+        Promise.resolve(onCommandRef.current(envelope.command)).catch((error) => onErrorRef.current?.(error));
+    }, [commandQuery.data, commandQueryKey, enabled, queryClient, requestSource]);
+    return {
+        navigationState,
+        command: commandQuery.data,
+        commandQueryKey,
+        clearCommand,
+    };
+}
+/**
+ * React Router convenience wrapper around `useSemanticNavigationState`.
+ *
+ * Use URL query params as the source of truth for shareable filters. This hook
+ * writes semantic aliases and stable IDs to `navigation`; the framework's
+ * built-in URL sync separately exposes raw `pathname`, `search`, and
+ * `searchParams` through `<current-url>` and the `set-search-params` tool.
+ */
+export function useAgentRouteState(options) {
+    const { navigationKey = "navigation", commandKey = "navigate", writeGlobalNavigation = true, readGlobalCommandFallback = true, } = options;
+    const location = useLocation();
+    const navigate = useNavigate();
+    const browserTabId = useMemo(() => normalizeBrowserTabId(options.browserTabId), [options.browserTabId]);
+    const navigationKeys = useMemo(() => {
+        const scopedKey = appStateKeyForBrowserTab(navigationKey, browserTabId);
+        const keys = [scopedKey];
+        if (browserTabId && writeGlobalNavigation)
+            keys.push(navigationKey);
+        return uniqueKeys(keys);
+    }, [browserTabId, navigationKey, writeGlobalNavigation]);
+    const commandKeys = useMemo(() => {
+        const scopedKey = appStateKeyForBrowserTab(commandKey, browserTabId);
+        const keys = [scopedKey];
+        if (browserTabId && readGlobalCommandFallback)
+            keys.push(commandKey);
+        return uniqueKeys(keys);
+    }, [browserTabId, commandKey, readGlobalCommandFallback]);
+    const commandQueryKey = useMemo(() => options.commandQueryKey ?? [
+        "navigate-command",
+        commandKey,
+        browserTabId ?? "global",
+    ], [browserTabId, commandKey, options.commandQueryKey]);
+    const routeLocation = useMemo(() => routeLocationFromReactRouter(location), [location]);
+    const navigationState = options.getNavigationState(routeLocation) ?? null;
+    return useSemanticNavigationState({
+        state: navigationState,
+        navigationKeys,
+        commandKeys,
+        commandQueryKey,
+        requestSource: options.requestSource,
+        commandRefetchInterval: options.refetchInterval,
+        enabled: options.enabled,
+        keepalive: options.keepalive,
+        writeDebounceMs: options.writeDebounceMs,
+        getCommandDedupKey: options.getCommandDedupKey,
+        onError: options.onError,
+        onCommand: (command) => {
+            const path = options.getCommandPath(command);
+            if (!path)
+                return;
+            options.onNavigate?.(command, path);
+            if (path === currentRouterPath(location))
+                return;
+            const navigateOptions = options.navigateOptions;
+            const resolvedOptions = typeof navigateOptions === "function"
+                ? navigateOptions(command)
+                : navigateOptions;
+            navigate(path, resolvedOptions);
+        },
+    });
+}
+//# sourceMappingURL=route-state.js.map

package/dist/client/route-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-state.js","sourceRoot":"","sources":["../../src/client/route-state.ts"],"names":[],"mappings":"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","sourcesContent":["import { useCallback, useEffect, useMemo, useRef } from \"react\";\nimport { useQuery, useQueryClient, type QueryKey } from \"@tanstack/react-query\";\nimport {\n  useLocation,\n  useNavigate,\n  type Location,\n  type NavigateOptions,\n} from \"react-router\";\nimport {\n  deleteClientAppState,\n  readClientAppState,\n  setClientAppState,\n} from \"./application-state.js\";\n\nconst SAFE_BROWSER_TAB_ID_RE = /^[A-Za-z0-9_-]{1,96}$/;\n\nexport interface SemanticNavigationCommandEnvelope<NavigateCommand> {\n  key: string;\n  command: NavigateCommand;\n}\n\nexport interface UseSemanticNavigationStateOptions<\n  NavigationState,\n  NavigateCommand = NavigationState,\n> {\n  /**\n   * Compact, semantic screen state to expose to the agent: view names, record\n   * IDs, active tabs, and useful aliases. Keep URL query params in the URL\n   * unless the app needs a human-readable semantic alias.\n   */\n  state: NavigationState | null | undefined;\n  /** Application-state keys the UI should write. Defaults to [`navigation`]. */\n  navigationKeys?: readonly string[];\n  /** Application-state keys to read for one-shot agent commands. Defaults to [`navigate`]. */\n  commandKeys?: readonly string[];\n  /** React Query key used for command polling/cache. Defaults to [`navigate-command`]. */\n  commandQueryKey?: QueryKey;\n  /** Request source tag for `useDbSync({ ignoreSource })` jitter prevention. */\n  requestSource?: string;\n  /** Poll interval for command reads. Defaults to 2000ms. Pass false to disable polling. */\n  commandRefetchInterval?: number | false;\n  /** Disable both navigation writes and command reads. */\n  enabled?: boolean;\n  /** Navigation writes use keepalive by default because they often fire during unload. */\n  keepalive?: boolean;\n  /** Debounce navigation writes. Defaults to 0ms. */\n  writeDebounceMs?: number;\n  /** Custom duplicate-command key. Defaults to `_writeId` or JSON content. */\n  getCommandDedupKey?: (command: NavigateCommand) => string;\n  /** Called once for each non-duplicate command after the command is consumed. */\n  onCommand: (command: NavigateCommand) => void | Promise<void>;\n  /** Optional sink for best-effort navigation write/read/delete/command errors. */\n  onError?: (error: unknown) => void;\n}\n\nexport interface UseSemanticNavigationStateResult<\n  NavigationState,\n  NavigateCommand = NavigationState,\n> {\n  navigationState: NavigationState | null;\n  command:\n    | SemanticNavigationCommandEnvelope<NavigateCommand>\n    | null\n    | undefined;\n  commandQueryKey: QueryKey;\n  clearCommand: () => Promise<void>;\n}\n\nexport interface AgentRouteLocation {\n  pathname: string;\n  search: string;\n  hash: string;\n  searchParams: URLSearchParams;\n  location: Location;\n}\n\nexport interface UseAgentRouteStateOptions<\n  NavigationState,\n  NavigateCommand = NavigationState,\n> {\n  /**\n   * Derive compact, semantic screen state from the current React Router URL.\n   * The framework separately exposes raw `pathname`, `search`, and parsed\n   * `searchParams` through `<current-url>`.\n   */\n  getNavigationState: (\n    location: AgentRouteLocation,\n  ) => NavigationState | null | undefined;\n  /**\n   * Convert an agent-authored one-shot command into an app-local React Router\n   * path. Return null to consume and ignore malformed or unsupported commands.\n   */\n  getCommandPath: (command: NavigateCommand) => string | null | undefined;\n  /** Application-state key the UI writes. Defaults to `navigation`. */\n  navigationKey?: string;\n  /** Application-state key the agent writes for one-shot navigation. */\n  commandKey?: string;\n  /** Current browser tab id. Enables tab-scoped reads/writes. */\n  browserTabId?: string;\n  /** Request source tag for `useDbSync({ ignoreSource })` jitter prevention. */\n  requestSource?: string;\n  /**\n   * Also write the unscoped navigation key when browserTabId is present.\n   * Defaults to true so CLI/external agents still have a useful fallback.\n   */\n  writeGlobalNavigation?: boolean;\n  /**\n   * Fall back to the unscoped command key when no tab-scoped command exists.\n   * Defaults to true for backwards compatibility with existing navigate tools.\n   */\n  readGlobalCommandFallback?: boolean;\n  /** React Query key used for command polling/cache. */\n  commandQueryKey?: QueryKey;\n  /** Poll interval for command reads. Defaults to 2000ms. Pass false to disable polling. */\n  refetchInterval?: number | false;\n  /** Disable both navigation writes and command reads. */\n  enabled?: boolean;\n  /** Navigation writes use keepalive by default because they often fire during unload. */\n  keepalive?: boolean;\n  /** Debounce navigation writes. Defaults to 0ms. */\n  writeDebounceMs?: number;\n  /** Custom duplicate-command key. Defaults to `_writeId` or JSON content. */\n  getCommandDedupKey?: (command: NavigateCommand) => string;\n  /** React Router navigate options, or a function of the consumed command. */\n  navigateOptions?:\n    | NavigateOptions\n    | ((command: NavigateCommand) => NavigateOptions | undefined);\n  /** Called after a command is consumed and before React Router navigation. */\n  onNavigate?: (command: NavigateCommand, path: string) => void;\n  /** Optional sink for best-effort navigation write/read/delete errors. */\n  onError?: (error: unknown) => void;\n}\n\nexport interface UseAgentRouteStateResult<\n  NavigationState,\n  NavigateCommand = NavigationState,\n> extends UseSemanticNavigationStateResult<NavigationState, NavigateCommand> {}\n\nfunction normalizeBrowserTabId(browserTabId?: string): string | undefined {\n  if (typeof browserTabId !== \"string\") return undefined;\n  const trimmed = browserTabId.trim();\n  return SAFE_BROWSER_TAB_ID_RE.test(trimmed) ? trimmed : undefined;\n}\n\nfunction appStateKeyForBrowserTab(key: string, browserTabId?: string): string {\n  return browserTabId ? `${key}:${browserTabId}` : key;\n}\n\nfunction routeLocationFromReactRouter(location: Location): AgentRouteLocation {\n  return {\n    pathname: location.pathname,\n    search: location.search,\n    hash: location.hash,\n    searchParams: new URLSearchParams(location.search),\n    location,\n  };\n}\n\nfunction uniqueKeys(keys: readonly string[]): string[] {\n  return Array.from(new Set(keys));\n}\n\nfunction defaultCommandDedupKey(command: unknown): string {\n  if (command && typeof command === \"object\" && \"_writeId\" in command) {\n    const writeId = (command as { _writeId?: unknown })._writeId;\n    if (typeof writeId === \"string\" && writeId) return writeId;\n  }\n  return JSON.stringify(command);\n}\n\nfunction currentRouterPath(location: Location): string {\n  return `${location.pathname}${location.search}${location.hash}`;\n}\n\nfunction stringifyForWriteDedup(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return \"\";\n  }\n}\n\n/**\n * Keeps semantic UI state agent-visible and consumes agent-authored one-shot\n * commands. This is the framework primitive behind route/navigation sync; it\n * intentionally knows nothing about app-specific route shapes.\n */\nexport function useSemanticNavigationState<\n  NavigationState,\n  NavigateCommand = NavigationState,\n>(\n  options: UseSemanticNavigationStateOptions<NavigationState, NavigateCommand>,\n): UseSemanticNavigationStateResult<NavigationState, NavigateCommand> {\n  const {\n    requestSource,\n    commandRefetchInterval = 2_000,\n    enabled = true,\n    keepalive = true,\n    writeDebounceMs = 0,\n  } = options;\n\n  const queryClient = useQueryClient();\n  const navigationKeys = useMemo(\n    () => uniqueKeys(options.navigationKeys ?? [\"navigation\"]),\n    [options.navigationKeys],\n  );\n  const commandKeys = useMemo(\n    () => uniqueKeys(options.commandKeys ?? [\"navigate\"]),\n    [options.commandKeys],\n  );\n  const commandQueryKey = useMemo<QueryKey>(\n    () => options.commandQueryKey ?? [\"navigate-command\"],\n    [options.commandQueryKey],\n  );\n  const navigationState = options.state ?? null;\n  const navigationWriteDedup = stringifyForWriteDedup({\n    keys: navigationKeys,\n    state: navigationState,\n  });\n\n  const getCommandDedupKeyRef = useRef(options.getCommandDedupKey);\n  const onCommandRef = useRef(options.onCommand);\n  const onErrorRef = useRef(options.onError);\n  getCommandDedupKeyRef.current = options.getCommandDedupKey;\n  onCommandRef.current = options.onCommand;\n  onErrorRef.current = options.onError;\n\n  const lastNavigationWriteRef = useRef<string | null>(null);\n\n  useEffect(() => {\n    if (!enabled) return;\n    if (lastNavigationWriteRef.current === navigationWriteDedup) return;\n    lastNavigationWriteRef.current = navigationWriteDedup;\n\n    const write = () => {\n      for (const key of navigationKeys) {\n        setClientAppState(key, navigationState, {\n          keepalive,\n          requestSource,\n        }).catch((error) => onErrorRef.current?.(error));\n      }\n    };\n\n    if (writeDebounceMs > 0) {\n      const timer = setTimeout(write, writeDebounceMs);\n      return () => clearTimeout(timer);\n    }\n    write();\n  }, [\n    enabled,\n    keepalive,\n    navigationKeys,\n    navigationState,\n    navigationWriteDedup,\n    requestSource,\n    writeDebounceMs,\n  ]);\n\n  const commandQuery =\n    useQuery<SemanticNavigationCommandEnvelope<NavigateCommand> | null>({\n      queryKey: commandQueryKey,\n      enabled,\n      retry: false,\n      refetchInterval: commandRefetchInterval,\n      queryFn: async () => {\n        for (const key of commandKeys) {\n          const command = await readClientAppState<NavigateCommand>(key);\n          if (command !== null && command !== undefined) {\n            return { key, command };\n          }\n        }\n        return null;\n      },\n    });\n\n  const clearCommand = useCallback(async () => {\n    await Promise.all(\n      commandKeys.map((key) =>\n        deleteClientAppState(key, { requestSource }).catch((error) => {\n          onErrorRef.current?.(error);\n        }),\n      ),\n    );\n    queryClient.setQueryData(commandQueryKey, null);\n  }, [commandKeys, commandQueryKey, queryClient, requestSource]);\n\n  const lastProcessedDedupKeyRef = useRef<string | null>(null);\n\n  useEffect(() => {\n    const envelope = commandQuery.data;\n    if (!enabled || !envelope) return;\n\n    const dedupKey =\n      getCommandDedupKeyRef.current?.(envelope.command) ??\n      defaultCommandDedupKey(envelope.command);\n    const consume = () => {\n      deleteClientAppState(envelope.key, { requestSource }).catch((error) =>\n        onErrorRef.current?.(error),\n      );\n      queryClient.setQueryData(commandQueryKey, null);\n    };\n\n    if (lastProcessedDedupKeyRef.current === dedupKey) {\n      consume();\n      return;\n    }\n    lastProcessedDedupKeyRef.current = dedupKey;\n    consume();\n\n    Promise.resolve(onCommandRef.current(envelope.command)).catch((error) =>\n      onErrorRef.current?.(error),\n    );\n  }, [commandQuery.data, commandQueryKey, enabled, queryClient, requestSource]);\n\n  return {\n    navigationState,\n    command: commandQuery.data,\n    commandQueryKey,\n    clearCommand,\n  };\n}\n\n/**\n * React Router convenience wrapper around `useSemanticNavigationState`.\n *\n * Use URL query params as the source of truth for shareable filters. This hook\n * writes semantic aliases and stable IDs to `navigation`; the framework's\n * built-in URL sync separately exposes raw `pathname`, `search`, and\n * `searchParams` through `<current-url>` and the `set-search-params` tool.\n */\nexport function useAgentRouteState<\n  NavigationState,\n  NavigateCommand = NavigationState,\n>(\n  options: UseAgentRouteStateOptions<NavigationState, NavigateCommand>,\n): UseAgentRouteStateResult<NavigationState, NavigateCommand> {\n  const {\n    navigationKey = \"navigation\",\n    commandKey = \"navigate\",\n    writeGlobalNavigation = true,\n    readGlobalCommandFallback = true,\n  } = options;\n\n  const location = useLocation();\n  const navigate = useNavigate();\n  const browserTabId = useMemo(\n    () => normalizeBrowserTabId(options.browserTabId),\n    [options.browserTabId],\n  );\n  const navigationKeys = useMemo(() => {\n    const scopedKey = appStateKeyForBrowserTab(navigationKey, browserTabId);\n    const keys = [scopedKey];\n    if (browserTabId && writeGlobalNavigation) keys.push(navigationKey);\n    return uniqueKeys(keys);\n  }, [browserTabId, navigationKey, writeGlobalNavigation]);\n  const commandKeys = useMemo(() => {\n    const scopedKey = appStateKeyForBrowserTab(commandKey, browserTabId);\n    const keys = [scopedKey];\n    if (browserTabId && readGlobalCommandFallback) keys.push(commandKey);\n    return uniqueKeys(keys);\n  }, [browserTabId, commandKey, readGlobalCommandFallback]);\n  const commandQueryKey = useMemo<QueryKey>(\n    () =>\n      options.commandQueryKey ?? [\n        \"navigate-command\",\n        commandKey,\n        browserTabId ?? \"global\",\n      ],\n    [browserTabId, commandKey, options.commandQueryKey],\n  );\n\n  const routeLocation = useMemo(\n    () => routeLocationFromReactRouter(location),\n    [location],\n  );\n  const navigationState = options.getNavigationState(routeLocation) ?? null;\n\n  return useSemanticNavigationState<NavigationState, NavigateCommand>({\n    state: navigationState,\n    navigationKeys,\n    commandKeys,\n    commandQueryKey,\n    requestSource: options.requestSource,\n    commandRefetchInterval: options.refetchInterval,\n    enabled: options.enabled,\n    keepalive: options.keepalive,\n    writeDebounceMs: options.writeDebounceMs,\n    getCommandDedupKey: options.getCommandDedupKey,\n    onError: options.onError,\n    onCommand: (command) => {\n      const path = options.getCommandPath(command);\n      if (!path) return;\n      options.onNavigate?.(command, path);\n      if (path === currentRouterPath(location)) return;\n\n      const navigateOptions = options.navigateOptions;\n      const resolvedOptions =\n        typeof navigateOptions === \"function\"\n          ? navigateOptions(command)\n          : navigateOptions;\n      navigate(path, resolvedOptions);\n    },\n  });\n}\n"]}

package/dist/templates/default/AGENTS.md

@@ -57,6 +57,12 @@ Ephemeral UI state is stored in the SQL `application_state` table, accessed via
 
 The `navigation` key is written by the UI whenever the route changes. The `navigate` key is a one-shot command: the agent writes it, the UI reads and executes the navigation, then deletes it.
 
+UI code should use `useAgentRouteState` / `useSemanticNavigationState` from
+`@agent-native/core/client` for navigation sync instead of hand-written
+`fetch("/_agent-native/application-state/...")` calls. Keep shareable filters
+in URL query params; the framework exposes them as `<current-url>` and the
+built-in agent can update them with `set-search-params`.
+
 ## Mounted Workspace Routing
 
 This app may be mounted under `/<app-id>` in a workspace. Inside app source, React Router paths are app-local: use `<Link to="/review">` and `navigate("/review")`, not `/<app-id>/review`. The workspace gateway and `APP_BASE_PATH` add the mounted prefix in the browser; hardcoding it inside React Router links causes doubled URLs such as `/<app-id>/<app-id>/review`.
@@ -123,7 +129,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 
 **Read the `adding-a-feature` skill first** — it has the full four-area checklist (UI / Action / Skills / App-State). Quick summary:
 
-1. **Add navigation state entries** — extend `app/hooks/use-navigation-state.ts` to track new routes
+1. **Add navigation state entries** — extend `app/hooks/use-navigation-state.ts` to track new routes with `useAgentRouteState`
 2. **Enhance view-screen** — make the view-screen script return relevant context for the new view
 3. **Create domain actions** — add actions in `actions/` for CRUD operations on new data models; do not create REST wrappers around those actions
 4. **Wire UI for auto-refresh** — use `useActionQuery` / `useActionMutation` for normal CRUD. If a raw `useQuery` is unavoidable, fold `useChangeVersions([<source>, "action"])` into its key with `placeholderData`. When the agent mutates this data, the UI must reflect the change without a manual refresh. See `real-time-sync` skill.

package/dist/templates/default/app/hooks/use-navigation-state.ts

@@ -1,10 +1,7 @@
-import { useEffect, useRef } from "react";
-import { useLocation, useNavigate } from "react-router";
-import { useQuery, useQueryClient } from "@tanstack/react-query";
 import {
-  agentNativePath,
   appBasePath,
   appPath,
+  useAgentRouteState,
 } from "@agent-native/core/client";
 import { TAB_ID } from "../lib/tab-id";
 
@@ -18,79 +15,16 @@ export interface NavigationState {
 }
 
 export function useNavigationState() {
-  const location = useLocation();
-  const navigate = useNavigate();
-  const qc = useQueryClient();
-
-  useEffect(() => {
-    const state: NavigationState = {
-      view: viewFromPath(location.pathname),
-      path: appPath(location.pathname),
-    };
-
-    fetch(agentNativePath("/_agent-native/application-state/navigation"), {
-      method: "PUT",
-      keepalive: true,
-      headers: {
-        "Content-Type": "application/json",
-        "X-Request-Source": TAB_ID,
-      },
-      body: JSON.stringify(state),
-    }).catch(() => {});
-  }, [location.pathname]);
-
-  // Default React Query structuralSharing reuses the previous reference when
-  // the JSON is unchanged, so repeated invalidations driven by `useDbSync`
-  // (which fire on every relevant app-state event) don't re-fire the
-  // useEffect with a brand-new object containing the same command.
-  const { data: navCommand } = useQuery<NavigationState | null>({
-    queryKey: ["navigate-command"],
-    queryFn: async () => {
-      const res = await fetch(
-        agentNativePath("/_agent-native/application-state/navigate"),
-      );
-      if (!res.ok) return null;
-      const data = await res.json();
-      return data ?? null;
-    },
-    refetchInterval: 2_000,
+  useAgentRouteState<NavigationState>({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, search, hash }) => ({
+      view: viewFromPath(pathname),
+      path: appPath(`${pathname}${search}${hash}`),
+    }),
+    getCommandPath: (command) =>
+      routerPath(command.path || pathFromView(command.view)),
   });
-
-  const lastProcessedDedupKeyRef = useRef<string | null>(null);
-
-  useEffect(() => {
-    if (!navCommand) return;
-    const cmd = navCommand;
-    const dedupKey =
-      cmd._writeId ?? JSON.stringify({ view: cmd.view, path: cmd.path });
-    if (lastProcessedDedupKeyRef.current === dedupKey) {
-      // Same command we already handled — the consume-DELETE races against
-      // the next polling refetch, so when it loses the same command can show
-      // up again. Re-fire DELETE and bail rather than navigate again.
-      fetch(agentNativePath("/_agent-native/application-state/navigate"), {
-        method: "DELETE",
-        headers: {
-          "X-Agent-Native-CSRF": "1",
-          "X-Request-Source": TAB_ID,
-        },
-      }).catch(() => {});
-      qc.setQueryData(["navigate-command"], null);
-      return;
-    }
-    lastProcessedDedupKeyRef.current = dedupKey;
-
-    fetch(agentNativePath("/_agent-native/application-state/navigate"), {
-      method: "DELETE",
-      headers: {
-        "X-Agent-Native-CSRF": "1",
-        "X-Request-Source": TAB_ID,
-      },
-    }).catch(() => {});
-
-    const path = routerPath(cmd.path || pathFromView(cmd.view));
-    navigate(path);
-    qc.setQueryData(["navigate-command"], null);
-  }, [navCommand, navigate, qc]);
 }
 
 function viewFromPath(pathname: string): string {

package/docs/content/context-awareness.md

@@ -11,13 +11,14 @@ How the agent knows what the user is looking at -- and how the agent can control
 
 Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. With context awareness, the user can click a row, highlight a paragraph, select a slide element, or press Cmd+I, then say "summarize this" and the agent already knows what "this" means.
 
-Five patterns solve this:
+Six patterns solve this:
 
 1. **Navigation state** -- the UI writes a `navigation` key to application-state on every route change
-2. **Selection state** -- the UI writes a `selection` key when the user focuses, selects, or multi-selects something meaningful
-3. **`view-screen`** -- an action that reads application state, fetches contextual data, and returns a snapshot of what the user sees
-4. **Prompt handoff** -- UI controls call `sendToAgentChat()` when a click should become an agent turn
-5. **`navigate`** -- a one-shot command from the agent that tells the UI where to go
+2. **Current URL** -- the framework writes `__url__` so query params are visible and editable by the agent
+3. **Selection state** -- the UI writes a `selection` key when the user focuses, selects, or multi-selects something meaningful
+4. **`view-screen`** -- an action that reads application state, fetches contextual data, and returns a snapshot of what the user sees
+5. **Prompt handoff** -- UI controls call `sendToAgentChat()` when a click should become an agent turn
+6. **`navigate`** -- a one-shot command from the agent that tells the UI where to go
 
 ## Context layers {#context-layers}
 
@@ -25,25 +26,26 @@ Use different context channels for different jobs:
 
 | Layer                                     | Owner             | Use it for                                                                 |
 | ----------------------------------------- | ----------------- | -------------------------------------------------------------------------- |
-| `navigation` app-state key                | UI                | Current route, view, open record, filters, active tab                      |
+| `navigation` app-state key                | UI                | Semantic route state: current view, open record, active tab, stable IDs    |
+| `__url__` app-state key                   | Framework UI      | Current pathname, search string, hash, and parsed URL query params         |
+| `__set_url__` app-state key               | Agent / framework | One-shot URL edits from `set-search-params` and `set-url-path`             |
 | `selection` app-state key                 | UI                | Durable semantic selection: rows, blocks, shapes, assets, messages         |
 | `pending-selection-context` app-state key | UI / `AgentPanel` | One-shot selected text attached to the next chat turn, usually from Cmd+I  |
 | `view-screen` action                      | Agent             | Hydrating the app-state keys into real records and screen summaries        |
 | `sendToAgentChat()`                       | UI                | Turning a click, command, comment pin, or selected item into a chat prompt |
 | `navigate` app-state key                  | Agent             | Asking the UI to move to another route or focus another object             |
 
-The short version: app state tells the agent what the user is looking at, `view-screen` turns that state into useful data, and `sendToAgentChat()` turns UI intent into a chat message when the user clicks a command.
+The short version: URL query params are the source of truth for shareable filters, `navigation` stores semantic IDs and view names, `view-screen` turns those state layers into useful data, and `sendToAgentChat()` turns UI intent into a chat message when the user clicks a command.
 
 ## Navigation state {#navigation-state}
 
-The UI writes a `navigation` key to application-state on every route change. This tells the agent what view the user is on, what item is open, and which filters shape the visible list.
+The UI writes a `navigation` key to application-state on every route change. This tells the agent what view the user is on, what item is open, and which semantic UI state matters.
 
 ```json
 {
   "view": "inbox",
   "threadId": "thread-123",
   "focusedEmailId": "msg-456",
-  "search": "budget",
   "label": "important"
 }
 ```
@@ -52,10 +54,10 @@ What to include in navigation state:
 
 - `view` -- the current page/section, such as "inbox", "form-builder", or "dashboard"
 - Item IDs -- the selected/open item, such as `threadId` or `formId`
-- Filter state -- active search, label, or category filters
+- Semantic aliases -- active tab, label name, or other stable app concepts that help the agent reason
 - Light focus state -- focused row, active tab, current panel
 
-Keep `navigation` small and URL-like. It should identify the current screen, not duplicate whole records. Fetch records in `view-screen` so the agent always gets fresh data.
+Keep `navigation` small and semantic. It should identify the current screen, not duplicate whole records or mirror every query param. Fetch records in `view-screen` so the agent always gets fresh data.
 
 The agent reads this before acting:
 
@@ -66,6 +68,44 @@ const navigation = await readAppState("navigation");
 // { view: "inbox", threadId: "thread-123", label: "important" }
 ```
 
+## Current URL and filters {#current-url}
+
+`AgentPanel` automatically syncs the current React Router URL into the `__url__` application-state key. The built-in agent includes it in every turn as a `<current-url>` block:
+
+```txt
+<current-url>
+pathname: /adhoc/revenue
+search: ?f_region=west&q=renewal
+searchParams:
+  f_region: west
+  q: renewal
+</current-url>
+```
+
+This is the canonical layer for shareable filter state. If the user can copy a URL and come back to the same filtered list, the filter belongs in the query string. The agent can change those filters with the built-in `set-search-params` tool:
+
+```txt
+set-search-params({ "params": { "f_region": "east", "q": null } })
+```
+
+Use `navigation` only for semantic aliases that help `view-screen` fetch or summarize the right data. A dashboard might keep `navigation.dashboardId` while `__url__.searchParams` owns `f_region`, `f_dateStart`, and `q`.
+
+When `view-screen` returns a richer snapshot, it can copy important URL filters into a friendly `activeFilters` object:
+
+```ts
+const url = (await readAppState("__url__")) as {
+  searchParams?: Record<string, string>;
+} | null;
+
+if (url?.searchParams) {
+  screen.activeFilters = Object.fromEntries(
+    Object.entries(url.searchParams).filter(
+      ([key, value]) => key.startsWith("f_") && value,
+    ),
+  );
+}
+```
+
 ## Selection state {#selection-state}
 
 Selection is semantic UI state. It is how "the chart I clicked", "these three rows", "this slide title", or "the current email draft range" becomes model-visible context.
@@ -257,58 +297,60 @@ import { writeAppState } from "@agent-native/core/application-state";
 await writeAppState("navigate", { view: "inbox", threadId: "thread-123" });
 ```
 
-The UI polls for this command and navigates when it appears:
+The UI should consume these commands through `useAgentRouteState`, which handles command polling, tab-scoped fallback keys, duplicate-command protection, and delete-after-read:
 
-```ts
-// UI side -- poll for navigate commands
-import {
-  deleteClientAppState,
-  readClientAppState,
-} from "@agent-native/core/client";
-
-const { data: navCommand } = useQuery({
-  queryKey: ["navigate-command"],
-  queryFn: async () => {
-    const data = await readClientAppState<NavigateCommand>("navigate");
-    if (data) {
-      await deleteClientAppState("navigate");
-      return data;
-    }
-    return null;
-  },
-  staleTime: 2_000,
-});
+```tsx
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
 
-useEffect(() => {
-  if (navCommand) {
-    router.navigate(buildPath(navCommand));
-  }
-}, [navCommand]);
+interface NavigationState {
+  view: "inbox" | "thread";
+  threadId?: string;
+}
+
+export function useNavigationState() {
+  useAgentRouteState<NavigationState>({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname }) => {
+      const match = pathname.match(/^\/thread\/([^/]+)/);
+      return match ? { view: "thread", threadId: match[1] } : { view: "inbox" };
+    },
+    getCommandPath: (command) =>
+      command.view === "thread" && command.threadId
+        ? `/thread/${command.threadId}`
+        : "/",
+  });
+}
 ```
 
 The `navigation` key belongs to the UI -- the agent should never write to it directly. Instead, the agent writes to `navigate`, and the UI performs the actual navigation, which then updates `navigation`.
 
 ## useNavigationState hook {#use-navigation-state}
 
-The `use-navigation-state.ts` hook syncs routes to application-state on every navigation:
+The `use-navigation-state.ts` hook is usually a thin wrapper around `useAgentRouteState`. Template code supplies the app-specific route mapping; core owns application-state writes, command reads/deletes, request-source headers, and duplicate-command prevention.
 
-```ts
+```tsx
 // app/hooks/use-navigation-state.ts
-import { useEffect } from "react";
-import { useLocation } from "react-router";
-import { setClientAppState } from "@agent-native/core/client";
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
 
 export function useNavigationState() {
-  const location = useLocation();
-
-  useEffect(() => {
-    const state = deriveNavigationState(location.pathname);
-    setClientAppState("navigation", state).catch(() => {});
-  }, [location.pathname]);
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      // Optional semantic alias. Raw query params are still visible in
+      // <current-url> and controllable with set-search-params.
+      label: searchParams.get("label"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+  });
 }
 ```
 
-The `deriveNavigationState()` function is template-specific -- it parses the URL path and extracts the view, item IDs, and filters relevant to your app.
+For non-router state channels, use the lower-level `useSemanticNavigationState`. It takes a ready-made `state`, an ordered list of `navigationKeys`/`commandKeys`, and an `onCommand` callback, but does not import or assume React Router.
 
 ## Jitter prevention {#jitter-prevention}
 

package/docs/content/creating-templates.md

@@ -215,10 +215,31 @@ Common sources: `"action"` (every successful agent action — the reliable fallb
 
 Application state is how the agent knows what the user is seeing. At minimum, add:
 
-- A UI hook that writes `navigation` state when routes, selected records, filters, or editor selections change.
+- A UI hook that writes semantic `navigation` state when routes, selected records, active tabs, or editor selections change.
 - A `view-screen` action that reads that state and returns the current screen snapshot.
 - A `navigate` action that writes a one-shot `navigate` command for the UI to consume.
 
+Use `useAgentRouteState` for the UI hook so application-state writes, tab-scoped command reads, delete-after-read, and duplicate-command protection stay consistent:
+
+```tsx
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      selectedId: searchParams.get("id"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+  });
+}
+```
+
+Keep shareable filters in URL query params. The framework exposes them to the agent as `<current-url>` and the built-in agent can change them with `set-search-params`; `navigation` should hold semantic IDs and aliases, not a second copy of the full query string.
+
 ```ts
 // actions/navigate.ts
 import { defineAction } from "@agent-native/core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -43,6 +43,7 @@
     "./client/AgentPanel": "./dist/client/AgentPanel.js",
     "./client/application-state": "./dist/client/application-state.js",
     "./client/api-path": "./dist/client/api-path.js",
+    "./client/route-state": "./dist/client/route-state.js",
     "./client/observability": "./dist/client/observability/index.js",
     "./client/onboarding": "./dist/client/onboarding/index.js",
     "./client/settings/useBuilderStatus": "./dist/client/settings/useBuilderStatus.js",