@athenaintel/react 0.41.3 → 0.42.2

package/dist/references/src/formats/object/external-url-object.d.ts

@@ -0,0 +1,9 @@
+import type { ExternalUrlReference } from '../../types';
+/**
+ * Decode: `{ format: 'external_url_object', ... }` → ExternalUrlReference
+ */
+export declare function decodeFromExternalUrlObject(data: Record<string, unknown>): ExternalUrlReference;
+/**
+ * Encode: ExternalUrlReference → object with `format: 'external_url_object'`
+ */
+export declare function encodeToExternalUrlObject(ref: ExternalUrlReference): Record<string, unknown>;

package/dist/references/src/formats/object/group-object.d.ts

@@ -0,0 +1,9 @@
+import type { GroupReference } from '../../types';
+/**
+ * Decode: `{ format: 'group_object', ... }` → GroupReference
+ */
+export declare function decodeFromGroupObject(data: Record<string, unknown>): GroupReference;
+/**
+ * Encode: GroupReference → object with `format: 'group_object'`
+ */
+export declare function encodeToGroupObject(ref: GroupReference): Record<string, unknown>;

package/dist/references/src/formats/object/navigation-object.d.ts

@@ -0,0 +1,9 @@
+import type { NavigationReference } from '../../types';
+/**
+ * Decode: `{ format: 'navigation_object', ... }` → NavigationReference
+ */
+export declare function decodeFromNavigationObject(data: Record<string, unknown>): NavigationReference;
+/**
+ * Encode: NavigationReference → object with `format: 'navigation_object'`
+ */
+export declare function encodeToNavigationObject(ref: NavigationReference): Record<string, unknown>;

package/dist/references/src/formats/object/parse-reference-object.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Object wire: canonical `{ format: … }` first, then pre-reference inference.
+ */
+import { type DetectedObjectFormat } from '../format-catalog';
+import type { Reference } from '../../types';
+export { ObjectFormat, type DetectedObjectFormat } from '../format-catalog';
+/**
+ * Parse a stored object into a runtime Reference.
+ */
+export declare function parseReferenceObject(input: Record<string, unknown>): Reference;
+export declare function detectObjectFormat(input: Record<string, unknown>): DetectedObjectFormat;

package/dist/references/src/formats/object/person-object.d.ts

@@ -0,0 +1,9 @@
+import type { PersonReference } from '../../types';
+/**
+ * Decode: `{ format: 'person_object', ... }` → PersonReference
+ */
+export declare function decodeFromPersonObject(data: Record<string, unknown>): PersonReference;
+/**
+ * Encode: PersonReference → object with `format: 'person_object'`
+ */
+export declare function encodeToPersonObject(ref: PersonReference): Record<string, unknown>;

package/dist/references/src/formats/uri/asset-mention-uri.d.ts

@@ -0,0 +1,9 @@
+import type { AssetReference } from '../../types';
+/**
+ * Decode: `mention://asset?id=X&anchor=page&page=5` → AssetReference
+ */
+export declare function decodeFromAssetMentionUri(url: URL): AssetReference;
+/**
+ * Encode: AssetReference → `mention://asset?id=X&anchor=page&page=5`
+ */
+export declare function encodeToAssetMentionUri(reference: AssetReference): string;

package/dist/references/src/formats/uri/asset-spaces-url.d.ts

@@ -0,0 +1,9 @@
+import type { AssetReference } from '../../types';
+/**
+ * Decode: `/dashboard/spaces?asset_ids=X&...` → AssetReference
+ */
+export declare function decodeFromAssetSpacesUrl(url: URL): AssetReference;
+/**
+ * Encode: AssetReference → `/dashboard/spaces?asset_ids=X&...`
+ */
+export declare function encodeToAssetSpacesUrl(reference: AssetReference): string;

package/dist/references/src/formats/uri/callable-mention-uris.d.ts

