@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/collection-entries.d.ts

@@ -0,0 +1,833 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { AglynNodeSchema, NodeId } from '../foundation';
+import { type CollectionEntryDateFormat } from './collection-entry-date';
+import { type ContentAuthorLink, type ContentAuthorRecord } from './content-authors';
+export * from './collection-entry-date';
+/**
+ * Persisted component id of the "Collection entries" repeater block
+ * (plugins-mui). Like `layoutSlot`, the id lives here so the tenant compose
+ * pipeline can find the block without importing the component bundle.
+ */
+export declare const COLLECTION_ENTRIES_COMPONENT_ID = "collectionEntries";
+/** Persisted component id of the markdown "Entry body" block (plugins-mui). */
+export declare const COLLECTION_ENTRY_BODY_COMPONENT_ID = "collectionEntryBody";
+/**
+ * Persisted component id of the "Related posts" block (plugins-mui,
+ * AGL-582). The compose pipeline stamps the related entries onto the node,
+ * so the id lives here like the entries/body blocks.
+ */
+export declare const COLLECTION_RELATED_COMPONENT_ID = "collectionRelated";
+/** Persisted component id of the share-bar block (plugins-mui, AGL-582). */
+export declare const COLLECTION_SHARE_COMPONENT_ID = "collectionShare";
+/** Persisted component id of the entry-meta block (plugins-mui, AGL-582). */
+export declare const COLLECTION_ENTRY_META_COMPONENT_ID = "collectionEntryMeta";
+/**
+ * Persisted component id of the author card that closes an article
+ * (plugins-mui, AGL-2486).
+ *
+ * Entry Meta prints the byline — a NAME, on one line, beside the date. The
+ * author record it now resolves against carries a portrait, a bio, a job
+ * title and a url, and none of those have anywhere to render: a template that
+ * wanted the card the article frame draws had to type the name and the blurb
+ * as literal text, which then said "The Aglyn Team" under a post somebody
+ * else wrote and went stale the moment the author record was edited. The id
+ * lives here, with the other collection blocks, so the compose pipeline can
+ * fill the card without importing the bundle.
+ */
+export declare const COLLECTION_ENTRY_AUTHOR_COMPONENT_ID = "collectionEntryAuthor";
+/**
+ * Persisted component id of the "Category Pills" block (plugins-mui,
+ * AGL-1321). Like the entries repeater, the id lives here so the tenant
+ * compose pipeline can stamp the block's links without importing the bundle.
+ */
+export declare const COLLECTION_CATEGORIES_COMPONENT_ID = "collectionCategories";
+/**
+ * Persisted component id of the standalone "Collection Search" block
+ * (plugins-mui, AGL-1516).
+ *
+ * The Collection Entries block grew its own search box first, and it renders
+ * INSIDE that block — first child of the block's own stack. Figma 494:1220
+ * puts the field in the listing's toolbar row instead, beside the RSS button
+ * with the category pills opposite it, and no amount of authoring can lift a
+ * block's own child out of it. The pills cannot move the other way either:
+ * every child of an entries block is cloned once per entry.
+ *
+ * So the field became a block an author can put where the frame draws it.
+ * Suggestion-panel only, by construction rather than by omission — a
+ * standalone box has no clones to hide, so `filter` is a thing it genuinely
+ * cannot do, and the one behaviour it does have is the toolbar behaviour the
+ * frame asks for.
+ */
+export declare const COLLECTION_SEARCH_COMPONENT_ID = "collectionSearch";
+/**
+ * Reserved list sub-paths (AGL-620 `page`, AGL-1321 `category`). Both are
+ * only reserved as the HEAD of a longer path, so an entry legitimately
+ * slugged `page` or `category` keeps serving at `/{collection}/{entry}`.
+ */
+export declare const COLLECTION_PAGE_ROUTE_SEGMENT = "page";
+export declare const COLLECTION_CATEGORY_ROUTE_SEGMENT = "category";
+/** Namespaces cloned template ids per container/entry (cf. `rep__`). */
+export declare const COLLECTION_ENTRIES_NODE_ID_PREFIX = "centry__";
+/** Hard bound on entries a single block renders, before `entriesLimit`. */
+export declare const COLLECTION_ENTRIES_MAX = 100;
+/**
+ * Hard bound on the entries one READ of a collection returns (AGL-1516) — the
+ * `.limit()` the tenant's live-entries query carries.
+ *
+ * Named here, beside the render bound it has always silently matched, because
+ * a search index has to know the difference. The render bound is a choice
+ * about a block; this one is a choice about the DATA, and a set that reaches
+ * it is a set nobody has seen all of. Two 100s that happened to agree meant
+ * `entries.length === 100` could be read either as "this collection has 100
+ * entries" or "this read stopped at 100", and the honest empty state turns on
+ * exactly that distinction.
+ */
+export declare const COLLECTION_SOURCE_MAX = 100;
+/**
+ * Whether a collection source is a COMPLETE read or a bounded one
+ * (AGL-1516) — true when the read came back holding its own limit, which is
+ * the only signal a limited query without a count leaves behind.
+ *
+ * Deliberately errs toward "bounded": a collection of exactly
+ * {@link COLLECTION_SOURCE_MAX} entries answers true and gets described one
+ * notch more cautiously than it needed. Overstating what a search covered is
+ * the failure that renders as a confident "nothing matched".
+ */
+export declare function collectionSourceReachedBound(entries: readonly unknown[] | undefined): boolean;
+/**
+ * Whether the read behind a collection source was a bounded one (AGL-1516),
+ * asking the READER first and only then falling back to counting.
+ *
+ * The count is a proxy, and it under-reports in two ways that both landed
+ * after `collectionSourceReachedBound` was written:
+ *
+ * 1. The query takes `status in ['published', 'scheduled']` and the loader
+ *    then drops what is not live yet — a future `publishAt`, or since AGL-471
+ *    a due schedule the plan does not carry. A read that came back holding
+ *    its full 100 docs can therefore hand over 96 entries, and 96 does not
+ *    look like a ceiling. A blog with a scheduling queue is exactly the site
+ *    that hits this.
+ * 2. A category route filters `entries` before compose ever sees them, so the
+ *    "raw set" the entries block is careful to measure is already narrowed.
+ *
+ * Both make the flag read FALSE on a read that really did stop at its bound,
+ * and false is the direction that produces the confident "nothing matched"
+ * this signal exists to prevent. So `reachedBound` is threaded down from the
+ * query that owns the fact, and the count survives only as the fallback for a
+ * source that predates it — a payload cached before this shipped, or a caller
+ * that assembles a source by hand.
+ */
+export declare function collectionSourceIsBounded(source: Pick<CollectionEntriesSource, 'entries' | 'reachedBound'> | undefined): boolean;
+/** Default entries per page for a paginated collection list (AGL-620). */
+export declare const COLLECTION_LIST_PAGE_SIZE = 10;
+/**
+ * Total pages for `total` entries at `perPage` per page — at least 1 so an
+ * empty collection still has a page 1 (AGL-620).
+ */
+export declare function collectionTotalPages(total: number, perPage: number): number;
+/** Default/most related posts a Related posts block renders (AGL-582). */
+export declare const COLLECTION_RELATED_DEFAULT_LIMIT = 3;
+export declare const COLLECTION_RELATED_MAX = 12;
+/** Most categories a collection's taxonomy holds (AGL-582). */
+export declare const COLLECTION_CATEGORIES_MAX = 50;
+/**
+ * One taxonomy category on a COLLECTION doc (AGL-582): `id` is the stable
+ * slug-like key entries reference (`categoryId`), generated once from the
+ * initial name and never changed; `name` is the display label and freely
+ * renameable. Stored as an array to preserve author-defined ordering.
+ */
+export interface CollectionCategory {
+    id: string;
+    name: string;
+    /**
+     * What this category's listing is about, for the `<meta name="description">`
+     * of `/{collection}/category/{slug}`.
+     *
+     * Without one every filtered listing on a site inherits the list template
+     * screen's description — six `/blog/category/*` URLs all described as "the
+     * blog", which is the same duplicate-result problem the composed category
+     * TITLE was introduced to solve (AGL-1321), one tag over. Optional, and the
+     * template's description remains the fallback: a category nobody has
+     * described is better summarized by the list it filters than by nothing.
+     */
+    description?: string;
+}
+/**
+ * How many LIVE entries one content collection may hold (AGL-2266).
+ *
+ * `hosts/{hostId}/collections/{cid}/entries/{eid}` had a DEDICATED rules block
+ * re-granting `create` to any editor, client-direct — deliberately, because the
+ * name-based exclusions on the host catch-all must not reach entries — so it
+ * was the one quota-governed shape under a host with no quota at all. A free
+ * org could mint unbounded Firestore documents from the browser.
+ *
+ * This is a flat PLATFORM cap, not a plan dimension. AGL-1387 declined
+ * `collectionsPerHost` and this does not re-open it: nothing here is priced,
+ * no `OrgEntitlements` key is added, and every plan gets the same number. It is
+ * the `WEBHOOK_MAX_PER_HOST` (AGL-1360) / `NON_PAGE_SCREEN_MAX_PER_HOST`
+ * (AGL-1399) shape, which both issues invented for exactly this: uncapped
+ * infrastructure behind a $0 subscription.
+ *
+ * ## Per COLLECTION, paired with {@link COLLECTIONS_MAX_PER_HOST}
+ *
+ * A per-HOST entry cap would need a count across every collection the host
+ * holds, which is a collection-group read the entry documents carry no `hostId`
+ * to scope. Per collection is one `count()` on the collection the create is
+ * addressed to — the same read every other cap on `/api/hosts/resources`
+ * already pays — and the host is bounded by the PRODUCT of the two numbers,
+ * which is why the sibling cap had to land in the same change. One of the two
+ * alone bounds nothing: unbounded collections each holding 10,000 entries is
+ * the same unbounded store, spelled differently.
+ *
+ * ## Why 10,000
+ *
+ * A blog publishing daily reaches it after twenty-seven years; the largest
+ * content collection in production holds double digits. The failure mode of a
+ * flat cap set too low is blocking real authoring with an error the price list
+ * cannot explain, so it is sized to the heaviest plausible library rather than
+ * to today's data. It also bounds the cost of the console's own listing, which
+ * reads entries with `limit(200)` and would otherwise page through a store with
+ * no ceiling.
+ */
+export declare const ENTRIES_MAX_PER_COLLECTION = 10000;
+/**
+ * How many LIVE content collections one host may hold (AGL-2266).
+ *
+ * The other half of the entry bound above, and the reason it means anything.
+ * Collection creation was already server-owned — the rules deny client `create`
+ * and `/api/hosts/collections` claims the slug transactionally (AGL-978) — so
+ * the collection had a WRITER with authority and simply no number to enforce.
+ *
+ * Again a platform cap and not `collectionsPerHost`: AGL-1387 decided
+ * collections are not a thing customers are charged for, and that decision is
+ * untouched. 100 is far past any real site's taxonomy — production's busiest
+ * host has a handful — and short enough that the entries ceiling above
+ * multiplies out to a bounded store rather than an unbounded one.
+ */
+export declare const COLLECTIONS_MAX_PER_HOST = 100;
+/**
+ * One published content-collection entry as the compose pipeline sees it
+ * (AGL-551). Mirrors the tenant's `CollectionEntrySummary` without the
+ * Firestore dependency so the expansion stays pure.
+ */
+export interface CollectionEntryRecord {
+    $id?: string;
+    title?: string;
+    slug?: string;
+    excerpt?: string;
+    /**
+     * Per-entry byline (AGL-686); falls back to the site as author.
+     *
+     * Since AGL-2486 this is either the legacy free-typed string or the NAME of
+     * the author record `authorId` points at, denormalized by the tenant runtime
+     * so the byline block, the `{{entry.author}}` token and the RSS feed all
+     * keep reading one field.
+     */
+    authorName?: string;
+    /**
+     * Reference into `hosts/{hostId}/authors` (AGL-2486) — the custom author
+     * this entry publishes under. Absent on every entry written before it, and
+     * on any entry whose editor chose a one-off byline instead of a record.
+     */
+    authorId?: string;
+    /**
+     * The resolved author record, attached by the tenant runtime alongside the
+     * `authorName` it denormalizes (`get-collection-content.ts`). Carries the
+     * portrait, which is why the byline can show the author's own face rather
+     * than the site's mark — see {@link expandCollectionEntryMeta}.
+     */
+    author?: ContentAuthorRecord | null;
+    body?: string;
+    coverImage?: string;
+    /**
+     * The entry's featured video (AGL-2956), stored in the shape
+     * {@link coverImage} is: a `media:{scope}/{id}` reference or a URL, a Wistia
+     * media link included. Raw here for the reason every image field in this
+     * file is raw — the resolver needs the rendering host, which this record
+     * does not carry.
+     *
+     * An entry of a video collection is an article whose featured video sits
+     * where a post's cover image would, which is what makes its page a watch
+     * page. `{{entry.coverVideo}}` binds it into a template's Video element, and
+     * the built-in entry page plays it with no template at all.
+     */
+    coverVideo?: string;
+    /** Search-result title override (AGL-582); falls back to `title`. */
+    seoTitle?: string;
+    /** Meta description override (AGL-582); falls back to `excerpt`. */
+    seoDescription?: string;
+    /**
+     * Stable reference into the collection's `categories` taxonomy
+     * (AGL-582): the ID survives renames, so display names resolve at
+     * render via {@link resolveEntryCategoryName}.
+     */
+    categoryId?: string;
+    /**
+     * Legacy free-typed bucket (AGL-582), e.g. "Engineering". Still READ
+     * as a fallback everywhere; the editor writes `categoryId` going
+     * forward.
+     */
+    category?: string;
+    /** Free-form labels (AGL-582), e.g. ["nextjs", "seo"]. */
+    tags?: string[];
+    publishedAt?: {
+        seconds: number;
+    } | null;
+    /**
+     * The collection this entry came OUT of, stamped where the read happened
+     * (AGL-2518).
+     *
+     * Absent everywhere the routed collection already answers the question,
+     * which is every listing the platform had until now: a `/blog` page renders
+     * blog entries, so `entry.url` is built from the one slug the route
+     * resolved and no entry needs to carry its own.
+     *
+     * The author page breaks that assumption — it lists a blog post, a
+     * changelog note and a press release side by side, and building all three
+     * URLs from a single routed slug would produce two links to pages that do
+     * not exist. So the reader that mixes collections stamps each entry with
+     * where it came from, and {@link collectionEntryTokens} prefers it. Every
+     * other caller keeps passing one slug and keeps behaving identically.
+     */
+    collectionSlug?: string;
+    /**
+     * The display name of {@link collectionSlug} — "Changelog", not
+     * "changelog" — so a card on a mixed listing can label which section a
+     * post belongs to. Stamped by the same reader, for the same reason.
+     */
+    collectionName?: string;
+}
+/** A collection's published entries, keyed for expansion by its slug. */
+export interface CollectionEntriesSource {
+    slug: string;
+    entries: CollectionEntryRecord[];
+    /** The collection's category taxonomy (AGL-582), for name resolution. */
+    categories?: CollectionCategory[];
+    /**
+     * Whether the READ that produced `entries` came back holding its own
+     * `.limit()` (AGL-1516) — a fact recorded where the query ran, because by
+     * the time `entries` gets here it has been through a liveness filter and
+     * possibly a route's category filter, and its length no longer answers the
+     * question. See {@link collectionSourceIsBounded}.
+     */
+    reachedBound?: boolean;
+    /**
+     * The page the ROUTE asked for (AGL-1321), set only for the collection the
+     * URL resolved. Fills in a block that declares `perPage` but no `page` —
+     * which is every block a designer can author, since design time cannot
+     * know which page a visitor is on. A block that names its own `page` still
+     * wins: that is a deliberately pinned window, not a paginated list.
+     */
+    page?: number;
+}
+/**
+ * Display name of an entry's category (AGL-582): the `categoryId` lookup
+ * into the collection's taxonomy wins; the legacy free-typed
+ * `entry.category` string is the fallback so existing data keeps
+ * rendering. An ID referencing a deleted category resolves to nothing —
+ * by design the entry simply shows no category.
+ */
+export declare function resolveEntryCategoryName(entry: Pick<CollectionEntryRecord, 'categoryId' | 'category'>, categories?: readonly CollectionCategory[]): string | undefined;
+/**
+ * The values an Entry Meta block shows, in the exact spellings the
+ * `{{entry.date}}` / `{{entry.author}}` / `{{entry.category}}` /
+ * `{{entry.tags}}` tokens produce (AGL-1385, author added AGL-1459).
+ *
+ * Extracted so the token map and {@link expandCollectionEntryMeta} cannot
+ * drift: the same entry has to read the same way whether the author bound the
+ * tokens by hand or let the server fill the block in.
+ */
+export declare function collectionEntryMetaValues(entry: CollectionEntryRecord, categories?: readonly CollectionCategory[], dateFormat?: CollectionEntryDateFormat): {
+    date: string;
+    author: string;
+    category: string;
+    tags: string;
+};
+/**
+ * The values an Entry Author card shows (AGL-2486) — the fields of the
+ * resolved author RECORD, in the spellings the `{{entry.author*}}` tokens
+ * produce.
+ *
+ * Extracted for the reason {@link collectionEntryMetaValues} was: the card,
+ * the token map and {@link expandCollectionEntryAuthor} have to agree, and
+ * three copies of "name, falling back to the legacy string" would not.
+ *
+ * `image` stays RAW — a `media:` reference or a plain url, whichever the
+ * author saved — because the resolver that turns one into a fetchable src
+ * needs the rendering host and this function has no host (`resolveMediaSrc`,
+ * AGL-1215). Every other consumer of an image field in this file does the
+ * same.
+ */
+export declare function collectionEntryAuthorValues(entry: CollectionEntryRecord): {
+    name: string;
+    bio: string;
+    image: string;
+    url: string;
+    pageUrl: string;
+    links: ContentAuthorLink[];
+};
+/**
+ * The `{{entry.*}}` token map for one entry (AGL-105/551): substituted
+ * globally on entry-template screens and per-clone inside the Collection
+ * entries block. `entry.url` resolves to the entry's auto-route so links
+ * (`Read more`, titles) work without hardcoding the collection slug.
+ */
+export declare function collectionEntryTokens(entry: CollectionEntryRecord, collectionSlug: string, categories?: CollectionCategory[]): Record<string, string>;
+/**
+ * Category/tag membership check (AGL-582), shared by the Collection entries
+ * filter props and the query-less list surfaces. Matching is trimmed and
+ * case-insensitive — editors type these by hand. A category filter matches
+ * either the entry's stable `categoryId` or its RESOLVED display name (id
+ * lookup first, legacy string fallback), so filters written against either
+ * spelling keep working across the taxonomy migration.
+ */
+export declare function entryMatchesFilter(entry: CollectionEntryRecord, filter: {
+    category?: string;
+    tag?: string;
+}, categories?: CollectionCategory[]): boolean;
+/**
+ * URL form of a category id or display name (AGL-1321): lowercase, runs of
+ * non-alphanumerics collapsed to a single `-`, no leading/trailing dash.
+ *
+ * Deliberately lossy and idempotent, so the same category addresses the same
+ * URL whether the author typed the taxonomy id, the display name, or the URL
+ * segment itself. `Open source` → `open-source` → `open-source`.
+ */
+export declare function collectionCategorySlug(value: string | undefined): string;
+/**
+ * The taxonomy category a URL segment addresses (AGL-1321), matched on the
+ * stable `id` OR the slugified display name — an author linking
+ * `/blog/category/open-source` should not have to know which of the two the
+ * data happens to store, and an `id` that survives a rename is exactly why
+ * the taxonomy has one. `undefined` = the segment names no known category;
+ * the caller renders an empty listing rather than crashing.
+ */
+export declare function resolveCollectionCategoryBySlug(categories: readonly CollectionCategory[] | undefined, slug: string | undefined): CollectionCategory | undefined;
+/**
+ * The canonical URL of a collection listing (AGL-1321). ONE builder, because
+ * the pills, the pager, the `<link rel="canonical">`, the JSON-LD and the
+ * sitemap must all agree on the shape or the filter quietly becomes a
+ * duplicate-content generator.
+ *
+ * The unfiltered page-1 listing is the bare `/{collection}` — there is no
+ * `/{collection}/category/all` and no `?category=all`, so "All" cannot become
+ * a second address for the page that already exists.
+ */
+export declare function collectionListUrl(options: {
+    collectionSlug: string;
+    categorySlug?: string | null;
+    page?: number | null;
+}): string;
+/** Where a listing's pager can go from here (AGL-1386). */
+export interface CollectionPaginationLinks {
+    /** 1-based current page; 1 when the listing is unpaginated. */
+    page: number;
+    /** Total pages in the CURRENT (possibly category-filtered) set. */
+    totalPages: number;
+    /** The previous page's URL, or `''` on the first page. */
+    prevUrl: string;
+    /** The next page's URL, or `''` on the last page. */
+    nextUrl: string;
+}
+/**
+ * Everything a pager needs for one listing (AGL-1386): which page it is on,
+ * how many there are, and where prev/next go — through
+ * {@link collectionListUrl}, so both links stay inside the category they are
+ * paging rather than dumping the reader back onto the unfiltered list.
+ *
+ * **The edges resolve to the empty string, never to a URL.** No previous page
+ * means `prevUrl` is `''`; no next page means `nextUrl` is `''`. That is what
+ * lets an authored template bind these unconditionally: one static list screen
+ * serves the bare listing, every `/page/{n}`, and every
+ * `/category/{slug}` — and there is no runtime conditional to hide a link
+ * with. A link whose href resolves to `''` renders as an inert placeholder of
+ * the same element (AGL-1268/1357), which is the correct pager on page 1 of 1.
+ *
+ * ONE computation, because it has two consumers that must agree: the built-in
+ * fallback pager's nodes and the `{{pagination.*}}` tokens an authored
+ * template binds. A second derivation is how a fallback and a template start
+ * disagreeing about which page they are on.
+ */
+export declare function collectionPaginationLinks(options: {
+    collectionSlug: string;
+    categorySlug?: string | null;
+    /** 1-based current page; anything unusable reads as page 1. */
+    page?: number | null;
+    /** Total pages; anything unusable reads as a single page. */
+    totalPages?: number | null;
+}): CollectionPaginationLinks;
+/** A content-collection path resolved to what it addresses (AGL-1321). */
+export interface CollectionRoute {
+    collectionSlug: string;
+    /** Set only for `/{collection}/{entry}`. */
+    entrySlug?: string;
+    /** Set only for `/{collection}/category/{slug}[/page/{n}]`. */
+    categorySlug?: string;
+    /** 1-based list page; always 1 for entry routes. */
+    page: number;
+}
+/**
+ * Parses a non-screen path against the content-collection route shapes
+ * (AGL-81/620/1321), or `null` when it is none of them and the caller should
+ * fall through to the 404 chain:
+ *
+ * ```
+ * /{collection}                                list, page 1, all categories
+ * /{collection}/{entry}                        one entry
+ * /{collection}/page/{n}                       list page n
+ * /{collection}/category/{slug}                filtered list, page 1
+ * /{collection}/category/{slug}/page/{n}       filtered list, page n
+ * ```
+ *
+ * Pure, and shared by the tenant loader and its tests, because the route
+ * table IS the ISR cache key here: the tenant catch-all caches by PATH, so a
+ * listing variant that lives in the path gets its own cache entry for free,
+ * while one that lived in a query string would share `/blog`'s entry and
+ * serve one category's HTML for another.
+ */
+export declare function parseCollectionRoute(segments: readonly string[]): CollectionRoute | null;
+/**
+ * Does this entry belong to the category a URL segment addresses (AGL-1321)?
+ *
+ * Every spelling the route could plausibly mean is slugified into one set and
+ * checked against both of the entry's own spellings — the stable `categoryId`
+ * and the RESOLVED display name. So `/blog/category/open-source` answers for
+ * a taxonomy whose id is `opensource`, for one whose id is opaque but whose
+ * name is "Open source", and for a legacy free-typed entry that predates the
+ * taxonomy entirely. `entryMatchesFilter` cannot stand in: it compares raw
+ * trimmed strings, so it would miss every multi-word category name.
+ */
+export declare function entryMatchesCategoryRoute(entry: CollectionEntryRecord, route: {
+    slug: string;
+    category?: CollectionCategory;
+}, categories?: readonly CollectionCategory[]): boolean;
+/** One category pill as stamped onto a Category Pills block (AGL-1321). */
+export interface CollectionCategoryLink {
+    label: string;
+    href: string;
+    /** The pill for the listing currently being rendered. */
+    active: boolean;
+}
+/** Label the unfiltered pill carries when the author never named one. */
+export declare const COLLECTION_ALL_PILL_DEFAULT = "All";
+/**
+ * The value that persists "no All pill" (AGL-1336).
+ *
+ * The attribute documented "clear it to omit that pill" and could not do it:
+ * the attributes form strips an emptied text field's KEY (ddf maps an
+ * emptied field to its `clearedValue`, final-form's default parse turns
+ * `''` into `undefined`, and `updateNodeProps` replaces the props object),
+ * so the absent key took {@link COLLECTION_ALL_PILL_DEFAULT} and the pill
+ * came straight back. `''` is therefore not a value this field can hold —
+ * the same AGL-1191 trap that made the App Bar's "Default" unpersistable.
+ *
+ * So the field carries this as its `clearedValue`: clearing the box writes
+ * the word `none`, which survives the round trip and is honoured here.
+ * Deliberately a readable word rather than a magic character — an author who
+ * reopens the panel sees `none` in the All-label box and can read what it
+ * did. Removing the prop entirely (the ✕ affordance) still means "unset",
+ * and restores the default.
+ */
+export declare const COLLECTION_ALL_PILL_NONE = "none";
+/**
+ * What the unfiltered pill should be labelled, or `''` to omit it — the ONE
+ * place the {@link COLLECTION_ALL_PILL_NONE} sentinel is interpreted
+ * (AGL-1336). Matched case-insensitively on the trimmed value, because the
+ * sentinel is typed by a human only when they are re-entering it by hand.
+ *
+ * `undefined` is UNSET and takes the default. `null` is CLEARED and omits —
+ * it reaches here only from a hand-edited or imported document, but the two
+ * are different questions and must not collapse into one answer.
+ */
+export declare function resolveCollectionAllLabel(value?: string | null): string;
+/**
+ * The pill row for a collection (AGL-1321): "All" pointing at the canonical
+ * unfiltered listing, then one pill per taxonomy category.
+ *
+ * Each pill addresses its category by the STABLE id where there is one, so a
+ * rename moves the label without breaking the link. Active state is decided
+ * through the same resolver the route used, not by string equality, because
+ * the URL may legitimately have named the category by either spelling.
+ */
+export declare function buildCollectionCategoryLinks(options: {
+    collectionSlug: string;
+    categories?: readonly CollectionCategory[];
+    activeCategorySlug?: string;
+    /**
+     * Label for the unfiltered pill. Absent takes the default; `''` or the
+     * {@link COLLECTION_ALL_PILL_NONE} sentinel omits the pill.
+     */
+    allLabel?: string | null;
+}): CollectionCategoryLink[];
+/**
+ * The matchable text a search box holds for a set of entries (AGL-1516),
+ * built ONCE for both blocks that carry one — the entries block's in-place
+ * filter and the standalone toolbar box (AGL-1516, Figma 494:1220).
+ *
+ * Shared rather than copied for the same reason
+ * {@link COLLECTION_SEARCH_FUSE_OPTIONS} is: the two boxes can sit on the
+ * same page, over the same collection, and a reader who sees a suggestion in
+ * one and a miss in the other has been told the site is broken. Two builders
+ * is how the row's date, chip and link drift apart.
+ *
+ * The row's link, date and category are resolved HERE, where the entry still
+ * exists — a component only holds rendered markup by the time it runs, and
+ * the suggestion panel draws its rows from this index rather than from the
+ * clones. Through the same three resolvers Related posts uses (AGL-1926 for
+ * the date especially): a suggestion for a post is the same post as the card
+ * below it and must not be able to disagree with it about its date.
+ */
+export declare function buildCollectionSearchIndex(entries: readonly CollectionEntryRecord[], collectionSlug: string, categories?: readonly CollectionCategory[]): CollectionEntrySearchItem[];
+/**
+ * Does this tree render the collection `collectionSlug` away from the
+ * collection's own routes?
+ *
+ * The content twin of {@link nodesPlaceForm}, and it exists for the same
+ * reason: an entry edit changes every page that renders the collection, and
+ * those pages are found by SEARCHING node trees rather than by matching a
+ * pointer. A collection's own addresses are derivable from its slug; a rail
+ * on the home page is not derivable from anything.
+ *
+ * Matches only an EXPLICIT `collectionSlug`. A block that names none inherits
+ * the routed collection — which means it renders nothing at all off-route
+ * (`scanCollectionBlocks` adds no slug, so the block is left untouched) and
+ * renders the routed collection on-route, where the collection's own list and
+ * entry addresses already reach it. Treating an unbound block as a dependent
+ * of every collection on the site would make every entry save drop every page
+ * that carries one.
+ *
+ * The comparison is against the slug rather than the document id because that
+ * is what the binding stores, and what `scanCollectionBlocks` resolves. A
+ * collection whose slug was just changed is a different question, and one the
+ * slug change itself has to answer.
+ */
+export declare function nodesRenderCollection(nodes: Record<NodeId, AglynNodeSchema | undefined> | undefined | null, collectionSlug: string): boolean;
+/**
+ * Collection entries blocks (AGL-551): a `collectionEntries` container
+ * treats its children as the item template and renders them once per
+ * published entry, with `{{entry.*}}` tokens in cloned string props replaced
+ * per entry — the content-collection sibling of {@link expandRepeatables}.
+ *
+ * - The block's collection resolves from its `collectionSlug` prop, falling
+ *   back to `defaultSlug` (the routed collection on list-template screens).
+ * - Clone ids are namespaced `centry__{containerId}__{index}__…` so repeats
+ *   never collide; run AFTER grafting and BEFORE binding resolution.
+ * - Rows are bounded by `props.entriesLimit` and
+ *   {@link COLLECTION_ENTRIES_MAX}.
+ * - `props.firstPageOnly` renders zero rows past page 1 of the ROUTED
+ *   listing (AGL-1871), so a lead card does not repeat down the pagination.
+ * - An UNKNOWN collection leaves the node untouched (fail-open: a renamed
+ *   collection must never take a screen down). A known collection with no
+ *   matching entries renders zero rows — never the unsubstituted template.
+ * - Inputs are never mutated; template nodes stay in the map unreferenced.
+ */
+export declare function expandCollectionEntries<N extends AglynNodeSchema = AglynNodeSchema>(nodes: Record<NodeId, N>, sourcesBySlug: Record<string, CollectionEntriesSource | undefined>, defaultSlug?: string): Record<NodeId, N>;
+/**
+ * Category Pills blocks (AGL-1321): stamps each `collectionCategories` node
+ * with its collection's pill row as a serializable `items` prop the component
+ * renders as real anchors — the same server-stamped shape Related posts uses,
+ * and for the same reason: the block owns its markup, so there is no template
+ * to clone.
+ *
+ * `activeCategorySlug` marks a pill only on the ROUTED collection. A pills
+ * block pointing at some other collection is not what this URL filters, so
+ * marking one of its pills current would be a lie in the HTML.
+ *
+ * A collection with no taxonomy leaves its block untouched, so the component's
+ * besigner affordance / empty site render applies. Inputs are never mutated.
+ */
+export declare function expandCollectionCategories<N extends AglynNodeSchema = AglynNodeSchema>(nodes: Record<NodeId, N>, sourcesBySlug: Record<string, CollectionEntriesSource | undefined>, defaultSlug?: string, activeCategorySlug?: string): Record<NodeId, N>;
+/**
+ * Collection Search blocks (AGL-1516): stamps each `collectionSearch` node
+ * with its collection's search index, the size of the set that index was
+ * drawn from, and whether that set was a bounded read — the same
+ * server-stamped shape Category Pills and Related posts use, and for the same
+ * reason: the block owns its markup, so there is no template to clone.
+ *
+ * Indexes the WHOLE source rather than a page window. The entries block's box
+ * searches the entries that block rendered because it filters them in place;
+ * a toolbar box filters nothing and suggests, so scoping it to one page of a
+ * listing would be an arbitrary cut nobody asked for. What it can honestly
+ * cover is the set the page's listing is drawn from — which on a category
+ * route is that category, because `source.entries` arrives filtered.
+ *
+ * Clones are SKIPPED by their `centry__` prefix: a search box inside an entry
+ * template would otherwise be stamped once per card. Nodes are never mutated,
+ * and a collection with no entries leaves its block untouched, so the
+ * component's besigner affordance and its empty site render both stand.
+ */
+export declare function expandCollectionSearch<N extends AglynNodeSchema = AglynNodeSchema>(nodes: Record<NodeId, N>, sourcesBySlug: Record<string, CollectionEntriesSource | undefined>, defaultSlug?: string): Record<NodeId, N>;
+/**
+ * Entry Meta blocks (AGL-1385): stamps each `collectionEntryMeta` node with
+ * the routed entry's date, category and tags — the same server-stamped shape
+ * Category Pills and Related posts already use.
+ *
+ * MEASURED on the live marketing blog, which is what this fixes. The block was
+ * on `blogEntryTmpl` carrying props `{showDate: true, showCategory: true,
+ * showTags: true}` and NOTHING else, and rendered as an empty `<div>` at height
+ * 0 — while the very same entry's `<pubDate>` and `Guides` category appeared in
+ * its feed item, its JSON-LD, and a heading two nodes above it. So the data was
+ * never missing; the block simply had nothing bound to it.
+ *
+ * The design is what made that reachable. Every other collection block sources
+ * itself; this one required the author to type `{{entry.date}}` into a text
+ * field. Only the PRESET seeds those tokens — drag the bare component out of
+ * the palette and you get three switches labelled "Show date / Show category /
+ * Show tags", all defaulting to on, gating values that can never exist. That is
+ * an affordance promising something the component cannot deliver, so this is a
+ * defect in the block and not in anyone's content, and it hits every collection
+ * that uses it, not just blog.
+ *
+ * Deliberately narrow:
+ *
+ *  - An AUTHORED value always wins. Only an absent or blank prop is filled, so
+ *    a hand-typed byline, a pinned string, or a `{{entry.*}}` token still
+ *    awaiting substitution is never overwritten. (Blank counts as unset
+ *    because a cleared text field cannot persist `''` anyway — AGL-1336. The
+ *    way to hide a value is the switch that exists for it.)
+ *  - Nodes cloned per entry by {@link expandCollectionEntries} are SKIPPED by
+ *    their `centry__` id prefix. Their tokens resolve per clone; stamping the
+ *    routed entry into them would date every card in a listing the same.
+ *  - Without a routed entry — a list route, a plain screen — nothing is
+ *    stamped, so the besigner affordance and the empty site render stand.
+ *
+ * `dateFormat` (AGL-1459) is answered here, where the timestamp still exists,
+ * and is the ONE exception to "an authored value always wins" — narrowly, and
+ * only for the literal `{{entry.date}}` binding. That binding is what the
+ * block's own preset seeds, so a format that filled blanks only would do
+ * nothing on the exact surface it was built for. The token is not a hand-typed
+ * override; it NAMES the value being reformatted. A literal string an author
+ * typed still wins, unchanged.
+ *
+ * Inputs are never mutated.
+ */
+export declare function expandCollectionEntryMeta<N extends AglynNodeSchema = AglynNodeSchema>(nodes: Record<NodeId, N>, entry: CollectionEntryRecord | null | undefined, categories?: readonly CollectionCategory[]): Record<NodeId, N>;
+/**
+ * Fill Entry Author cards from the routed entry's author record (AGL-2486),
+ * on the same terms {@link expandCollectionEntryMeta} fills the byline:
+ *
+ *  - an authored value always wins, and a blank one is a blank, not a
+ *    request for the default — the way to hide a field is its Show switch;
+ *  - per-entry clones (`centry__`) are skipped, so a listing's cards keep
+ *    resolving their own tokens rather than every card naming the routed
+ *    entry's author;
+ *  - without a routed entry nothing is stamped, which leaves the besigner's
+ *    placeholder card visible on the canvas.
+ *
+ * Inputs are never mutated.
+ */
+export declare function expandCollectionEntryAuthor<N extends AglynNodeSchema = AglynNodeSchema>(nodes: Record<NodeId, N>, entry: CollectionEntryRecord | null | undefined): Record<NodeId, N>;
+/**
+ * The ONE matcher configuration behind every entry search in the product
+ * (AGL-1516/AGL-1525) — the block's toolbar box, its suggestion panel, and
+ * the site-wide results page the panel links to.
+ *
+ * Shared rather than copied because the two halves are joined by a link the
+ * reader clicks: the panel's "View all results" hands its query to /search,
+ * and if the results page matched more strictly it would answer a visible
+ * suggestion with "no results". A typo the panel forgave — "platfrom" — is
+ * exactly the query most likely to make that trip.
+ *
+ * The shape is the icon picker's (use-mdi-icons-fuzzy), tuned once for prose
+ * and MEASURED before shipping: the title names the post and the excerpt
+ * merely describes it, so they are weighted 0.7/0.3; the default location
+ * scoring buries a legitimate mid-sentence hit in a sentence-long excerpt,
+ * and the default 0.6 threshold matches "media" against every post on letter
+ * soup, so location is ignored and the threshold tightened to 0.3.
+ *
+ * A plain object, not a Fuse instance: `libs/aglyn` is dependency-light by
+ * design, and each consumer already imports Fuse from the vendor bundle.
+ */
+export declare const COLLECTION_SEARCH_FUSE_OPTIONS: {
+    keys: {
+        name: string;
+        weight: number;
+    }[];
+    includeScore: boolean;
+    shouldSort: boolean;
+    ignoreLocation: boolean;
+    threshold: number;
+};
+/**
+ * One entry of a Collection Entries search index (AGL-1516): the fields the
+ * block's client-side search box matches against, index-aligned with the
+ * entry clones the block rendered. Stamped by {@link expandCollectionEntries}
+ * only when the block's `search` prop is on; never set by hand.
+ */
+export interface CollectionEntrySearchItem {
+    title: string;
+    excerpt: string;
+    /**
+     * Entry permalink (AGL-1525). The `filter` mode never needs it — it hides
+     * and shows clones that already carry their own links — but a suggestion
+     * row IS the link, and the panel is drawn from the index, not from the
+     * clones. Optional because a page cached before this shipped has an index
+     * without it; the panel degrades to plain text rather than to a dead link.
+     */
+    url?: string;
+    /** Published date, through {@link formatCollectionEntryDate} (AGL-1525). */
+    date?: string;
+    /** Category display name for the suggestion row's chip (AGL-1525). */
+    category?: string;
+}
+/** One related post as stamped onto a Related posts block (AGL-582). */
+export interface CollectionRelatedItem {
+    title: string;
+    url: string;
+    date?: string;
+    excerpt?: string;
+    /** Per-entry byline (AGL-686); falls back to the site as author. */
+    authorName?: string;
+    category?: string;
+    /**
+     * The entry's cover, as STORED (AGL-1457) — a `media:` reference, a legacy
+     * URL, or a hotlink. Left unresolved on purpose: the block resolves it at
+     * render through `resolveMediaSrc`, exactly as the Image element does, so
+     * one reference keeps working across sites and CDN route changes.
+     */
+    coverImage?: string;
+    /**
+     * The author's description of that cover (AGL-2418). Travels WITH
+     * `coverImage`, and absent means "fall back to the title" rather than
+     * "silent" — on this block the cover is the link's own content.
+     */
+    coverImageAlt?: string;
+}
+/**
+ * Related-post selection (AGL-582): other entries of the same collection
+ * that share the current entry's category or at least one tag, newest
+ * first. Pure so the compose stage and tests share one implementation. An
+ * entry with no category and no tags relates to nothing — the caller
+ * renders nothing rather than guessing.
+ *
+ * Two entries share a category when their stable `categoryId`s are equal
+ * (survives renames AND deletions) or their RESOLVED display names match
+ * case-insensitively — so a legacy free-typed entry still relates to a
+ * migrated `categoryId` entry whose taxonomy name spells the same.
+ */
+export declare function selectRelatedEntries(entries: CollectionEntryRecord[], current: CollectionEntryRecord, limit?: number, categories?: CollectionCategory[]): CollectionEntryRecord[];
+/**
+ * Related posts blocks (AGL-582): stamps each `collectionRelated` node with
+ * the current entry's related posts as a serializable `entries` prop the
+ * component renders directly (no template cloning — the block owns its
+ * markup). Runs only on entry renders; without an entry context the nodes
+ * stay untouched, so the component's sample cards (editing surfaces) or its
+ * empty site render apply. Inputs are never mutated.
+ */
+export declare function expandCollectionRelated<N extends AglynNodeSchema = AglynNodeSchema>(nodes: Record<NodeId, N>, source: CollectionEntriesSource | undefined, currentEntry: CollectionEntryRecord | null | undefined): Record<NodeId, N>;
+export default expandCollectionEntries;