@athenaintel/react 0.10.37 → 0.10.39

package/README.md

@@ -144,28 +144,44 @@ Set `linkClicks={{ interceptAthenaCitations: false }}` to keep Athena citation l
 
 ## Standalone Asset Embeds
 
-Use `AthenaAssetEmbed` to render a native Athena asset without chat, thread history, tabs, or the SDK split-pane layout. Full mode supports documents, spreadsheets, and presentations.
+Use `AthenaAssetEmbed` to render a native Athena asset without chat, thread history, tabs, or the SDK split-pane layout. It defaults to the editable, full native asset experience (`readOnly={false}` and `displayMode="full"`). The embed token and the current user must still have edit permission; otherwise Athena renders the asset read-only.
 
 ```tsx
-import { AthenaAssetEmbed, AthenaProvider } from '@athenaintel/react';
+import { useState } from 'react';
+import {
+  AthenaAssetEmbed,
+  AthenaProvider,
+  type AthenaAssetCitationReference,
+} from '@athenaintel/react';
 
 function AssetView() {
+  const [linkedReference, setLinkedReference] =
+    useState<AthenaAssetCitationReference | null>(null);
+
   return (
     <AthenaProvider config={{ token: accessToken }}>
       <div style={{ height: 800 }}>
         <AthenaAssetEmbed
           assetId="asset_123"
           displayMode="full"
-          readOnly
+          readOnly={false}
           onCitationClick={({ reference, sourceAssetId }) => {
             console.log('Citation clicked', { reference, sourceAssetId });
           }}
           onCitationAction={({ action, reference }) => {
             if (action === 'open-in-spaces') {
-              openAssetInMyApp(reference);
+              setLinkedReference(reference);
             }
           }}
         />
+        {linkedReference && (
+          <AthenaAssetEmbed
+            assetId={linkedReference.id}
+            reference={linkedReference}
+            displayMode="full"
+            readOnly={false}
+          />
+        )}
       </div>
     </AthenaProvider>
   );
@@ -176,6 +192,43 @@ When `onCitationClick` is provided, citation navigation is delegated to the host
 
 `onCitationAction` handles actions initiated from a citation popover. It currently receives `action: 'open-in-spaces'` when the user clicks the (+) button. Providing the handler delegates that action to the host by default. Set `citationActionBehavior="browser"` to observe the event while preserving Athena's default navigation; requesting host mode without a handler safely falls back to browser behavior.
 
+Pass the callback's complete `reference` to the linked `AthenaAssetEmbed`, rather than storing only
+`reference.id`. The embed uses the reference anchor to navigate PDFs to the cited page. Updating the
+reference also navigates when the host opens another citation in the same asset.
+
+If the host starts with an Athena citation URL/string instead of an
+`onCitationAction` event, parse it and pass the returned `reference` directly to the embed:
+
+```tsx
+import {
+  AthenaAssetEmbed,
+  parseAthenaCitationLink,
+} from '@athenaintel/react';
+
+const citation = parseAthenaCitationLink({
+  href: citationString,
+  appUrl: 'https://app.athenaintel.com',
+});
+
+return citation ? (
+  <AthenaAssetEmbed
+    assetId={citation.assetId}
+    reference={citation.reference}
+    displayMode="full"
+    readOnly={false}
+  />
+) : null;
+```
+
+For example, this citation opens the PDF directly at page 34:
+
+```text
+https://app.athenaintel.com/dashboard/spaces/?asset_ids=asset_pdf&anchor=page&page=34&excerpt=Term%20debt
+```
+
+The important query parameters are `asset_ids`, `anchor=page`, and `page`. Page ranges and
+positioned citations are also preserved by `parseAthenaCitationLink`.
+
 ## Theming
 
 ```tsx

package/dist/assets/AthenaAssetEmbed.d.ts

@@ -1,10 +1,12 @@
 import { type FC, type IframeHTMLAttributes } from "react";