@@ -0,0 +1,9 @@
+import type { CallableReference } from '../../types';
+/**
+ * Decode: `mention://tool|toolkit|workspaceitem?...` → CallableReference (`kind` from hostname).
+ */
+export declare function decodeFromCallableMentionUri(url: URL): CallableReference;
+/**
+ * Encode: CallableReference → `mention://tool|toolkit|workspaceitem?name=X&...`
+ */
+export declare function encodeCallableToMentionUri(ref: CallableReference): string;

package/dist/references/src/formats/uri/detect-uri-wire.d.ts

@@ -0,0 +1,9 @@
+import { type DetectedUriFormat } from '../format-catalog';
+/**
+ * Detect URI format from a string.
+ *
+ * Checks canonical wire signatures (asset Spaces URL, asset/callable/person/group `mention://`,
+ * then legacy `pre_reference_uri`). Callable `mention://tool|toolkit|workspaceitem` share one format:
+ * `callable_mention_uri` (`kind` is determined from the hostname when decoding).
+ */
+export declare function detectUriFormat(input: string): DetectedUriFormat;

package/dist/references/src/formats/uri/group-mention-uri.d.ts

@@ -0,0 +1,12 @@
+import type { GroupReference } from '../../types';
+/**
+ * Decode: `mention://group?id=X&name=Y` → GroupReference
+ *
+ * `id` is the workspace group id (`group_<uuid>`); `name` is display-only and
+ * lands in `meta.name`, mirroring `mention://person`'s `name` param.
+ */
+export declare function decodeFromGroupMentionUri(url: URL): GroupReference;
+/**
+ * Encode: GroupReference → `mention://group?id=X&name=Y`
+ */
+export declare function encodeToGroupMentionUri(ref: GroupReference): string;

package/dist/references/src/formats/uri/navigation-spaces-url.d.ts

@@ -0,0 +1,14 @@
+import type { NavigationReference } from '../../types';
+/**
+ * True when `asset_ids` lists only Spaces drive tab slots (`drive`, `drive1`, …),
+ * not normal asset UUIDs. Used to distinguish navigation URLs from asset Spaces URLs.
+ */
+export declare function isDriveTabAssetIds(assetIds: string): boolean;
+/**
+ * Decode: `/dashboard/spaces?...` where `asset_ids` is drive-tab-only → NavigationReference
+ */
+export declare function decodeFromNavigationSpacesUrl(url: URL): NavigationReference;
+/**
+ * Encode: NavigationReference → relative Spaces path (pathname + search)
+ */
+export declare function encodeToNavigationSpacesUrl(ref: NavigationReference): string;

package/dist/references/src/formats/uri/parse-reference-uri.d.ts

@@ -0,0 +1,20 @@
+/**
+ * URI format: detection + parsing.
+ *
+ * Detects the URI sub-format and dispatches to the appropriate decoder.
+ * Canonical URI wires are handled directly. `pre_reference_uri`
+ * is routed to the legacy decoder which handles all pre-reference URI types.
+ */
+import type { Reference, Referenced } from '../../types';
+export { UriFormat, type DetectedUriFormat } from '../format-catalog';
+export { detectUriFormat } from './detect-uri-wire';
+/**
+ * Parse a URI string into a runtime Reference.
+ *
+ * Never fails on a valid URL — unrecognized strings degrade to ExternalUrlReference.
+ */
+export declare function parseReferenceURI(input: string): Reference;
+/**
+ * Level-1 `Referenced` discriminator from a URI string without full decode.
+ */
+export declare function getReferencedFromUriString(input: string): Referenced | undefined;

package/dist/references/src/formats/uri/person-mention-uri.d.ts

@@ -0,0 +1,9 @@
+import type { PersonReference } from '../../types';
+/**
+ * Decode: `mention://person?id=X&email=Y` → PersonReference
+ */
+export declare function decodeFromPersonMentionUri(url: URL): PersonReference;
+/**
+ * Encode: PersonReference → `mention://person?id=X&email=Y`
+ */
+export declare function encodeToPersonMentionUri(ref: PersonReference): string;

