grok-digest 0.3.0 → 0.3.2

package/BOT.md

@@ -54,17 +54,24 @@ bun run validate
   "shelf_life": "evergreen",
   "tldr": "Stale workaround comments spread because coding agents copy them",
   "summary": "Argues you should delete most code comments, because coding agents copy existing workaround comments and spread hacks through the codebase.",
-  "text": "ban and delete most if not all code comments!\n\nagents love copying what already exists.",
+  "text": "ban and delete most if not all code comments!\n\nagents love copying what already exists. https://t.co/Xq7mPLe0Ab",
   "key_points": [
     "Agents imitate existing code, so stale workaround comments spread like weeds.",
     "Keep only comments that must exist, such as browser-quirk explanations."
   ],
   "action": "Have an agent run /no-comments on one repo and sort each comment into refactor or delete.",
-  "links": [{ "title": "pstack: the /no-comments skill", "url": "https://github.com/example/pstack" }]
+  "links": [{ "title": "pstack: the /no-comments skill", "url": "https://github.com/example/pstack" }],
+  "media": [
+    {
+      "url": "https://pbs.twimg.com/media/G3xAmPLeAAAbCdE.jpg",
+      "alt": "A diff that deletes a workaround comment",
+      "link": "https://t.co/Xq7mPLe0Ab"
+    }
+  ]
 }
 ```
 
-Write every field, in this order. The build rejects an entry with a missing field or a field not listed here. `text` and `action` may be empty strings, and `key_points` and `links` may be empty arrays.
+Write every field, in this order. The build rejects an entry with a missing field or a field not listed here. `text` and `action` may be empty strings, and `key_points`, `links`, and `media` may be empty arrays. Entries saved before `media` existed have no `media` field; that is valid, and you don't need to add one.
 
 ### id
 
@@ -125,7 +132,7 @@ One or two sentences on what the post says and why it matters. For a thread, sum
 
 ### text
 
-The post's own words, copied exactly as posted, with its line breaks. For a thread, the author's posts in order, separated by a blank line. Write `""` when the post has no text.
+The post's own words, copied exactly as posted, with its line breaks. For a thread, the author's posts in order, separated by a blank line. Keep a `t.co` line that stands for an image or video as it is; the image itself goes in `media`. Write `""` when the post has no text.
 
 Keep it complete. Most AI assistants can't open x.com, so when the owner copies a bookmark into one, this text is all it gets of the post.
 
@@ -151,6 +158,19 @@ Every link in the post and its thread, followed to where it really lands. Expand
 - Leave out links to the post itself, to the author's profile, and to the post's images or videos.
 - Write `[]` when there are none.
 
+### media
+
+The images in the post and its thread, in thread order, so the card can show each one with the post it came from. One object per photo:
+
+- `url`: the image's `https://pbs.twimg.com/` address, such as `https://pbs.twimg.com/media/G3xAmPLeAAAbCdE.jpg`. A `?format=jpg&name=large` query is fine. Never a `t.co` link or an `x.com/…/photo/1` page; the build rejects any other host.
+- `alt`: the author's alt text for the image when it has one, otherwise a few words on what it shows. Leave `alt` out rather than writing `""`.
+- `link`: the short link that stands for the image in `text`, copied exactly as it appears there, such as `https://t.co/Xq7mPLe0Ab` or `pic.x.com/Xq7mPLe0Ab`. X gives all the photos of one post a single link, so photos from the same post share it. The card shows the images where that link is and hides the link. The build rejects a `link` that is not in `text`. Leave `link` out only when `text` has no link for the image; the card then shows it after the post.
+- For a video or GIF, add its poster image (the `pbs.twimg.com` thumbnail X shows before it plays) when you can find it. Skip it otherwise.
+- Don't add link-preview cards or the author's profile picture.
+- Write `[]` when the post has no images.
+
+Images never go in `links`, and `text` keeps the post's exact words, including any `t.co` lines that stood for the images.
+
 ## Change or remove a bookmark
 
 To change one, edit its fields in place. Keep `id` and `saved_at`. Commit with `Update bookmark (@handle)`.

package/README.md

