agentic-drive 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.12.0
+
+- Add typed embedded navigation with `DriveLocation`, `location`, and `onNavigate`.
+  Mounted views expose `setLocation` and `getLocation` for host routing.
+  File links download in place. Explicit download locations return with a
+  history replace hint, and navigation cancels pending downloads.
+- Keep the current location on option updates. Route embedded activity actions
+  through the host navigation API.
+
 ## 0.11.1
 
 - Allow `agentic-design` and `agentic-identity` releases below 1.0.0 while keeping the existing lower bounds. Test with identity 0.12.0 and design 0.10.1.

package/README.md

@@ -248,7 +248,7 @@ view.unmount();
 ```
 
 `mount` returns a `MountedDrive` handle. `DriveBrowser` is the React component;
-`DriveUiOptions` is its configuration. `OnOpenItem` is the reference-open callback type, and `Item` is its argument type. The CSS path supplies its styles.
+`DriveUiOptions` is its configuration. `DriveLocation` is the folder, trash, activity, or file location type. `DriveNavigationOptions` describes host history updates. `OnOpenItem` is the reference-open callback type, and `Item` is its argument type. The CSS path supplies its styles.
 
 ### CLI, MCP, and adapters
 
@@ -323,6 +323,62 @@ drive.update({ baseUrl: location.origin, getToken: () => session.token, onOpenIt
 
 `DriveUiOptions` exports this optional hook for both `mount` and `DriveBrowser`. `update()` can replace or remove it. React hosts can change the `onOpenItem` prop without resetting the current folder. The callback is synchronous.
 
+### Embed navigation
+
+Use the exported `DriveLocation` type to select a folder, trash, item activity,
+or file download. A folder location has `{ kind: "folder", path: "/" }`.
+Its `path` accepts a folder id, an absolute path such as `"/Work/Plans"`,
+or a path from a folder id. Other locations use `{ kind: "trash" }`,
+`{ kind: "activity", itemId }`, or `{ kind: "file", itemId }`.
+The server checks access for each request. An inaccessible folder shows an error.
+
+`mount` starts at `options.location`, or root when it is absent.
+`setLocation` changes the view without remounting the drive.
+`getLocation` returns a copy of the active location. For a folder, pass its
+`path` as `folder` to the client's `registerDocument` method.
+Trash, activity, and downloads have no active folder.
+
+```ts
+import { mount, type DriveLocation } from "agentic-drive/ui";
+
+const readLocation = (): DriveLocation =>
+  JSON.parse(new URL(location.href).searchParams.get("drive") ??
+    '{"kind":"folder","path":"/"}'); // Validate URL data in your app.
+const drive = mount(document.getElementById("drive")!, {
+  baseUrl: location.origin,
+  getToken: () => session.token,
+  location: readLocation(),
+  onNavigate(next, { replace }) {
+    const url = new URL(location.href);
+    url.searchParams.set("drive", JSON.stringify(next));
+    if (replace) history.replaceState(null, "", url);
+    else history.pushState(null, "", url);
+  },
+});
+addEventListener("popstate", () => drive.setLocation(readLocation()));
+const active = drive.getLocation();
+if (active.kind === "folder") {
+  await client.registerDocument({ name: "Plan", ref: "docs:plan", folder: active.path });
+}
+```
+
+`onNavigate` reports folder, breadcrumb, trash, and activity navigation with
+`replace: false`. File links download in place without changing the location or
+notifying the host. Errors leave the folder open. Navigation cancels pending
+downloads, so a late response cannot move the view or start a download.
+An explicit `file` location returns to its parent with `replace: true`. Use
+`replaceState` for that return. Root returns use `"/"`.
+Assigning a location through initial render, `setLocation`, or `update` does not
+call the callback itself. An explicit file location starts a download; its completed return
+does call the callback. An explicit file location that fails shows an error and
+stays selected; the host can set a folder location to leave it.
+`update` keeps the current location unless it receives a new `location`.
+In React, `DriveBrowser location={current} onNavigate={setCurrent}` is controlled:
+the host must apply the next location. Without `location`, React keeps it locally.
+Changes to server or token options keep the location and reload its data.
+The embed never changes the host URL itself.
+
+
 `getToken` returns 1 to 512 letters, digits, `-` or `_`, or `undefined` to send no `authorization` header. A bad `baseUrl` or a `getToken` that is not a function makes `mount` throw a `TypeError`. The server still checks every request against the token. The embed shows files and trash with upload, rename, move, share, and the "Created by agent" label. It has no sign-in form, because your app owns sign-in. It does not change the page address, and it has no theme switch. `agentic-design/styles.css` sets base styles for the whole page, and it follows the dark mode of the system unless your page sets `data-theme`. Add `agentic-design@">=0.8.0 <1.0.0"` to your own dependencies, because your page imports its files. The Worker sends no CORS headers, so the server must be on the origin of your page. Set `baseUrl` to the same address as `DRIVE_PUBLIC_URL`, or the UI refuses its download links. `unmount` and `update` abort the requests that run and stop an upload that has more files to send. The UI keeps the list or grid choice in `localStorage` under `agentic-drive-view`, and it has its own heading for each view. Dialogs, menus, and messages render in `document.body`, outside your element. A click with Ctrl, Cmd, Shift, or the middle button on a folder link does not open the folder. The class names start with `drive-`. The design-system classes start with `agd-`. `DriveBrowser` is the same UI as a React component. It closes its requests when it unmounts. Wrap it in `TooltipProvider` and `ToastProvider` from `agentic-design/react`. `react` and `react-dom` (version 19 or later) are optional peer dependencies. Install them in your project when you use `agentic-drive/ui`. The web UI that the Worker serves uses the same views.
 
 ### Serve the UI from the package

package/dist/account.d.ts

@@ -1,4 +1,4 @@
-import { A as Actor, D as Drive, C as Ctx } from './drive-CS1CLfqo.js';
+import { A as Actor, D as Drive, C as Ctx } from './drive-9cZ_9xU4.js';
 import 'agentic-identity';
 
 interface DriveAccountDeps {

package/dist/{chunk-W27ZQYPT.js → chunk-J2EPNUYS.js}

@@ -1,6 +1,6 @@
 // src/version.ts
 import { createRequire } from "module";
-var VERSION = true ? "0.11.1" : readPackageVersion();
+var VERSION = true ? "0.12.0" : readPackageVersion();
 
 export {
   VERSION

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
 } from "./chunk-AB2RTTHJ.js";
 import {
   VERSION
-} from "./chunk-W27ZQYPT.js";
+} from "./chunk-J2EPNUYS.js";
 import {
   buildExport,
   upload

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import { i as ErrorCode, N as Node, d as ActivityEntry, S as SearchQuery } from './drive-CS1CLfqo.js';
-export { c as ActivityAction } from './drive-CS1CLfqo.js';
+import { i as ErrorCode, N as Node, d as ActivityEntry, S as SearchQuery } from './drive-9cZ_9xU4.js';
+export { c as ActivityAction } from './drive-9cZ_9xU4.js';
 import 'agentic-identity';
 
 type Role = "viewer" | "commenter" | "editor" | "owner";

package/dist/{drive-CS1CLfqo.d.ts → drive-9cZ_9xU4.d.ts}

@@ -248,7 +248,7 @@ declare function createDrive(deps: DriveDeps): {
     exportPerson(ctx: Ctx): Promise<{
         subject: {
             id: string;
-            kind: "human" | "agent_of_human" | "agent_of_agent" | "agent" | "user_token" | null;
+            kind: "human" | "agent" | "agent_of_human" | "agent_of_agent" | "user_token" | null;
         };
         partial: boolean;
         authored: {

package/dist/embed.d.ts

@@ -1,12 +1,34 @@
 import * as react from 'react';
 import { Item } from './client.js';
-import './drive-CS1CLfqo.js';
+import './drive-9cZ_9xU4.js';
 import 'agentic-identity';
 
 /** Return true to handle a reference open; false or void keeps the download action. */
 type OnOpenItem = (item: Item) => boolean | void;
 
+/** Folder locators follow the SDK rules: "/" is root; use an id or an absolute path. */
+type DriveLocation = {
+    kind: "folder";
+    path: string;
+} | {
+    kind: "trash";
+} | {
+    kind: "activity";
+    itemId: string;
+} | {
+    kind: "file";
+    itemId: string;
+};
+/** Replace the current host history entry for a transient navigation. */
+interface DriveNavigationOptions {
+    replace: boolean;
+}
 interface DriveUiOptions {
+    /** Controlled in React. In mount/update, selects the location; omission preserves it. */
+    location?: DriveLocation;
+    /** Internal navigation. Controlled React hosts must apply the next location.
+     * Use replaceState when options.replace is true (an explicit download returns). */
+    onNavigate?: (location: DriveLocation, options: DriveNavigationOptions) => void;
     /** Runs when a person activates a reference item. Return true to skip the built-in download. */
     onOpenItem?: OnOpenItem;
     /** The address of the drive server, for example `https://drive.example.com`. Only its origin is used. */