package/dist/references/src/formats/uri/template-placeholder.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Unwraps a query value an agent copied from a link template with the
+ * template's brackets kept, e.g. `asset_ids=[asset_x]` from
+ * `asset_ids=[ASSET_ID]`. Kept verbatim, the id never resolves and the mention
+ * reads "Asset Not Found" for an asset that exists.
+ *
+ * Only a single bracketed token is unwrapped; anything containing a comma,
+ * whitespace or nested brackets is returned unchanged. So is the template's own
+ * placeholder (`[ASSET_ID]`, `[ASSET_TYPE]`): a prompt that teaches the link
+ * template must read back exactly as written.
+ */
+export declare function unwrapTemplatePlaceholder(value: string): string;

package/dist/references/src/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @athenaintel/references — Core reference system (parse, serialize, types).
+ *
+ * Pure TypeScript, no React or frontend dependencies.
+ *
+ * Pre-reference (TipTap-era) codecs are exported from `@athenaintel/references/legacy`.
+ * Olympus extends the core with UI-specific layers (anchor editors, renderers).
+ * `@athenaintel/references/asset-links` is the zod-free slice the React SDK bundles.
+ *
+ * The only exception is the TipTap node -> {reference} transform, which
+ * stays in Olympus because it is deeply coupled to the TipTap mention
+ * extension. That will migrate once the mention system uses runtime
+ * References directly.
+ */
+export { type AssetLike, assetToReference } from './asset-reference';
+export { anchorSchema, parseAnchor, } from './anchors/schemas';
+export { parseAnchorFromParams, } from './anchors/parse';
+export { serializeAnchorToParams, } from './anchors/serialize';
+export { formatReferenceAnchor, type ReferenceAnchorFormatMode } from './anchors/format';
+export { FILE_LINE_RANGE_BOUNDS, fileLineRangeAnchorByteLength, fileLineRangeAnchorProblem, repoPathProblem, type FileLineRangeFields, } from './anchors/file-line-range';
+export { findMessageText, messageBlockHash, messageHeadingSlug, messageTextContext, normalizeMessageText, type MessageTextMatch, } from './anchors/message-anchors';
+export { ASSET_ANCHOR_REGISTRY, getAnchorSupport, isAnchorAllowed, isAnchorPreferred, } from './anchors/registry';
+export { AnchorType, QueryResultRelationship } from './anchors/types';
+export type { Anchor, CellAnchor, CellRangeAnchor, CommentAnchor, CommentThreadAnchor, FileLineRangeAnchor, LineAnchor, LineRangeAnchor, MessageAnchor, MessageBlockAnchor, MessageRangeAnchor, MessageSectionAnchor, MessageTextAnchor, PageAnchor, PageRangeAnchor, PageRectAnchor, PageTextAnchor, PathAnchor, PixelRangeAnchor, PmMarkAnchor, PmNodeAnchor, PmNodeRangeAnchor, RectAnchor, SectionAnchor, SemanticQueryAnchor, ShapeAnchor, SheetCellAnchor, SheetRangeAnchor, SheetTabAnchor, SheetTableAnchor, LakehouseTableAnchor, SlideAnchor, SqlQueryAnchor, TimeAnchor, TimeRangeAnchor, TimeAnchorSeconds, TimeRangeAnchorSeconds, ToolCallAnchor, } from './anchors/types';
+export { isAnchor, isAnchorType, LEGACY_ANCHOR_TYPES } from './anchors/types';
+export { formatSecondsForCitation, formatSecondsForDisplay, formatTimestampForDisplay, getAnchorTimeSeconds, getTimeAnchorSeconds, parseTimeInput, parseTimestampToSeconds, timeSecondsToAnchor, } from './anchors/time';
+export { quoteSheetName } from './sheet-name';
+export type { AssetBounds } from './asset-bounds';
+export { FORMAT_CATALOG, getFormatEntry, getPreferredFormat, getReferencedForFormat, isCanonicalObjectFormat, ObjectFormat, UriFormat, } from './formats/format-catalog';
+export type { DetectedObjectFormat, DetectedUriFormat, FormatEntry, WireType, } from './formats/format-catalog';
+export { detectUriFormat, getReferencedFromUriString, } from './formats/uri/parse-reference-uri';
+export { detectObjectFormat } from './formats/object/parse-reference-object';
+export { MARKDOWN_AT_LINK, parseReferenceMarkdownChunks, } from './formats/markdown/parse-reference-markdown';
+export { getDisplayNameFromReference } from './formats/markdown/reference-display-name';
+export { encodeToAssetSpacesUrl } from './formats/uri/asset-spaces-url';
+export { encodeToAssetMentionUri } from './formats/uri/asset-mention-uri';
+export { encodeToNavigationSpacesUrl, isDriveTabAssetIds } from './formats/uri/navigation-spaces-url';
+export { detectFormat, parseReference, parseReferenceURI, parseReferenceObject, getReferencedEntity, } from './parse-reference';
+export type { DetectedFormat } from './parse-reference';
+export type { AssetLinkFormat, SerializeReferenceToMarkdownOptions, SerializeUriOptions, SerializeUrlOptions, } from './serialize-reference';
+export { serializeReference, serializeReferenceToMarkdown, serializeReferenceToObject, serializeReferenceToURI, serializeReferenceToURL, } from './serialize-reference';
+export { getPinnedVersionId, normalizeAssetReference, parseVersionRefFromParams, serializeVersionRefToParams, splitVersionedAssetId, } from './version-ref';
+export { assetReferenceSchema, assetVersionRefSchema, threadReferenceDataSchema, parseAssetReference, parseThreadReference, } from './schemas';
+export { addDisplayNameToReference, resolveNodeAttrsToReference, } from './mention-node/resolve-node-attrs';
+export { MENTION_HREF_PATTERNS, isMentionLikeHref } from './mention-href-patterns';
+export type { AssetMeta, AssetReference, AssetVersionRef, CallableMeta, CallableReference, ExternalUrlMeta, ExternalUrlReference, GroupMeta, GroupReference, NavigationMeta, NavigationReference, PersonMeta, PersonReference, Reference, } from './types';
+export { Referenced, CallableKind, isAssetReference, isCallableReference, isCitation, isExternalUrlReference, isGroupReference, isNavigationReference, isPersonReference, } from './types';

