@agent-native/core 0.35.3 → 0.37.0

package/dist/server/security-headers.d.ts

@@ -3,9 +3,9 @@
  *
  * Sets a baseline set of "no-brainer" security headers on every framework HTTP
  * response. These headers are layered defenses: each one mitigates a specific
- * class of attack, and together they harden the surface against clickjacking,
- * MIME-sniffing, referrer leakage, mixed-content downgrades, and cross-origin
- * window/embed access.
+ * class of attack, and together they harden the surface against MIME-sniffing,
+ * referrer leakage, mixed-content downgrades, and cross-origin window/embed
+ * access.
  *
  * The headers we emit:
  *
@@ -16,15 +16,6 @@
  *   - `X-Content-Type-Options: nosniff` — disables browser MIME sniffing so
  *     a tool /render route serving user-authored HTML can't be misinterpreted
  *     as some other content type by a clever Accept header.
- *   - `X-Frame-Options: DENY` — prevents the entire app from being iframed by
- *     other origins (clickjacking the agent chat, booking pages, etc.). The
- *     tool /render endpoint and any other route that legitimately needs to be
- *     embedded in the same-origin app shell can opt out by setting its own
- *     header inside the route handler — h3's `setResponseHeader` overwrites,
- *     so a route emitting `SAMEORIGIN` wins over our middleware default.
- *     We skip this header entirely in dev (NODE_ENV !== "production") so the
- *     desktop app's local dev frame (localhost:3334) can iframe templates
- *     running on other localhost ports (e.g. mail at 8085).
  *   - `Referrer-Policy: strict-origin-when-cross-origin` — strips path/query
  *     from outbound Referer headers when the request crosses origin, so a
  *     public-share viewer's outbound link clicks never leak the share token.
@@ -36,25 +27,31 @@
  *   - `Cross-Origin-Opener-Policy: same-origin` — isolates window.opener so
  *     a popup-window opener reference can't read or modify our document.
  *   - `Cross-Origin-Embedder-Policy: require-corp` — emitted only for
- *     validated MCP embed-session page loads. COEP hosts such as Claude's MCP
- *     Apps proxy require framed cross-origin documents to opt in explicitly.
+ *     validated MCP embed-session page loads and browser iframe navigations.
+ *     COEP hosts such as Claude's MCP Apps proxy require framed cross-origin
+ *     documents to opt in explicitly.
  *   - `Cross-Origin-Resource-Policy: same-site` — prevents other origins from
  *     embedding our endpoints as `<img>` / `<script>` / `<audio>`, blocking
  *     the simplest data-leak chain when combined with auth cookies. Validated
- *     MCP embed-session page loads use `cross-origin` so COEP hosts such as
- *     Claude's MCP Apps proxy can frame the short-lived app document.
+ *     MCP embed-session page loads and browser iframe navigations use
+ *     `cross-origin` so COEP hosts can frame app documents.
  *
  * NOTE: `Cross-Origin-Embedder-Policy` is NOT set by default because it
  * requires every embedded subresource to opt in via CORP/CORS, which would
  * break Builder's iframe editor and template embed use cases. COOP + CORP
  * without COEP gives us most of the protection on normal responses; COEP is
