rewind-mcp-server 0.1.1 → 0.4.0

package/dist/tools/cross-domain.js

@@ -1,13 +1,40 @@
 import { z } from 'zod';
-import { withErrorHandling, timeAgo, fmt, READ_ONLY_ANNOTATIONS, } from './helpers.js';
+import { withRichResponse, text, resourceLink, imageBlock, timeAgo, fmt, READ_ONLY_ANNOTATIONS, LIST_IMAGE_PX, } from './helpers.js';
+const SEARCH_TOP_N = 5;
+/**
+ * Map a cross-domain entity reference to a Rewind resource URI.
+ * Returns null when the entity type has no registered resource template.
+ */
+function rewindUri(domain, entityType, entityId) {
+    if (!entityId)
+        return null;
+    const map = {
+        'listening:artist': 'artist',
+        'listening:album': 'album',
+        'watching:movie': 'movie',
+        'watching:show': 'show',
+        'collecting:vinyl': 'vinyl',
+        'collecting:release': 'vinyl',
+        'collecting:media': 'physical-media',
+        'reading:article': 'article',
+        'reading:highlight': 'highlight',
+        'running:activity': 'activity',
+    };
+    const kind = map[`${domain}:${entityType}`];
+    return kind ? `rewind://${kind}/${entityId}` : null;
+}
 export function registerCrossDomainTools(server, client) {
-    // search
-    server.tool('search', 'Search across all domains (listening, running, watching, collecting, reading) using full-text search. Returns matching artists, albums, movies, articles, runs, and more.', {
+    // search ─────────────────────────────────────────────────────────
+    server.tool('search', 'Search across all domains (listening, running, watching, collecting, reading). Three ranking modes: keyword (default) uses FTS5 full-text search across all domains; semantic uses Voyage AI embeddings for paraphrased / meaning-based recall (reading domain only); hybrid fuses both (reading domain only). Use semantic or hybrid when the user describes what an article was ABOUT rather than quoting its words.', {
         query: z.string().describe('Search query text'),
         domain: z
             .enum(['listening', 'running', 'watching', 'collecting', 'reading'])
             .optional()
             .describe('Optional: filter results to a single domain'),
+        mode: z
+            .enum(['keyword', 'semantic', 'hybrid'])
+            .optional()
+            .describe('Ranking mode. keyword = FTS (default). semantic = cosine-similarity over article embeddings (reading only). hybrid = FTS + semantic via reciprocal rank fusion (reading only).'),
         limit: z
             .number()
             .min(1)
@@ -15,7 +42,7 @@ export function registerCrossDomainTools(server, client) {
             .default(10)
             .describe('Number of results to return'),
         page: z.number().min(1).default(1).describe('Page number for pagination'),
-    }, READ_ONLY_ANNOTATIONS, async ({ query, domain, limit, page }) => withErrorHandling(async () => {
+    }, READ_ONLY_ANNOTATIONS, async ({ query, domain, mode, limit, page }) => withRichResponse(async () => {
         const params = {
             q: query,
             limit,
@@ -23,19 +50,106 @@ export function registerCrossDomainTools(server, client) {
         };
         if (domain)
             params.domain = domain;
+        if (mode)
+            params.mode = mode;
         const data = await client.get('/search', params);
-        if (!data.data.length)
-            return `No results found for "${query}"${domain ? ` in ${domain}` : ''}.`;
+        if (!data.data.length) {
+            return {
+                content: [
+                    text(`No results found for "${query}"${domain ? ` in ${domain}` : ''}.`),
+                ],
+                structuredContent: { items: [], pagination: data.pagination },
+            };
+        }
+        const modeLabel = mode && mode !== 'keyword' ? ` [${mode}]` : '';
+        const lines = [
+            `Search results for "${query}"${modeLabel} (${fmt(data.pagination.total)} total):`,
+        ];
+        for (const [i, r] of data.data.entries()) {
+            const sub = r.subtitle ? ` -- ${r.subtitle}` : '';
+            const score = typeof r.score === 'number' ? ` (score=${r.score.toFixed(2)})` : '';
+            lines.push(`${i + 1}. [${r.domain}/${r.entity_type}] ${r.title}${sub}${score}`);
+        }
+        // Emit one resource_link per result that maps to a known entity.
+        const links = data.data
+            .map((r) => {
+            const uri = rewindUri(r.domain, r.entity_type, r.entity_id);
+            if (!uri)
+                return null;
+            return resourceLink(uri, r.title, {
+                mimeType: 'application/json',
+                description: r.subtitle ?? undefined,
+            });
+        })
+            .filter((b) => b !== null);
+        // Emit image blocks for the top-N results that carry an image.
+        const topN = data.data.slice(0, SEARCH_TOP_N);
+        const images = await Promise.all(topN.map((r) => imageBlock(client, r.image, LIST_IMAGE_PX)));
+        const imageBlocks = images.filter((b) => b !== null);
+        const content = [
+            text(lines.join('\n')),
+            ...imageBlocks,
+            ...links,
+        ];
+        return {
+            content,
+            structuredContent: { items: data.data, pagination: data.pagination },
+        };
+    }));
+    // semantic_search ────────────────────────────────────────────────
+    server.tool('semantic_search', 'Semantic search over the reading domain using Voyage AI embeddings. Use when the user describes the gist or topic of an article they remember rather than quoting exact words — e.g. "article about a former SNL writer" or "piece about tech layoffs". Returns articles ranked by cosine similarity with a score in [0,1]. Reading domain only.', {
+        query: z.string().describe('Natural-language description of the article'),
+        limit: z
+            .number()
+            .min(1)
+            .max(25)
+            .default(10)
+            .describe('Number of matches to return'),
+    }, READ_ONLY_ANNOTATIONS, async ({ query, limit }) => withRichResponse(async () => {
+        const data = await client.get('/search', {
+            q: query,
+            domain: 'reading',
+            mode: 'semantic',
+            limit,
+        });
+        if (!data.data.length) {
+            return {
+                content: [text(`No semantic matches found for "${query}".`)],
+                structuredContent: { items: [], pagination: data.pagination },
+            };
+        }
         const lines = [
-            `Search results for "${query}" (${fmt(data.pagination.total)} total):`,
+            `Semantic matches for "${query}" (${fmt(data.data.length)} shown):`,
         ];
         for (const [i, r] of data.data.entries()) {
             const sub = r.subtitle ? ` -- ${r.subtitle}` : '';
-            lines.push(`${i + 1}. [${r.domain}/${r.entity_type}] ${r.title}${sub}`);
+            lines.push(`${i + 1}. ${r.title}${sub} (score=${r.score.toFixed(2)})`);
         }
-        return lines.join('\n');
+        const links = data.data
+            .map((r) => {
+            const uri = rewindUri(r.domain, r.entity_type, r.entity_id);
+            if (!uri)
+                return null;
+            return resourceLink(uri, r.title, {
+                mimeType: 'application/json',
+                description: r.subtitle ?? undefined,
+            });
+        })
+            .filter((b) => b !== null);
+        const topN = data.data.slice(0, SEARCH_TOP_N);
+        const images = await Promise.all(topN.map((r) => imageBlock(client, r.image, LIST_IMAGE_PX)));
+        const imageBlocks = images.filter((b) => b !== null);
+        const content = [
+            text(lines.join('\n')),
+            ...imageBlocks,
+            ...links,
+        ];
+        return {
+            content,
+            structuredContent: { items: data.data, pagination: data.pagination },
+        };
     }));
-    // get_feed
+    // get_feed ───────────────────────────────────────────────────────
     server.tool('get_feed', 'Get the unified activity feed across all domains. Returns a chronological list of recent activities (listens, runs, watches, reads, collection adds). Supports date filtering.', {
         limit: z
             .number()
@@ -59,7 +173,7 @@ export function registerCrossDomainTools(server, client) {
             .string()
             .optional()
             .describe('Optional: end of date range (ISO 8601)'),
-    }, READ_ONLY_ANNOTATIONS, async ({ limit, domain, date, from, to }) => withErrorHandling(async () => {
+    }, READ_ONLY_ANNOTATIONS, async ({ limit, domain, date, from, to }) => withRichResponse(async () => {
         const params = {
             limit,
             date,
@@ -68,8 +182,12 @@ export function registerCrossDomainTools(server, client) {
         };
         const path = domain ? `/feed/domain/${domain}` : '/feed';
         const data = await client.get(path, params);
-        if (!data.data.length)
-            return 'No feed activity found for the given filters.';
+        if (!data.data.length) {
+            return {
+                content: [text('No feed activity found for the given filters.')],
+                structuredContent: { items: [], pagination: data.pagination },
+            };
+        }
         const lines = ['Activity Feed:'];
         for (const item of data.data) {
             const sub = item.subtitle ? ` -- ${item.subtitle}` : '';
@@ -78,9 +196,12 @@ export function registerCrossDomainTools(server, client) {
         if (data.pagination.has_more) {
             lines.push('\nMore items available. Increase limit or narrow date range.');
         }
-        return lines.join('\n');
+        return {
+            content: [text(lines.join('\n'))],
+            structuredContent: { items: data.data, pagination: data.pagination },
+        };
     }));
-    // get_on_this_day
+    // get_on_this_day ────────────────────────────────────────────────
     server.tool('get_on_this_day', "Get historical 'on this day' items -- what happened on a given date in previous years across all domains. Defaults to today. Great for nostalgia and reflection.", {
         month: z
             .number()
@@ -94,11 +215,15 @@ export function registerCrossDomainTools(server, client) {
             .max(31)
             .optional()
             .describe('Optional: day (1-31). Defaults to current day.'),
-    }, READ_ONLY_ANNOTATIONS, async ({ month, day }) => withErrorHandling(async () => {
+    }, READ_ONLY_ANNOTATIONS, async ({ month, day }) => withRichResponse(async () => {
         const params = { month, day };
         const data = await client.get('/feed/on-this-day', params);
-        if (!data.years.length)
-            return "No 'on this day' history found.";
+        if (!data.years.length) {
+            return {
+                content: [text("No 'on this day' history found.")],
+                structuredContent: data,
+            };
+        }
         const lines = [`On This Day (${data.month}/${data.day}):`];
         for (const yearGroup of data.years) {
             lines.push('');
@@ -108,7 +233,10 @@ export function registerCrossDomainTools(server, client) {
                 lines.push(`  - [${item.domain}] ${item.title}${sub}`);
             }
         }
-        return lines.join('\n');
+        return {
+            content: [text(lines.join('\n'))],
+            structuredContent: data,
+        };
     }));
 }
 //# sourceMappingURL=cross-domain.js.map

package/dist/tools/cross-domain.js.map

@@ -1 +1 @@
-{"version":3,"file":"cross-domain.js","sourceRoot":"","sources":["../../src/tools/cross-domain.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cross-domain.js","sourceRoot":"","sources":["../../src/tools/cross-domain.ts"],"names":[],"mappings":"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"}

package/dist/tools/debug.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Debug tools for MCP Apps pipeline verification. Throwaway -- will be
+ * removed once Phase 2 stabilizes.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDebugTools(server: McpServer): void;

package/dist/tools/debug.js

@@ -0,0 +1,26 @@
+import { READ_ONLY_ANNOTATIONS } from './helpers.js';
+export function registerDebugTools(server) {
+    server.registerTool('ui_hello_debug', {
+        title: 'UI Hello (debug)',
+        description: 'Show the Rewind MCP Apps diagnostic UI. Invoke this to verify the MCP Apps pipeline end-to-end against a known-working minimal React app.',
+        inputSchema: {},
+        annotations: READ_ONLY_ANNOTATIONS,
+        _meta: {
+            ui: { resourceUri: 'ui://rewind/hello.html' },
+            'ui/resourceUri': 'ui://rewind/hello.html',
+        },
+    }, async () => ({
+        content: [
+            {
+                type: 'text',
+                text: 'Rewind MCP Apps diagnostic. If the UI renders inline, the MCP Apps pipeline is working; if it fails with "Failed to set up MCP app", the issue is client-side (Anthropic sandbox).',
+            },
+        ],
+        structuredContent: {
+            greeting: 'hello',
+            server_time: new Date().toISOString(),
+            app: 'rewind-hello',
+        },
+    }));
+}
+//# sourceMappingURL=debug.js.map

package/dist/tools/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/tools/debug.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,UAAU,kBAAkB,CAAC,MAAiB;IAClD,MAAM,CAAC,YAAY,CACjB,gBAAgB,EAChB;QACE,KAAK,EAAE,kBAAkB;QACzB,WAAW,EACT,2IAA2I;QAC7I,WAAW,EAAE,EAAE;QACf,WAAW,EAAE,qBAAqB;QAClC,KAAK,EAAE;YACL,EAAE,EAAE,EAAE,WAAW,EAAE,wBAAwB,EAAE;YAC7C,gBAAgB,EAAE,wBAAwB;SAC3C;KACF,EACD,KAAK,IAAI,EAAE,CAAC,CAAC;QACX,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,oLAAoL;aAC3L;SACF;QACD,iBAAiB,EAAE;YACjB,QAAQ,EAAE,OAAO;YACjB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACrC,GAAG,EAAE,cAAc;SACpB;KACF,CAAC,CACH,CAAC;AACJ,CAAC"}

package/dist/tools/helpers.d.ts

@@ -1,32 +1,108 @@
 import { z } from 'zod';
 import type { RewindClient } from '../client.js';
+export type TextBlock = {
+    type: 'text';
+    text: string;
+};
+export type ImageBlock = {
+    type: 'image';
+    data: string;
+    mimeType: string;
+};
+export type ResourceLinkBlock = {
+    type: 'resource_link';
+    uri: string;
+    name: string;
+    mimeType?: string;
+    description?: string;
+};
+export type ContentBlock = TextBlock | ImageBlock | ResourceLinkBlock;
+export type ToolResult<S = unknown> = {
+    content: ContentBlock[];
+    structuredContent?: S;
+    isError?: boolean;
+};
+/** Build a text content block. */
+export declare function text(value: string): TextBlock;
+/**
+ * Build a resource_link content block.
+ * Returns null if the URI is missing/empty so callers can `.filter(Boolean)`.
+ */
+export declare function resourceLink(uri: string | null | undefined, name: string, opts?: {
+    mimeType?: string;
+    description?: string;
+}): ResourceLinkBlock | null;
+/**
+ * An image attachment as returned by Rewind entity responses.
+ * Accepts both `cdn_url` (live API) and `url` (OpenAPI-schema-example field).
+ */
+export type ImageAttachment = {
+    cdn_url?: string | null;
+    url?: string | null;
+    thumbhash?: string | null;
+    dominant_color?: string | null;
+    accent_color?: string | null;
+} | null | undefined;
+/**
+ * Build an image content block from an entity's image attachment by fetching
+ * the public CDN URL directly. Returns null on any failure or missing URL --
+ * never throws. Image blocks are best-effort; we always want to return
+ * text/data even if the image fetch breaks.
+ *
+ * Pass `targetPx` to request a smaller transform -- overrides the `width` and
+ * `height` query params on the CDN URL. Useful for list tools that must stay
+ * under the client's per-response size budget. Omit for full-size (typically
+ * 300x300) detail-tool posters.
+ */
+export declare function imageBlock(client: RewindClient, image: ImageAttachment, targetPx?: number): Promise<ImageBlock | null>;
+/** Target pixel size for list-tool image blocks. Keeps responses under ~250KB. */
+export declare const LIST_IMAGE_PX = 150;
 /**
- * Wrap a tool handler with standard error handling.
+ * Wrap a tool handler that returns only text.
  * Returns { content, isError: true } on failure.
  */
 export declare function withErrorHandling(fn: () => Promise<string>): Promise<{
-    content: {
-        type: 'text';
-        text: string;
-    }[];
+    content: TextBlock[];
     isError?: boolean;
 }>;
+/**
+ * Wrap a tool handler that returns a rich response (text + images + resource_links + structuredContent).
+ * Returns a well-formed error ToolResult on failure.
+ *
+ * Callers should construct content arrays via the builders above and filter nulls:
+ *   return {
+ *     content: [text(summary), ...blocks.filter(Boolean)],
+ *     structuredContent: data,
+ *   };
+ */
+export declare function withRichResponse<S = unknown>(fn: () => Promise<ToolResult<S>>): Promise<ToolResult<S>>;
 /** Format a date string as "Jan 15, 2025" */
 export declare function formatDate(iso: string | null | undefined): string;
 /** Format a date string as relative time like "2h ago" */
 export declare function timeAgo(iso: string): string;
 /** Format a number with commas */
 export declare function fmt(n: number | null | undefined): string;
+/**
+ * Format a Letterboxd-style 0-5 star user rating. The Rewind API stores
+ * these in the 0-5 half-star range (e.g. 4.5 = four and a half stars).
+ * Renders as "4.5★" or "4★" -- never "4/10", which is a different scale.
+ */
+export declare function formatStars(r: number | null | undefined): string;
 /** Common date filter params reused across tools. */
 export declare const dateFilterParams: {
     date: z.ZodOptional<z.ZodString>;
     from: z.ZodOptional<z.ZodString>;
     to: z.ZodOptional<z.ZodString>;
 };
+/** Shared optional input for tools that return image content blocks. */
+export declare const includeImagesParam: {
+    include_images: z.ZodDefault<z.ZodBoolean>;
+};
 /** Standard annotations for all Rewind tools (read-only, open-world). */
 export declare const READ_ONLY_ANNOTATIONS: {
     readOnlyHint: true;
     destructiveHint: false;
+    idempotentHint: true;
     openWorldHint: true;
 };
 export type { RewindClient };

package/dist/tools/helpers.js

@@ -1,21 +1,136 @@
 import { z } from 'zod';
+// ─── Content block builders ──────────────────────────────────────────
+/** Build a text content block. */
+export function text(value) {
+    return { type: 'text', text: value };
+}
+/**
+ * Build a resource_link content block.
+ * Returns null if the URI is missing/empty so callers can `.filter(Boolean)`.
+ */
+export function resourceLink(uri, name, opts) {
+    if (!uri)
+        return null;
+    const block = { type: 'resource_link', uri, name };
+    if (opts?.mimeType)
+        block.mimeType = opts.mimeType;
+    if (opts?.description)
+        block.description = opts.description;
+    return block;
+}
+/**
+ * Build an image content block from an entity's image attachment by fetching
+ * the public CDN URL directly. Returns null on any failure or missing URL --
+ * never throws. Image blocks are best-effort; we always want to return
+ * text/data even if the image fetch breaks.
+ *
+ * Pass `targetPx` to request a smaller transform -- overrides the `width` and
+ * `height` query params on the CDN URL. Useful for list tools that must stay
+ * under the client's per-response size budget. Omit for full-size (typically
+ * 300x300) detail-tool posters.
+ */
+export async function imageBlock(client, image, targetPx) {
+    if (!image)
+        return null;
+    let url = image.cdn_url ?? image.url ?? null;
+    if (!url)
+        return null;
+    if (targetPx)
+        url = resizeCdnUrl(url, targetPx);
+    try {
+        const { bytes, mimeType } = await client.getBinaryFromUrl(url);
+        return {
+            type: 'image',
+            data: bytesToBase64(bytes),
+            mimeType,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Rewrite a Rewind CDN URL to use the Cloudflare Images transform path
+ * (`/cdn-cgi/image/<opts>/<asset>`) at the requested pixel size. The raw
+ * `cdn_url` field returned by the API points at the original (full-res) R2
+ * object and does not honor width/height query params. Transform URLs do.
+ *
+ * Input:  https://cdn.rewind.rest/watching/movies/707/original.jpg?width=300&height=300&...&v=1
+ * Output: https://cdn.rewind.rest/cdn-cgi/image/width=150,height=150,fit=cover,format=auto,quality=85/watching/movies/707/original.jpg?v=1
+ *
+ * Returns the input unchanged if it is not a valid URL or is already a
+ * transform URL.
+ */
+function resizeCdnUrl(url, targetPx) {
+    try {
+        const u = new URL(url);
+        if (u.pathname.startsWith('/cdn-cgi/image/'))
+            return url;
+        const opts = `width=${targetPx},height=${targetPx},fit=cover,format=auto,quality=85`;
+        const version = u.searchParams.get('v');
+        const versionSuffix = version ? `?v=${version}` : '';
+        return `${u.origin}/cdn-cgi/image/${opts}${u.pathname}${versionSuffix}`;
+    }
+    catch {
+        return url;
+    }
+}
+/** Target pixel size for list-tool image blocks. Keeps responses under ~250KB. */
+export const LIST_IMAGE_PX = 150;
 /**
- * Wrap a tool handler with standard error handling.
+ * Convert bytes to base64. Uses globalThis.Buffer when available (Node / Workers),
+ * falls back to a manual encoding that works in any JS runtime.
+ */
+function bytesToBase64(bytes) {
+    const g = globalThis;
+    if (g.Buffer)
+        return g.Buffer.from(bytes).toString('base64');
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++)
+        binary += String.fromCharCode(bytes[i]);
+    return btoa(binary);
+}
+// ─── Response wrappers ───────────────────────────────────────────────
+/**
+ * Wrap a tool handler that returns only text.
  * Returns { content, isError: true } on failure.
  */
 export async function withErrorHandling(fn) {
     try {
-        const text = await fn();
-        return { content: [{ type: 'text', text }] };
+        const textValue = await fn();
+        return { content: [text(textValue)] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [text(`Error: ${message}`)],
+            isError: true,
+        };
+    }
+}
+/**
+ * Wrap a tool handler that returns a rich response (text + images + resource_links + structuredContent).
+ * Returns a well-formed error ToolResult on failure.
+ *
+ * Callers should construct content arrays via the builders above and filter nulls:
+ *   return {
+ *     content: [text(summary), ...blocks.filter(Boolean)],
+ *     structuredContent: data,
+ *   };
+ */
+export async function withRichResponse(fn) {
+    try {
+        return await fn();
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         return {
-            content: [{ type: 'text', text: `Error: ${message}` }],
+            content: [text(`Error: ${message}`)],
             isError: true,
         };
     }
 }
+// ─── Existing utilities (unchanged) ──────────────────────────────────
 /** Format a date string as "Jan 15, 2025" */
 export function formatDate(iso) {
     if (!iso)
@@ -48,6 +163,17 @@ export function fmt(n) {
         return '0';
     return n.toLocaleString('en-US');
 }
+/**
+ * Format a Letterboxd-style 0-5 star user rating. The Rewind API stores
+ * these in the 0-5 half-star range (e.g. 4.5 = four and a half stars).
+ * Renders as "4.5★" or "4★" -- never "4/10", which is a different scale.
+ */
+export function formatStars(r) {
+    if (r === null || r === undefined)
+        return '';
+    const display = r % 1 === 0 ? r.toFixed(0) : r.toFixed(1);
+    return `${display}★`;
+}
 /** Common date filter params reused across tools. */
 export const dateFilterParams = {
     date: z
@@ -60,10 +186,18 @@ export const dateFilterParams = {
         .describe('Optional: start of date range (ISO 8601)'),
     to: z.string().optional().describe('Optional: end of date range (ISO 8601)'),
 };
+/** Shared optional input for tools that return image content blocks. */
+export const includeImagesParam = {
+    include_images: z
+        .boolean()
+        .default(true)
+        .describe('Include artwork/poster image content blocks in the response. Default true. Set false to keep responses small.'),
+};
 /** Standard annotations for all Rewind tools (read-only, open-world). */
 export const READ_ONLY_ANNOTATIONS = {
     readOnlyHint: true,
     destructiveHint: false,
+    idempotentHint: true,
     openWorldHint: true,
 };
 //# sourceMappingURL=helpers.js.map

package/dist/tools/helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/tools/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,EAAyB;IAEzB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,EAAE,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAC/C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC;YACtD,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;AACH,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,UAAU,CAAC,GAA8B;IACvD,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,kBAAkB,CAAC,OAAO,EAAE;QAC/C,KAAK,EAAE,OAAO;QACd,GAAG,EAAE,SAAS;QACd,IAAI,EAAE,SAAS;KAChB,CAAC,CAAC;AACL,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC;IAClD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC;IAC1C,IAAI,OAAO,GAAG,CAAC;QAAE,OAAO,UAAU,CAAC;IACnC,IAAI,OAAO,GAAG,EAAE;QAAE,OAAO,GAAG,OAAO,OAAO,CAAC;IAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACvC,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,GAAG,KAAK,OAAO,CAAC;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;IACpC,IAAI,IAAI,GAAG,CAAC;QAAE,OAAO,GAAG,IAAI,OAAO,CAAC;IACpC,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,kCAAkC;AAClC,MAAM,UAAU,GAAG,CAAC,CAA4B;IAC9C,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IAC9C,OAAO,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC;AAED,qDAAqD;AACrD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,kDAAkD,CAAC;IAC/D,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,0CAA0C,CAAC;IACvD,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;CAC7E,CAAC;AAEF,yEAAyE;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,YAAY,EAAE,IAAa;IAC3B,eAAe,EAAE,KAAc;IAC/B,aAAa,EAAE,IAAa;CAC7B,CAAC"}
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/tools/helpers.ts"],"names":[],"mappings":"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"}