agentic-drive 0.10.3 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.11.0
+
+- Add `onOpenItem` to the public UI options. Hosts can handle reference opens in list and grid views by pointer or keyboard. Export `OnOpenItem` and `Item` from `agentic-drive/ui`. Keep the download action for unhandled items.
+
 ## 0.10.3
 
 - Allow `agentic-design` 0.10 and `agentic-identity` 0.11 without changing the lower bounds.

package/README.md

@@ -248,7 +248,7 @@ view.unmount();
 ```
 
 `mount` returns a `MountedDrive` handle. `DriveBrowser` is the React component;
-`DriveUiOptions` is its configuration. The CSS path supplies its styles.
+`DriveUiOptions` is its configuration. `OnOpenItem` is the reference-open callback type, and `Item` is its argument type. The CSS path supplies its styles.
 
 ### CLI, MCP, and adapters
 
@@ -308,6 +308,21 @@ drive.update({ baseUrl, getToken });  // use another server or callback
 drive.unmount();                      // remove the UI
 ```
 
+Use `onOpenItem` to open a reference in your app. It receives the full `Item`, including `id`, `kind` (`"ref"`), and `ref` (for example, `"docs:plan"`). Return `true` to handle the action and skip the download. Return `false` or nothing to keep the built-in download action. The hook runs for reference links in the list and grid, by pointer or Enter. Files and folders keep their built-in action. Modified clicks keep their existing behavior.
+
+```ts
+import type { Item, OnOpenItem } from "agentic-drive/ui";
+
+const onOpenItem: OnOpenItem = (item: Item) => {
+  if (!item.ref?.startsWith("docs:")) return false;
+  openEditor(item.ref.slice(5)); // Your app opens its editor.
+  return true;
+};
+drive.update({ baseUrl: location.origin, getToken: () => session.token, onOpenItem });
+```
+
+`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.
+
 `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 <0.11.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 { b as Actor, D as Drive, C as Ctx } from './drive-BhMTeQ-s.js';
+import { A as Actor, D as Drive, C as Ctx } from './drive-CS1CLfqo.js';
 import 'agentic-identity';
 
 interface DriveAccountDeps {

package/dist/{chunk-Q4ZADTVR.js → chunk-NMHARN2A.js}

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

package/dist/cli.js

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

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import { E as ErrorCode, N as Node, A as ActivityEntry, S as SearchQuery } from './drive-BhMTeQ-s.js';
-export { a as ActivityAction } from './drive-BhMTeQ-s.js';
+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 'agentic-identity';
 
 type Role = "viewer" | "commenter" | "editor" | "owner";

package/dist/{drive-BhMTeQ-s.d.ts → drive-CS1CLfqo.d.ts}

@@ -380,4 +380,4 @@ declare function createDrive(deps: DriveDeps): {
     }>;
 };
 
-export { type ActivityEntry as A, type Ctx as C, type Drive as D, type ErrorCode as E, type Node as N, type OnConflict as O, ROOT_ID as R, type SearchQuery as S, type ActivityAction as a, type Actor as b, ACTOR_KINDS as c, type Action as d, type ActorKind as e, type Can as f, type DriveDeps as g, DriveError as h, ERROR_STATUS as i, createDrive as j, parseSubject as k, parseName as p, subjectKindOf as s };
+export { type Actor as A, type Ctx as C, type Drive as D, ERROR_STATUS as E, type Node as N, type OnConflict as O, ROOT_ID as R, type SearchQuery as S, ACTOR_KINDS as a, type Action as b, type ActivityAction as c, type ActivityEntry as d, type ActorKind as e, type Can as f, type DriveDeps as g, DriveError as h, type ErrorCode as i, createDrive as j, parseSubject as k, parseName as p, subjectKindOf as s };

package/dist/embed.d.ts

@@ -1,6 +1,14 @@
 import * as react from 'react';
+import { Item } from './client.js';
+import './drive-CS1CLfqo.js';
+import 'agentic-identity';
+
+/** Return true to handle a reference open; false or void keeps the download action. */
+type OnOpenItem = (item: Item) => boolean | void;
 
 interface DriveUiOptions {
+    /** 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. */
     baseUrl: string;
     /** Returns the bearer token for the next request. It runs before every request, so it can refresh a token. No token sends no `authorization` header. */
@@ -8,9 +16,9 @@ interface DriveUiOptions {
 }
 /** 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 }: DriveUiOptions): react.JSX.Element | null;
+declare function DriveBrowser({ baseUrl, getToken, onOpenItem }: DriveUiOptions): react.JSX.Element | null;
 interface MountedDrive {
-    /** Show the drive with another address or token callback. The folder the person has open resets. */
+    /** Show the drive with another address, token callback, or item-open callback. The folder the person has open resets. */
     update(options: DriveUiOptions): void;
     /** Remove the UI. A request that runs is aborted, and no later request starts or calls `getToken`. Calling it again does nothing. */
     unmount(): void;
@@ -18,4 +26,4 @@ interface MountedDrive {
 /** 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, type MountedDrive, mount };
+export { DriveBrowser, type DriveUiOptions, Item, type MountedDrive, type OnOpenItem, mount };

package/dist/embed.js

@@ -123,7 +123,7 @@ function ExpandableSearch({ value, onChange }) {
     /* @__PURE__ */ jsx2(Button, { variant: "ghost", size: "sm", onClick: close, children: "Close search" })
   ] });
 }
