@athenaintel/react 0.41.2 → 0.42.1

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

@@ -0,0 +1,194 @@
+/**
+ * Zod schemas for anchor types — runtime validation at the storage boundary.
+ *
+ * These schemas mirror the TypeScript types in `types.ts` and are used to
+ * validate data read from Y.Doc thread data, API responses, etc.
+ *
+ * The `anchorSchema` discriminated union is the primary export — use it
+ * with `safeParse` at trust boundaries.
+ */
+import * as z from 'zod';
+import type { Anchor } from './types';
+/**
+ * Stored anchors written before the session-anchor rename use
+ * `type: 'message'` / `'message_range'`; map them to the current
+ * discriminators before validating so persisted references keep decoding.
+ */
+export declare function normalizeLegacyAnchorType(value: unknown): unknown;
+export declare const anchorSchema: 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">>;
+export declare function parseAnchor(value: unknown): Anchor | undefined;

package/dist/references/src/anchors/serialize.d.ts

@@ -0,0 +1,8 @@
+import type { Anchor } from './types';
+/**
+ * Serialize an Anchor to snake_case URL query parameters.
+ *
+ * Returns a `URLSearchParams` containing `anchor=<type>` plus type-specific params.
+ * The caller appends these to the asset URL.
+ */
+export declare function serializeAnchorToParams(anchor: Anchor): URLSearchParams;

package/dist/references/src/anchors/time.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Time anchors: how a media position is written in a reference and read back as seconds. The
+ * packages that read time anchors (comments, the editors) and Olympus (`olympus/src/lib/time-utils.ts`
+ * and `olympus/src/lib/references/anchors/anchor-accessors.ts` re-export these) share this one
+ * reading.
+ *
+ * Time anchors are the one anchor type whose stored form differs from its runtime form: stored as
+ * formatted strings ("1:30"), consumed as numeric seconds.
+ *
+ *   Stored → Runtime:  getAnchorTimeSeconds(anchor)
+ *   Runtime → Stored:  timeSecondsToAnchor(runtime)
+ *
+ * Consumers work with runtime types (TimeAnchorSeconds / TimeRangeAnchorSeconds) and call the
+ * transforms only at storage boundaries.
+ */
+import type { Anchor, TimeAnchor, TimeAnchorSeconds, TimeRangeAnchor, TimeRangeAnchorSeconds } from './types';
+/**
+ * Parses a timestamp string in HH:MM:SS format to seconds.
+ * Returns null if parsing fails (safer than returning 0 which could cause silent seeks).
+ *
+ * @param timestamp - Timestamp string in format "HH:MM:SS" (e.g., "00:05:30")
+ * @returns Number of seconds, or null if parsing fails
+ */
+export declare function parseTimestampToSeconds(timestamp: string): number | null;
+/**
+ * Formats seconds to a display string (M:SS or H:MM:SS).
+ * Removes leading zeros for a cleaner display.
+ *
+ * @param seconds - Number of seconds
+ * @returns Formatted string like "5:30" or "1:05:30"
+ */
+export declare function formatSecondsForDisplay(seconds: number): string;
+/**
+ * Formats seconds to HH:MM:SS for citation storage.
+ * Always includes leading zeros for consistent storage format.
+ *
+ * @param seconds - Number of seconds
+ * @returns Formatted string like "00:05:30" or "01:23:45"
+ */
+export declare function formatSecondsForCitation(seconds: number): string;
+/**
+ * Formats an HH:MM:SS timestamp string to a shorter display format.
+ * Removes leading zeros for a cleaner display.
+ *
+ * @param timestamp - Timestamp string in format "HH:MM:SS"
+ * @returns Formatted string like "5:30" or "1:05:30", or original string if parsing fails
+ */
+export declare function formatTimestampForDisplay(timestamp: string): string;
+/**
+ * Parses a flexible time input string (M:SS, MM:SS, H:MM:SS, or HH:MM:SS) to seconds.
+ * More lenient than parseTimestampToSeconds - accepts various input formats.
+ * The seconds may carry a fraction (`00:01:05.432`, how Clio writes a time
+ * anchor with milliseconds), which is kept: dropping it lands a seek in the
+ * silence before the cited turn. Returns null if parsing fails.
+ *
+ * @param input - Time string in various formats
+ * @returns Number of seconds, or null if parsing fails
+ */
+export declare function parseTimeInput(input: string): number | null;
+/**
+ * Convert a stored time anchor to its seconds-based runtime form.
+ *
+ *   const t = getAnchorTimeSeconds(anchor);
+ *   if (!t) return; // not a time anchor
+ *   if (t.type === 'time_seconds') player.currentTime = t.timeSeconds;
+ *   if (t.type === 'time_range_seconds') { ... t.startTimeSeconds, t.endTimeSeconds ... }
+ */
+export declare function getAnchorTimeSeconds(anchor: Anchor): TimeAnchorSeconds | TimeRangeAnchorSeconds | undefined;
+export declare function timeSecondsToAnchor(runtime: TimeAnchorSeconds): TimeAnchor;
+export declare function timeSecondsToAnchor(runtime: TimeRangeAnchorSeconds): TimeRangeAnchor;
+export declare function timeSecondsToAnchor(runtime: TimeAnchorSeconds | TimeRangeAnchorSeconds): TimeAnchor | TimeRangeAnchor;
+/**
+ * @deprecated Use `getAnchorTimeSeconds` instead.
+ */
+export declare function getTimeAnchorSeconds(anchor: Anchor): {
+    start: number;
+    end?: number;
+} | undefined;