@@ -15,15 +37,19 @@ interface DriveUiOptions {
     getToken: () => string | undefined | Promise<string | undefined>;
 }
 /** The folders and trash of the signed-in caller, with upload, share, and the machine-made label. It needs the tooltip and toast providers above it. `mount` adds them.
- * It shows the root again when `baseUrl` changes. A bad `baseUrl` or `getToken` throws. Pass a stable `getToken`, because a new function makes a new client. */
-declare function DriveBrowser({ baseUrl, getToken, onOpenItem }: DriveUiOptions): react.JSX.Element | null;
+ * It keeps its location when `baseUrl` changes. A bad `baseUrl` or `getToken` throws. Pass a stable `getToken`, because a new function makes a new client. */
+declare function DriveBrowser({ baseUrl, getToken, onOpenItem, location, onNavigate }: DriveUiOptions): react.JSX.Element | null;
 interface MountedDrive {
-    /** Show the drive with another address, token callback, or item-open callback. The folder the person has open resets. */
+    /** Show the drive with another address, token callback, or item-open callback. The current location stays unless options.location is supplied. */
     update(options: DriveUiOptions): void;
+    /** Select a location without remounting the drive. Does not call onNavigate. */
+    setLocation(location: DriveLocation): void;
+    /** Current location. A folder path is suitable for SDK registerDocument({ folder }). */
+    getLocation(): DriveLocation;
     /** Remove the UI. A request that runs is aborted, and no later request starts or calls `getToken`. Calling it again does nothing. */
     unmount(): void;
 }
 /** Render the drive into an element, for an app that does not use React itself. A bad `baseUrl` or `getToken` throws a `TypeError`. */
 declare function mount(element: HTMLElement, options: DriveUiOptions): MountedDrive;
 