-function ItemTable({ label, items, sort, onSort, selected = /* @__PURE__ */ new Set(), onSelect, href, who: who2, actions, dateOf = (i) => i.updatedAt }) {
+function ItemTable({ label, items, sort, onSort, selected = /* @__PURE__ */ new Set(), onSelect, href, onOpen, who: who2, actions, dateOf = (i) => i.updatedAt }) {
   const all = items.length > 0 && items.every((i) => selected.has(i.id));
   const some = !all && items.some((i) => selected.has(i.id));
   const head = useRef(null);
@@ -153,7 +153,7 @@ function ItemTable({ label, items, sort, onSort, selected = /* @__PURE__ */ new
       onSelect && /* @__PURE__ */ jsx2("td", { className: "drive-table__check", children: /* @__PURE__ */ jsx2("input", { type: "checkbox", className: "agd-checkbox", "aria-label": `Select ${i.name}`, checked: selected.has(i.id), onChange: (e) => toggle(i.id, e.target.checked) }) }),
       /* @__PURE__ */ jsx2("td", { children: /* @__PURE__ */ jsxs2("div", { className: "drive-table__name", children: [
         /* @__PURE__ */ jsx2("span", { className: "drive-table__icon", "aria-hidden": "true", children: i.kind === "folder" ? /* @__PURE__ */ jsx2(FolderIcon, {}) : /* @__PURE__ */ jsx2(FileIcon, {}) }),
-        /* @__PURE__ */ jsx2("a", { href: href(i), children: i.name })
+        /* @__PURE__ */ jsx2("a", { href: href(i), onClick: (e) => onOpen?.(e, i), children: i.name })
       ] }) }),
       /* @__PURE__ */ jsx2("td", { className: "drive-table__who", children: /* @__PURE__ */ jsx2(PresenceChip, { entry: who2(i.updatedBy, i.owner) }) }),
       /* @__PURE__ */ jsx2("td", { className: "drive-table__date", children: /* @__PURE__ */ jsx2(Stamp, { at: dateOf(i) }) }),
@@ -204,14 +204,18 @@ var goHash = (loc) => {
   history.replaceState(null, "", `#/${loc}`);
   dispatchEvent(new HashChangeEvent("hashchange"));
 };
-function Routes({ hash, client, origin, go }) {
+function Routes({ hash, client, origin, go, onOpenItem }) {
   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 }, hash);
+  return /* @__PURE__ */ jsx3(Browser, { client, loc: parts[0] || "/", origin, onOpenItem }, hash);
 }
-function Browser({ client, loc, origin }) {
+function Browser({ client, loc, origin, onOpenItem }) {
+  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();
+  };
   const toast = useToast();
   const [view, setView] = useState2(() => localStorage.getItem("agentic-drive-view") === "grid" ? "grid" : "list");
   const [dlg, setDlg] = useState2(null);
@@ -336,9 +340,9 @@ function Browser({ client, loc, origin }) {
         /* @__PURE__ */ jsxs3("div", { children: [
           /* @__PURE__ */ jsx3("div", { className: "drive-tools", children: /* @__PURE__ */ jsx3(ExpandableSearch, { value: query, onChange: setQuery }) }),
           /* @__PURE__ */ jsx3("p", { role: "status", className: "drive-sr", children: needle ? `${items.length} of ${state.data.items.length} items match` : "" }),
-          state.data.items.length === 0 ? /* @__PURE__ */ jsx3(EmptyState, { title: "This folder is empty", description: "Drop files here, or use Upload files.", action: /* @__PURE__ */ jsx3(Button2, { onClick: () => input.current?.click(), disabled: busy, children: "Upload files" }) }) : items.length === 0 ? /* @__PURE__ */ jsx3(EmptyState, { title: "Nothing matches", description: `No item in this folder has \u201C${query.trim()}\u201D in its name.`, action: /* @__PURE__ */ jsx3(Button2, { onClick: () => setQuery(""), children: "Clear search" }) }) : view === "list" ? /* @__PURE__ */ jsx3(ItemTable, { label: `Items in ${folder.name || "My files"}`, items, sort, onSort, selected, onSelect: setSelected, href, who, actions }) : /* @__PURE__ */ jsx3("ul", { className: "drive-grid", "aria-label": `Items in ${folder.name || "My files"}`, children: items.map((i) => /* @__PURE__ */ jsxs3("li", { className: "drive-card", children: [
+          state.data.items.length === 0 ? /* @__PURE__ */ jsx3(EmptyState, { title: "This folder is empty", description: "Drop files here, or use Upload files.", action: /* @__PURE__ */ jsx3(Button2, { onClick: () => input.current?.click(), disabled: busy, children: "Upload files" }) }) : items.length === 0 ? /* @__PURE__ */ jsx3(EmptyState, { title: "Nothing matches", description: `No item in this folder has \u201C${query.trim()}\u201D in its name.`, action: /* @__PURE__ */ jsx3(Button2, { onClick: () => setQuery(""), children: "Clear search" }) }) : view === "list" ? /* @__PURE__ */ jsx3(ItemTable, { label: `Items in ${folder.name || "My files"}`, items, sort, onSort, selected, onSelect: setSelected, onOpen: openItem, href, who, actions }) : /* @__PURE__ */ jsx3("ul", { className: "drive-grid", "aria-label": `Items in ${folder.name || "My files"}`, children: items.map((i) => /* @__PURE__ */ jsxs3("li", { className: "drive-card", children: [
             /* @__PURE__ */ jsx3("span", { className: "drive-card__icon", "aria-hidden": "true", children: i.kind === "folder" ? /* @__PURE__ */ jsx3(FolderIcon2, {}) : /* @__PURE__ */ jsx3(FileIcon2, {}) }),
-            /* @__PURE__ */ jsx3("a", { href: href(i), className: "drive-card__name", children: i.name }),
+            /* @__PURE__ */ jsx3("a", { href: href(i), onClick: (e) => openItem(e, i), className: "drive-card__name", children: i.name }),
             /* @__PURE__ */ jsxs3("span", { className: "drive-card__meta", children: [
               "Edited by ",
               /* @__PURE__ */ jsx3(PresenceChip2, { entry: who(i.updatedBy, i.owner) })
@@ -539,16 +543,16 @@ function makeClient({ baseUrl, getToken }) {
   return { client: createClient({ baseUrl, token: PLACEHOLDER, fetch: fetchWithToken }), close: () => closed.abort() };
 }
 var clients = 0;
-function DriveBrowser({ baseUrl, getToken }) {
+function DriveBrowser({ baseUrl, getToken, onOpenItem }) {
   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 }, made.id) : null;
+  return made ? /* @__PURE__ */ jsx4(DriveView, { client: made.client, origin: made.origin, onOpenItem }, made.id) : null;
 }
-function DriveView({ client, origin }) {
+function DriveView({ client, origin, onOpenItem }) {
   const [hash, setHash] = useState3("#/");
   const go = (loc) => setHash(`#/${loc === "/" ? "" : loc}`);
   const follow = (e) => {
@@ -564,7 +568,7 @@ function DriveView({ client, origin }) {
       { 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 }) })
+    /* @__PURE__ */ jsx4("div", { className: "drive-main", children: /* @__PURE__ */ jsx4(Routes, { hash, client, origin, go, onOpenItem }) })
   ] });
 }
 function mount(element, options) {
@@ -573,7 +577,7 @@ function mount(element, options) {
   let open = true;
   let version = 0;
   const render = (next, client) => root.render(
-    /* @__PURE__ */ jsx4(TooltipProvider, { children: /* @__PURE__ */ jsx4(ToastProvider, { children: /* @__PURE__ */ jsx4(DriveView, { client, origin: new URL(next.baseUrl).origin }, version++) }) })
+    /* @__PURE__ */ jsx4(TooltipProvider, { children: /* @__PURE__ */ jsx4(ToastProvider, { children: /* @__PURE__ */ jsx4(DriveView, { client, origin: new URL(next.baseUrl).origin, onOpenItem: next.onOpenItem }, version++) }) })
   );
   render(options, current.client);
   return {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { O as OnConflict, D as Drive, C as Ctx, N as Node, b as Actor } from './drive-BhMTeQ-s.js';
-export { c as ACTOR_KINDS, d as Action, a as ActivityAction, A as ActivityEntry, e as ActorKind, f as Can, g as DriveDeps, h as DriveError, i as ERROR_STATUS, E as ErrorCode, R as ROOT_ID, S as SearchQuery, j as createDrive, p as parseName, k as parseSubject, s as subjectKindOf } from './drive-BhMTeQ-s.js';
+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 { 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-Q4ZADTVR.js";
+} from "./chunk-NMHARN2A.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-BhMTeQ-s.js';
+import { D as Drive, C as Ctx } from './drive-CS1CLfqo.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-Q4ZADTVR.js";
+} from "./chunk-NMHARN2A.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-BhMTeQ-s.js';
-export { i as ERROR_STATUS, E as ErrorCode, N as Node } from './drive-BhMTeQ-s.js';
+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';
 export { B as BackfillOptions, a as BackfillResult, b as backfillAuthorIds, c as backfillResources } from './migrate-B79gRPMu.js';
 
 /**

package/llms.txt

@@ -108,6 +108,7 @@ view.unmount();
 `DriveUiOptions` is its configuration. The CSS path supplies its styles. The handle
 has `update` and `unmount` 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.
 
 ### CLI, MCP, and adapters

package/package.json

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