@agent-native/core 0.58.5 → 0.59.1

package/docs/content/creating-templates.md

@@ -234,12 +234,17 @@ export function useNavigationState() {
       selectedId: searchParams.get("id"),
     }),
     getCommandPath: (command: any) => command.path ?? "/",
+    navigateOptions: { replace: true, flushSync: true },
   });
 }
 ```
 
 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.
 
+For app navigation, prefer one `navigate` command that includes a same-origin
+`path` when the URL is known. Do not also write `__set_url__` for the same move;
+that key is reserved for the framework URL tools and URL-only filter changes.
+
 ```ts
 // actions/navigate.ts
 import { defineAction } from "@agent-native/core";
@@ -251,6 +256,7 @@ export default defineAction({
   schema: z.object({
     view: z.enum(["home", "project"]),
     projectId: z.string().optional(),
+    path: z.string().optional(),
   }),
   run: async (args) => {
     await writeAppState("navigate", args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.58.5",
+  "version": "0.59.1",
   "type": "module",
   "engines": {
     "node": ">=22"

package/src/templates/workspace-core/.agents/skills/client-side-routing/SKILL.md

@@ -66,6 +66,15 @@ export default function Settings() {
 
 If a page needs per-route data (e.g. sidebar highlighting the active document), derive it inside the layout from `useParams()` / `useLocation()` — don't pass it as a prop through every route file.
 
+## Chat-First Routes
+
+If `/` is a full-page chat such as `AgentChatHome`, keep the app shell mounted
+around it when possible so `AgentSidebar` URL sync and route warmup stay active.
+If the chat route intentionally lives outside the shell, add a tiny app-owned
+prewarm for the routes agents commonly open from that chat. In local dev,
+React Router can update the address bar before a cold Vite route chunk commits,
+which makes navigation look broken even when the URL is correct.
+
 ## Adding a New Route
 
 - **Pattern #1** (AppLayout in `root.tsx`): just render page content — nothing else.

package/src/templates/workspace-core/.agents/skills/context-awareness/SKILL.md

@@ -125,6 +125,15 @@ await writeAppState("navigate", { view: "inbox", threadId: "abc123" });
 **UI side** — use `useAgentRouteState`, shown above. It polls command keys,
 dedupes `_writeId`, deletes consumed commands, and applies app-local routing.
 
+When a destination has a real URL, let the `navigate` command carry that local
+`path` (plus semantic fields when useful) and have the UI prefer `path` before
+falling back to semantic routing. Keep app navigation single-channel: do not
+also write `__set_url__` for the same navigation. `__set_url__` belongs to the
+framework URL tools (`set-url-path`, `set-search-params`) and URL-only filter
+changes. If a command can arrive while a chat stream is rendering, prefer
+`navigate(path, { replace: true, flushSync: true })` over a view-transition
+wrapper so the URL and visible route commit together.
+
 ## Jitter Prevention
 
 When the agent writes to application-state via script helpers (`writeAppState`), the write is tagged with `requestSource: "agent"`. The UI uses the `ignoreSource` option on `useDbSync()` with a per-tab ID so it ignores its own writes while still picking up changes from agents, other tabs, and scripts.
@@ -171,7 +180,7 @@ The mail template demonstrates these patterns working together:
 - Keep shareable filters in URL query params so `<current-url>` and `set-search-params` work
 - Update `view-screen` when adding new features — it should return data for every view
 - Use `useAgentRouteState` or `useSemanticNavigationState` for UI-side navigation sync and command consumption
-- Use the one-shot `navigate` command pattern for semantic agent-initiated navigation
+- Use the one-shot `navigate` command pattern for app navigation; include a same-origin `path` when the target URL is known
 - Tag agent writes with `requestSource: "agent"` (the script helpers do this automatically)
 
 ## Don't
@@ -179,6 +188,7 @@ The mail template demonstrates these patterns working together:
 - Don't assume the user is on a specific page — always check navigation state
 - Don't hardcode navigation paths in scripts — read the current state and branch
 - Don't write to the `navigation` key from the agent — it belongs to the UI. Use `navigate` instead.
+- Don't write both `navigate` and `__set_url__` for one app navigation; competing consumers can make the browser URL change before React Router commits the page.
 - Don't ignore the `<current-screen>` block — it tells you where the user is
 - Don't duplicate whole URL query strings into `navigation` when `<current-url>` already exposes them
 - Don't store fetched data in navigation state — it holds IDs and semantic UI state only. The `view-screen` script fetches the actual data.