agentic-drive 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.13.0
+
+- Add the trusted host `claimResourceRef` helper. Commit app ownership and a reference atomically. Release on direct trash or removal and reclaim on restore. Report ownership conflicts as `REF_CONFLICT`. Require identity 0.12.0.
+
+## 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

@@ -134,6 +134,39 @@ try {
 - A browser page needs the Worker on its own origin for now: the Worker sends no CORS headers.
 - Share with a subject: `share("/pub", { kind: "human", id: "u2" }, "viewer")`.
 
+### Atomic app resource ownership
+
+Trusted hosts can call `drive.claimResourceRef(ctx, path, ref, ownership, opts)`.
+Use the same Store for Drive and identity sharing. Check app access first. This
+host-only helper is not exposed by HTTP, CLI, or MCP.
+
+```ts
+const item = await drive.claimResourceRef(ctx, "/Plan", "docs:plan", {
+  resourceId: "plan", type: "doc", subject: { kind: "human", id: "ana" },
+});
+await drive.trash(ctx, item.id);
+await drive.restore(ctx, item.id);
+```
+
+The same claim at the same path returns the existing reference, including when
+calls run at the same time. Options accept `parents` to create missing folders.
+Resource ids use 1 to 128 letters, digits, underscores, or hyphens. Resource types
+start with a lowercase letter and use lowercase letters, digits, underscores, or
+hyphens. The reference, resource, and owner grant commit in one transaction. A conflict
+throws `DriveError` with code `REF_CONFLICT` (HTTP status 409). A failed path or
+owner grant leaves no reference or claim. One subject can hold several references.
+Direct trash releases one claim. Restore reacquires it and can conflict with a
+new owner. Trashing a folder only hides its children; their claims stay until
+those references are trashed or removed. Hard removal releases live claims.
+If identity erase has removed an old claim, local trash and removal still succeed.
+They keep any claim that another subject now holds. Call `erasePerson` as part of
+account erase. It clears the subject from claimed references in other drives,
+even when another person made the reference. Restore then restores the item
+without recreating the erased subject's ownership.
+Existing resources must already grant the subject ownership. The identity
+lifecycle keeps existing shares and resources when it releases a claim.
+This helper needs `agentic-identity` 0.12.0 or later.
+
 ### Other exports
 
 The root export, `agentic-drive`, also exports these names. The package typings give the type of each one.
@@ -189,7 +222,7 @@ checks), `upload`, `sniffMime`, `DEFAULT_MAX_BYTES` (upload helpers), `buildExpo
 (account plug-in). See Other exports and Features for behavior and limits.
 
 Root types: `ActivityAction`, `ActivityEntry`, `Action`, `Actor`, `ActorKind`,
-`Can`, `Ctx`, `Drive`, `DriveDeps`, `ErrorCode`, `Node`, `OnConflict`,
+`Can`, `Ctx`, `Drive`, `DriveDeps`, `ErrorCode`, `Node`, `OnConflict`, `ResourceOwnership`,
 `UploadOptions`, `SearchQuery`, `BackfillOptions`, `BackfillResult`,
 `DriveAccount`, and `DriveAccountDeps`. They describe activity, callers, drive
 operations, uploads, migrations, and account operations.
@@ -248,7 +281,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 +356,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-BncyFxBL.js';
 import 'agentic-identity';
 
 interface DriveAccountDeps {

package/dist/account.js

@@ -1,7 +1,7 @@
 import {
   driveAccount
-} from "./chunk-ECVUDAHL.js";
-import "./chunk-DB4F5EWD.js";
+} from "./chunk-OHDNQ23Q.js";
+import "./chunk-FTIWCBCI.js";
 export {
   driveAccount
 };

package/dist/{chunk-W27ZQYPT.js → chunk-6TPC3BUW.js}

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

package/dist/{chunk-DB4F5EWD.js → chunk-FTIWCBCI.js}

@@ -1,5 +1,5 @@
 // src/drive.ts
-import { EraseRefusedError, isMachineMade, StoreConflictError, MAX_FOLDER_DEPTH, PRINCIPAL_KINDS, ROLES, SUBJECT_KINDS, hasScope } from "agentic-identity";
+import { ResourceClaimConflictError, EraseRefusedError, isMachineMade, StoreConflictError, MAX_FOLDER_DEPTH, PRINCIPAL_KINDS, ROLES, SUBJECT_KINDS, hasScope } from "agentic-identity";
 var ROOT_ID = "root";
 var NODES = "drive_nodes";
 var NAMES = "drive_names";
@@ -7,6 +7,7 @@ var ACTIVITY = "drive_activity";
 var ACTOR_KINDS = PRINCIPAL_KINDS;
 var DECIDED = /* @__PURE__ */ Symbol("decided");
 var ERROR_STATUS = Object.freeze({
+  REF_CONFLICT: 409,
   CROSS_DRIVE: 409,
   INVALID_SHARE: 400,
   TOO_MANY_ITEMS: 409,
@@ -354,7 +355,7 @@ function createDrive(deps) {
     if (node.kind !== "folder") throw new DriveError("NOT_A_FOLDER", `${node.name} is not a folder`);
     return node;
   }
-  async function insert(ops, w, ctx, parent, rawName, fields, onConflict) {
+  async function insert(ops, w, ctx, parent, rawName, fields, onConflict, fixedId) {
     let { name, key } = parseName(rawName);
     const empty = w.fresh.has(parent.id);
     if (!empty) await need(ctx, "write", parent);
@@ -370,7 +371,7 @@ function createDrive(deps) {
       name = await freeName(ops, parent.owner, parent.id, name);
       key = parseName(name).key;
     }
-    const id = newId();
+    const id = fixedId ?? newId();
     if (sharing) {
       const depth = await depthOf(ops, w, parent) + 1;
       if (depth > MAX_ITEM_DEPTH) throw new DriveError("TOO_DEEP", `an item can sit at most ${MAX_ITEM_DEPTH} folders deep`);
@@ -506,13 +507,31 @@ function createDrive(deps) {
       throw error;
     }
   }
-  async function transactAs(ctx, fn) {
+  async function transactAs(ctx, fn, lifecycle) {
+    const run = async (mutate) => {
+      if (!lifecycle) return transact(mutate);
+      if (!sharing) throw new DriveError("INVALID_SHARE", "sharing is not set up");
+      const { ownership: o, id, release } = lifecycle;
+      let result;
+      try {
+        await sharing[release ? "releaseResourceClaim" : "claimResource"](o.resourceId, o.subject, id, async (tx, claims) => {
+          result = await mutate(tx);
+          if (!release) claims.ensureOwner(o.type);
+        });
+      } catch (error) {
+        if (release && error instanceof ResourceClaimConflictError) return transact(mutate);
+        if (error instanceof ResourceClaimConflictError) throw new DriveError("REF_CONFLICT", "the app resource has a conflicting owner or reference");
+        if (error instanceof StoreConflictError) throw new DriveError("BUSY", "the drive changed at the same time. Try again.");
+        throw error;
+      }
+      return result;
+    };
     const answers = /* @__PURE__ */ new Map();
     let runs = 0;
     let asked = false;
     for (; ; ) {
       try {
-        return await transact((tx) => {
+        return await run((tx) => {
           if (++runs > 2 * MAX_ASKS) throw new DriveError("BUSY", "the drive changed at the same time. Try again.");
           if (runs > 1 && !asked) answers.clear();
           asked = false;
@@ -641,7 +660,17 @@ function createDrive(deps) {
     for (let i = 0; i < rows.length; i += size) {
       const chunk = rows.slice(i, i + size);
       for (const node of chunk) if (node.blobKey) await blobs.delete(node.blobKey);
-      for (const node of chunk) await finishResource(principal, node.id);
+      for (const node of chunk) {
+        const current = await store.get(NODES, node.id);
+        if (current?.resourceOwnership && !current.trashed) await transactAs({ owner: node.owner, actor: node.updatedBy }, async (tx) => {
+          const held = await tx.get(NODES, node.id);
+          if (held) {
+            const { resourceOwnership: _released, resourceOwnerId: _id, resourceOwnerKind: _kind, ...rest } = held;
+            await tx.put(NODES, node.id, rest);
+          }
+        }, { ownership: current.resourceOwnership, id: node.id, release: true });
+        await finishResource(principal, node.id);
+      }
       for (const node of chunk) for (const entry of await allWhere(store, ACTIVITY, { itemId: node.id, owner: node.owner })) await store.delete(ACTIVITY, entry.id);
       await transact(async (tx) => {
         const held = [];
@@ -801,8 +830,9 @@ function createDrive(deps) {
     },
     /** Hides an item and, for a folder, everything under it. Nothing else changes. */
     async trash(ctx, loc) {
+      const probe = await resolve(store, ctx, loc);
       return transactAs(ctx, async (tx, ctx2) => {
-        const node = await resolve(tx, ctx2, loc);
+        const node = await resolve(tx, ctx2, probe.id);
         if (node.id === ROOT_ID) throw new DriveError("IS_ROOT", "cannot trash the root");
         await need(ctx2, "write", node);
         const claim = await claimId(node.owner, node.parentId, node.nameKey);
@@ -814,7 +844,7 @@ function createDrive(deps) {
         await tx.put(ACTIVITY, entry.id, entry);
         if (held?.nodeId === node.id) await tx.delete(NAMES, claim);
         return trashed;
-      });
+      }, probe.resourceOwnership ? { ownership: probe.resourceOwnership, id: probe.id, release: true } : void 0);
     },
     /** Items trashed on their own, newest first. */
     async listTrash(ctx) {
@@ -835,6 +865,7 @@ function createDrive(deps) {
     },
     /** Puts a trashed item back. It needs a live parent folder. */
     async restore(ctx, id, opts = {}) {
+      const ownership = (await fetch(store, ctx, id))?.resourceOwnership;
       let height = 0;
       if (sharing && opts.parentId !== void 0) {
         const probe = await fetch(store, ctx, id);
@@ -844,6 +875,10 @@ function createDrive(deps) {
       return transactAs(ctx, async (tx, ctx2) => {
         const node = await fetch(tx, ctx2, id);
         if (!node || node.id === ROOT_ID) throw new DriveError("NOT_FOUND", `no item ${id}`);
+        const current = node.resourceOwnership;
+        if (Boolean(current) !== Boolean(ownership) || current?.resourceId !== ownership?.resourceId || current?.type !== ownership?.type || current?.subject?.id !== ownership?.subject?.id || current?.subject?.kind !== ownership?.subject?.kind) {
+          throw new DriveError("BUSY", "the reference ownership changed at the same time. Try again.");
+        }
         if (!node.trashed) throw new DriveError("NOT_TRASHED", `${node.name} is not in the trash`);
         await need(ctx2, "write", node);
         const parent = opts.parentId === void 0 ? await rawNode(tx, node.parentId, node.owner, ctx2.actor) : await rawNode(tx, opts.parentId, ctx2.owner, ctx2.actor);
@@ -870,7 +905,7 @@ function createDrive(deps) {
         await tx.put(NAMES, await claimId(parent.owner, parent.id, key), { nodeId: restored.id, owner: parent.owner, parentId: parent.id });
         if (sharing && parent.id !== node.parentId) await tx.put("resources", restored.id, await resourceDoc(restored, parent));
         return restored;
-      });
+      }, ownership ? { ownership, id } : void 0);
     },
     /** Live items that match every field given, sorted by path. */
     async search(ctx, q = {}) {
@@ -1021,6 +1056,48 @@ function createDrive(deps) {
       await store.put(ACTIVITY, ...logDoc(ctx, node, "share", { subjectKind: subject.kind, subjectId: subject.id, role: claim.role }));
       return node;
     },
+    /** Trusted host only. Check app access before calling. Own the app resource and create its reference atomically. */
+    async claimResourceRef(ctx, path, ref, ownership, opts = {}) {
+      if (!REF.test(ref)) throw new DriveError("INVALID_REF", "a reference looks like docs:<id>");
+      if (!ownership || typeof ownership !== "object" || typeof ownership.resourceId !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(ownership.resourceId) || typeof ownership.type !== "string" || !/^[a-z][a-z0-9_-]*$/.test(ownership.type)) {
+        throw new DriveError("INVALID_REF", "ownership needs a safe resource id and a lowercase resource type");
+      }
+      const subject = parseSubject(ownership.subject);
+      const claim = { ...ownership, subject };
+      for (let attempt = 0; ; attempt++) {
+        let existing = null;
+        try {
+          existing = await resolve(store, ctx, path);
+        } catch (error) {
+          if (!(error instanceof DriveError) || error.code !== "NOT_FOUND") throw error;
+        }
+        const id = existing?.id ?? newId();
+        if (typeof id !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(id)) throw new DriveError("INVALID_REF", "the reference needs a safe id");
+        try {
+          return await transactAs(ctx, async (tx, ctx2) => {
+            const w = batch();
+            const { parent, name } = await parentAndName(tx, w, ctx2, path, opts.parents ?? false);
+            const slot = await claimed(tx, parent.owner, parent.id, parseName(name).key);
+            if (slot.node?.id === id) {
+              await need(ctx2, "write", slot.node);
+              const held = slot.node.resourceOwnership;
+              if (slot.node.ref !== ref || !held || held.resourceId !== claim.resourceId || held.type !== claim.type || !held.subject || held.subject.id !== subject.id || held.subject.kind !== subject.kind) {
+                throw new DriveError("REF_CONFLICT", "this path has a conflicting reference");
+              }
+              return slot.node;
+            }
+            if (existing) throw new DriveError("BUSY", "the reference moved at the same time. Try again.");
+            const { node } = await insert(tx, w, ctx2, parent, name, { kind: "ref", ref }, "fail", id);
+            const owned = { ...node, resourceOwnership: claim, resourceOwnerId: subject.id, resourceOwnerKind: subject.kind };
+            w.put(NODES, id, owned);
+            await w.apply(tx);
+            return owned;
+          }, { ownership: claim, id });
+        } catch (error) {
+          if (attempt >= 2 || !(error instanceof DriveError) || error.code !== "NAME_TAKEN") throw error;
+        }
+      }
+    },
     /** An app deleted a document. Its references in this drive go to the trash. Returns how many. */
     async forgetDocument(ctx, ref) {
       if (!REF.test(ref)) throw new DriveError("INVALID_REF", `a reference looks like "docs:<id>", got ${JSON.stringify(ref)}`);
@@ -1121,6 +1198,18 @@ function createDrive(deps) {
       let invites = 0;
       for (const [actor, kind] of heldBy(subjectOf(ctx), ownedAgents)) grants += await sweep(await ofDrive(await allWhere(store, "grants", { subjectId: actor, subjectKind: kind })), "grants");
       for (const actor of actors) invites += await sweep(await ofDrive(await allWhere(store, "invites", { createdBy: actor })), "invites");
+      for (const [actor, kind] of heldBy(subjectOf(ctx), ownedAgents)) {
+        for (const { data } of await allWhere(store, NODES, { resourceOwnerId: actor, resourceOwnerKind: kind })) {
+          const node = data;
+          if (!node.resourceOwnership) continue;
+          await transactAs(ctx, async (tx) => {
+            const current = await tx.get(NODES, node.id);
+            if (current?.resourceOwnerId !== actor || current.resourceOwnerKind !== kind) return;
+            const { resourceOwnership: _claim, resourceOwnerId: _id, resourceOwnerKind: _kind, ...rest } = current;
+            await tx.put(NODES, node.id, rest);
+          }, { ownership: node.resourceOwnership, id: node.id, release: true });
+        }
+      }
       const todo = await madeBy(store, actors);
       for (let i = 0; i < todo.length; i += CHUNK) {
         await transact(async (tx) => {

package/dist/{chunk-HJXRMOUY.js → chunk-NPJG2MYP.js}

@@ -1,7 +1,7 @@
 import {
   DriveError,
   safeMime
-} from "./chunk-DB4F5EWD.js";
+} from "./chunk-FTIWCBCI.js";
 
 // src/upload.ts
 var DEFAULT_MAX_BYTES = 25 * 1024 * 1024;

package/dist/{chunk-ECVUDAHL.js → chunk-OHDNQ23Q.js}

@@ -1,7 +1,7 @@
 import {
   DriveError,
   publicNode
-} from "./chunk-DB4F5EWD.js";
+} from "./chunk-FTIWCBCI.js";
 
 // src/account.ts
 var plain = (value) => JSON.parse(JSON.stringify(value));

package/dist/{chunk-SEHT5Q5L.js → chunk-TGOARFYZ.js}

@@ -11,6 +11,7 @@ var DriveApiError = class extends Error {
 };
 var BASE = "/api/v1/drive";
 var CODES = {
+  REF_CONFLICT: true,
   NOT_FOUND: true,
   NAME_TAKEN: true,
   BLOB_EXISTS: true,

package/dist/cli.js

@@ -4,11 +4,11 @@ import {
 } from "./chunk-AB2RTTHJ.js";
 import {
   VERSION
-} from "./chunk-W27ZQYPT.js";
+} from "./chunk-6TPC3BUW.js";
 import {
   buildExport,
   upload
-} from "./chunk-HJXRMOUY.js";
+} from "./chunk-NPJG2MYP.js";
 import {
   AuthError,
   DriveError,
@@ -22,7 +22,7 @@ import {
   resolveToken,
   revokeKey,
   revokePrincipal
-} from "./chunk-DB4F5EWD.js";
+} from "./chunk-FTIWCBCI.js";
 
 // src/cli.ts
 import { createReadStream, realpathSync, writeFileSync } from "fs";

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-BncyFxBL.js';
+export { c as ActivityAction } from './drive-BncyFxBL.js';
 import 'agentic-identity';
 
 type Role = "viewer" | "commenter" | "editor" | "owner";

package/dist/client.js

@@ -1,7 +1,7 @@
 import {
   DriveApiError,
   createClient
-} from "./chunk-SEHT5Q5L.js";
+} from "./chunk-TGOARFYZ.js";
 export {
   DriveApiError,
   createClient

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

@@ -1,5 +1,5 @@
 import * as agentic_identity from 'agentic-identity';
-import { PrincipalKind, Store, Blobs, PrincipalContext, createSharing, Subject, Role, SubjectKind } from 'agentic-identity';
+import { PrincipalKind, Store, Blobs, PrincipalContext, Subject, SubjectKind, createSharing, Role } from 'agentic-identity';
 
 declare const ROOT_ID = "root";
 declare const ACTOR_KINDS: readonly ["human", "agent_of_human", "agent_of_agent", "agent", "user_token"];
@@ -38,7 +38,17 @@ type Action = "read" | "write" | "delete";
 type Sharing = ReturnType<typeof createSharing>;
 /** The seam for access. With `sharing`, the default is a role check through agentic-identity. */
 type Can = (ctx: Ctx, action: Action, node: Node) => boolean | Promise<boolean>;
+type ResourceOwnership = {
+    resourceId: string;
+    subject: Subject;
+    type: string;
+};
 type Node = {
+    /** Trusted host claim. Kept in trash so restore can reacquire it. */
+    resourceOwnership?: ResourceOwnership;
+    /** Indexed subject fields let account erase find claims in other drives. */
+    resourceOwnerId?: string;
+    resourceOwnerKind?: SubjectKind;
     id: string;
     owner: string;
     parentId: string;
@@ -63,7 +73,7 @@ type Node = {
     /** Set while a purge deletes the item. Nothing can see or change it then. */
     purging: boolean;
 };
-type ErrorCode = "NOT_FOUND" | "NAME_TAKEN" | "BLOB_EXISTS" | "INVALID_NAME" | "INVALID_PATH" | "INVALID_REF" | "NOT_A_FOLDER" | "NOT_A_FILE" | "MOVE_INTO_SELF" | "TOO_DEEP" | "PARENT_GONE" | "TRASHED" | "NOT_TRASHED" | "IS_ROOT" | "FORBIDDEN" | "BLOB_MISSING" | "TOO_LARGE" | "INVALID_EXPIRY" | "BUSY" | "CROSS_DRIVE" | "INVALID_SHARE" | "TOO_MANY_ITEMS";
+type ErrorCode = "REF_CONFLICT" | "NOT_FOUND" | "NAME_TAKEN" | "BLOB_EXISTS" | "INVALID_NAME" | "INVALID_PATH" | "INVALID_REF" | "NOT_A_FOLDER" | "NOT_A_FILE" | "MOVE_INTO_SELF" | "TOO_DEEP" | "PARENT_GONE" | "TRASHED" | "NOT_TRASHED" | "IS_ROOT" | "FORBIDDEN" | "BLOB_MISSING" | "TOO_LARGE" | "INVALID_EXPIRY" | "BUSY" | "CROSS_DRIVE" | "INVALID_SHARE" | "TOO_MANY_ITEMS";
 /** The HTTP status of each error code. A host that serves the drive reuses it. */
 declare const ERROR_STATUS: Readonly<Record<ErrorCode, 400 | 403 | 404 | 409 | 413 | 500>>;
 declare class DriveError extends Error {
@@ -234,6 +244,10 @@ declare function createDrive(deps: DriveDeps): {
         parents?: boolean;
         onConflict?: OnConflict;
     }): Promise<Node>;
+    /** Trusted host only. Check app access before calling. Own the app resource and create its reference atomically. */
+    claimResourceRef(ctx: Ctx, path: string, ref: string, ownership: ResourceOwnership, opts?: {
+        parents?: boolean;
+    }): Promise<Node>;
     /** An app deleted a document. Its references in this drive go to the trash. Returns how many. */
     forgetDocument(ctx: Ctx, ref: string): Promise<{
         trashed: number;
@@ -248,7 +262,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: {
@@ -380,4 +394,4 @@ declare function createDrive(deps: DriveDeps): {
     }>;
 };
 
-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 };
+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, type ResourceOwnership 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, ROOT_ID as j, createDrive as k, parseSubject as l, parseName as p, subjectKindOf as s };

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-BncyFxBL.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 };