-export { DriveBrowser, type DriveUiOptions, Item, type MountedDrive, type OnOpenItem, mount };
+export { DriveBrowser, type DriveLocation, type DriveNavigationOptions, type DriveUiOptions, Item, type MountedDrive, type OnOpenItem, mount };

package/dist/embed.js

@@ -4,9 +4,9 @@ import {
 } from "./chunk-SEHT5Q5L.js";
 
 // ui/embed.tsx
-import { useEffect as useEffect3, useState as useState3 } from "react";
+import { useEffect as useEffect3, useRef as useRef3, useState as useState3 } from "react";
 import { createRoot } from "react-dom/client";
-import { FolderIcon as FolderIcon3, SidebarNav as SidebarNav2, ToastProvider, TooltipProvider } from "agentic-design/react";
+import { FolderIcon as FolderIcon3, SidebarNav as SidebarNav2, ToastProvider, TooltipProvider, useToast as useToast2 } from "agentic-design/react";
 
 // ui/App.tsx
 import { useEffect as useEffect2, useMemo, useRef as useRef2, useState as useState2 } from "react";
@@ -183,11 +183,9 @@ function useLoad(fn) {
   const [state, set] = useState2({ status: "loading" });
   const [tick, setTick] = useState2(0);
   useEffect2(() => {
-    let live = true;
-    fn().then((data) => live && set({ status: "ok", data }), (e) => live && set({ status: "error", error: errorText(e) }));
-    return () => {
-      live = false;
-    };
+    const pending = new AbortController();
+    fn(pending.signal).then((data) => !pending.signal.aborted && set({ status: "ok", data }), (e) => !pending.signal.aborted && set({ status: "error", error: errorText(e) }));
+    return () => pending.abort();
   }, [tick]);
   return [state, () => setTick((n) => n + 1)];
 }
