@athenaintel/react 0.41.3 → 0.42.1

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

@@ -0,0 +1,23 @@
+import type { DetectedUriFormat, DetectedObjectFormat } from './formats/format-catalog';
+import type { Reference, Referenced } from './types';
+export { parseReferenceURI } from './formats/uri/parse-reference-uri';
+export { parseReferenceObject } from './formats/object/parse-reference-object';
+export type DetectedFormat = DetectedUriFormat | DetectedObjectFormat;
+/**
+ * Detect the format of an unknown input.
+ *
+ * For strings: URI wire detection.
+ * For plain objects: object wire detection.
+ */
+export declare function detectFormat(input: unknown): DetectedFormat;
+/**
+ * Parse any input (URI string or stored object) into runtime Reference.
+ *
+ * Dispatches by JavaScript shape: string → URI codec; plain object → object codec.
+ */
+export declare function parseReference(input: unknown): Reference;
+/**
+ * Quick Level 1 extraction without full parse.
+ * Returns the discriminator or undefined for unrecognized input.
+ */
+export declare function getReferencedEntity(input: unknown): Referenced | undefined;

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

@@ -0,0 +1,463 @@
+/**
+ * Zod schemas for the reference system — runtime validation at storage boundaries.
+ *
+ * Primary use: validating `thread.data.reference` read from Y.Doc, which is
+ * typed as `Record<string, unknown>` at the Yjs layer.
+ */
+import * as z from 'zod';
+import type { AssetReference } from './types';
+export declare const assetMetaSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    excerpt: z.ZodOptional<z.ZodString>;
+    assetType: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodString>;
+    providerLocation: z.ZodOptional<z.ZodString>;
+    sheetName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const callableMetaSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const personMetaSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    avatar: z.ZodOptional<z.ZodString>;
+    phone: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const groupMetaSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const externalUrlMetaSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    excerpt: z.ZodOptional<z.ZodString>;
+    thumbnailUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const navigationMetaSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const assetVersionRefSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"latest">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"pinned">;
+    versionId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"as_of">;
+    at: z.ZodString;
+    keryxClock: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], "kind">;
+export declare const recordSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const callableKindSchema: z.ZodEnum<{
+    tool: "tool";
+    toolkit: "toolkit";
+    workspace_item: "workspace_item";
+}>;
+export declare const referencedSchema: z.ZodEnum<{
+    asset: "asset";
+    callable: "callable";
+    external_url: "external_url";
+    group: "group";
+    navigation: "navigation";
+    person: "person";
+}>;
+export declare const assetReferenceSchema: z.ZodObject<{
+    referenced: z.ZodLiteral<"asset">;
+    id: z.ZodString;
+    anchor: z.ZodOptional<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"cell">;
+        cellId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"cell_range">;
+        startCellId: z.ZodString;
+        endCellId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"comment">;
+        threadId: z.ZodString;
+        commentId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"comment_thread">;
+        threadId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"file_line_range">;
+        path: z.ZodString;
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"line">;
+        line: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"line_range">;
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"msg">;
+        messageId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"msg_range">;
+        startMessageId: z.ZodString;
+        endMessageId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"msg_block">;
+        messageId: z.ZodString;
+        block: z.ZodNumber;
+        hash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"msg_section">;
+        messageId: z.ZodString;
+        heading: z.ZodString;
+        nth: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"msg_text">;
+        messageId: z.ZodString;
+        text: z.ZodString;
+        block: z.ZodOptional<z.ZodNumber>;
+        prefix: z.ZodOptional<z.ZodString>;
+        suffix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"page">;
+        page: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"page_range">;
+        startPage: z.ZodNumber;
+        endPage: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"page_rect">;
+        page: z.ZodNumber;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        unit: z.ZodOptional<z.ZodEnum<{
+            percent: "percent";
+            point: "point";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"page_text">;
+        page: z.ZodNumber;
+        text: z.ZodString;
+        prefix: z.ZodOptional<z.ZodString>;
+        suffix: z.ZodOptional<z.ZodString>;
+        hash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"path">;
+        path: z.ZodString;
+        line: z.ZodOptional<z.ZodNumber>;
+        column: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"pixel_range">;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"pm_node">;
+        nodeId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"pm_node_range">;
+        startNodeId: z.ZodString;
+        endNodeId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"pm_mark">;
+        markId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"rect">;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"section">;
+        section: z.ZodString;
+        topic: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"semantic_query">;
+        query: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        field: z.ZodOptional<z.ZodString>;
+        rowKey: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        rowIndex: z.ZodOptional<z.ZodNumber>;
+        relationship: z.ZodOptional<z.ZodEnum<{
+            exact: "exact";
+            supporting: "supporting";
+        }>>;
+        schemaVersion: z.ZodOptional<z.ZodNumber>;
+        schemaHash: z.ZodOptional<z.ZodString>;
+        sourceSnapshots: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        dataAsOf: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"shape">;
+        slideId: z.ZodString;
+        slideIndex: z.ZodNumber;
+        shapeIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"sheet_cell">;
+        sheetId: z.ZodNumber;
+        cell: z.ZodString;
+        chartId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"sheet_range">;
+        sheetId: z.ZodNumber;
+        range: z.ZodString;
+        frontier: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"sheet_tab">;
+        sheetId: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"sheet_table">;
+        sheetId: z.ZodNumber;
+        tableName: z.ZodString;
+        fallbackRange: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"lakehouse_table">;
+        table: z.ZodString;
+        tableUuid: z.ZodOptional<z.ZodString>;
+        snapshotId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"slide">;
+        slideId: z.ZodString;
+        slideIndex: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"sql_query">;
+        sql: z.ZodOptional<z.ZodString>;
+        querySnippetAssetId: z.ZodOptional<z.ZodString>;
+        dialect: z.ZodOptional<z.ZodString>;
+        field: z.ZodOptional<z.ZodString>;
+        rowKey: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        rowIndex: z.ZodOptional<z.ZodNumber>;
+        relationship: z.ZodOptional<z.ZodEnum<{
+            exact: "exact";
+            supporting: "supporting";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"time">;
+        time: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"time_range">;
+        startTime: z.ZodString;
+        endTime: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"tool_call">;
+        toolCallId: z.ZodString;
+        messageId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "type">>>;
+    version: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"latest">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"pinned">;
+        versionId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"as_of">;
+        at: z.ZodString;
+        keryxClock: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>], "kind">>;
+    meta: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        excerpt: z.ZodOptional<z.ZodString>;
+        assetType: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
+        providerLocation: z.ZodOptional<z.ZodString>;
+        sheetName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const threadReferenceDataSchema: z.ZodObject<{
+    reference: z.ZodObject<{
+        referenced: z.ZodLiteral<"asset">;
+        id: z.ZodString;
+        anchor: z.ZodOptional<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"cell">;
+            cellId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"cell_range">;
+            startCellId: z.ZodString;
+            endCellId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"comment">;
+            threadId: z.ZodString;
+            commentId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"comment_thread">;
+            threadId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"file_line_range">;
+            path: z.ZodString;
+            startLine: z.ZodNumber;
+            endLine: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"line">;
+            line: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"line_range">;
+            startLine: z.ZodNumber;
+            endLine: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"msg">;
+            messageId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"msg_range">;
+            startMessageId: z.ZodString;
+            endMessageId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"msg_block">;
+            messageId: z.ZodString;
+            block: z.ZodNumber;
+            hash: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"msg_section">;
+            messageId: z.ZodString;
+            heading: z.ZodString;
+            nth: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"msg_text">;
+            messageId: z.ZodString;
+            text: z.ZodString;
+            block: z.ZodOptional<z.ZodNumber>;
+            prefix: z.ZodOptional<z.ZodString>;
+            suffix: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"page">;
+            page: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"page_range">;
+            startPage: z.ZodNumber;
+            endPage: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"page_rect">;
+            page: z.ZodNumber;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            unit: z.ZodOptional<z.ZodEnum<{
+                percent: "percent";
+                point: "point";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"page_text">;
+            page: z.ZodNumber;
+            text: z.ZodString;
+            prefix: z.ZodOptional<z.ZodString>;
+            suffix: z.ZodOptional<z.ZodString>;
+            hash: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"path">;
+            path: z.ZodString;
+            line: z.ZodOptional<z.ZodNumber>;
+            column: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"pixel_range">;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"pm_node">;
+            nodeId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"pm_node_range">;
+            startNodeId: z.ZodString;
+            endNodeId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"pm_mark">;
+            markId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"rect">;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"section">;
+            section: z.ZodString;
+            topic: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"semantic_query">;
+            query: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            field: z.ZodOptional<z.ZodString>;
+            rowKey: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            rowIndex: z.ZodOptional<z.ZodNumber>;
+            relationship: z.ZodOptional<z.ZodEnum<{
+                exact: "exact";
+                supporting: "supporting";
+            }>>;
+            schemaVersion: z.ZodOptional<z.ZodNumber>;
+            schemaHash: z.ZodOptional<z.ZodString>;
+            sourceSnapshots: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            dataAsOf: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"shape">;
+            slideId: z.ZodString;
+            slideIndex: z.ZodNumber;
+            shapeIds: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"sheet_cell">;
+            sheetId: z.ZodNumber;
+            cell: z.ZodString;
+            chartId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"sheet_range">;
+            sheetId: z.ZodNumber;
+            range: z.ZodString;
+            frontier: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"sheet_tab">;
+            sheetId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"sheet_table">;
+            sheetId: z.ZodNumber;
+            tableName: z.ZodString;
+            fallbackRange: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"lakehouse_table">;
+            table: z.ZodString;
+            tableUuid: z.ZodOptional<z.ZodString>;
+            snapshotId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"slide">;
+            slideId: z.ZodString;
+            slideIndex: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"sql_query">;
+            sql: z.ZodOptional<z.ZodString>;
+            querySnippetAssetId: z.ZodOptional<z.ZodString>;
+            dialect: z.ZodOptional<z.ZodString>;
+            field: z.ZodOptional<z.ZodString>;
+            rowKey: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            rowIndex: z.ZodOptional<z.ZodNumber>;
+            relationship: z.ZodOptional<z.ZodEnum<{
+                exact: "exact";
+                supporting: "supporting";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"time">;
+            time: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"time_range">;
+            startTime: z.ZodString;
+            endTime: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"tool_call">;
+            toolCallId: z.ZodString;
+            messageId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "type">>>;
+        version: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"latest">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"pinned">;
+            versionId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"as_of">;
+            at: z.ZodString;
+            keryxClock: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>], "kind">>;
+        meta: z.ZodOptional<z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            excerpt: z.ZodOptional<z.ZodString>;
+            assetType: z.ZodOptional<z.ZodString>;
+            provider: z.ZodOptional<z.ZodString>;
+            providerLocation: z.ZodOptional<z.ZodString>;
+            sheetName: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare function parseAssetReference(value: unknown): AssetReference | undefined;
+export declare function parseThreadReference(data: Record<string, unknown> | undefined): AssetReference | undefined;

package/dist/references/src/serialize-reference.d.ts

@@ -0,0 +1,50 @@
+import type { Reference } from './types';
+export type AssetLinkFormat = 'spaces_url' | 'mention_uri';
+export interface SerializeUriOptions {
+    linkFormat?: AssetLinkFormat;
+}
+/**
+ * Serialize a runtime Reference to canonical storage format.
+ *
+ * - `'uri'` (default) → canonical URI string
+ * - `'object'` → canonical storage object with `format` discriminator
+ */
+export declare function serializeReference(ref: Reference, format?: 'uri' | 'object'): string | Record<string, unknown>;
+/**
+ * Serialize a runtime Reference to its canonical URI string.
+ * For assets, `linkFormat` selects between Spaces URL (default) and `mention://asset` URI.
+ */
+export declare function serializeReferenceToURI(ref: Reference, opts?: SerializeUriOptions): string;
+/**
+ * Serialize a runtime Reference to its canonical storage object.
+ */
+export declare function serializeReferenceToObject(ref: Reference): Record<string, unknown>;
+export interface SerializeUrlOptions extends SerializeUriOptions {
+    origin: string;
+}
+/**
+ * Serialize a runtime Reference to a navigable absolute URL.
+ *
+ * Prepends `origin` to the canonical URI when that URI is a site-relative
+ * path (assets, navigation). URIs that already carry a scheme — external
+ * `https://` URLs, `mention://` people, groups and tools — are returned as-is.
+ * Use this when the output is for browser navigation, clipboard sharing,
+ * or backend storage that requires scheme + host.
+ *
+ * For storage/wire identifiers, prefer {@link serializeReferenceToURI}.
+ */
+export declare function serializeReferenceToURL(ref: Reference, opts: SerializeUrlOptions): string;
+export type SerializeReferenceToMarkdownOptions = SerializeUriOptions & {
+    /** Visible label inside `[@…](url)`; overrides {@link getDisplayNameFromReference}. */
+    linkLabel?: string;
+    /** When set, `href` is absolute: `linkOrigin` + canonical path (composer, clipboard, share). */
+    linkOrigin?: string;
+};
+/**
+ * Serialize to markdown at-link: `[@label](uri)` where `uri` is the canonical
+ * URI for this reference. Standalone utility — not part of `serializeReference`.
+ *
+ * Use {@link SerializeReferenceToMarkdownOptions.linkLabel} to override the bracket text;
+ * use {@link SerializeReferenceToMarkdownOptions.linkOrigin} for an absolute URL in the link.
+ */
+export declare function serializeReferenceToMarkdown(ref: Reference, opts?: SerializeReferenceToMarkdownOptions): string;

package/dist/references/src/sheet-name.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Quote a sheet name for Excel cross-sheet reference notation.
+ *
+ * A name that is not a bare run of ASCII letters and digits is wrapped in
+ * single quotes with embedded apostrophes doubled, so `1. Form Factor SKUs`
+ * renders as `'1. Form Factor SKUs'` and `O'Brien` as `'O''Brien'`. Mirrors
+ * `sanitizeSheetName` in `@rowsncolumns/utils` (kept local so the citation
+ * label formatter does not import the sheets engine).
+ */
+export declare function quoteSheetName(name: string): string;