- * only added for validated MCP embed-session page loads (see above).
+ * only added for validated MCP embed-session page loads and browser iframe
+ * navigations (see above).
+ *
+ * NOTE: `X-Frame-Options` is intentionally not set globally. Agent-native apps
+ * are expected to run inside iframe hosts such as Builder, Design, and MCP app
+ * shells. Routes that render especially sensitive iframe-only documents should
+ * set their own route-specific CSP / frame policy.
  */
 /**
  * Create the security-headers h3 middleware. Mount this BEFORE other route
  * handlers so the headers are present on every response (including 4xx/5xx
- * error pages). Route handlers that need to relax a specific header (e.g.
- * `X-Frame-Options: SAMEORIGIN` on the tool render route) can call
+ * error pages). Route handlers that need to tighten a specific header can call
  * `setResponseHeader` after this runs — the latest write wins.
  */
 export declare function createSecurityHeadersMiddleware(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, any>;

package/dist/server/security-headers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"security-headers.d.ts","sourceRoot":"","sources":["../../src/server/security-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AA2CH;;;;;;GAMG;AACH,wBAAgB,+BAA+B,8EA6C9C"}
+{"version":3,"file":"security-headers.d.ts","sourceRoot":"","sources":["../../src/server/security-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AA+CH;;;;;GAKG;AACH,wBAAgB,+BAA+B,8EA4C9C"}

package/dist/server/security-headers.js

@@ -3,9 +3,9 @@
  *
  * Sets a baseline set of "no-brainer" security headers on every framework HTTP
  * response. These headers are layered defenses: each one mitigates a specific
- * class of attack, and together they harden the surface against clickjacking,
- * MIME-sniffing, referrer leakage, mixed-content downgrades, and cross-origin
- * window/embed access.
+ * class of attack, and together they harden the surface against MIME-sniffing,
+ * referrer leakage, mixed-content downgrades, and cross-origin window/embed
+ * access.
  *
  * The headers we emit:
  *
@@ -16,15 +16,6 @@
  *   - `X-Content-Type-Options: nosniff` — disables browser MIME sniffing so
  *     a tool /render route serving user-authored HTML can't be misinterpreted
  *     as some other content type by a clever Accept header.
- *   - `X-Frame-Options: DENY` — prevents the entire app from being iframed by
- *     other origins (clickjacking the agent chat, booking pages, etc.). The
- *     tool /render endpoint and any other route that legitimately needs to be
- *     embedded in the same-origin app shell can opt out by setting its own
- *     header inside the route handler — h3's `setResponseHeader` overwrites,
- *     so a route emitting `SAMEORIGIN` wins over our middleware default.
- *     We skip this header entirely in dev (NODE_ENV !== "production") so the
- *     desktop app's local dev frame (localhost:3334) can iframe templates
- *     running on other localhost ports (e.g. mail at 8085).
  *   - `Referrer-Policy: strict-origin-when-cross-origin` — strips path/query
  *     from outbound Referer headers when the request crosses origin, so a
  *     public-share viewer's outbound link clicks never leak the share token.
@@ -36,19 +27,26 @@
  *   - `Cross-Origin-Opener-Policy: same-origin` — isolates window.opener so
  *     a popup-window opener reference can't read or modify our document.
  *   - `Cross-Origin-Embedder-Policy: require-corp` — emitted only for
- *     validated MCP embed-session page loads. COEP hosts such as Claude's MCP
- *     Apps proxy require framed cross-origin documents to opt in explicitly.
+ *     validated MCP embed-session page loads and browser iframe navigations.
+ *     COEP hosts such as Claude's MCP Apps proxy require framed cross-origin
+ *     documents to opt in explicitly.
  *   - `Cross-Origin-Resource-Policy: same-site` — prevents other origins from
  *     embedding our endpoints as `<img>` / `<script>` / `<audio>`, blocking
  *     the simplest data-leak chain when combined with auth cookies. Validated
- *     MCP embed-session page loads use `cross-origin` so COEP hosts such as
- *     Claude's MCP Apps proxy can frame the short-lived app document.
+ *     MCP embed-session page loads and browser iframe navigations use
+ *     `cross-origin` so COEP hosts can frame app documents.
  *
  * NOTE: `Cross-Origin-Embedder-Policy` is NOT set by default because it
  * requires every embedded subresource to opt in via CORP/CORS, which would
  * break Builder's iframe editor and template embed use cases. COOP + CORP
  * without COEP gives us most of the protection on normal responses; COEP is
- * only added for validated MCP embed-session page loads (see above).
+ * only added for validated MCP embed-session page loads and browser iframe
+ * navigations (see above).
+ *
+ * NOTE: `X-Frame-Options` is intentionally not set globally. Agent-native apps
+ * are expected to run inside iframe hosts such as Builder, Design, and MCP app
+ * shells. Routes that render especially sensitive iframe-only documents should
+ * set their own route-specific CSP / frame policy.
  */
 import { defineEventHandler, getHeader, setResponseHeader } from "h3";
 import { requestHasEmbedAuthMarker } from "./embed-session.js";
@@ -82,30 +80,31 @@ function isMcpEndpointRequest(event) {
         String(event?.node?.req?.url ?? event?.path ?? "/").split("?")[0];
     return (pathname === "/_agent-native/mcp" || pathname.endsWith("/_agent-native/mcp"));
 }
+function isIframeNavigationRequest(event) {
+    return getHeader(event, "sec-fetch-dest") === "iframe";
+}
 /**
  * Create the security-headers h3 middleware. Mount this BEFORE other route
  * handlers so the headers are present on every response (including 4xx/5xx
- * error pages). Route handlers that need to relax a specific header (e.g.
- * `X-Frame-Options: SAMEORIGIN` on the tool render route) can call
+ * error pages). Route handlers that need to tighten a specific header can call
  * `setResponseHeader` after this runs — the latest write wins.
  */
 export function createSecurityHeadersMiddleware() {
-    const isProduction = process.env.NODE_ENV === "production";
     return defineEventHandler((event) => {
         const embedFrameRequest = requestHasEmbedAuthMarker(event);
         const mcpEndpointRequest = isMcpEndpointRequest(event);
+        const iframeNavigationRequest = isIframeNavigationRequest(event);
         const requestOrigin = getHeader(event, "origin");
         setResponseHeader(event, "X-Content-Type-Options", "nosniff");
-        if (isProduction && !embedFrameRequest) {
-            setResponseHeader(event, "X-Frame-Options", "DENY");
-        }
         setResponseHeader(event, "Referrer-Policy", embedFrameRequest ? "no-referrer" : "strict-origin-when-cross-origin");
         setResponseHeader(event, "Permissions-Policy", PERMISSIONS_POLICY);
         setResponseHeader(event, "Cross-Origin-Opener-Policy", "same-origin");
-        if (embedFrameRequest) {
+        if (embedFrameRequest || iframeNavigationRequest) {
             setResponseHeader(event, "Cross-Origin-Embedder-Policy", "require-corp");
         }
-        setResponseHeader(event, "Cross-Origin-Resource-Policy", embedFrameRequest || mcpEndpointRequest ? "cross-origin" : "same-site");
+        setResponseHeader(event, "Cross-Origin-Resource-Policy", embedFrameRequest || mcpEndpointRequest || iframeNavigationRequest
+            ? "cross-origin"
+            : "same-site");
         if (embedFrameRequest && isMcpEmbedCorsOrigin(requestOrigin)) {
             setResponseHeader(event, "Access-Control-Allow-Origin", requestOrigin);
             setResponseHeader(event, "Vary", "Origin");

package/dist/server/security-headers.js.map

@@ -1 +1 @@
-{"version":3,"file":"security-headers.js","sourceRoot":"","sources":["../../src/server/security-headers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Security response headers middleware.\n *\n * Sets a baseline set of \"no-brainer\" security headers on every framework HTTP\n * response. These headers are layered defenses: each one mitigates a specific\n * class of attack, and together they harden the surface against clickjacking,\n * MIME-sniffing, referrer leakage, mixed-content downgrades, and cross-origin\n * window/embed access.\n *\n * The headers we emit:\n *\n *   - `Strict-Transport-Security` — forces HTTPS for the browser's lifetime\n *     of the cached value, preventing SSL-strip MITM. Only emitted when the\n *     request scheme is `https` (we don't want to break local-dev HTTP, and\n *     emitting HSTS over HTTP is a no-op per the spec but causes confusion).\n *   - `X-Content-Type-Options: nosniff` — disables browser MIME sniffing so\n *     a tool /render route serving user-authored HTML can't be misinterpreted\n *     as some other content type by a clever Accept header.\n *   - `X-Frame-Options: DENY` — prevents the entire app from being iframed by\n *     other origins (clickjacking the agent chat, booking pages, etc.). The\n *     tool /render endpoint and any other route that legitimately needs to be\n *     embedded in the same-origin app shell can opt out by setting its own\n *     header inside the route handler — h3's `setResponseHeader` overwrites,\n *     so a route emitting `SAMEORIGIN` wins over our middleware default.\n *     We skip this header entirely in dev (NODE_ENV !== \"production\") so the\n *     desktop app's local dev frame (localhost:3334) can iframe templates\n *     running on other localhost ports (e.g. mail at 8085).\n *   - `Referrer-Policy: strict-origin-when-cross-origin` — strips path/query\n *     from outbound Referer headers when the request crosses origin, so a\n *     public-share viewer's outbound link clicks never leak the share token.\n *   - `Permissions-Policy: camera=(), microphone=(self), geolocation=(),\n *     screen-wake-lock=()` — allows the app shell to request microphone access\n *     for composer dictation while keeping camera/location/wake-lock blocked\n *     by default. Templates that need broader media capture for recording UI\n *     override this on their own routes.\n *   - `Cross-Origin-Opener-Policy: same-origin` — isolates window.opener so\n *     a popup-window opener reference can't read or modify our document.\n *   - `Cross-Origin-Embedder-Policy: require-corp` — emitted only for\n *     validated MCP embed-session page loads. COEP hosts such as Claude's MCP\n *     Apps proxy require framed cross-origin documents to opt in explicitly.\n *   - `Cross-Origin-Resource-Policy: same-site` — prevents other origins from\n *     embedding our endpoints as `<img>` / `<script>` / `<audio>`, blocking\n *     the simplest data-leak chain when combined with auth cookies. Validated\n *     MCP embed-session page loads use `cross-origin` so COEP hosts such as\n *     Claude's MCP Apps proxy can frame the short-lived app document.\n *\n * NOTE: `Cross-Origin-Embedder-Policy` is NOT set by default because it\n * requires every embedded subresource to opt in via CORP/CORS, which would\n * break Builder's iframe editor and template embed use cases. COOP + CORP\n * without COEP gives us most of the protection on normal responses; COEP is\n * only added for validated MCP embed-session page loads (see above).\n */\n\nimport { defineEventHandler, getHeader, setResponseHeader } from \"h3\";\nimport { requestHasEmbedAuthMarker } from \"./embed-session.js\";\nimport {\n  isMcpEmbedCorsOrigin,\n  MCP_EMBED_CORS_ALLOW_HEADERS,\n} from \"../shared/mcp-embed-headers.js\";\n\nconst HSTS = \"max-age=31536000; includeSubDomains; preload\";\nconst PERMISSIONS_POLICY =\n  \"camera=(), microphone=(self), geolocation=(), screen-wake-lock=()\";\n\n/**\n * Returns true when the request was received over HTTPS. We trust both the\n * underlying connection (when the server is terminating TLS itself) and the\n * `x-forwarded-proto` header (set by Netlify, Vercel, Cloudflare, and any\n * other reverse proxy that fronts the framework).\n */\nfunction isHttpsRequest(event: any): boolean {\n  const xfp =\n    event?.node?.req?.headers?.[\"x-forwarded-proto\"] ??\n    event?.headers?.get?.(\"x-forwarded-proto\");\n  if (typeof xfp === \"string\" && xfp.split(\",\")[0].trim() === \"https\")\n    return true;\n  if (Array.isArray(xfp) && xfp[0] === \"https\") return true;\n  // h3 sets `event.url.protocol` to \"http:\" or \"https:\".\n  const proto = event?.url?.protocol;\n  if (proto === \"https:\") return true;\n  // Direct Node `req.connection.encrypted` (older runtimes).\n  if (event?.node?.req?.connection?.encrypted) return true;\n  return false;\n}\n\nfunction isMcpEndpointRequest(event: any): boolean {\n  const pathname =\n    event?.url?.pathname ??\n    String(event?.node?.req?.url ?? event?.path ?? \"/\").split(\"?\")[0];\n  return (\n    pathname === \"/_agent-native/mcp\" || pathname.endsWith(\"/_agent-native/mcp\")\n  );\n}\n\n/**\n * Create the security-headers h3 middleware. Mount this BEFORE other route\n * handlers so the headers are present on every response (including 4xx/5xx\n * error pages). Route handlers that need to relax a specific header (e.g.\n * `X-Frame-Options: SAMEORIGIN` on the tool render route) can call\n * `setResponseHeader` after this runs — the latest write wins.\n */\nexport function createSecurityHeadersMiddleware() {\n  const isProduction = process.env.NODE_ENV === \"production\";\n  return defineEventHandler((event) => {\n    const embedFrameRequest = requestHasEmbedAuthMarker(event);\n    const mcpEndpointRequest = isMcpEndpointRequest(event);\n    const requestOrigin = getHeader(event, \"origin\");\n    setResponseHeader(event, \"X-Content-Type-Options\", \"nosniff\");\n    if (isProduction && !embedFrameRequest) {\n      setResponseHeader(event, \"X-Frame-Options\", \"DENY\");\n    }\n    setResponseHeader(\n      event,\n      \"Referrer-Policy\",\n      embedFrameRequest ? \"no-referrer\" : \"strict-origin-when-cross-origin\",\n    );\n    setResponseHeader(event, \"Permissions-Policy\", PERMISSIONS_POLICY);\n    setResponseHeader(event, \"Cross-Origin-Opener-Policy\", \"same-origin\");\n    if (embedFrameRequest) {\n      setResponseHeader(event, \"Cross-Origin-Embedder-Policy\", \"require-corp\");\n    }\n    setResponseHeader(\n      event,\n      \"Cross-Origin-Resource-Policy\",\n      embedFrameRequest || mcpEndpointRequest ? \"cross-origin\" : \"same-site\",\n    );\n    if (embedFrameRequest && isMcpEmbedCorsOrigin(requestOrigin)) {\n      setResponseHeader(event, \"Access-Control-Allow-Origin\", requestOrigin);\n      setResponseHeader(event, \"Vary\", \"Origin\");\n      setResponseHeader(\n        event,\n        \"Access-Control-Allow-Methods\",\n        \"GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS\",\n      );\n      setResponseHeader(\n        event,\n        \"Access-Control-Allow-Headers\",\n        MCP_EMBED_CORS_ALLOW_HEADERS,\n      );\n    }\n    if (isHttpsRequest(event)) {\n      setResponseHeader(event, \"Strict-Transport-Security\", HSTS);\n    }\n    // Continue to the next handler — we only set headers, don't return a body.\n    return undefined;\n  });\n}\n"]}
+{"version":3,"file":"security-headers.js","sourceRoot":"","sources":["../../src/server/security-headers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Security response headers middleware.\n *\n * Sets a baseline set of \"no-brainer\" security headers on every framework HTTP\n * response. These headers are layered defenses: each one mitigates a specific\n * class of attack, and together they harden the surface against MIME-sniffing,\n * referrer leakage, mixed-content downgrades, and cross-origin window/embed\n * access.\n *\n * The headers we emit:\n *\n *   - `Strict-Transport-Security` — forces HTTPS for the browser's lifetime\n *     of the cached value, preventing SSL-strip MITM. Only emitted when the\n *     request scheme is `https` (we don't want to break local-dev HTTP, and\n *     emitting HSTS over HTTP is a no-op per the spec but causes confusion).\n *   - `X-Content-Type-Options: nosniff` — disables browser MIME sniffing so\n *     a tool /render route serving user-authored HTML can't be misinterpreted\n *     as some other content type by a clever Accept header.\n *   - `Referrer-Policy: strict-origin-when-cross-origin` — strips path/query\n *     from outbound Referer headers when the request crosses origin, so a\n *     public-share viewer's outbound link clicks never leak the share token.\n *   - `Permissions-Policy: camera=(), microphone=(self), geolocation=(),\n *     screen-wake-lock=()` — allows the app shell to request microphone access\n *     for composer dictation while keeping camera/location/wake-lock blocked\n *     by default. Templates that need broader media capture for recording UI\n *     override this on their own routes.\n *   - `Cross-Origin-Opener-Policy: same-origin` — isolates window.opener so\n *     a popup-window opener reference can't read or modify our document.\n *   - `Cross-Origin-Embedder-Policy: require-corp` — emitted only for\n *     validated MCP embed-session page loads and browser iframe navigations.\n *     COEP hosts such as Claude's MCP Apps proxy require framed cross-origin\n *     documents to opt in explicitly.\n *   - `Cross-Origin-Resource-Policy: same-site` — prevents other origins from\n *     embedding our endpoints as `<img>` / `<script>` / `<audio>`, blocking\n *     the simplest data-leak chain when combined with auth cookies. Validated\n *     MCP embed-session page loads and browser iframe navigations use\n *     `cross-origin` so COEP hosts can frame app documents.\n *\n * NOTE: `Cross-Origin-Embedder-Policy` is NOT set by default because it\n * requires every embedded subresource to opt in via CORP/CORS, which would\n * break Builder's iframe editor and template embed use cases. COOP + CORP\n * without COEP gives us most of the protection on normal responses; COEP is\n * only added for validated MCP embed-session page loads and browser iframe\n * navigations (see above).\n *\n * NOTE: `X-Frame-Options` is intentionally not set globally. Agent-native apps\n * are expected to run inside iframe hosts such as Builder, Design, and MCP app\n * shells. Routes that render especially sensitive iframe-only documents should\n * set their own route-specific CSP / frame policy.\n */\n\nimport { defineEventHandler, getHeader, setResponseHeader } from \"h3\";\nimport { requestHasEmbedAuthMarker } from \"./embed-session.js\";\nimport {\n  isMcpEmbedCorsOrigin,\n  MCP_EMBED_CORS_ALLOW_HEADERS,\n} from \"../shared/mcp-embed-headers.js\";\n\nconst HSTS = \"max-age=31536000; includeSubDomains; preload\";\nconst PERMISSIONS_POLICY =\n  \"camera=(), microphone=(self), geolocation=(), screen-wake-lock=()\";\n\n/**\n * Returns true when the request was received over HTTPS. We trust both the\n * underlying connection (when the server is terminating TLS itself) and the\n * `x-forwarded-proto` header (set by Netlify, Vercel, Cloudflare, and any\n * other reverse proxy that fronts the framework).\n */\nfunction isHttpsRequest(event: any): boolean {\n  const xfp =\n    event?.node?.req?.headers?.[\"x-forwarded-proto\"] ??\n    event?.headers?.get?.(\"x-forwarded-proto\");\n  if (typeof xfp === \"string\" && xfp.split(\",\")[0].trim() === \"https\")\n    return true;\n  if (Array.isArray(xfp) && xfp[0] === \"https\") return true;\n  // h3 sets `event.url.protocol` to \"http:\" or \"https:\".\n  const proto = event?.url?.protocol;\n  if (proto === \"https:\") return true;\n  // Direct Node `req.connection.encrypted` (older runtimes).\n  if (event?.node?.req?.connection?.encrypted) return true;\n  return false;\n}\n\nfunction isMcpEndpointRequest(event: any): boolean {\n  const pathname =\n    event?.url?.pathname ??\n    String(event?.node?.req?.url ?? event?.path ?? \"/\").split(\"?\")[0];\n  return (\n    pathname === \"/_agent-native/mcp\" || pathname.endsWith(\"/_agent-native/mcp\")\n  );\n}\n\nfunction isIframeNavigationRequest(event: any): boolean {\n  return getHeader(event, \"sec-fetch-dest\") === \"iframe\";\n}\n\n/**\n * Create the security-headers h3 middleware. Mount this BEFORE other route\n * handlers so the headers are present on every response (including 4xx/5xx\n * error pages). Route handlers that need to tighten a specific header can call\n * `setResponseHeader` after this runs — the latest write wins.\n */\nexport function createSecurityHeadersMiddleware() {\n  return defineEventHandler((event) => {\n    const embedFrameRequest = requestHasEmbedAuthMarker(event);\n    const mcpEndpointRequest = isMcpEndpointRequest(event);\n    const iframeNavigationRequest = isIframeNavigationRequest(event);\n    const requestOrigin = getHeader(event, \"origin\");\n    setResponseHeader(event, \"X-Content-Type-Options\", \"nosniff\");\n    setResponseHeader(\n      event,\n      \"Referrer-Policy\",\n      embedFrameRequest ? \"no-referrer\" : \"strict-origin-when-cross-origin\",\n    );\n    setResponseHeader(event, \"Permissions-Policy\", PERMISSIONS_POLICY);\n    setResponseHeader(event, \"Cross-Origin-Opener-Policy\", \"same-origin\");\n    if (embedFrameRequest || iframeNavigationRequest) {\n      setResponseHeader(event, \"Cross-Origin-Embedder-Policy\", \"require-corp\");\n    }\n    setResponseHeader(\n      event,\n      \"Cross-Origin-Resource-Policy\",\n      embedFrameRequest || mcpEndpointRequest || iframeNavigationRequest\n        ? \"cross-origin\"\n        : \"same-site\",\n    );\n    if (embedFrameRequest && isMcpEmbedCorsOrigin(requestOrigin)) {\n      setResponseHeader(event, \"Access-Control-Allow-Origin\", requestOrigin);\n      setResponseHeader(event, \"Vary\", \"Origin\");\n      setResponseHeader(\n        event,\n        \"Access-Control-Allow-Methods\",\n        \"GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS\",\n      );\n      setResponseHeader(\n        event,\n        \"Access-Control-Allow-Headers\",\n        MCP_EMBED_CORS_ALLOW_HEADERS,\n      );\n    }\n    if (isHttpsRequest(event)) {\n      setResponseHeader(event, \"Strict-Transport-Security\", HSTS);\n    }\n    // Continue to the next handler — we only set headers, don't return a body.\n    return undefined;\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/docs/content/external-agents.md

@@ -616,7 +616,7 @@ If `connect dev` cannot infer your local owner identity from an existing connect
 
 The standard OAuth path never exposes tokens to MCP Apps: the host stores OAuth access/refresh tokens and mediates tool calls and `resources/read` over the authenticated MCP connection. Embedded iframes receive app data and tool results, not bearer secrets.
 
-Full-app embeds also avoid handing the MCP bearer token to the browser. The MCP caller mints a one-time embed ticket in SQL; the iframe launch route consumes it and sets a short-lived, iframe-safe browser session cookie. The landing URL carries a temporary `__an_embed_token` query param only long enough for the client to capture it, remove it from the address bar, and attach it to same-origin `fetch` calls when third-party cookies are blocked. Embed sessions are route-scoped; app fetches include the current embedded target, and the server rejects token reuse outside the minted route. Production `X-Frame-Options: DENY` stays in place for normal page loads and is omitted only when that embed session marker is present.
+Full-app embeds also avoid handing the MCP bearer token to the browser. The MCP caller mints a one-time embed ticket in SQL; the iframe launch route consumes it and sets a short-lived, iframe-safe browser session cookie. The landing URL carries a temporary `__an_embed_token` query param only long enough for the client to capture it, remove it from the address bar, and attach it to same-origin `fetch` calls when third-party cookies are blocked. Embed sessions are route-scoped; app fetches include the current embedded target, and the server rejects token reuse outside the minted route. App pages intentionally do not emit `X-Frame-Options` or CSP `frame-ancestors`, so Builder, Design, and MCP app hosts can iframe them. Browser iframe navigations also opt into COEP/CORP when needed for cross-origin isolated hosts.
 
 The fallback hosted `connect` flow never copies the deployment's shared secret. Instead:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.35.3",
+  "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",