package/dist/references/src/legacy/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Pre-reference codecs and types for backward compatibility.
+ *
+ * Consolidated into @athenaintel/references so pre-reference and current codecs
+ * live in one shared package.
+ */
+export { CitationDefinitionSchema, CitationLineSchema, CitationNodeSchema, CitationNotebookSchema, CitationPaginationSchema, CitationPlaybackSchema, CitationSpreadsheetSchema, } from './pre-reference-citation';
+export type { CitationDefinition, CitationLine, CitationNode, CitationNotebook, CitationPagination, CitationPlayback, CitationSpreadsheet, } from './pre-reference-citation';
+export { anchorToCitationDefinition, citationDefinitionToAnchor, } from './pre-reference-citation-bridge';
+export { preReferenceMentionToReference, referenceToPreReferenceMention, } from './pre-reference-mention';
+export type { CitationMentionParams } from './pre-reference-mention';
+export { decodePreReferenceAssetUrl, extractCitation, } from './pre-reference-asset-url';
+export { encodeUrlCitation, parseUrlCitation, referenceToUrlCitation, urlCitationToReference, } from './pre-reference-external-url';
+export type { UrlCitationData } from './pre-reference-external-url';

package/dist/references/src/legacy/pre-reference-asset-url.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @legacy Asset URL codecs for the old spaces URL format.
+ *
+ * The old format uses flat query params like `?page=5&line=3` without an `anchor=`
+ * discriminator. The new canonical format uses `?anchor=page&page=5`.
+ *
+ * This module provides:
+ * - extractCitation: flat URL params -> CitationDefinition
+ * - decodePreReferenceAssetUrl: old-style spaces URL -> AssetReference
+ *
+ * Once all producers emit the new anchor-based format, this decoder will only
+ * be needed for reading old legacy URLs.
+ */
+import type { AssetReference } from '../types';
+import type { CitationDefinition } from './pre-reference-citation';
+/**
+ * @legacy Extract a CitationDefinition from flat URL search params.
+ *
+ * Handles the old param naming conventions (page, line, cell, sheet_id, etc.)
+ * used before the anchor-based URL format was introduced.
+ */
+export declare function extractCitation(params: {
+    time?: string;
+    startTime?: string;
+    endTime?: string;
+    page?: number;
+    startPage?: number;
+    endPage?: number;
+    bboxLeft?: number;
+    bboxTop?: number;
+    bboxWidth?: number;
+    bboxHeight?: number;
+    line?: number;
+    startLine?: number;
+    endLine?: number;
+    sheetId?: number;
+    sheetName?: string;
+    range?: string;
+    cell?: string;
+    startCell?: string;
+    endCell?: string;
+    nodeId?: string;
+    startNodeId?: string;
+    endNodeId?: string;
+}): CitationDefinition | undefined;
+/**
+ * @legacy Parse an old-style spaces URL into an AssetReference.
+ *
+ * Old format: `/dashboard/spaces?asset_ids=X&page=5&line=3`
+ * (flat citation params, no `anchor=` discriminator)
+ *
+ * Supports legacy param names: `page` vs `page_number`, `cell` vs `cell_id`,
+ * `sheet_id` vs `sheet_idx`, etc.
+ *
+ * Returns null if the URL doesn't contain `asset_ids`.
+ */
+export declare function decodePreReferenceAssetUrl(urlString: string): AssetReference | null;