@@ -200,18 +198,14 @@ function Status({ state, retry, children }) {
   return /* @__PURE__ */ jsx3(Fragment, { children });
 }
 var routeParts = (hash) => hash.replace(/^#\/?/, "").split("/");
-var goHash = (loc) => {
-  history.replaceState(null, "", `#/${loc}`);
-  dispatchEvent(new HashChangeEvent("hashchange"));
-};
-function Routes({ hash, client, origin, go, onOpenItem }) {
+function Routes({ hash, client, origin, go, onOpenItem, folderLoc }) {
   const parts = routeParts(hash);
   if (parts[0] === "trash") return /* @__PURE__ */ jsx3(TrashView, { client }, "trash");
   if (parts[0] === "a" && parts[1]) return /* @__PURE__ */ jsx3(ActivityView, { client, id: parts[1] }, hash);
   if (parts[0] === "f" && parts[1]) return /* @__PURE__ */ jsx3(Download, { client, id: parts[1], origin, go }, hash);
-  return /* @__PURE__ */ jsx3(Browser, { client, loc: parts[0] || "/", origin, onOpenItem }, hash);
+  return /* @__PURE__ */ jsx3(Browser, { client, loc: folderLoc ?? (parts[0] || "/"), go, origin, onOpenItem }, hash);
 }
-function Browser({ client, loc, origin, onOpenItem }) {
+function Browser({ client, loc, origin, onOpenItem, go }) {
   const openItem = (e, item) => {
     if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || item.kind !== "ref") return;
     if (onOpenItem?.(item) === true) e.preventDefault();
@@ -299,7 +293,7 @@ function Browser({ client, loc, origin, onOpenItem }) {
       /* @__PURE__ */ jsx3(Menu, { align: "end", trigger: /* @__PURE__ */ jsx3(IconButton, { label: `Actions for ${item.name}`, icon: /* @__PURE__ */ jsx3(MoreIcon, {}), variant: "ghost" }), items: [
         { label: "Rename", onSelect: () => setDlg({ kind: "rename", item }) },
         { label: "Move", onSelect: () => setDlg({ kind: "move", item }) },
-        { label: "Activity", onSelect: () => goHash(`a/${item.id}`) },
+        { label: "Activity", onSelect: () => go(`a/${item.id}`) },
         { label: "Share", onSelect: () => setDlg({ kind: "share", item }) },
         "separator",
         { label: "Move to trash", danger: true, onSelect: () => void act(() => client.trash(item.id), `Moved ${item.name} to trash`) }
@@ -508,16 +502,23 @@ function ActivityView({ client, id }) {
     /* @__PURE__ */ jsx3(ActivityList, { entries: state.data.entries })
   ] }) }) });
 }
+async function downloadItem(client, id, origin, signal) {
+  const item = await client.stat(id, { signal });
+  signal.throwIfAborted();
+  const { url } = await client.url(id, void 0, { signal });
+  signal.throwIfAborted();
+  if (new URL(url, origin).origin !== origin) throw new Error("The download link points to another site.");
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = item.name;
+  a.click();
+  return item;
+}
 function Download({ client, id, origin, go }) {
-  const [state, retry] = useLoad(async () => {
-    const item = await client.stat(id);
-    const { url } = await client.url(id);
-    if (new URL(url, origin).origin !== origin) throw new Error("The download link points to another site.");
-    const a = document.createElement("a");
-    a.href = url;
-    a.download = item.name;
-    a.click();
-    go(item.parentId);
+  const [state, retry] = useLoad(async (signal) => {
+    const item = await downloadItem(client, id, origin, signal);
+    signal.throwIfAborted();
+    go(item.parentId, { replace: true });
     return item;
   });
   return /* @__PURE__ */ jsx3(Status, { state, retry, children: null });
@@ -525,6 +526,22 @@ function Download({ client, id, origin, go }) {
 
 // ui/embed.tsx
 import { jsx as jsx4, jsxs as jsxs4 } from "react/jsx-runtime";
+var ROOT = { kind: "folder", path: "/" };
+function locationHash(location2) {
+  if (location2.kind === "folder" && typeof location2.path === "string" && location2.path.length)
+    return `#/folder/${encodeURIComponent(location2.path)}`;
+  if (location2.kind === "trash") return "#/trash";
+  if ((location2.kind === "activity" || location2.kind === "file") && typeof location2.itemId === "string" && location2.itemId.length)
+    return `#/${location2.kind === "activity" ? "a" : "f"}/${encodeURIComponent(location2.itemId)}`;
+  throw new TypeError("Invalid drive location");
+}
+function fromHash(hash) {
+  const path = hash.slice(2);
+  if (path === "trash") return { kind: "trash" };
+  if (path.startsWith("a/")) return { kind: "activity", itemId: path.slice(2) };
+  if (path.startsWith("f/")) return { kind: "file", itemId: path.slice(2) };
+  return { kind: "folder", path: path || "/" };
+}
 var PLACEHOLDER = "from-get-token";
 function makeClient({ baseUrl, getToken }) {
   if (typeof getToken !== "function") throw new TypeError("getToken must be a function");
@@ -543,24 +560,48 @@ function makeClient({ baseUrl, getToken }) {
   return { client: createClient({ baseUrl, token: PLACEHOLDER, fetch: fetchWithToken }), close: () => closed.abort() };
 }
 var clients = 0;
-function DriveBrowser({ baseUrl, getToken, onOpenItem }) {
+function DriveBrowser({ baseUrl, getToken, onOpenItem, location: location2, onNavigate }) {
+  const [local, setLocal] = useState3(ROOT);
+  const active = location2 ?? local;
+  locationHash(active);
+  const navigate = (next, options = { replace: false }) => {
+    if (location2 === void 0) setLocal(next);
+    onNavigate?.(next, options);
+  };
   const [made, setMade] = useState3();
   useEffect3(() => {
     const next = makeClient({ baseUrl, getToken });
     setMade({ id: ++clients, client: next.client, origin: new URL(baseUrl).origin });
     return () => next.close();
   }, [baseUrl, getToken]);
-  return made ? /* @__PURE__ */ jsx4(DriveView, { client: made.client, origin: made.origin, onOpenItem }, made.id) : null;
+  return made ? /* @__PURE__ */ jsx4(DriveView, { client: made.client, origin: made.origin, onOpenItem, location: active, onNavigate: navigate }, made.id) : null;
 }
-function DriveView({ client, origin, onOpenItem }) {
-  const [hash, setHash] = useState3("#/");
-  const go = (loc) => setHash(`#/${loc === "/" ? "" : loc}`);
+function DriveView({ client, origin, onOpenItem, location: location2, onNavigate }) {
+  const hash = locationHash(location2);
+  const toast = useToast2();
+  const pending = useRef3(new AbortController());
+  useEffect3(() => {
+    const controller = new AbortController();
+    pending.current = controller;
+    return () => controller.abort();
+  }, [hash]);
+  const download = async (id) => {
+    const signal = pending.current.signal;
+    try {
+      await downloadItem(client, id, origin, signal);
+    } catch (e) {
+      if (!signal.aborted) toast({ title: "Could not download", description: e instanceof DriveApiError ? `${e.message} (${e.code})` : e instanceof Error ? e.message : "Download failed", tone: "danger" });
+    }
+  };
+  const go = (loc, options = { replace: false }) => onNavigate(fromHash(`#/${loc === "/" || loc === "root" ? "" : loc}`), options);
   const follow = (e) => {
     if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
     const link = e.target.closest?.("a[href^='#/']");
     if (!link || !e.currentTarget.contains(link)) return;
     e.preventDefault();
-    setHash(link.getAttribute("href"));
+    const next = fromHash(link.getAttribute("href"));
+    if (next.kind === "file") void download(next.itemId);
+    else onNavigate(next, { replace: false });
   };
   const place = hash.startsWith("#/trash") ? "trash" : "files";
   return /* @__PURE__ */ jsxs4("div", { className: "drive-root", onClick: follow, children: [
@@ -568,26 +609,45 @@ function DriveView({ client, origin, onOpenItem }) {
       { href: "#/", label: "My files", icon: /* @__PURE__ */ jsx4(FolderIcon3, { "aria-hidden": "true" }), current: place === "files" },
       { href: "#/trash", label: "Trash", current: place === "trash" }
     ] }),
-    /* @__PURE__ */ jsx4("div", { className: "drive-main", children: /* @__PURE__ */ jsx4(Routes, { hash, client, origin, go, onOpenItem }) })
+    /* @__PURE__ */ jsx4("div", { className: "drive-main", children: /* @__PURE__ */ jsx4(Routes, { hash, client, origin, go, onOpenItem, folderLoc: location2.kind === "folder" ? location2.path : void 0 }) })
   ] });
 }
 function mount(element, options) {
+  let active = { ...options.location ?? ROOT };
+  locationHash(active);
+  let settings = options;
   let current = makeClient(options);
   const root = createRoot(element);
   let open = true;
   let version = 0;
+  const navigate = (next, options2 = { replace: false }) => {
+    active = { ...next };
+    render(settings, current.client);
+    settings.onNavigate?.({ ...active }, options2);
+  };
   const render = (next, client) => root.render(
-    /* @__PURE__ */ jsx4(TooltipProvider, { children: /* @__PURE__ */ jsx4(ToastProvider, { children: /* @__PURE__ */ jsx4(DriveView, { client, origin: new URL(next.baseUrl).origin, onOpenItem: next.onOpenItem }, version++) }) })
+    /* @__PURE__ */ jsx4(TooltipProvider, { children: /* @__PURE__ */ jsx4(ToastProvider, { children: /* @__PURE__ */ jsx4(DriveView, { client, origin: new URL(next.baseUrl).origin, onOpenItem: next.onOpenItem, location: active, onNavigate: navigate }, version) }) })
   );
   render(options, current.client);
   return {
     update: (next) => {
       if (!open) return;
+      if (next.location !== void 0) locationHash(next.location);
       const made = makeClient(next);
+      settings = next;
+      if (next.location !== void 0) active = { ...next.location };
+      version++;
       current.close();
       current = made;
       render(next, made.client);
     },
+    setLocation: (next) => {
+      if (!open) return;
+      locationHash(next);
+      active = { ...next };
+      render(settings, current.client);
+    },
+    getLocation: () => ({ ...active }),
     unmount: () => {
       if (!open) return;
       open = false;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { O as OnConflict, D as Drive, C as Ctx, N as Node, A as Actor } from './drive-CS1CLfqo.js';
-export { a as ACTOR_KINDS, b as Action, c as ActivityAction, d as ActivityEntry, e as ActorKind, f as Can, g as DriveDeps, h as DriveError, E as ERROR_STATUS, i as ErrorCode, R as ROOT_ID, S as SearchQuery, j as createDrive, p as parseName, k as parseSubject, s as subjectKindOf } from './drive-CS1CLfqo.js';
+import { O as OnConflict, D as Drive, C as Ctx, N as Node, A as Actor } from './drive-9cZ_9xU4.js';
+export { a as ACTOR_KINDS, b as Action, c as ActivityAction, d as ActivityEntry, e as ActorKind, f as Can, g as DriveDeps, h as DriveError, E as ERROR_STATUS, i as ErrorCode, R as ROOT_ID, S as SearchQuery, j as createDrive, p as parseName, k as parseSubject, s as subjectKindOf } from './drive-9cZ_9xU4.js';
 import { Store, Blobs, Doc } from 'agentic-identity';
 export { B as BackfillOptions, a as BackfillResult, b as backfillAuthorIds, c as backfillResources } from './migrate-B79gRPMu.js';
 export { DriveAccount, DriveAccountDeps, driveAccount } from './account.js';

package/dist/index.js

@@ -6,7 +6,7 @@ import {
 } from "./chunk-AB2RTTHJ.js";
 import {
   VERSION
-} from "./chunk-W27ZQYPT.js";
+} from "./chunk-J2EPNUYS.js";
 import {
   DEFAULT_MAX_BYTES,
   buildExport,

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { D as Drive, C as Ctx } from './drive-CS1CLfqo.js';
+import { D as Drive, C as Ctx } from './drive-9cZ_9xU4.js';
 import { Store } from 'agentic-identity';
 
 declare function createMcpServer(drive: Drive, ctx: Ctx, exportDir: string, store: Store): McpServer;

package/dist/mcp.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-W27ZQYPT.js";
+} from "./chunk-J2EPNUYS.js";
 import {
   buildExport,
   upload

package/dist/worker.d.ts

@@ -1,8 +1,8 @@
 import { Hono } from 'hono';
 import { D1Like, R2Like } from 'agentic-identity/cloudflare';
 import { Store, Blobs } from 'agentic-identity';
-import { C as Ctx, D as Drive } from './drive-CS1CLfqo.js';
-export { E as ERROR_STATUS, i as ErrorCode, N as Node } from './drive-CS1CLfqo.js';
+import { C as Ctx, D as Drive } from './drive-9cZ_9xU4.js';
+export { E as ERROR_STATUS, i as ErrorCode, N as Node } from './drive-9cZ_9xU4.js';
 export { B as BackfillOptions, a as BackfillResult, b as backfillAuthorIds, c as backfillResources } from './migrate-B79gRPMu.js';
 
 /**

package/llms.txt

@@ -105,8 +105,8 @@ view.unmount();
 ```
 
 `mount` returns a `MountedDrive` handle. `DriveBrowser` is the React component;
-`DriveUiOptions` is its configuration. The CSS path supplies its styles. The handle
-has `update` and `unmount` methods. The `getToken` callback runs before each request
+`DriveUiOptions` is its configuration. `DriveLocation` is the folder, trash, activity, or file location type. `DriveNavigationOptions` describes host history updates. The CSS path supplies its styles. The handle
+has `update`, `unmount`, `setLocation`, and `getLocation` methods. The `getToken` callback runs before each request
 and may return undefined. The UI does not change the page address or theme.
 The optional `onOpenItem` hook receives the full `Item` for a reference link, by pointer or Enter in list and grid views. Return true to skip the download; false or void keeps it. `OnOpenItem` and `Item` are exported types from `agentic-drive/ui`. Both `update` and React props can replace the hook.
 React 19 and React DOM 19 are optional peer dependencies.
@@ -122,3 +122,23 @@ The CLI uses `AGENTIC_DRIVE_TOKEN`. The MCP command serves tools over stdio;
 call `drive_ls` with a path. Storage adapters are provided by `agentic-identity`,
 not by a drive subpath. For example: `import { createFileStore, createFileBlobs } from "agentic-identity/file"`;
 pass `createFileStore({ path: "./data/db" })` and `createFileBlobs({ dir: "./data/blobs" })` to `createDrive`. The Worker uses D1 and R2 adapters by default.
+
+
+### Embedded navigation
+
+Set the location option to a folder with kind "folder" and path "/" (root),
+a folder id, or an absolute path. Use kind "trash" for trash. Activity and file
+locations use kind "activity" or "file" with itemId.
+
+The mounted handle also has setLocation and getLocation methods. getLocation
+returns a copy of the active location. A folder path can be passed as folder to
+registerDocument. update keeps the location unless its options supply one.
+React hosts can control location and apply onNavigate to their own state.
+
+onNavigate receives the next location and history options. Use pushState when
+replace is false, and replaceState when replace is true. File links download in place
+without changing location or notifying the host, including on error. Navigation
+cancels pending downloads. Explicit file locations return to the parent with
+replace true on success; an error leaves that explicit location selected.
+Root returns use "/". A direct location assignment does not notify the host,
+but a completed download does. Apply popstate with setLocation or React props.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-drive",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Store, sort, and share files and folders.",
   "keywords": [
     "drive",