@agent-native/core 0.12.15 → 0.12.16

package/dist/templates/default/AGENTS.md

@@ -50,6 +50,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.
 
+## 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`.
+
+For raw paths outside React Router, use the core helpers: `appPath()` for static assets or normal hrefs, `appApiPath()` for `/api/*`, and `agentNativePath()` for `/_agent-native/*`.
+
 ## Agent Operations
 
 **Always know what the user is currently viewing before you edit anything.** The user's view can change mid-conversation. Stale IDs lead to editing the wrong record.
@@ -101,7 +107,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 
 As you build out this app, follow this checklist for each new feature:
 
-1. **Add navigation state entries** -- create or 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
 2. **Enhance view-screen** -- make the view-screen script return relevant context for the new view
 3. **Create domain actions** -- add scripts for CRUD operations on new data models
 4. **Create domain skills** -- add `.agents/skills/<feature>/SKILL.md` documenting the data model, storage patterns, and agent operations

package/dist/templates/default/DEVELOPING.md

@@ -20,6 +20,18 @@ app/routes/inbox.$threadId.tsx     → /inbox/:threadId
 app/routes/$id.tsx                 → /:id (dynamic param)
 ```
 
+## Mounted Workspace Routing
+
+In a workspace, this app can be mounted under `/<app-id>`. React Router already receives `APP_BASE_PATH`/`VITE_APP_BASE_PATH` through `appBasePath()`, so route code stays app-local:
+
+| Route file              | App-internal route | Mounted browser URL |
+| ----------------------- | ------------------ | ------------------- |
+| `app/routes/_index.tsx` | `/`                | `/<app-id>`         |
+| `app/routes/review.tsx` | `/review`          | `/<app-id>/review`  |
+| `app/routes/$id.tsx`    | `/:id`             | `/<app-id>/:id`     |
+
+Use `<Link to="/review">` and `navigate("/review")` inside this app. Do not prefix React Router paths with `/<app-id>` or the URL can double-prefix, e.g. `/<app-id>/<app-id>/review`. Use `appPath()` for raw `href`s/static assets, `appApiPath()` for `/api/*`, and `agentNativePath()` for `/_agent-native/*`.
+
 Each route file exports a default component and optional `meta()`:
 
 ```tsx

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

@@ -0,0 +1,81 @@
+import { useEffect } from "react";
+import { useLocation, useNavigate } from "react-router";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  agentNativePath,
+  appBasePath,
+  appPath,
+} from "@agent-native/core/client";
+
+export interface NavigationState {
+  view: string;
+  path?: string;
+}
+
+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" },
+      body: JSON.stringify(state),
+    }).catch(() => {});
+  }, [location.pathname]);
+
+  const { data: navCommand } = useQuery({
+    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 ? { ...data, _ts: Date.now() } : null;
+    },
+    refetchInterval: 2_000,
+    refetchIntervalInBackground: true,
+    structuralSharing: false,
+  });
+
+  useEffect(() => {
+    if (!navCommand) return;
+    fetch(agentNativePath("/_agent-native/application-state/navigate"), {
+      method: "DELETE",
+      headers: { "X-Agent-Native-CSRF": "1" },
+    }).catch(() => {});
+    const cmd = navCommand as NavigationState;
+
+    const path = routerPath(cmd.path || pathFromView(cmd.view));
+    navigate(path);
+    qc.setQueryData(["navigate-command"], null);
+  }, [navCommand, navigate, qc]);
+}
+
+function viewFromPath(pathname: string): string {
+  if (!pathname || pathname === "/") return "home";
+  return pathname.replace(/^\/+/, "") || "home";
+}
+
+function pathFromView(view: string | undefined): string {
+  if (!view || view === "home") return "/";
+  return `/${view.replace(/^\/+/, "")}`;
+}
+
+function routerPath(path: string): string {
+  const basePath = appBasePath();
+  if (!basePath) return path;
+  if (path === basePath) return "/";
+  if (path.startsWith(`${basePath}/`)) {
+    return path.slice(basePath.length) || "/";
+  }
+  return path;
+}

package/dist/templates/default/app/root.tsx

@@ -16,10 +16,15 @@ import {
 } from "@tanstack/react-query";
 import { ThemeProvider } from "next-themes";
 import { useDbSync } from "@agent-native/core";
-import { ClientOnly, DefaultSpinner } from "@agent-native/core/client";
-import { getThemeInitScript } from "@agent-native/core/client";
+import {
+  ClientOnly,
+  DefaultSpinner,
+  appPath,
+  getThemeInitScript,
+} from "@agent-native/core/client";
 import { Toaster } from "sonner";
 import { configureTracking } from "@agent-native/core/client";
+import { useNavigationState } from "./hooks/use-navigation-state";
 configureTracking({
   getDefaultProps: (_name, properties) => ({
     ...properties,
@@ -56,8 +61,8 @@ export function Layout({ children }: { children: React.ReactNode }) {
           suppressHydrationWarning
           dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }}
         />
-        <link rel="manifest" href="/manifest.json" />
-        <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+        <link rel="manifest" href={appPath("/manifest.json")} />
+        <link rel="icon" type="image/svg+xml" href={appPath("/favicon.svg")} />
         <meta name="theme-color" content="#111111" />
         <meta name="mobile-web-app-capable" content="yes" />
         <meta
@@ -65,7 +70,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
           content="black-translucent"
         />
         <meta name="apple-mobile-web-app-title" content="App" />
-        <link rel="apple-touch-icon" href="/icon-180.svg" />
+        <link rel="apple-touch-icon" href={appPath("/icon-180.svg")} />
         <Meta />
         <Links />
       </head>
@@ -80,6 +85,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
 
 function DbSyncSetup() {
   const qc = useQueryClient();
+  useNavigationState();
   useDbSync({ queryClient: qc, queryKeys: ["files", "data"] });
   return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.12.15",
+  "version": "0.12.16",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",

package/src/templates/default/AGENTS.md

@@ -50,6 +50,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.
 
+## 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`.
+
+For raw paths outside React Router, use the core helpers: `appPath()` for static assets or normal hrefs, `appApiPath()` for `/api/*`, and `agentNativePath()` for `/_agent-native/*`.
+
 ## Agent Operations
 
 **Always know what the user is currently viewing before you edit anything.** The user's view can change mid-conversation. Stale IDs lead to editing the wrong record.
@@ -101,7 +107,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 
 As you build out this app, follow this checklist for each new feature:
 
-1. **Add navigation state entries** -- create or 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
 2. **Enhance view-screen** -- make the view-screen script return relevant context for the new view
 3. **Create domain actions** -- add scripts for CRUD operations on new data models
 4. **Create domain skills** -- add `.agents/skills/<feature>/SKILL.md` documenting the data model, storage patterns, and agent operations

package/src/templates/default/DEVELOPING.md

@@ -20,6 +20,18 @@ app/routes/inbox.$threadId.tsx     → /inbox/:threadId
 app/routes/$id.tsx                 → /:id (dynamic param)
 ```
 
+## Mounted Workspace Routing
+
+In a workspace, this app can be mounted under `/<app-id>`. React Router already receives `APP_BASE_PATH`/`VITE_APP_BASE_PATH` through `appBasePath()`, so route code stays app-local:
+
+| Route file              | App-internal route | Mounted browser URL |
+| ----------------------- | ------------------ | ------------------- |
+| `app/routes/_index.tsx` | `/`                | `/<app-id>`         |
+| `app/routes/review.tsx` | `/review`          | `/<app-id>/review`  |
+| `app/routes/$id.tsx`    | `/:id`             | `/<app-id>/:id`     |
+
+Use `<Link to="/review">` and `navigate("/review")` inside this app. Do not prefix React Router paths with `/<app-id>` or the URL can double-prefix, e.g. `/<app-id>/<app-id>/review`. Use `appPath()` for raw `href`s/static assets, `appApiPath()` for `/api/*`, and `agentNativePath()` for `/_agent-native/*`.
+
 Each route file exports a default component and optional `meta()`:
 
 ```tsx

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

@@ -0,0 +1,81 @@
+import { useEffect } from "react";
+import { useLocation, useNavigate } from "react-router";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+  agentNativePath,
+  appBasePath,
+  appPath,
+} from "@agent-native/core/client";
+
+export interface NavigationState {
+  view: string;
+  path?: string;
+}
+
+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" },
+      body: JSON.stringify(state),
+    }).catch(() => {});
+  }, [location.pathname]);
+
+  const { data: navCommand } = useQuery({
+    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 ? { ...data, _ts: Date.now() } : null;
+    },
+    refetchInterval: 2_000,
+    refetchIntervalInBackground: true,
+    structuralSharing: false,
+  });
+
+  useEffect(() => {
+    if (!navCommand) return;
+    fetch(agentNativePath("/_agent-native/application-state/navigate"), {
+      method: "DELETE",
+      headers: { "X-Agent-Native-CSRF": "1" },
+    }).catch(() => {});
+    const cmd = navCommand as NavigationState;
+
+    const path = routerPath(cmd.path || pathFromView(cmd.view));
+    navigate(path);
+    qc.setQueryData(["navigate-command"], null);
+  }, [navCommand, navigate, qc]);
+}
+
+function viewFromPath(pathname: string): string {
+  if (!pathname || pathname === "/") return "home";
+  return pathname.replace(/^\/+/, "") || "home";
+}
+
+function pathFromView(view: string | undefined): string {
+  if (!view || view === "home") return "/";
+  return `/${view.replace(/^\/+/, "")}`;
+}
+
+function routerPath(path: string): string {
+  const basePath = appBasePath();
+  if (!basePath) return path;
+  if (path === basePath) return "/";
+  if (path.startsWith(`${basePath}/`)) {
+    return path.slice(basePath.length) || "/";
+  }
+  return path;
+}

package/src/templates/default/app/root.tsx

@@ -16,10 +16,15 @@ import {
 } from "@tanstack/react-query";
 import { ThemeProvider } from "next-themes";
 import { useDbSync } from "@agent-native/core";
-import { ClientOnly, DefaultSpinner } from "@agent-native/core/client";
-import { getThemeInitScript } from "@agent-native/core/client";
+import {
+  ClientOnly,
+  DefaultSpinner,
+  appPath,
+  getThemeInitScript,
+} from "@agent-native/core/client";
 import { Toaster } from "sonner";
 import { configureTracking } from "@agent-native/core/client";
+import { useNavigationState } from "./hooks/use-navigation-state";
 configureTracking({
   getDefaultProps: (_name, properties) => ({
     ...properties,
@@ -56,8 +61,8 @@ export function Layout({ children }: { children: React.ReactNode }) {
           suppressHydrationWarning
           dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }}
         />
-        <link rel="manifest" href="/manifest.json" />
-        <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+        <link rel="manifest" href={appPath("/manifest.json")} />
+        <link rel="icon" type="image/svg+xml" href={appPath("/favicon.svg")} />
         <meta name="theme-color" content="#111111" />
         <meta name="mobile-web-app-capable" content="yes" />
         <meta
@@ -65,7 +70,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
           content="black-translucent"
         />
         <meta name="apple-mobile-web-app-title" content="App" />
-        <link rel="apple-touch-icon" href="/icon-180.svg" />
+        <link rel="apple-touch-icon" href={appPath("/icon-180.svg")} />
         <Meta />
         <Links />
       </head>
@@ -80,6 +85,7 @@ export function Layout({ children }: { children: React.ReactNode }) {
 
 function DbSyncSetup() {
   const qc = useQueryClient();
+  useNavigationState();
   useDbSync({ queryClient: qc, queryKeys: ["files", "data"] });
   return null;
 }