-import { type AthenaAssetCitationActionEvent, type AthenaAssetCitationBehavior, type AthenaAssetCitationClickEvent } from "./asset-embed-messages";
+import { type AthenaAssetCitationActionEvent, type AthenaAssetCitationBehavior, type AthenaAssetCitationClickEvent, type AthenaAssetCitationReference } from "./asset-embed-messages";
 export interface AthenaAssetEmbedProps extends Omit<IframeHTMLAttributes<HTMLIFrameElement>, "src" | "onError" | "onLoad"> {
     assetId: string;
+    /** Optional citation target to open inside the embedded asset, such as a PDF page. */
+    reference?: AthenaAssetCitationReference;
     /** Defaults to the native full asset experience. */
     displayMode?: "minimal" | "full";
-    /** Defaults to true. */
+    /** Defaults to false so authorized users can edit the embedded asset. */
     readOnly?: boolean;
     expiresInSeconds?: number;
     citationBehavior?: AthenaAssetCitationBehavior;

package/dist/assets/use-asset-embed.d.ts

@@ -1,9 +1,12 @@
+import type { AthenaAssetCitationReference } from './asset-embed-messages';
 export interface UseAssetEmbedOptions {
     readOnly?: boolean;
     expiresInSeconds?: number;
-    /** Native Olympus surface rendered by the iframe. Defaults to `minimal`. */
+    /** Native Olympus surface rendered by the iframe. Defaults to `full`. */
     displayMode?: 'minimal' | 'full';
 }
+export declare const DEFAULT_ASSET_EMBED_READ_ONLY = false;
+export declare const DEFAULT_ASSET_EMBED_DISPLAY_MODE: 'full';
 export interface UseAssetEmbedResult {
     embedUrl: string | null;
     isLoading: boolean;
@@ -26,7 +29,7 @@ export declare function resolveAssetEmbedUrl({ embedUrl, appUrl, backendUrl, cur
     backendUrl?: string | null;
     currentOrigin?: string | null;
 }): string;
-export declare function buildSdkAssetEmbedUrl(embedUrl: string): string;
+export declare function buildSdkAssetEmbedUrl(embedUrl: string, reference?: AthenaAssetCitationReference): string;
 export declare function getAssetEmbedAuthContext({ token, apiKey }: {
     token?: string | null;
     apiKey?: string;

package/dist/chat/athena-citation-links.d.ts

@@ -1,3 +1,4 @@
+import type { AthenaAssetCitationReference } from '../assets/asset-embed-messages';
 import { type AssetType } from '../assets/asset-panel-store';
 import type { AthenaCitationLinkHandler, AthenaLinkClickHandler } from '../provider/citation-links';
 export interface ParsedAthenaCitationLink {
@@ -5,6 +6,8 @@ export interface ParsedAthenaCitationLink {
     assetId: string;
     assetIds: string[];
     assetType: AssetType | null;
+    /** Complete target that can be passed directly to AthenaAssetEmbed.reference. */
+    reference: AthenaAssetCitationReference;
 }
 export declare const parseAthenaCitationLink: ({ href, appUrl, }: {
     href: string;

package/dist/index.cjs

@@ -47521,6 +47521,51 @@ const ASSET_TYPE_ALIASES = {
   word_document: "document"
 };
 const isAthenaSpacesPath = (url) => url.pathname.replace(/\/+$/, "") === "/dashboard/spaces";
+const getFiniteNumber = (url, key) => {
+  const value = url.searchParams.get(key);
+  if (value === null || value.trim() === "") return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+const parseCitationReference = ({
+  url,
+  assetId
+}) => {
+  const reference2 = { id: assetId };
+  const anchorType = url.searchParams.get("anchor");
+  const page = getFiniteNumber(url, "page");
+  switch (anchorType) {
+    case "page":
+      if (page !== null) reference2.anchor = { type: anchorType, page };
+      break;
+    case "page_range": {
+      const startPage = getFiniteNumber(url, "start_page");
+      const endPage = getFiniteNumber(url, "end_page");
+      if (startPage !== null && endPage !== null) {
+        reference2.anchor = { type: anchorType, startPage, endPage };
+      }
+      break;
+    }
+    case "page_rect": {
+      const x = getFiniteNumber(url, "x");
+      const y = getFiniteNumber(url, "y");
+      const width = getFiniteNumber(url, "width");
+      const height = getFiniteNumber(url, "height");
+      if (page !== null && x !== null && y !== null && width !== null && height !== null) {
+        reference2.anchor = { type: anchorType, page, x, y, width, height };
+      }
+      break;
+    }
+    case "page_text": {
+      const text2 = url.searchParams.get("text");
+      if (page !== null && text2) reference2.anchor = { type: anchorType, page, text: text2 };
+      break;
+    }
+  }
+  const excerpt = url.searchParams.get("excerpt");
+  if (excerpt) reference2.meta = { excerpt };
+  return reference2;
+};
 const normalizeAssetType = (value) => {
   if (!value) {
     return null;
@@ -47609,7 +47654,8 @@ const parseAthenaCitationLink = ({
     url,
     assetId,
     assetIds,
-    assetType: normalizeAssetType(url.searchParams.get("asset_type") ?? url.searchParams.get("type"))
+    assetType: normalizeAssetType(url.searchParams.get("asset_type") ?? url.searchParams.get("type")),
+    reference: parseCitationReference({ url, assetId })
   };
 };
 const isAthenaCitationUrl = ({
@@ -56278,6 +56324,8 @@ function isAthenaAssetCitationClickEvent(value) {
 function isAthenaAssetCitationActionEvent(value) {
   return typeof value === "object" && value !== null && "type" in value && value.type === ATHENA_ASSET_CITATION_ACTION_MESSAGE && "version" in value && value.version === 1 && "action" in value && value.action === "open-in-spaces" && "reference" in value && typeof value.reference === "object" && value.reference !== null && "id" in value.reference && typeof value.reference.id === "string";
 }
+const DEFAULT_ASSET_EMBED_READ_ONLY = false;
+const DEFAULT_ASSET_EMBED_DISPLAY_MODE = "full";
 function buildAssetEmbedRequestBody({
   assetId,
   readOnly,
@@ -56390,10 +56438,92 @@ function resolveAssetEmbedUrl({
     return embedUrl;
   }
 }
-function buildSdkAssetEmbedUrl(embedUrl) {
+function setFiniteNumberParam({ params, key, value }) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    params.set(key, String(value));
+  }
+}
+function appendCitationReferenceParams({
+  params,
+  reference: reference2
+}) {
+  var _a2;
+  const anchor = reference2 == null ? void 0 : reference2.anchor;
+  if (!anchor || typeof anchor !== "object" || !("type" in anchor) || typeof anchor.type !== "string") {
+    return;
+  }
+  switch (anchor.type) {
+    case "page":
+      params.set("anchor", anchor.type);
+      setFiniteNumberParam({
+        params,
+        key: "page",
+        value: "page" in anchor ? anchor.page : void 0
+      });
+      break;
+    case "page_range":
+      params.set("anchor", anchor.type);
+      setFiniteNumberParam({
+        params,
+        key: "start_page",
+        value: "startPage" in anchor ? anchor.startPage : void 0
+      });
+      setFiniteNumberParam({
+        params,
+        key: "end_page",
+        value: "endPage" in anchor ? anchor.endPage : void 0
+      });
+      break;
+    case "page_rect":
+      params.set("anchor", anchor.type);
+      setFiniteNumberParam({
+        params,
+        key: "page",
+        value: "page" in anchor ? anchor.page : void 0
+      });
+      setFiniteNumberParam({
+        params,
+        key: "x",
+        value: "x" in anchor ? anchor.x : void 0
+      });
+      setFiniteNumberParam({
+        params,
+        key: "y",
+        value: "y" in anchor ? anchor.y : void 0
+      });
+      setFiniteNumberParam({
+        params,
+        key: "width",
+        value: "width" in anchor ? anchor.width : void 0
+      });
+      setFiniteNumberParam({
+        params,
+        key: "height",
+        value: "height" in anchor ? anchor.height : void 0
+      });
+      break;
+    case "page_text":
+      params.set("anchor", anchor.type);
+      setFiniteNumberParam({
+        params,
+        key: "page",
+        value: "page" in anchor ? anchor.page : void 0
+      });
+      if ("text" in anchor && typeof anchor.text === "string") {
+        params.set("text", anchor.text);
+      }
+      break;
+  }
+  const excerpt = (_a2 = reference2.meta) == null ? void 0 : _a2.excerpt;
+  if (typeof excerpt === "string" && excerpt) {
+    params.set("excerpt", excerpt);
+  }
+}
+function buildSdkAssetEmbedUrl(embedUrl, reference2) {
   try {
     const url = new URL(embedUrl);
     url.searchParams.set("athena_sdk_bridge", "1");
+    appendCitationReferenceParams({ params: url.searchParams, reference: reference2 });
     return url.toString();
   } catch {
     return embedUrl;
@@ -56429,9 +56559,9 @@ function useAssetEmbed(assetId, options = {
   backendUrl: ""
 }) {
   const {
-    readOnly = false,
+    readOnly = DEFAULT_ASSET_EMBED_READ_ONLY,
     expiresInSeconds = 60 * 60 * 24 * 30,
-    displayMode = "minimal",
+    displayMode = DEFAULT_ASSET_EMBED_DISPLAY_MODE,
     backendUrl,
     appUrl,
     apiKey,
@@ -56523,8 +56653,9 @@ const DEFAULT_STYLE = {
 const AUTH_SYNC_INTERVAL_MS = 6e4;
 const AthenaAssetEmbed = ({
   assetId,
-  displayMode = "full",
-  readOnly = true,
+  reference: reference2,
+  displayMode = DEFAULT_ASSET_EMBED_DISPLAY_MODE,
+  readOnly = DEFAULT_ASSET_EMBED_READ_ONLY,
   expiresInSeconds,
   citationBehavior,
   onCitationClick,
@@ -56560,7 +56691,10 @@ const AthenaAssetEmbed = ({
       return null;
     }
   }, [embedUrl]);
-  const iframeSrc = React.useMemo(() => embedUrl ? buildSdkAssetEmbedUrl(embedUrl) : null, [embedUrl]);
+  const iframeSrc = React.useMemo(
+    () => embedUrl ? buildSdkAssetEmbedUrl(embedUrl, reference2) : null,
+    [embedUrl, reference2]
+  );
   const effectiveCitationBehavior = resolveAthenaAssetCitationBehavior({
     citationBehavior,
     hasCitationClickHandler: !!onCitationClick