@agent-native/core 0.35.3 → 0.37.0

package/src/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/src/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 {