@rmdes/indiekit-endpoint-activitypub 2.0.30 → 2.0.32

package/assets/reader-decks.js

@@ -0,0 +1,212 @@
+/**
+ * Deck components — Alpine.js components for the TweetDeck-style deck view.
+ *
+ * Registers:
+ *   apDeckToggle  — star/favorite button to add/remove a deck on the Search tab
+ *   apDeckColumn  — single deck column with its own infinite-scroll timeline
+ */
+
+document.addEventListener("alpine:init", () => {
+  // ── apDeckToggle ──────────────────────────────────────────────────────────
+  //
+  // Star/favorite button that adds or removes a deck entry for the current
+  // instance+scope combination.
+  //
+  // Parameters (passed via x-data):
+  //   domain       — instance hostname (e.g. "mastodon.social")
+  //   scope        — "local" | "federated"
+  //   mountPath    — plugin mount path for API URL construction
+  //   csrfToken    — CSRF token from server session
+  //   deckCount    — current number of saved decks (for limit enforcement)
+  //   initialState — true if this instance+scope is already a deck
+  // eslint-disable-next-line no-undef
+  Alpine.data("apDeckToggle", (domain, scope, mountPath, csrfToken, deckCount, initialState) => ({
+    inDeck: initialState,
+    currentCount: deckCount,
+    loading: false,
+
+    get deckLimitReached() {
+      return this.currentCount >= 8 && !this.inDeck;
+    },
+
+    async toggle() {
+      if (this.loading) return;
+      if (!this.inDeck && this.deckLimitReached) return;
+
+      this.loading = true;
+      try {
+        const url = this.inDeck
+          ? `${mountPath}/admin/reader/api/decks/remove`
+          : `${mountPath}/admin/reader/api/decks`;
+
+        const res = await fetch(url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-CSRF-Token": csrfToken,
+          },
+          body: JSON.stringify({ domain, scope }),
+        });
+
+        if (res.ok) {
+          this.inDeck = !this.inDeck;
+          // Track actual count so deckLimitReached stays accurate
+          this.currentCount += this.inDeck ? 1 : -1;
+        }
+      } catch {
+        // Network error — state unchanged, server is source of truth
+      } finally {
+        this.loading = false;
+      }
+    },
+  }));
+
+  // ── apDeckColumn ─────────────────────────────────────────────────────────
+  //
+  // Individual deck column component. Fetches timeline from the explore API
+  // and renders it in a scrollable column with infinite scroll.
+  //
+  // Uses its own IntersectionObserver referencing `this.$refs.sentinel`
+  // (NOT apExploreScroll which hardcodes document.getElementById).
+  //
+  // Parameters (passed via x-data):
+  //   domain    — instance hostname
+  //   scope     — "local" | "federated"
+  //   mountPath — plugin mount path
+  //   index     — column position (0-based), used for staggered loading delay
+  //   csrfToken — CSRF token for remove calls
+  // eslint-disable-next-line no-undef
+  Alpine.data("apDeckColumn", (domain, scope, mountPath, index, csrfToken) => ({
+    itemCount: 0,
+    html: "",
+    maxId: null,
+    loading: false,
+    done: false,
+    error: null,
+    observer: null,
+    abortController: null,
+
+    init() {
+      // Stagger initial fetch: column 0 loads immediately, column N waits N*200ms
+      const delay = index * 200;
+      if (delay === 0) {
+        this.loadMore();
+      } else {
+        setTimeout(() => {
+          this.loadMore();
+        }, delay);
+      }
+
+      // Set up IntersectionObserver scoped to this column's scrollable body
+      // (root must be the scroll container, not viewport, to avoid premature triggers)
+      this.$nextTick(() => {
+        const root = this.$refs.body || null;
+        this.observer = new IntersectionObserver(
+          (entries) => {
+            for (const entry of entries) {
+              if (entry.isIntersecting && !this.loading && !this.done && this.itemCount > 0) {
+                this.loadMore();
+              }
+            }
+          },
+          { root, rootMargin: "200px" },
+        );
+
+        if (this.$refs.sentinel) {
+          this.observer.observe(this.$refs.sentinel);
+        }
+      });
+    },
+
+    destroy() {
+      if (this.abortController) {
+        this.abortController.abort();
+        this.abortController = null;
+      }
+
+      if (this.observer) {
+        this.observer.disconnect();
+        this.observer = null;
+      }
+    },
+
+    async loadMore() {
+      if (this.loading || this.done) return;
+
+      this.loading = true;
+      this.error = null;
+
+      try {
+        this.abortController = new AbortController();
+
+        const url = new URL(`${mountPath}/admin/reader/api/explore`, window.location.origin);
+        url.searchParams.set("instance", domain);
+        url.searchParams.set("scope", scope);
+        if (this.maxId) url.searchParams.set("max_id", this.maxId);
+
+        const res = await fetch(url.toString(), {
+          headers: { Accept: "application/json" },
+          signal: this.abortController.signal,
+        });
+
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status}`);
+        }
+
+        const data = await res.json();
+
+        if (data.html && data.html.trim() !== "") {
+          this.html += data.html;
+          this.itemCount++;
+        }
+
+        if (data.maxId) {
+          this.maxId = data.maxId;
+        } else {
+          this.done = true;
+        }
+
+        // If no content came back on first load, mark as done
+        if (!data.html || data.html.trim() === "") {
+          this.done = true;
+        }
+      } catch (fetchError) {
+        this.error = fetchError.message || "Could not load timeline";
+      } finally {
+        this.loading = false;
+      }
+    },
+
+    async retryLoad() {
+      this.error = null;
+      this.done = false;
+      await this.loadMore();
+    },
+
+    async removeDeck() {
+      try {
+        const res = await fetch(`${mountPath}/admin/reader/api/decks/remove`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-CSRF-Token": csrfToken,
+          },
+          body: JSON.stringify({ domain, scope }),
+        });
+
+        if (res.ok) {
+          // Remove column from DOM
+          if (this.observer) {
+            this.observer.disconnect();
+          }
+
+          this.$el.remove();
+        } else {
+          this.error = `Failed to remove (${res.status})`;
+        }
+      } catch {
+        this.error = "Network error — could not remove column";
+      }
+    },
+  }));
+});

package/assets/reader.css

@@ -2022,3 +2022,190 @@
   color: var(--color-on-offset);
   font-weight: 600;
 }
+
+/* ---------- Explore: deck toggle button ---------- */
+
+.ap-explore-deck-toggle {
+  display: flex;
+  justify-content: flex-end;
+  margin-bottom: var(--space-s);
+}
+
+.ap-explore-deck-toggle__btn {
+  align-items: center;
+  background: none;
+  border: var(--border-width-thin) solid var(--color-outline);
+  border-radius: var(--border-radius-small);
+  color: var(--color-on-background);
+  cursor: pointer;
+  display: inline-flex;
+  font-size: var(--font-size-s);
+  gap: var(--space-2xs);
+  padding: var(--space-xs) var(--space-s);
+  transition: background 0.15s, color 0.15s, border-color 0.15s;
+}
+
+.ap-explore-deck-toggle__btn:hover:not(:disabled) {
+  background: var(--color-offset);
+}
+
+.ap-explore-deck-toggle__btn--active {
+  background: var(--color-accent5);
+  border-color: var(--color-accent5);
+  color: var(--color-on-accent, #fff);
+}
+
+.ap-explore-deck-toggle__btn--active:hover:not(:disabled) {
+  background: var(--color-accent45);
+  border-color: var(--color-accent45);
+}
+
+.ap-explore-deck-toggle__btn:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+/* ---------- Deck grid layout ---------- */
+
+.ap-deck-grid {
+  display: grid;
+  gap: var(--space-m);
+  grid-template-columns: repeat(auto-fill, minmax(360px, 1fr));
+  margin-top: var(--space-m);
+  min-width: 0;
+}
+
+/* ---------- Deck column ---------- */
+
+.ap-deck-column {
+  background: var(--color-offset);
+  border: var(--border-width-thin) solid var(--color-outline);
+  border-radius: var(--border-radius-small);
+  display: flex;
+  flex-direction: column;
+  max-height: calc(100dvh - 220px);
+  min-height: 200px;
+  min-width: 0;
+  overflow: hidden;
+}
+
+.ap-deck-column__header {
+  align-items: center;
+  background: var(--color-background);
+  border-bottom: var(--border-width-thin) solid var(--color-outline);
+  display: flex;
+  flex-shrink: 0;
+  gap: var(--space-xs);
+  padding: var(--space-xs) var(--space-s);
+}
+
+.ap-deck-column__domain {
+  font-size: var(--font-size-s);
+  font-weight: 600;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.ap-deck-column__scope-badge {
+  border-radius: var(--border-radius-small);
+  flex-shrink: 0;
+  font-size: var(--font-size-xs);
+  font-weight: 600;
+  padding: 2px var(--space-xs);
+  text-transform: uppercase;
+}
+
+.ap-deck-column__scope-badge--local {
+  background: var(--color-blue10, #dbeafe);
+  color: var(--color-blue50, #1e40af);
+}
+
+.ap-deck-column__scope-badge--federated {
+  background: var(--color-purple10, #ede9fe);
+  color: var(--color-purple50, #5b21b6);
+}
+
+.ap-deck-column__remove {
+  background: none;
+  border: none;
+  color: var(--color-on-offset);
+  cursor: pointer;
+  flex-shrink: 0;
+  font-size: 1.2rem;
+  line-height: 1;
+  margin-left: auto;
+  padding: 0 2px;
+}
+
+.ap-deck-column__remove:hover {
+  color: var(--color-red45);
+}
+
+.ap-deck-column__body {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding: var(--space-xs);
+}
+
+.ap-deck-column__loading,
+.ap-deck-column__loading-more,
+.ap-deck-column__error,
+.ap-deck-column__empty,
+.ap-deck-column__done {
+  color: var(--color-on-offset);
+  font-size: var(--font-size-s);
+  padding: var(--space-s);
+  text-align: center;
+}
+
+.ap-deck-column__retry {
+  background: none;
+  border: var(--border-width-thin) solid var(--color-outline);
+  border-radius: var(--border-radius-small);
+  color: var(--color-on-background);
+  cursor: pointer;
+  font-size: var(--font-size-s);
+  margin-top: var(--space-xs);
+  padding: var(--space-xs) var(--space-s);
+}
+
+.ap-deck-column__retry:hover {
+  background: var(--color-offset);
+}
+
+/* Cards inside deck columns are more compact */
+.ap-deck-column__items .ap-item-card {
+  font-size: var(--font-size-s);
+}
+
+/* ---------- Deck empty state ---------- */
+
+.ap-deck-empty {
+  margin-top: var(--space-xl);
+  text-align: center;
+}
+
+.ap-deck-empty p {
+  color: var(--color-on-offset);
+  font-size: var(--font-size-s);
+  margin-bottom: var(--space-s);
+}
+
+.ap-deck-empty__link {
+  font-size: var(--font-size-s);
+}
+
+/* ---------- Deck responsive ---------- */
+
+@media (max-width: 767px) {
+  .ap-deck-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .ap-deck-column {
+    max-height: 60vh;
+  }
+}

package/index.js

@@ -69,6 +69,11 @@ import {
   popularAccountsApiController,
 } from "./lib/controllers/explore.js";
 import { followTagController, unfollowTagController } from "./lib/controllers/follow-tag.js";
+import {
+  listDecksController,
+  addDeckController,
+  removeDeckController,
+} from "./lib/controllers/decks.js";
 import { publicProfileController } from "./lib/controllers/public-profile.js";
 import { authorizeInteractionController } from "./lib/controllers/authorize-interaction.js";
 import { myProfileController } from "./lib/controllers/my-profile.js";
@@ -236,6 +241,9 @@ export default class ActivityPubEndpoint {
     router.get("/admin/reader/api/instances", instanceSearchApiController(mp));
     router.get("/admin/reader/api/instance-check", instanceCheckApiController(mp));
     router.get("/admin/reader/api/popular-accounts", popularAccountsApiController(mp));
+    router.get("/admin/reader/api/decks", listDecksController(mp));
+    router.post("/admin/reader/api/decks", addDeckController(mp));
+    router.post("/admin/reader/api/decks/remove", removeDeckController(mp));
     router.post("/admin/reader/follow-tag", followTagController(mp));
     router.post("/admin/reader/unfollow-tag", unfollowTagController(mp));
     router.get("/admin/reader/notifications", notificationsController(mp));
@@ -876,6 +884,8 @@ export default class ActivityPubEndpoint {
     Indiekit.addCollection("ap_interactions");
     Indiekit.addCollection("ap_notes");
     Indiekit.addCollection("ap_followed_tags");
+    // Deck collections
+    Indiekit.addCollection("ap_decks");
 
     // Store collection references (posts resolved lazily)
     const indiekitCollections = Indiekit.collections;
@@ -896,6 +906,8 @@ export default class ActivityPubEndpoint {
       ap_interactions: indiekitCollections.get("ap_interactions"),
       ap_notes: indiekitCollections.get("ap_notes"),
       ap_followed_tags: indiekitCollections.get("ap_followed_tags"),
+      // Deck collections
+      ap_decks: indiekitCollections.get("ap_decks"),
       get posts() {
         return indiekitCollections.get("posts");
       },
@@ -1019,6 +1031,12 @@ export default class ActivityPubEndpoint {
         { category: 1, published: -1 },
         { background: true },
       );
+
+      // Deck index — compound unique ensures same instance can appear at most once per scope
+      this._collections.ap_decks.createIndex(
+        { domain: 1, scope: 1 },
+        { unique: true, background: true },
+      );
     } catch {
       // Index creation failed — collections not yet available.
       // Indexes already exist from previous startups; non-fatal.

package/lib/controllers/decks.js

@@ -0,0 +1,137 @@
+/**
+ * Deck CRUD controller — manages favorited instance deck entries.
+ * Stored in the ap_decks MongoDB collection.
+ */
+
+import { validateToken } from "../csrf.js";
+import { validateInstance } from "./explore.js";
+
+const MAX_DECKS = 8;
+
+/**
+ * GET /admin/reader/api/decks
+ * Returns all deck entries sorted by addedAt ascending.
+ */
+export function listDecksController(_mountPath) {
+  return async (request, response, next) => {
+    try {
+      const { application } = request.app.locals;
+      const collection = application?.collections?.get("ap_decks");
+      if (!collection) {
+        return response.json([]);
+      }
+
+      const decks = await collection
+        .find({}, { projection: { _id: 0 } })
+        .sort({ addedAt: 1 })
+        .toArray();
+
+      return response.json(decks);
+    } catch (error) {
+      return next(error);
+    }
+  };
+}
+
+/**
+ * POST /admin/reader/api/decks
+ * Adds a new deck entry for the given domain + scope.
+ * Body: { domain, scope }
+ */
+export function addDeckController(_mountPath) {
+  return async (request, response, next) => {
+    try {
+      // CSRF protection
+      if (!validateToken(request)) {
+        return response.status(403).json({ error: "Invalid CSRF token" });
+      }
+
+      const { application } = request.app.locals;
+      const collection = application?.collections?.get("ap_decks");
+      if (!collection) {
+        return response.status(500).json({ error: "Deck storage unavailable" });
+      }
+
+      const { domain: rawDomain, scope: rawScope } = request.body;
+
+      // Validate domain (SSRF prevention)
+      const domain = validateInstance(rawDomain);
+      if (!domain) {
+        return response.status(400).json({ error: "Invalid instance domain" });
+      }
+
+      // Validate scope
+      const scope = rawScope === "federated" ? "federated" : "local";
+
+      // Enforce max deck limit
+      const count = await collection.countDocuments();
+      if (count >= MAX_DECKS) {
+        return response.status(400).json({
+          error: `Maximum of ${MAX_DECKS} decks reached`,
+        });
+      }
+
+      // Insert (unique index on domain+scope will throw on duplicate)
+      const deck = {
+        domain,
+        scope,
+        addedAt: new Date().toISOString(),
+      };
+
+      try {
+        await collection.insertOne(deck);
+      } catch (insertError) {
+        if (insertError.code === 11_000) {
+          // Duplicate key — deck already exists
+          return response.status(409).json({
+            error: "Deck already exists for this domain and scope",
+          });
+        }
+
+        throw insertError;
+      }
+
+      return response.status(201).json(deck);
+    } catch (error) {
+      return next(error);
+    }
+  };
+}
+
+/**
+ * POST /admin/reader/api/decks/remove
+ * Removes the deck entry for the given domain + scope.
+ * Body: { domain, scope }
+ */
+export function removeDeckController(_mountPath) {
+  return async (request, response, next) => {
+    try {
+      // CSRF protection
+      if (!validateToken(request)) {
+        return response.status(403).json({ error: "Invalid CSRF token" });
+      }
+
+      const { application } = request.app.locals;
+      const collection = application?.collections?.get("ap_decks");
+      if (!collection) {
+        return response.status(500).json({ error: "Deck storage unavailable" });
+      }
+
+      const { domain: rawDomain, scope: rawScope } = request.body;
+
+      // Validate domain (SSRF prevention)
+      const domain = validateInstance(rawDomain);
+      if (!domain) {
+        return response.status(400).json({ error: "Invalid instance domain" });
+      }
+
+      const scope = rawScope === "federated" ? "federated" : "local";
+
+      await collection.deleteOne({ domain, scope });
+
+      return response.json({ success: true });
+    } catch (error) {
+      return next(error);
+    }
+  };
+}

package/lib/controllers/explore.js

@@ -8,6 +8,7 @@
 import sanitizeHtml from "sanitize-html";
 import { sanitizeContent } from "../timeline-store.js";
 import { searchInstances, checkInstanceTimeline, getPopularAccounts } from "../fedidb.js";
+import { getToken } from "../csrf.js";
 
 const FETCH_TIMEOUT_MS = 10_000;
 const MAX_RESULTS = 20;
@@ -18,7 +19,7 @@ const MAX_RESULTS = 20;
  * @param {string} instance - Raw instance parameter from query string
  * @returns {string|null} Validated hostname or null
  */
-function validateInstance(instance) {
+export function validateInstance(instance) {
   if (!instance || typeof instance !== "string") return null;
 
   try {
@@ -122,6 +123,23 @@ export function exploreController(mountPath) {
       const rawInstance = request.query.instance || "";
       const scope = request.query.scope === "federated" ? "federated" : "local";
       const maxId = request.query.max_id || "";
+      const activeTab = request.query.tab === "decks" ? "decks" : "search";
+
+      // Fetch deck list for both tabs (needed for star button state + deck tab)
+      const { application } = request.app.locals;
+      const decksCollection = application?.collections?.get("ap_decks");
+      let decks = [];
+      try {
+        decks = await decksCollection
+          .find({})
+          .sort({ addedAt: 1 })
+          .toArray();
+      } catch {
+        // Collection unavailable — non-fatal, decks defaults to []
+      }
+
+      const csrfToken = getToken(request.session);
+      const deckCount = decks.length;
 
       // No instance specified — render clean initial page (no error)
       if (!rawInstance.trim()) {
@@ -133,6 +151,11 @@ export function exploreController(mountPath) {
           maxId: null,
           error: null,
           mountPath,
+          activeTab,
+          decks,
+          deckCount,
+          isInDeck: false,
+          csrfToken,
         });
       }
 
@@ -146,6 +169,11 @@ export function exploreController(mountPath) {
           maxId: null,
           error: response.locals.__("activitypub.reader.explore.invalidInstance"),
           mountPath,
+          activeTab,
+          decks,
+          deckCount,
+          isInDeck: false,
+          csrfToken,
         });
       }
 
@@ -194,6 +222,10 @@ export function exploreController(mountPath) {
         error = msg;
       }
 
+      const isInDeck = decks.some(
+        (d) => d.domain === instance && d.scope === scope,
+      );
+
       response.render("activitypub-explore", {
         title: response.locals.__("activitypub.reader.explore.title"),
         instance,
@@ -202,9 +234,13 @@ export function exploreController(mountPath) {
         maxId: nextMaxId,
         error,
         mountPath,
+        activeTab,
+        decks,
+        deckCount,
+        isInDeck,
+        csrfToken,
         // Pass empty interactionMap — explore posts are not in our DB
         interactionMap: {},
-        csrfToken: "",
       });
     } catch (error) {
       next(error);

package/lib/fedidb.js

@@ -2,10 +2,13 @@
  * FediDB API client with MongoDB caching.
  *
  * Wraps https://api.fedidb.org/v1/ endpoints:
- * - /servers?q=... — search known fediverse instances
+ * - /servers — cursor-paginated list of known fediverse instances (ranked by size)
  * - /popular-accounts — top accounts by follower count
  *
- * Responses are cached in ap_kv to avoid hitting the API on every keystroke.
+ * NOTE: The /servers endpoint ignores query params (q, search, name) and always
+ * returns the same ranked list. We paginate through ~500 servers, cache the full
+ * corpus for 24 hours, and filter locally when the user searches.
+ *
  * Cache TTL: 24 hours for both datasets.
  */
 
@@ -71,46 +74,90 @@ async function writeToCache(kvCollection, cacheKey, data) {
 }
 
 /**
- * Search FediDB for instances matching a query.
- * Returns a flat array of { domain, software, description, mau, openRegistration }.
+ * Fetch the FediDB server catalogue by paginating through cursor-based results.
+ * Cached for 24 hours as a single entry. The API ignores the `q` param and
+ * always returns a ranked list, so we collect a large corpus and filter locally.
  *
- * Results are cached per normalized query for 24 hours.
+ * Paginates up to MAX_PAGES (13 pages × 40 = ~520 servers), which covers
+ * all well-known instances. Results are cached in ap_kv for 24 hours.
  *
  * @param {object} kvCollection - MongoDB ap_kv collection
- * @param {string} query - Search term (e.g. "mast")
- * @param {number} [limit=10] - Max results
  * @returns {Promise<Array>}
  */
-export async function searchInstances(kvCollection, query, limit = 10) {
-  const q = (query || "").trim().toLowerCase();
-  if (!q) return [];
+const MAX_PAGES = 13;
 
-  const cacheKey = `fedidb:instances:${q}:${limit}`;
+async function getAllServers(kvCollection) {
+  const cacheKey = "fedidb:servers-all";
   const cached = await getFromCache(kvCollection, cacheKey);
   if (cached) return cached;
 
+  const results = [];
+
   try {
-    const url = `${API_BASE}/servers?q=${encodeURIComponent(q)}&limit=${limit}`;
-    const res = await fetchWithTimeout(url);
-    if (!res.ok) return [];
+    let cursor = null;
+
+    for (let page = 0; page < MAX_PAGES; page++) {
+      let url = `${API_BASE}/servers?limit=40`;
+      if (cursor) url += `&cursor=${cursor}`;
+
+      const res = await fetchWithTimeout(url);
+      if (!res.ok) break;
+
+      const json = await res.json();
+      const servers = json.data || [];
+      if (servers.length === 0) break;
+
+      for (const s of servers) {
+        results.push({
+          domain: s.domain,
+          software: s.software?.name || "Unknown",
+          description: s.description || "",
+          mau: s.stats?.monthly_active_users || 0,
+          userCount: s.stats?.user_count || 0,
+          openRegistration: s.open_registration || false,
+        });
+      }
 
-    const json = await res.json();
-    const servers = json.data || [];
-
-    const results = servers.map((s) => ({
-      domain: s.domain,
-      software: s.software?.name || "Unknown",
-      description: s.description || "",
-      mau: s.stats?.monthly_active_users || 0,
-      userCount: s.stats?.user_count || 0,
-      openRegistration: s.open_registration || false,
-    }));
+      cursor = json.meta?.next_cursor;
+      if (!cursor) break;
+    }
 
-    await writeToCache(kvCollection, cacheKey, results);
-    return results;
+    if (results.length > 0) {
+      await writeToCache(kvCollection, cacheKey, results);
+    }
   } catch {
-    return [];
+    // Return whatever we collected so far
   }
+
+  return results;
+}
+
+/**
+ * Search FediDB for instances matching a query.
+ * Returns a flat array of { domain, software, description, mau, openRegistration }.
+ *
+ * Fetches the full server list once (cached 24h) and filters by domain/software match.
+ * FediDB's /v1/servers endpoint ignores the `q` param and always returns a static
+ * ranked list, so server-side filtering is the only way to get relevant results.
+ *
+ * @param {object} kvCollection - MongoDB ap_kv collection
+ * @param {string} query - Search term (e.g. "mast")
+ * @param {number} [limit=10] - Max results
+ * @returns {Promise<Array>}
+ */
+export async function searchInstances(kvCollection, query, limit = 10) {
+  const q = (query || "").trim().toLowerCase();
+  if (!q) return [];
+
+  const allServers = await getAllServers(kvCollection);
+
+  return allServers
+    .filter(
+      (s) =>
+        s.domain.toLowerCase().includes(q) ||
+        s.software.toLowerCase().includes(q),
+    )
+    .slice(0, limit);
 }
 
 /**

package/locales/en.json

@@ -239,7 +239,24 @@
         "invalidInstance": "Invalid instance hostname. Please enter a valid domain name.",
         "mauLabel": "MAU",
         "timelineSupported": "Public timeline available",
-        "timelineUnsupported": "Public timeline not available"
+        "timelineUnsupported": "Public timeline not available",
+        "tabs": {
+          "search": "Search",
+          "decks": "Decks"
+        },
+        "deck": {
+          "addToDeck": "Add to deck",
+          "removeFromDeck": "Remove from deck",
+          "inDeck": "In deck",
+          "deckLimitReached": "Maximum of 8 decks reached",
+          "localBadge": "Local",
+          "federatedBadge": "Federated",
+          "removeColumn": "Remove column",
+          "retry": "Retry",
+          "loadError": "Could not load timeline from this instance.",
+          "emptyState": "No decks yet. Browse an instance in the Search tab and click the star to add it.",
+          "emptyStateLink": "Go to Search"
+        }
       },
       "tagTimeline": {
         "postsTagged": "%d posts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmdes/indiekit-endpoint-activitypub",
-  "version": "2.0.30",
+  "version": "2.0.32",
   "description": "ActivityPub federation endpoint for Indiekit via Fedify. Adds full fediverse support: actor, inbox, outbox, followers, following, syndication, and Mastodon migration.",
   "keywords": [
     "indiekit",

package/views/activitypub-explore.njk

@@ -9,6 +9,23 @@
     <p class="ap-explore-header__desc">{{ __("activitypub.reader.explore.description") }}</p>
   </header>
 
+  {# Tab navigation #}
+  {% set exploreBase = mountPath + "/admin/reader/explore" %}
+  <nav class="ap-tabs">
+    <a href="{{ exploreBase }}" class="ap-tab{% if activeTab != 'decks' %} ap-tab--active{% endif %}">
+      {{ __("activitypub.reader.explore.tabs.search") }}
+    </a>
+    <a href="{{ exploreBase }}?tab=decks" class="ap-tab{% if activeTab == 'decks' %} ap-tab--active{% endif %}">
+      {{ __("activitypub.reader.explore.tabs.decks") }}
+      {% if decks and decks.length > 0 %}
+        <span class="ap-tab__count">{{ decks.length }}</span>
+      {% endif %}
+    </a>
+  </nav>
+
+  {# ── Search tab ────────────────────────────────────────────────── #}
+  {% if activeTab != 'decks' %}
+
   {# Instance form with autocomplete #}
   <form action="{{ mountPath }}/admin/reader/explore" method="get" class="ap-explore-form"
     x-data="apInstanceSearch('{{ mountPath }}')"
@@ -90,6 +107,23 @@
 
   {# Results #}
   {% if instance and not error %}
+    {# Add to deck toggle button (shown when browsing results) #}
+    {% if items.length > 0 %}
+      <div class="ap-explore-deck-toggle"
+        x-data="apDeckToggle('{{ instance }}', '{{ scope }}', '{{ mountPath }}', '{{ csrfToken }}', {{ deckCount }}, {{ 'true' if isInDeck else 'false' }})">
+        <button
+          type="button"
+          class="ap-explore-deck-toggle__btn"
+          :class="{ 'ap-explore-deck-toggle__btn--active': inDeck }"
+          @click="toggle()"
+          :disabled="!inDeck && deckLimitReached"
+          :title="!inDeck && deckLimitReached ? '{{ __('activitypub.reader.explore.deck.deckLimitReached') }}' : (inDeck ? '{{ __('activitypub.reader.explore.deck.removeFromDeck') }}' : '{{ __('activitypub.reader.explore.deck.addToDeck') }}')"
+          :aria-label="!inDeck && deckLimitReached ? '{{ __('activitypub.reader.explore.deck.deckLimitReached') }}' : (inDeck ? '{{ __('activitypub.reader.explore.deck.removeFromDeck') }}' : '{{ __('activitypub.reader.explore.deck.addToDeck') }}')"
+          x-text="inDeck ? '★ {{ __('activitypub.reader.explore.deck.inDeck') }}' : '☆ {{ __('activitypub.reader.explore.deck.addToDeck') }}'">
+        </button>
+      </div>
+    {% endif %}
+
     {% if items.length > 0 %}
       <div class="ap-timeline ap-explore-timeline"
         id="ap-explore-timeline"
@@ -123,4 +157,62 @@
       {{ prose({ text: __("activitypub.reader.explore.noResults") }) }}
     {% endif %}
   {% endif %}
+
+  {% endif %}{# end Search tab #}
+
+  {# ── Decks tab ──────────────────────────────────────────────────── #}
+  {% if activeTab == 'decks' %}
+    {% if decks and decks.length > 0 %}
+      <div class="ap-deck-grid" data-csrf-token="{{ csrfToken }}">
+        {% for deck in decks %}
+          <div class="ap-deck-column"
+            x-data="apDeckColumn('{{ deck.domain }}', '{{ deck.scope }}', '{{ mountPath }}', {{ loop.index0 }}, '{{ csrfToken }}')"
+            x-init="init()">
+            <header class="ap-deck-column__header">
+              <span class="ap-deck-column__domain">{{ deck.domain }}</span>
+              <span class="ap-deck-column__scope-badge ap-deck-column__scope-badge--{{ deck.scope }}">
+                {{ __("activitypub.reader.explore.deck." + deck.scope + "Badge") }}
+              </span>
+              <button
+                type="button"
+                class="ap-deck-column__remove"
+                @click="removeDeck()"
+                title="{{ __('activitypub.reader.explore.deck.removeColumn') }}"
+                aria-label="{{ __('activitypub.reader.explore.deck.removeColumn') }}">×</button>
+            </header>
+            <div class="ap-deck-column__body" x-ref="body">
+              <div x-show="loading && itemCount === 0" class="ap-deck-column__loading">
+                <span>{{ __("activitypub.reader.pagination.loading") }}</span>
+              </div>
+              <div x-show="error" class="ap-deck-column__error" x-cloak>
+                <p x-text="error"></p>
+                <button type="button" class="ap-deck-column__retry" @click="retryLoad()">
+                  {{ __("activitypub.reader.explore.deck.retry") }}
+                </button>
+              </div>
+              <div x-show="!loading && !error && itemCount === 0" class="ap-deck-column__empty" x-cloak>
+                {{ __("activitypub.reader.explore.noResults") }}
+              </div>
+              <div x-html="html" class="ap-deck-column__items"></div>
+              <div class="ap-deck-column__sentinel" x-ref="sentinel"></div>
+              <div x-show="loading && itemCount > 0" class="ap-deck-column__loading-more" x-cloak>
+                <span>{{ __("activitypub.reader.pagination.loading") }}</span>
+              </div>
+              <p x-show="done && itemCount > 0" class="ap-deck-column__done" x-cloak>
+                {{ __("activitypub.reader.pagination.noMore") }}
+              </p>
+            </div>
+          </div>
+        {% endfor %}
+      </div>
+    {% else %}
+      <div class="ap-deck-empty">
+        <p>{{ __("activitypub.reader.explore.deck.emptyState") }}</p>
+        <a href="{{ exploreBase }}" class="ap-deck-empty__link">
+          {{ __("activitypub.reader.explore.deck.emptyStateLink") }}
+        </a>
+      </div>
+    {% endif %}
+  {% endif %}{# end Decks tab #}
+
 {% endblock %}

package/views/layouts/ap-reader.njk

@@ -5,6 +5,8 @@
   <script defer src="/assets/@rmdes-indiekit-endpoint-activitypub/reader-infinite-scroll.js"></script>
   {# Autocomplete components for explore + popular accounts #}
   <script defer src="/assets/@rmdes-indiekit-endpoint-activitypub/reader-autocomplete.js"></script>
+  {# Deck components — apDeckToggle and apDeckColumn #}
+  <script defer src="/assets/@rmdes-indiekit-endpoint-activitypub/reader-decks.js"></script>
 
   {# Alpine.js for client-side reactivity (CW toggles, interaction buttons, infinite scroll) #}
   <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.14.9/dist/cdn.min.js"></script>