package/dist/references/src/legacy/pre-reference-citation-bridge.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @legacy Bridge between mention CitationDefinition and reference Anchor types.
+ *
+ * CitationDefinition is used by the old mention system (mentions.config, assetMentionToUrl).
+ * Anchor is the canonical reference system type. This module provides bidirectional
+ * conversion so both systems can interoperate while we migrate to Anchor everywhere.
+ *
+ * Once the mention system is updated to use runtime References directly, this
+ * bridge will only be needed for reading old legacy content.
+ */
+import type { Anchor } from '../anchors/types';
+import type { CitationDefinition } from './pre-reference-citation';
+/**
+ * @legacy Convert CitationDefinition (mention schema) to Anchor (reference schema).
+ * Returns null if the citation type has no Anchor equivalent.
+ */
+export declare function citationDefinitionToAnchor(citation: CitationDefinition): Anchor | null;
+/**
+ * @legacy Convert Anchor (reference schema) to CitationDefinition (mention schema).
+ * Used when mention components need to display or edit anchor data.
+ */
+export declare function anchorToCitationDefinition(anchor: Anchor): CitationDefinition | null;

package/dist/references/src/legacy/pre-reference-citation.d.ts

@@ -0,0 +1,138 @@
+/**
+ * CitationDefinition — mention-system citation shapes (pre-Anchor).
+ *
+ * Stored in mention node params before the Anchor type was introduced.
+ * New code should use Anchor from the core types where possible.
+ */
+import { z } from 'zod';
+/** Page-based citations for PDFs, presentations, etc. */
+export declare const CitationPaginationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"page">;
+    page: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"page_range">;
+    startPage: z.ZodNumber;
+    endPage: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"page_bbox">;
+    page: z.ZodNumber;
+    bboxLeft: z.ZodNumber;
+    bboxTop: z.ZodNumber;
+    bboxWidth: z.ZodNumber;
+    bboxHeight: z.ZodNumber;
+}, z.core.$strict>], "type">;
+export type CitationPagination = z.infer<typeof CitationPaginationSchema>;
+/** Time-based citations for video/audio assets. */
+export declare const CitationPlaybackSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"time">;
+    time: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"duration">;
+    startTime: z.ZodString;
+    endTime: z.ZodString;
+}, z.core.$strict>], "type">;
+export type CitationPlayback = z.infer<typeof CitationPlaybackSchema>;
+/** Line-based citations for text/code assets. */
+export declare const CitationLineSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"line">;
+    line: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"line_range">;
+    startLine: z.ZodNumber;
+    endLine: z.ZodNumber;
+}, z.core.$strict>], "type">;
+export type CitationLine = z.infer<typeof CitationLineSchema>;
+/** Spreadsheet citations (sheet_range). */
+export declare const CitationSpreadsheetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"sheet_range">;
+    sheetId: z.ZodNumber;
+    sheetName: z.ZodOptional<z.ZodString>;
+    range: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "type">;
+export type CitationSpreadsheet = z.infer<typeof CitationSpreadsheetSchema>;
+/** Notebook cell citations. */
+export declare const CitationNotebookSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"notebook-cell">;
+    cell: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"notebook-cell-range">;
+    startCell: z.ZodString;
+    endCell: z.ZodString;
+}, z.core.$strict>], "type">;
+export type CitationNotebook = z.infer<typeof CitationNotebookSchema>;
+/** TipTap document node citations. */
+export declare const CitationNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"node">;
+    nodeId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"node_range">;
+    startNodeId: z.ZodString;
+    endNodeId: z.ZodString;
+}, z.core.$strict>], "type">;
+export type CitationNode = z.infer<typeof CitationNodeSchema>;
+/** Pixel-region citations for image assets (no page; coords in natural pixels). */
+export declare const CitationImageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"pixel_bbox">;
+    bboxLeft: z.ZodNumber;
+    bboxTop: z.ZodNumber;
+    bboxWidth: z.ZodNumber;
+    bboxHeight: z.ZodNumber;
+}, z.core.$strict>], "type">;
+export type CitationImage = z.infer<typeof CitationImageSchema>;
+/** Union of all citation sub-types used by the mention system. */
+export declare const CitationDefinitionSchema: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"page">;
+    page: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"page_range">;
+    startPage: z.ZodNumber;
+    endPage: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"page_bbox">;
+    page: z.ZodNumber;
+    bboxLeft: z.ZodNumber;
+    bboxTop: z.ZodNumber;
+    bboxWidth: z.ZodNumber;
+    bboxHeight: z.ZodNumber;
+}, z.core.$strict>], "type">, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"time">;
+    time: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"duration">;
+    startTime: z.ZodString;
+    endTime: z.ZodString;
+}, z.core.$strict>], "type">, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"line">;
+    line: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"line_range">;
+    startLine: z.ZodNumber;
+    endLine: z.ZodNumber;
+}, z.core.$strict>], "type">, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"sheet_range">;
+    sheetId: z.ZodNumber;
+    sheetName: z.ZodOptional<z.ZodString>;
+    range: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "type">, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"notebook-cell">;
+    cell: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"notebook-cell-range">;
+    startCell: z.ZodString;
+    endCell: z.ZodString;
+}, z.core.$strict>], "type">, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"node">;
+    nodeId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"node_range">;
+    startNodeId: z.ZodString;
+    endNodeId: z.ZodString;
+}, z.core.$strict>], "type">, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"pixel_bbox">;
+    bboxLeft: z.ZodNumber;
+    bboxTop: z.ZodNumber;
+    bboxWidth: z.ZodNumber;
+    bboxHeight: z.ZodNumber;
+}, z.core.$strict>], "type">]>;
+/** The mention-system citation type (union of sub-shapes). */
+export type CitationDefinition = CitationPagination | CitationPlayback | CitationLine | CitationSpreadsheet | CitationNotebook | CitationNode | CitationImage;

