youtube-knowledge-mcp 2.2.0 → 3.0.1

package/dist/utils/youtube-schemas.d.ts

@@ -92,9 +92,16 @@ export declare const videoDetailsRowSchema: z.ZodObject<{
     }>, "many">>>;
     upload_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     duration: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    /**
+     * The video's real comment count — trustworthy ONLY here, because this read
+     * does not pass --write-comments. With that flag yt-dlp replaces the value
+     * with the number it extracted (measured: 300 against a video with 2.4M).
+     */
+    comment_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {
     duration?: number | null | undefined;
     upload_date?: string | null | undefined;
+    comment_count?: number | null | undefined;
     chapters?: {
         title: string;
         start_time: number;
@@ -103,66 +110,157 @@ export declare const videoDetailsRowSchema: z.ZodObject<{
 }, {
     duration?: number | null | undefined;
     upload_date?: string | null | undefined;
+    comment_count?: number | null | undefined;
     chapters?: {
         title: string;
         start_time: number;
         end_time: number;
     }[] | null | undefined;
 }>;
+/**
+ * Every field yt-dlp returns for a comment, verified against 2026.08.19.
+ *
+ * Nine of these were previously dropped on the floor after being paid for:
+ * the extraction fetches them either way, so discarding `id` and `parent`
+ * meant a thread could not be rebuilt from what we already had.
+ */
 export declare const commentRowSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     author: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    author_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    author_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    author_thumbnail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    author_is_uploader: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    author_is_verified: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     like_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     is_pinned: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    is_favorited: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    timestamp: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    _time_text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** 'root' for a top-level comment; the parent's id for a reply. */
     parent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
+    id?: string | null | undefined;
     author?: string | null | undefined;
     text?: string | null | undefined;
+    timestamp?: number | null | undefined;
     parent?: string | null | undefined;
     like_count?: number | null | undefined;
+    author_id?: string | null | undefined;
+    author_url?: string | null | undefined;
+    author_thumbnail?: string | null | undefined;
+    author_is_uploader?: boolean | null | undefined;
+    author_is_verified?: boolean | null | undefined;
     is_pinned?: boolean | null | undefined;
+    is_favorited?: boolean | null | undefined;
+    _time_text?: string | null | undefined;
 }, {
+    id?: string | null | undefined;
     author?: string | null | undefined;
     text?: string | null | undefined;
+    timestamp?: number | null | undefined;
     parent?: string | null | undefined;
     like_count?: number | null | undefined;
+    author_id?: string | null | undefined;
+    author_url?: string | null | undefined;
+    author_thumbnail?: string | null | undefined;
+    author_is_uploader?: boolean | null | undefined;
+    author_is_verified?: boolean | null | undefined;
     is_pinned?: boolean | null | undefined;
+    is_favorited?: boolean | null | undefined;
+    _time_text?: string | null | undefined;
 }>;
 export declare const commentsRowSchema: z.ZodObject<{
     comments: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         author: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        author_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        author_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        author_thumbnail: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        author_is_uploader: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        author_is_verified: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
         text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         like_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         is_pinned: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        is_favorited: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        timestamp: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        _time_text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** 'root' for a top-level comment; the parent's id for a reply. */
         parent: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, "strip", z.ZodTypeAny, {
+        id?: string | null | undefined;
         author?: string | null | undefined;
         text?: string | null | undefined;
+        timestamp?: number | null | undefined;
         parent?: string | null | undefined;
         like_count?: number | null | undefined;
+        author_id?: string | null | undefined;
+        author_url?: string | null | undefined;
+        author_thumbnail?: string | null | undefined;
+        author_is_uploader?: boolean | null | undefined;
+        author_is_verified?: boolean | null | undefined;
         is_pinned?: boolean | null | undefined;
+        is_favorited?: boolean | null | undefined;
+        _time_text?: string | null | undefined;
     }, {
+        id?: string | null | undefined;
         author?: string | null | undefined;
         text?: string | null | undefined;
+        timestamp?: number | null | undefined;
         parent?: string | null | undefined;
         like_count?: number | null | undefined;
+        author_id?: string | null | undefined;
+        author_url?: string | null | undefined;
+        author_thumbnail?: string | null | undefined;
+        author_is_uploader?: boolean | null | undefined;
+        author_is_verified?: boolean | null | undefined;
         is_pinned?: boolean | null | undefined;
+        is_favorited?: boolean | null | undefined;
+        _time_text?: string | null | undefined;
     }>, "many">>>;
+    /**
+     * With --write-comments yt-dlp OVERWRITES this with the number extracted,
+     * and sets it to null when the extraction was interrupted. So it is a
+     * three-state signal about this run, never the video's real total, which
+     * only a separate metadata pass can report.
+     */
+    comment_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {
+    comment_count?: number | null | undefined;
     comments?: {
+        id?: string | null | undefined;
         author?: string | null | undefined;
         text?: string | null | undefined;
+        timestamp?: number | null | undefined;
         parent?: string | null | undefined;
         like_count?: number | null | undefined;
+        author_id?: string | null | undefined;
+        author_url?: string | null | undefined;
+        author_thumbnail?: string | null | undefined;
+        author_is_uploader?: boolean | null | undefined;
+        author_is_verified?: boolean | null | undefined;
         is_pinned?: boolean | null | undefined;
+        is_favorited?: boolean | null | undefined;
+        _time_text?: string | null | undefined;
     }[] | null | undefined;
 }, {
+    comment_count?: number | null | undefined;
     comments?: {
+        id?: string | null | undefined;
         author?: string | null | undefined;
         text?: string | null | undefined;
+        timestamp?: number | null | undefined;
         parent?: string | null | undefined;
         like_count?: number | null | undefined;
+        author_id?: string | null | undefined;
+        author_url?: string | null | undefined;
+        author_thumbnail?: string | null | undefined;
+        author_is_uploader?: boolean | null | undefined;
+        author_is_verified?: boolean | null | undefined;
         is_pinned?: boolean | null | undefined;
+        is_favorited?: boolean | null | undefined;
+        _time_text?: string | null | undefined;
     }[] | null | undefined;
 }>;
 export declare const formatRowSchema: z.ZodObject<{
@@ -340,24 +438,30 @@ export declare const channelMetaSchema: z.ZodObject<{
     channel_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     uploader_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     channel_follower_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    channel_is_verified: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    tags: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
     description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     /** Checked by `selectChannelImages`, which tolerates any shape. */
     thumbnails: z.ZodUnknown;
 }, "strip", z.ZodTypeAny, {
     channel?: string | null | undefined;
     description?: string | null | undefined;
+    tags?: string[] | null | undefined;
     channel_id?: string | null | undefined;
     channel_url?: string | null | undefined;
     uploader_id?: string | null | undefined;
     channel_follower_count?: number | null | undefined;
+    channel_is_verified?: boolean | null | undefined;
     thumbnails?: unknown;
 }, {
     channel?: string | null | undefined;
     description?: string | null | undefined;
+    tags?: string[] | null | undefined;
     channel_id?: string | null | undefined;
     channel_url?: string | null | undefined;
     uploader_id?: string | null | undefined;
     channel_follower_count?: number | null | undefined;
+    channel_is_verified?: boolean | null | undefined;
     thumbnails?: unknown;
 }>;
 export declare const playlistMetaSchema: z.ZodObject<{

package/dist/utils/youtube-schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"youtube-schemas.d.ts","sourceRoot":"","sources":["../../src/utils/youtube-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AAEH,2FAA2F;AAC3F,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgB7B,CAAC;AAEH,wFAAwF;AACxF,eAAO,MAAM,kBAAkB;;;;;;;;;EAG7B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;EAI3B,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAIhC,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;EAM3B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE5B,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY1B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE3B,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;EAG9B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAO7B,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;EASjC,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;IAO5B,mEAAmE;;;;;;;;;;;;;;;;;;EAEnE,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAU7B,CAAC"}
+{"version":3,"file":"youtube-schemas.d.ts","sourceRoot":"","sources":["../../src/utils/youtube-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AAEH,2FAA2F;AAC3F,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgB7B,CAAC;AAEH,wFAAwF;AACxF,eAAO,MAAM,kBAAkB;;;;;;;;;EAG7B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;EAI3B,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;IAIhC;;;;OAIG;;;;;;;;;;;;;;;;;;;;EAEH,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;IAc3B,mEAAmE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEnE,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;QAJ5B,mEAAmE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAMnE;;;;;OAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEH,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY1B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE3B,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;EAG9B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAO7B,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;EASjC,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;IAS5B,mEAAmE;;;;;;;;;;;;;;;;;;;;;;EAEnE,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAU7B,CAAC"}

package/dist/utils/youtube-schemas.js

@@ -40,16 +40,46 @@ export const videoDetailsRowSchema = z.object({
     chapters: z.array(chapterRowSchema).nullish(),
     upload_date: z.string().nullish(),
     duration: z.number().nullish(),
+    /**
+     * The video's real comment count — trustworthy ONLY here, because this read
+     * does not pass --write-comments. With that flag yt-dlp replaces the value
+     * with the number it extracted (measured: 300 against a video with 2.4M).
+     */
+    comment_count: z.number().nullish(),
 });
+/**
+ * Every field yt-dlp returns for a comment, verified against 2026.08.19.
+ *
+ * Nine of these were previously dropped on the floor after being paid for:
+ * the extraction fetches them either way, so discarding `id` and `parent`
+ * meant a thread could not be rebuilt from what we already had.
+ */
 export const commentRowSchema = z.object({
+    id: z.string().nullish(),
     author: z.string().nullish(),
+    author_id: z.string().nullish(),
+    author_url: z.string().nullish(),
+    author_thumbnail: z.string().nullish(),
+    author_is_uploader: z.boolean().nullish(),
+    author_is_verified: z.boolean().nullish(),
     text: z.string().nullish(),
     like_count: z.number().nullish(),
     is_pinned: z.boolean().nullish(),
+    is_favorited: z.boolean().nullish(),
+    timestamp: z.number().nullish(),
+    _time_text: z.string().nullish(),
+    /** 'root' for a top-level comment; the parent's id for a reply. */
     parent: z.string().nullish(),
 });
 export const commentsRowSchema = z.object({
     comments: z.array(commentRowSchema).nullish(),
+    /**
+     * With --write-comments yt-dlp OVERWRITES this with the number extracted,
+     * and sets it to null when the extraction was interrupted. So it is a
+     * three-state signal about this run, never the video's real total, which
+     * only a separate metadata pass can report.
+     */
+    comment_count: z.number().nullish(),
 });
 export const formatRowSchema = z.object({
     format_id: z.string(),
@@ -100,6 +130,8 @@ export const channelMetaSchema = z.object({
     channel_url: z.string().nullish(),
     uploader_id: z.string().nullish(),
     channel_follower_count: z.number().nullish(),
+    channel_is_verified: z.boolean().nullish(),
+    tags: z.array(z.string()).nullish(),
     description: z.string().nullish(),
     /** Checked by `selectChannelImages`, which tolerates any shape. */
     thumbnails: z.unknown(),

package/dist/utils/youtube-schemas.js.map

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

package/dist/utils/youtube-video.d.ts

@@ -1,3 +1,4 @@
+import { type ThreadedComments } from './comment-threads.js';
 /** Everything read about one video: metadata, chapters and comments. */
 export interface VideoInfo {
     id: string;
@@ -41,7 +42,27 @@ export interface VideoDetails {
     uploadDate: string;
     durationSeconds: number;
     chapters: Chapter[];
+    /** YouTube's own count, from a read without --write-comments. Approximate and lagging. */
+    commentCount?: number;
 }
 export declare function getVideoDetails(urlOrId: string): Promise<VideoDetails>;
-export declare function getComments(urlOrId: string, limit?: number): Promise<VideoComment[]>;
+export interface CommentsResult extends ThreadedComments {
+    /**
+     * Whether yt-dlp's own iteration finished rather than being cut off.
+     *
+     * From common.py:3882-3908: `comment_count` is overwritten with the number
+     * extracted, and set to null when the walk was interrupted. Necessary for
+     * completeness but NOT sufficient — `itertools.islice` also ends iteration
+     * at a cap, so a capped run reports that it finished too.
+     */
+    ranToExhaustion: boolean;
+    /** True when the video has comments turned off, where zero is the real total. */
+    commentsDisabled: boolean;
+    extractedTotal: number;
+}
+export declare function getComments(urlOrId: string, options?: {
+    limit?: number;
+    sort?: 'top' | 'new';
+    maxRepliesPerThread?: number;
+}): Promise<CommentsResult>;
 //# sourceMappingURL=youtube-video.d.ts.map

package/dist/utils/youtube-video.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"youtube-video.d.ts","sourceRoot":"","sources":["../../src/utils/youtube-video.ts"],"names":[],"mappings":"AAMA,wEAAwE;AAExE,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAKD,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAoDtE;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAErE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAqB5E;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA2BtF"}
+{"version":3,"file":"youtube-video.d.ts","sourceRoot":"","sources":["../../src/utils/youtube-video.ts"],"names":[],"mappings":"AAKA,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGxE,wEAAwE;AAExE,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAKD,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAoDtE;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAErE;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,0FAA0F;IAC1F,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAkB5E;AAED,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD;;;;;;;OAOG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB,iFAAiF;IACjF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAO,GACnF,OAAO,CAAC,cAAc,CAAC,CAgCzB"}

package/dist/utils/youtube-video.js

@@ -1,8 +1,10 @@
 import { formatYouTubeDate } from './format.js';
 import { classifyPlayability } from './errors.js';
 import { TIMEOUTS, parseYtDlpJson, runYtDlp } from './ytdlp.js';
-import { commentsRowSchema, videoDetailsRowSchema, videoInfoRowSchema } from './youtube-schemas.js';
+import { commentsRowSchema, videoInfoRowSchema } from './youtube-schemas.js';
 import { extractVideoId, formatDuration, watchUrl } from './youtube-url.js';
+import { toThreads } from './comment-threads.js';
+import { readVideoStats } from './video-stats-cache.js';
 const VIDEO_INFO_TEMPLATE = '%(.{id,title,channel,duration,upload_date,description,tags,thumbnail,view_count,like_count,comment_count,availability,live_status})j';
 export async function getVideoInfo(urlOrId) {
     const videoId = extractVideoId(urlOrId);
@@ -54,26 +56,26 @@ export async function getChapters(urlOrId) {
     return (await getVideoDetails(urlOrId)).chapters;
 }
 export async function getVideoDetails(urlOrId) {
-    const videoId = extractVideoId(urlOrId);
-    const url = watchUrl(videoId);
-    const stdout = await runYtDlp(['-j', '--skip-download'], {
-        label: 'get_video_details',
-        target: url,
-    });
-    const data = parseYtDlpJson(stdout, videoDetailsRowSchema, 'video details');
+    // A projection of the one full read, not a second spawn. This used to run
+    // its own `-j` and discard everything but three fields, so a caller wanting
+    // a title and a chapter list paid for two extractions of the same video.
+    const { stats } = await readVideoStats(urlOrId);
     return {
-        uploadDate: formatYouTubeDate(data.upload_date ?? ''),
-        durationSeconds: typeof data.duration === 'number' ? data.duration : 0,
-        chapters: (data.chapters ?? []).map((ch) => ({
-            title: ch.title,
-            startTime: ch.start_time,
-            startTimeFormatted: formatDuration(Math.floor(ch.start_time)),
-            endTime: ch.end_time,
-            endTimeFormatted: formatDuration(Math.floor(ch.end_time)),
+        uploadDate: stats.uploadDate,
+        durationSeconds: stats.durationSeconds,
+        chapters: stats.chapters.map((chapter) => ({
+            title: chapter.title,
+            startTime: chapter.startTime,
+            startTimeFormatted: formatDuration(Math.floor(chapter.startTime)),
+            endTime: chapter.endTime,
+            endTimeFormatted: formatDuration(Math.floor(chapter.endTime)),
         })),
+        ...(stats.commentCount === undefined ? {} : { commentCount: stats.commentCount }),
     };
 }
-export async function getComments(urlOrId, limit = 20) {
+export async function getComments(urlOrId, options = {}) {
+    const limit = options.limit ?? 20;
+    const sort = options.sort ?? 'top';
     const videoId = extractVideoId(urlOrId);
     const url = watchUrl(videoId);
     const stdout = await runYtDlp([
@@ -81,18 +83,28 @@ export async function getComments(urlOrId, limit = 20) {
         '--skip-download',
         '--write-comments',
         '--extractor-args',
-        `youtube:comment_sort=top;max_comments=${limit}`,
+        // Five positions, per _video.py:2578: total, parents, replies, per
+        // thread, depth. An omitted position means unbounded, not a default, so
+        // every one is stated. Depth is 2 because YouTube's tree is two levels
+        // and a deeper cap would spend requests on nothing.
+        youtubeCommentArgs({ limit, sort, maxRepliesPerThread: options.maxRepliesPerThread ?? 100 }),
     ], { label: 'get_comments', timeoutMs: TIMEOUTS.comments, target: url });
     const data = parseYtDlpJson(stdout, commentsRowSchema, 'video comments');
-    const comments = data.comments ?? [];
-    return comments
-        .filter((c) => c.parent === 'root')
-        .slice(0, limit)
-        .map((c) => ({
-        author: c.author ?? 'Unknown',
-        text: c.text ?? '',
-        likeCount: c.like_count ?? 0,
-        isPinned: c.is_pinned ?? false,
-    }));
+    const rows = data.comments ?? [];
+    return {
+        ...toThreads(rows),
+        ranToExhaustion: data.comment_count !== null && data.comment_count !== undefined,
+        commentsDisabled: (data.comments === null || data.comments === undefined) &&
+            (data.comment_count === null || data.comment_count === undefined),
+        extractedTotal: rows.length,
+    };
+}
+function youtubeCommentArgs(options) {
+    const parents = Math.max(1, Math.ceil(options.limit / 2));
+    const replies = Math.max(0, options.limit - parents);
+    return [
+        `youtube:comment_sort=${options.sort}`,
+        `max_comments=${String(options.limit)},${String(parents)},${String(replies)},${String(options.maxRepliesPerThread)},2`,
+    ].join(';');
 }
 //# sourceMappingURL=youtube-video.js.map

package/dist/utils/youtube-video.js.map

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

package/dist/utils/ytdlp-limiter.d.ts

@@ -19,6 +19,9 @@ export declare function releaseSlot(): void;
 export declare function concurrencyState(): {
     active: number;
     queued: number;
+    /** The level in force now, which throttling can lower. */
     limit: number;
+    /** The configured maximum the level never exceeds. */
+    ceiling: number;
 };
 //# sourceMappingURL=ytdlp-limiter.d.ts.map

package/dist/utils/ytdlp-limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ytdlp-limiter.d.ts","sourceRoot":"","sources":["../../src/utils/ytdlp-limiter.ts"],"names":[],"mappings":"AAqBA;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAOlC;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAEpF"}
+{"version":3,"file":"ytdlp-limiter.d.ts","sourceRoot":"","sources":["../../src/utils/ytdlp-limiter.ts"],"names":[],"mappings":"AAiCA;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAOlC;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,IAAI;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB,CAOA"}

package/dist/utils/ytdlp-limiter.js

@@ -1,13 +1,24 @@
 import { envInt } from './env.js';
 import { YouTubeError } from './errors.js';
+import { effectiveConcurrency } from './ytdlp-pacer.js';
 /**
  * The concurrency limiter every yt-dlp spawn passes through.
  *
  * A cap so batch operations do not look like a scraper to YouTube, with a queue
  * that honours cancellation so an abandoned request never holds a place in it.
  */
-/** A limit of 0 (or NaN) would queue every call forever, so the floor is 1. */
+/**
+ * The ceiling this server will never exceed.
+ *
+ * A limit of 0 (or NaN) would queue every call forever, so the floor is 1.
+ * Under throttling the pacer lowers the level below this; the setting is the
+ * maximum, not the level.
+ */
 const MAX_CONCURRENT = envInt('YOUTUBE_MCP_MAX_CONCURRENCY', 3, { min: 1, max: 32 });
+/** The level in force right now: the configured ceiling, or less if throttled. */
+function currentLimit() {
+    return Math.max(1, Math.min(MAX_CONCURRENT, effectiveConcurrency()));
+}
 let active = 0;
 const waiting = [];
 /**
@@ -23,7 +34,7 @@ export async function acquireSlot(signal) {
     // No already-aborted check here: `runYtDlp` makes it before every attempt and
     // nothing awaits in between, so a second one could never fire — an
     // unreachable guard that reads like a reachable one.
-    if (active < MAX_CONCURRENT) {
+    if (active < currentLimit()) {
         active++;
         return;
     }
@@ -64,6 +75,11 @@ export function releaseSlot() {
 }
 /** Test seam: lets the suite assert the limiter without spawning processes. */
 export function concurrencyState() {
-    return { active, queued: waiting.length, limit: MAX_CONCURRENT };
+    return {
+        active,
+        queued: waiting.length,
+        limit: currentLimit(),
+        ceiling: MAX_CONCURRENT,
+    };
 }
 //# sourceMappingURL=ytdlp-limiter.js.map

package/dist/utils/ytdlp-limiter.js.map

@@ -1 +1 @@
-{"version":3,"file":"ytdlp-limiter.js","sourceRoot":"","sources":["../../src/utils/ytdlp-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;GAKG;AAEH,+EAA+E;AAC/E,MAAM,cAAc,GAAG,MAAM,CAAC,6BAA6B,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;AAOrF,IAAI,MAAM,GAAG,CAAC,CAAC;AACf,MAAM,OAAO,GAAa,EAAE,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAA+B;IAC/D,8EAA8E;IAC9E,mEAAmE;IACnE,qDAAqD;IACrD,IAAI,MAAM,GAAG,cAAc,EAAE,CAAC;QAC5B,MAAM,EAAE,CAAC;QACT,OAAO;IACT,CAAC;IAED,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,MAAM,GAAW;YACrB,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC9C,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;gBAChB,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC9C,MAAM,CAAC,KAAK,CAAC,CAAC;YAChB,CAAC;SACF,CAAC;QAEF,SAAS,OAAO;YACd,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACtC,IAAI,KAAK,KAAK,CAAC,CAAC;gBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAC3C,MAAM,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,WAAW,EAAE,4BAA4B,CAAC,CAAC,CAAC;QAC7E,CAAC;QAED,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAC7B,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO;IACT,CAAC;IACD,MAAM,EAAE,CAAC;AACX,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB;IAC9B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC;AACnE,CAAC"}
+{"version":3,"file":"ytdlp-limiter.js","sourceRoot":"","sources":["../../src/utils/ytdlp-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,cAAc,GAAG,MAAM,CAAC,6BAA6B,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;AAErF,kFAAkF;AAClF,SAAS,YAAY;IACnB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,oBAAoB,EAAE,CAAC,CAAC,CAAC;AACvE,CAAC;AAOD,IAAI,MAAM,GAAG,CAAC,CAAC;AACf,MAAM,OAAO,GAAa,EAAE,CAAC;AAE7B;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAA+B;IAC/D,8EAA8E;IAC9E,mEAAmE;IACnE,qDAAqD;IACrD,IAAI,MAAM,GAAG,YAAY,EAAE,EAAE,CAAC;QAC5B,MAAM,EAAE,CAAC;QACT,OAAO;IACT,CAAC;IAED,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,MAAM,GAAW;YACrB,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC9C,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;gBAChB,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;gBAC9C,MAAM,CAAC,KAAK,CAAC,CAAC;YAChB,CAAC;SACF,CAAC;QAEF,SAAS,OAAO;YACd,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACtC,IAAI,KAAK,KAAK,CAAC,CAAC;gBAAE,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAC3C,MAAM,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,WAAW,EAAE,4BAA4B,CAAC,CAAC,CAAC;QAC7E,CAAC;QAED,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAC7B,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO;IACT,CAAC;IACD,MAAM,EAAE,CAAC;AACX,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB;IAQ9B,OAAO;QACL,MAAM;QACN,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,KAAK,EAAE,YAAY,EAAE;QACrB,OAAO,EAAE,cAAc;KACxB,CAAC;AACJ,CAAC"}

package/dist/utils/ytdlp-pacer.d.ts

@@ -0,0 +1,64 @@
+import type { YouTubeErrorCode } from './errors.js';
+/**
+ * How this server reacts to being throttled.
+ *
+ * The old behaviour was three attempts with at most ~1.5 seconds of jitter and
+ * no memory between calls, which is fine for a blip and useless for an
+ * hour-long harvest: nothing slowed down, nothing waited, and a hard block
+ * produced an hour of identical failures.
+ *
+ * This adds three things that only make sense across calls — a shared
+ * cooldown, an adaptive concurrency ceiling, and a circuit breaker — so the
+ * state is deliberately process-global, the same scope as the limiter it
+ * cooperates with.
+ */
+export declare const RATE_LIMIT_COOLDOWN_BASE_MS = 30000;
+export declare const RATE_LIMIT_COOLDOWN_MAX_MS: number;
+export declare const BOT_CHECK_COOLDOWN_MS: number;
+export declare const MAX_BACKOFF_MS = 120000;
+export declare const BASE_BACKOFF_MS = 750;
+export declare const AIMD_MIN_CONCURRENCY = 1;
+export declare const AIMD_INCREASE_AFTER_SUCCESSES = 20;
+export declare const AIMD_DECREASE_FACTOR = 0.5;
+/** Consecutive throttles before a global cooldown starts. */
+export declare const COOLDOWN_AFTER_STRIKES = 2;
+export declare const CIRCUIT_STRIKES = 5;
+export declare const CIRCUIT_OPEN_MS: number;
+interface RetryPolicy {
+    /** Total spawns, including the first. */
+    attempts: number;
+    backoff: 'none' | 'exponential';
+    cooldown: 'none' | 'rate-limit' | 'bot-check';
+    concurrency: 'none' | 'decrease' | 'floor';
+}
+export declare function policyFor(code: YouTubeErrorCode): RetryPolicy;
+export declare function backoffDelay(attempt: number, style: RetryPolicy['backoff']): number;
+export interface PacerDecision {
+    giveUp: boolean;
+    delayMs: number;
+}
+/** Records a failure and says whether to try again, and after how long. */
+export declare function onFailure(code: YouTubeErrorCode, attempt: number, now?: number): PacerDecision;
+/** Records a clean spawn, easing the ceiling back up one step at a time. */
+export declare function onSuccess(): void;
+/** How long a caller should wait before spawning, in milliseconds. */
+export declare function waitMs(now?: number): number;
+export declare function circuitOpen(now?: number): boolean;
+/**
+ * The ceiling the limiter should honour right now.
+ *
+ * Infinite until something throttles us, so an untroubled server runs at
+ * whatever YOUTUBE_MCP_MAX_CONCURRENCY allows and the limiter stays the only
+ * authority on the normal case.
+ */
+export declare function effectiveConcurrency(now?: number): number;
+export declare function pacerState(now?: number): {
+    cooldownMs: number;
+    circuitOpen: boolean;
+    strikes: number;
+    concurrency: number;
+};
+/** Test seam; the pacer is process-global in normal use. */
+export declare function resetPacer(): void;
+export {};
+//# sourceMappingURL=ytdlp-pacer.d.ts.map

package/dist/utils/ytdlp-pacer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ytdlp-pacer.d.ts","sourceRoot":"","sources":["../../src/utils/ytdlp-pacer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAClD,eAAO,MAAM,0BAA0B,QAAc,CAAC;AACtD,eAAO,MAAM,qBAAqB,QAAc,CAAC;AACjD,eAAO,MAAM,cAAc,SAAU,CAAC;AACtC,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAChD,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,6DAA6D;AAC7D,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,eAAe,QAAa,CAAC;AAE1C,UAAU,WAAW;IACnB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,aAAa,CAAC;IAChC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,WAAW,CAAC;IAC9C,WAAW,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;CAC5C;AAkCD,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,WAAW,CAE7D;AA+BD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,SAAS,CAAC,GAAG,MAAM,CAMnF;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,2EAA2E;AAC3E,wBAAgB,SAAS,CACvB,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,GAAG,SAAa,GACf,aAAa,CAuCf;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,IAAI,IAAI,CAQhC;AAED,sEAAsE;AACtE,wBAAgB,MAAM,CAAC,GAAG,SAAa,GAAG,MAAM,CAG/C;AAED,wBAAgB,WAAW,CAAC,GAAG,SAAa,GAAG,OAAO,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,SAAa,GAAG,MAAM,CAG7D;AAED,wBAAgB,UAAU,CAAC,GAAG,SAAa,GAAG;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB,CAOA;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,IAAI,IAAI,CAQjC"}