@@ -63,7 +63,7 @@ The site needs no Astro config. The package depends on the Astro version it was
 import { SCHEMA_VERSION, bookmarkSchema, parseBookmarks, TOPICS } from "grok-digest/schema";
 ```
 
-`SCHEMA_VERSION` is `1`. The JSON files have no version field. A `bookmarks.json` that already validates is version 1. `posted_at` with milliseconds and a `Z` offset, as the bot writes it, is version 1.
+`SCHEMA_VERSION` is `1`. The JSON files have no version field. A `bookmarks.json` that already validates is version 1. `posted_at` with milliseconds and a `Z` offset, as the bot writes it, is version 1. The optional `media` field, a post's images, is part of version 1 too: a bookmark without it parses with `media` set to `[]`.
 
 | File                  | Version 1 shape                                                      |
 | --------------------- | -------------------------------------------------------------------- |

package/dist/components/BookmarkCard.astro

@@ -5,6 +5,7 @@ import { Button } from "./ui/button";
 import { Card } from "./ui/card";
 import type { Bookmark } from "../lib/bookmarks";
 import { copyText } from "../lib/copy";
+import { postParts } from "../lib/media";
 import { TOPIC_LABELS } from "../lib/topics";
 
 type Props = {
@@ -12,13 +13,13 @@ type Props = {
 };
 
 const { bookmark } = Astro.props;
-const { id, url, author, postedAt, savedAt, topic, shelfLife, tldr, summary, text, keyPoints, action, links } =
-  bookmark;
+const { id, url, author, postedAt, savedAt, topic, shelfLife, tldr, summary, keyPoints, action, links } = bookmark;
 
 const dateFormat = new Intl.DateTimeFormat("en", { dateStyle: "medium", timeZone: "UTC" });
 const isoDay = (date: Date) => date.toISOString().slice(0, 10);
 const postedOtherDay = isoDay(postedAt) !== isoDay(savedAt);
 const hostOf = (link: string) => new URL(link).hostname.replace(/^www\./, "");
+const post = postParts(bookmark);
 ---
 
 <li id={`b-${id}`} data-bookmark-id={id} data-url={url} data-topic={topic} class="group/bookmark scroll-mt-6">
@@ -88,11 +89,43 @@ const hostOf = (link: string) => new URL(link).hostname.replace(/^www\./, "");
             ))}
           </ul>
         )}
-        {text !== "" && (
+        {post.length > 0 && (
           <figure class="border-t border-border pt-4">
             <figcaption class="mb-2 text-xs font-medium text-muted-foreground">Original post</figcaption>
-            <blockquote class="text-sm leading-relaxed whitespace-pre-wrap text-pretty text-foreground/80">
-              {text}
+            <blockquote class="flex flex-col gap-3 text-sm leading-relaxed text-pretty text-foreground/80">
+              {post.map((part) =>
+                part.kind === "text" ? (
+                  <p class="whitespace-pre-wrap">{part.text}</p>
+                ) : (
+                  <ul
+                    class:list={["grid max-w-md gap-2", { "grid-cols-2": part.images.length > 1 }]}
+                    aria-label="Images in the post"
+                  >
+                    {part.images.map((image, index) => (
+                      <li
+                        class:list={{
+                          "col-span-2": index === 0 && part.images.length > 1 && part.images.length % 2 === 1,
+                        }}
+                      >
+                        <a
+                          href={image.url}
+                          target="_blank"
+                          rel="noopener noreferrer"
+                          class="block overflow-hidden rounded-lg border border-border bg-muted focus-visible:ring-3 focus-visible:ring-ring/50 focus-visible:outline-none"
+                        >
+                          <img
+                            src={image.url}
+                            alt={image.alt}
+                            loading="lazy"
+                            decoding="async"
+                            class="aspect-video w-full object-cover"
+                          />
+                        </a>
+                      </li>
+                    ))}
+                  </ul>
+                ),
+              )}
             </blockquote>
           </figure>
         )}

package/dist/lib/bookmarks.d.ts

@@ -31,6 +31,11 @@ export declare const bookmarkSchema: z.ZodPipe<z.ZodObject<{
         title: z.ZodString;
         url: z.ZodURL;
     }, z.core.$strict>>;
+    media: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        url: z.ZodURL;
+        alt: z.ZodOptional<z.ZodString>;
+        link: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>, z.ZodTransform<{
     shelfLife: "news" | "evergreen";
     postedAt: Date;
@@ -51,6 +56,11 @@ export declare const bookmarkSchema: z.ZodPipe<z.ZodObject<{
         title: string;
         url: string;
     }[];
+    media: {
+        url: string;
+        alt?: string | undefined;
+        link?: string | undefined;
+    }[];
 }, {
     id: string;
     url: string;
@@ -71,6 +81,11 @@ export declare const bookmarkSchema: z.ZodPipe<z.ZodObject<{
         title: string;
         url: string;
     }[];
+    media: {
+        url: string;
+        alt?: string | undefined;
+        link?: string | undefined;
+    }[];
 }>>;
 export declare const bookmarksFileSchema: z.ZodArray<z.ZodPipe<z.ZodObject<{
     id: z.ZodString;
@@ -103,6 +118,11 @@ export declare const bookmarksFileSchema: z.ZodArray<z.ZodPipe<z.ZodObject<{
         title: z.ZodString;
         url: z.ZodURL;
     }, z.core.$strict>>;
+    media: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        url: z.ZodURL;
+        alt: z.ZodOptional<z.ZodString>;
+        link: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>, z.ZodTransform<{
     shelfLife: "news" | "evergreen";
     postedAt: Date;
@@ -123,6 +143,11 @@ export declare const bookmarksFileSchema: z.ZodArray<z.ZodPipe<z.ZodObject<{
         title: string;
         url: string;
     }[];
+    media: {
+        url: string;
+        alt?: string | undefined;
+        link?: string | undefined;
+    }[];
 }, {
     id: string;
     url: string;
@@ -143,6 +168,11 @@ export declare const bookmarksFileSchema: z.ZodArray<z.ZodPipe<z.ZodObject<{
         title: string;
         url: string;
     }[];
+    media: {
+        url: string;
+        alt?: string | undefined;
+        link?: string | undefined;
+    }[];
 }>>>;
 export declare const stateFileSchema: z.ZodArray<z.ZodString>;
 export type BookmarkFileEntry = z.input<typeof bookmarkSchema>;

package/dist/lib/bookmarks.js

@@ -3,6 +3,7 @@ import { TOPICS } from "./topics.js";
 export const SCHEMA_VERSION = 1;
 const X_HOSTNAME = /^(www\.|mobile\.)?(x|twitter)\.com$/;
 const X_HANDLE = /^[A-Za-z0-9_]{1,15}$/;
+const X_MEDIA_HOSTNAME = /^pbs\.twimg\.com$/;
 const nonEmpty = z.string().trim().min(1);
 const instant = z.iso.datetime({ offset: true });
 const SHELF_LIVES = ["news", "evergreen"];
@@ -28,6 +29,20 @@ export const bookmarkSchema = z
     key_points: z.array(nonEmpty),
     action: z.string().trim(),
     links: z.array(z.strictObject({ title: nonEmpty, url: z.url({ protocol: /^https$/ }) })),
+    media: z
+        .array(z.strictObject({
+        url: z.url({ protocol: /^https$/, hostname: X_MEDIA_HOSTNAME }),
+        alt: nonEmpty.optional(),
+        link: nonEmpty.optional(),
+    }))
+        .default([]),
+})
+    .superRefine(({ text, media }, ctx) => {
+    media.forEach(({ link }, index) => {
+        if (link !== undefined && !text.includes(link)) {
+            ctx.addIssue({ code: "custom", path: ["media", index, "link"], message: `"${link}" is not in text` });
+        }
+    });
 })
     .transform(({ posted_at, saved_at, shelf_life, key_points, ...rest }) => ({
     ...rest,

package/dist/lib/copy.d.ts

@@ -1,2 +1,2 @@
 import type { Bookmark } from "./bookmarks.ts";
-export declare function copyText({ url, author, postedAt, tldr, summary, text, keyPoints, action, links }: Bookmark): string;
+export declare function copyText({ url, author, postedAt, tldr, summary, text, media, keyPoints, action, links, }: Bookmark): string;

package/dist/lib/copy.js

@@ -8,11 +8,12 @@ function quote(text) {
 function list(heading, items) {
     return items.length === 0 ? "" : [`${heading}:`, ...items.map((item) => `- ${item}`)].join("\n");
 }
-export function copyText({ url, author, postedAt, tldr, summary, text, keyPoints, action, links }) {
+export function copyText({ url, author, postedAt, tldr, summary, text, media, keyPoints, action, links, }) {
     return [
         "A post I saved from X:",
         `**${tldr}**\n${author.name} (@${author.handle}) · posted ${dateFormat.format(postedAt)} · ${url}`,
         text === "" ? "" : quote(text),
+        list("Images", media.map((image) => (image.alt === undefined ? image.url : `${image.alt}: ${image.url}`))),
         `Summary: ${summary}`,
         list("Key points", keyPoints),
         action === "" ? "" : `Try: ${action}`,

package/dist/lib/feed.js

@@ -1,4 +1,5 @@
 import { isTopic } from "./filter.js";
+import { postParts } from "./media.js";
 import { TOPIC_LABELS } from "./topics.js";
 const LOCAL_ORIGIN = "http://localhost:4321";
 export function feedOrigin(site) {
@@ -29,7 +30,11 @@ function feedItem(bookmark, page) {
     const link = new URL(page.href);
     link.hash = `b-${id}`;
     const points = keyPoints.map((point) => `<li>${escapeHtml(point)}</li>`).join("");
-    const quote = text === "" ? "" : `<blockquote><p>${escapeHtml(text)}</p></blockquote>`;
+    const quoted = postParts(bookmark)
+        .flatMap((part) => part.kind === "text"
+        ? [`<p>${escapeHtml(part.text)}</p>`]
+        : part.images.map((image) => `<p><img src="${escapeHtml(image.url)}" alt="${escapeHtml(image.alt)}"></p>`))
+        .join("");
     const linkItems = links
         .map((outbound) => `<li><a href="${escapeHtml(outbound.url)}">${escapeHtml(outbound.title)}</a></li>`)
         .join("");
@@ -43,7 +48,7 @@ function feedItem(bookmark, page) {
             action === "" ? "" : `<p>Try: ${escapeHtml(action)}</p>`,
             points === "" ? "" : `<ul>${points}</ul>`,
             linkItems === "" ? "" : `<ul>${linkItems}</ul>`,
-            quote,
+            quoted === "" ? "" : `<blockquote>${quoted}</blockquote>`,
             `<p><a href="${escapeHtml(url)}">Open on X</a></p>`,
         ]
             .filter((part) => part !== "")

package/dist/lib/load-bookmarks.d.ts

@@ -18,4 +18,9 @@ export declare const bookmarks: {
         title: string;
         url: string;
     }[];
+    media: {
+        url: string;
+        alt?: string | undefined;
+        link?: string | undefined;
+    }[];
 }[];

package/dist/lib/media.d.ts

@@ -0,0 +1,14 @@
+import type { Bookmark } from "./bookmarks.ts";
+type Image = {
+    url: string;
+    alt: string;
+};
+type PostPart = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "images";
+    images: Image[];
+};
+export declare function postParts({ author, text, media }: Bookmark): PostPart[];
+export {};

package/dist/lib/media.js

@@ -0,0 +1,22 @@
+export function postParts({ author, text, media }) {
+    const position = (index) => (media.length === 1 ? "" : ` ${index + 1} of ${media.length}`);
+    const images = media.map(({ url, alt, link }, index) => ({
+        url,
+        alt: alt ?? `Image${position(index)} from the post by @${author.handle}`,
+        link,
+    }));
+    const imagesFor = (link) => ({
+        kind: "images",
+        images: images.filter((image) => image.link === link).map(({ url, alt }) => ({ url, alt })),
+    });
+    const links = [...new Set(images.flatMap(({ link }) => (link === undefined ? [] : [link])))].toSorted((a, b) => text.indexOf(a) - text.indexOf(b));
+    const parts = [];
+    let rest = text;
+    for (const link of links) {
+        const at = rest.indexOf(link);
+        parts.push({ kind: "text", text: rest.slice(0, at).trim() }, imagesFor(link));
+        rest = rest.slice(at + link.length);
+    }
+    parts.push({ kind: "text", text: rest.trim() }, imagesFor(undefined));
+    return parts.filter((part) => (part.kind === "text" ? part.text !== "" : part.images.length > 0));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grok-digest",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Astro integration that renders a Grok Digest site: X bookmarks summarized by Grok, searchable, sorted by topic, with RSS feeds.",
   "keywords": [
     "astro",