package/dist/references/src/legacy/pre-reference-external-url.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @legacy External URL citation codec.
+ *
+ * Encodes/decodes external URL citations where the URL itself is the reference
+ * and an optional `excerpt` search param carries a text snippet.
+ *
+ * Used by the old Citation/url mention type.
+ */
+import type { ExternalUrlReference } from '../types';
+export interface UrlCitationData {
+    url: string;
+    excerpt?: string;
+}
+/**
+ * @legacy Encode a URL citation — appends optional `excerpt` search param.
+ */
+export declare function encodeUrlCitation(data: UrlCitationData): string;
+/**
+ * @legacy Parse a URL citation — extracts optional `excerpt` search param.
+ *
+ * Includes recovery logic for malformed URLs with `&excerpt=` instead of `?excerpt=`.
+ */
+export declare function parseUrlCitation(url: string): UrlCitationData | null;
+/**
+ * @legacy Convert UrlCitationData to an ExternalUrlReference.
+ */
+export declare function urlCitationToReference(data: UrlCitationData): ExternalUrlReference;
+/**
+ * @legacy Convert an ExternalUrlReference to UrlCitationData.
+ */
+export declare function referenceToUrlCitation(ref: ExternalUrlReference): UrlCitationData;

package/dist/references/src/legacy/pre-reference-format.d.ts

@@ -0,0 +1,8 @@
+import type { Referenced } from '../types';
+/**
+ * Fallback for objects with wrong `format` strings
+ * (e.g. `asset_mention`, `asset_citation`, `callable_tool`) that were
+ * proliferated before the 4 canonical ObjectFormats existed.
+ * Infers the `Referenced` entity kind by prefix matching.
+ */
+export declare function getReferencedFromPreReferenceFormat(format: unknown): Referenced | undefined;

package/dist/references/src/legacy/pre-reference-mention.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @legacy Bidirectional adapter between runtime Reference objects and legacy mention params.
+ *
+ * - preReferenceMentionToReference: old mention params -> Reference
+ * - referenceToPreReferenceMention: Reference -> old mention params (for TipTap renderers)
+ *
+ * Once the mention system is updated to use runtime References directly, this
+ * adapter will only be needed for reading old legacy content.
+ */
+import type { Reference } from '../types';
+export type CitationMentionParams = Record<string, unknown>;
+/**
+ * @legacy Derive a Reference from legacy mention node params + mention type string.
+ *
+ * Used when reading mention nodes that don't have `params.reference` yet.
+ */
+export declare function preReferenceMentionToReference(mentionType: string, params: CitationMentionParams): Reference | null;
+/**
+ * @legacy Convert a Reference back to the legacy param shape expected by existing mention renderers.
+ *
+ * Returns { mentionType, params } where mentionType is the MENTION_TYPES key
+ * and params matches the schema for that type.
+ */
+export declare function referenceToPreReferenceMention(ref: Reference): {
+    mentionType: string;
+    params: CitationMentionParams;
+} | null;

package/dist/references/src/legacy/pre-reference-object.d.ts

@@ -0,0 +1,8 @@
+import { type DetectedObjectFormat } from '../formats/format-catalog';
+import type { Reference } from '../types';
+/**
+ * Stored objects that are not in canonical `{ format: asset_object | … }` shape:
+ * infer from `referenced`, old `format` strings, or TipTap `{ type, params }`.
+ */
+export declare function detectPreReferenceObject(input: Record<string, unknown>): DetectedObjectFormat;
+export declare function parsePreReferenceObject(input: Record<string, unknown>): Reference;

package/dist/references/src/legacy/pre-reference-uri.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pre-reference URI decoder — handles all legacy URI formats.
+ *
+ * - Spaces URLs without `anchor=` → decodePreReferenceAssetUrl (flat citation params)
+ * - mention://reference → asset mention (legacy host)
+ * - mention://tool without `name=` → lenient callable decoder
+ * - mention://toolkit without `name=` → lenient callable decoder
+ * - mention://group without `id=` → group decoder (empty id)
+ * - Any other mention:// → lenient decoders by host
+ */
+import type { Reference } from '../types';
+export declare function parsePreReferenceUri(url: URL, rawInput: string): Reference;

package/dist/references/src/legacy.d.ts

@@ -0,0 +1,2 @@
+/** npm: `@athenaintel/references/legacy` — pre-reference codecs only. */
+export * from './legacy/index';

package/dist/references/src/mention-href-patterns.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared href patterns that identify mention-like anchors.
+ *
+ * Used by:
+ *   - MentionNode.parseHTML (table-cell safety-net rule)
+ *   - converter-olympus promoteTableCellMentionAnchors (pre-parseHTML pass)
+ *
+ * Add new mention URI schemes here — both consumers pick them up automatically.
+ */
+/**
+ * Substrings whose presence in an anchor's `href` indicates the link
+ * represents a mention (asset, tool/toolkit, person, etc.).
+ */
+export declare const MENTION_HREF_PATTERNS: readonly string[];
+/**
+ * Returns `true` when `href` contains at least one of the known mention
+ * URI patterns, meaning the anchor should be treated as a mention chip.
+ */
+export declare function isMentionLikeHref(href: string): boolean;

package/dist/references/src/mention-node/index.d.ts

@@ -0,0 +1,5 @@
+/** @athenaintel/references/mention-node — Shared TipTap mention node + resolution. */
+export { MentionNode, getNodeDisplayName, preReferenceFromReference } from './mention-node';
+export type { MentionNodeOptions } from './mention-node';
+export { addDisplayNameToReference, resolveNodeAttrsToReference } from './resolve-node-attrs';
+export { MENTION_HREF_PATTERNS, isMentionLikeHref } from '../mention-href-patterns';

package/dist/references/src/mention-node/mention-node.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @athenaintel/references/mention-node — Shared TipTap mention node.
+ *
+ * `MentionNode` is a TipTap Node with the canonical attribute schema,
+ * comprehensive parseHTML rules, and reference-aware renderHTML/renderText.
+ *
+ * Consumers extend it for environment-specific behavior:
+ *   - Olympus: .extend({ addNodeView, addKeyboardShortcuts, addPasteRules })
+ *   - Agora converter: use directly (no React needed)
+ */
+import { Node } from '@tiptap/core';
+import type { Reference } from '../types';
+/**
+ * Derive pre-reference `type`/`params` from a Reference for backward compat
+ * with old Yjs clients that read those attributes.
+ */
+export declare function preReferenceFromReference(ref: Reference): Record<string, unknown>;
+export { resolveNodeAttrsToReference } from './resolve-node-attrs';
+export { addDisplayNameToReference } from './resolve-node-attrs';
+/**
+ * Resolve the display name for a mention node from the reference in its attrs.
+ *
+ * Shared by renderHTML, renderText, and the markdown serializer so the
+ * display-name resolution is identical everywhere.
+ */
+export declare function getNodeDisplayName(attrs: Record<string, unknown>): string;
+export interface MentionNodeOptions {
+    HTMLAttributes: Record<string, unknown>;
+}
+export declare const MentionNode: Node<MentionNodeOptions, any>;
+export default MentionNode;

package/dist/references/src/mention-node/resolve-node-attrs.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolve raw TipTap mention node attributes into a canonical Reference.
+ *
+ * Two paths:
+ *   1. Primary: `reference` attr (JSON string or object) → parseReference()
+ *   2. Fallback: legacy `type`/`params` → preReferenceMentionToReference()
+ *
+ * Both paths are synchronous. The function handles JSON string parsing,
+ * Zod validation, legacy pageNumber/excerpt injection, and (on the legacy
+ * path only) merging the top-level `name` attr into meta as the display title.
+ *
+ * No TipTap dependency — this is pure data normalization.
+ */
+import type { Reference } from '../types';
+/**
+ * Enrich a Reference with a display name in its meta.
+ * Person and group references get `meta.name`, everything else gets `meta.title`.
+ */
+export declare function addDisplayNameToReference(ref: Reference, displayName: string): Reference;
+/**
+ * Resolve a bag of mention node attributes into a canonical Reference.
+ *
+ * Handles both the canonical `reference` attribute (object or JSON string)
+ * and the legacy `type`/`name`/`params` triple. When both are present,
+ * `reference` wins.
+ */
+export declare function resolveNodeAttrsToReference(attrs: Record<string, unknown>): Reference | null;