wiki-formant 0.59.0 → 0.61.0

package/dist/store.d.ts

@@ -0,0 +1,166 @@
+import type { Sql } from './analytics.js';
+import type { BlockGroup, DiffBlock } from './revisions.js';
+import { type ChangeType } from './versioning.js';
+import { type HistoryChange } from './history.js';
+export type { Sql };
+export type PageMetadata = Record<string, unknown>;
+/** A page as stored. */
+export interface WikiPageRow<B = unknown> {
+    id: string;
+    siteId: string;
+    tagPath: string;
+    slug: string;
+    title: string;
+    content: B[];
+    metadata: PageMetadata;
+    version: string;
+    authorId: string | null;
+    lastVerifiedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * A page as a listing carries it: one line of the article instead of the
+ * article. A category of 200 cards otherwise ships 200 block arrays to the
+ * browser.
+ */
+export type WikiPageListing = Omit<WikiPageRow, 'content'> & {
+    snippet: string;
+};
+export interface WikiPageRef {
+    tagPath: string;
+    slug: string;
+    title: string;
+}
+export interface WikiRevisionRow<B = unknown> {
+    id: string;
+    pageId: string;
+    title: string;
+    content: B[];
+    version: string;
+    changeType: string;
+    message: string | null;
+    authorId: string | null;
+    createdAt: Date;
+}
+export type WikiRevisionEntry = Omit<WikiRevisionRow, 'content'> & {
+    changes: HistoryChange[];
+};
+export type ListSort = 'title' | 'recent' | 'date';
+export interface WikiStoreOptions<B extends DiffBlock> {
+    sql: Sql;
+    /** The site every read and write is scoped to. "" in an app that serves one wiki. */
+    siteId?: string;
+    /**
+     * Tag paths a listing leaves out unless it names them: a wiki's back office,
+     * such as the maintenance log a routine rewrites every few hours. A hidden
+     * page keeps its URL, its twin and its history; it never arrives unasked.
+     */
+    hidden?: readonly string[];
+    /** The block tree's containers, for diffs. Defaults to the core model's (`coreBlockGroups`). */
+    containers?: (block: B) => BlockGroup<B>[] | null;
+    /**
+     * A listing's line for a page when nothing better is found: a search hit
+     * whose match is in the title alone, and every card. Defaults to the
+     * article's opening; a wiki that keeps a written summary in metadata says so.
+     */
+    snippet?: (page: Pick<WikiPageRow<B>, 'content' | 'metadata'>) => string;
+}
+export interface SaveInput<B> {
+    tagPath: string;
+    slug: string;
+    title?: string;
+    content?: B[];
+    /** Replaces the page's metadata whole. Omit to keep it. */
+    metadata?: PageMetadata;
+    authorId?: string | null;
+    /** The history's line for this save. Defaults to what the diff found ("1 block modified"). */
+    message?: string | null;
+    /**
+     * The version the writer opened. A save that finds the page has moved on is
+     * refused with 409 rather than quietly overwriting the edit in between.
+     */
+    baseVersion?: string;
+    /**
+     * The bump to record instead of the one the diff picks, for a writer that
+     * knows. Stated, it always writes a revision, even for a save the diff finds
+     * empty: a routine recording a reading in metadata wants it in the history.
+     */
+    change?: Exclude<ChangeType, 'none'>;
+    /** The writer's word that the page's facts were checked: stamps `lastVerifiedAt`. */
+    verified?: boolean;
+    /** Moves the page to another slug in the same tag path. */
+    newSlug?: string;
+}
+export interface SaveResult<B> {
+    page: WikiPageRow<B>;
+    created: boolean;
+    /** `none` when the save changed nothing a revision records, so none was written. */
+    changeType: ChangeType;
+    summary: string;
+}
+/** A row as a listing carries it, for an app that runs a listing query of its own. */
+export declare function toListing<R extends {
+    content?: unknown;
+}>(row: R): Omit<R, 'content'> & {
+    snippet: string;
+};
+/** Re-order rows to match an id list, dropping ids that no longer resolve. */
+export declare function orderByIds<T extends {
+    id: string;
+}>(rows: readonly T[], ids: readonly string[]): T[];
+export declare function wikiStore<B extends DiffBlock = DiffBlock>(o: WikiStoreOptions<B>): {
+    siteId: string;
+    hidden: string[];
+    isHidden: (tagPath: string) => boolean;
+    get: (tagPath: string, slug: string) => Promise<NonNullable<WikiPageRow<B> & {
+        revisionCount: number;
+    }> | null>;
+    getById: (id: string) => Promise<NonNullable<WikiPageRow<B> & {
+        revisionCount: number;
+    }> | null>;
+    list: (tagPath: string, { sort, limit, offset }?: {
+        sort?: ListSort;
+        limit?: number;
+        offset?: number;
+    }) => Promise<WikiPageListing[]>;
+    articles: (tagPath: string, { sort, limit, offset }?: {
+        sort?: ListSort;
+        limit?: number;
+        offset?: number;
+    }) => Promise<WikiPageRow<B>[]>;
+    subtree: (tagPath: string) => Promise<WikiPageRef[]>;
+    recent: ({ tagPath, limit }?: {
+        tagPath?: string;
+        limit?: number;
+    }) => Promise<WikiPageListing[]>;
+    byIds: (ids: readonly string[]) => Promise<WikiPageListing[]>;
+    refs: () => Promise<Omit<WikiPageRow<unknown>, "content">[]>;
+    corpus: () => Promise<WikiPageRow<B>[]>;
+    stats: () => Promise<{
+        pages: number;
+        updated: Date | null;
+    }>;
+    search: (query: string, { tagPath, skip, take }?: {
+        tagPath?: string | null;
+        skip?: number;
+        take?: number;
+    }) => Promise<{
+        items: (WikiPageListing & {
+            score: number;
+        })[];
+        total: number;
+    }>;
+    history: (pageId: string, { limit, offset }?: {
+        limit?: number;
+        offset?: number;
+    }) => Promise<WikiRevisionEntry[]>;
+    revision: (pageId: string, revisionId: string) => Promise<WikiRevisionRow<B> | null>;
+    save: (input: SaveInput<B>) => Promise<SaveResult<B>>;
+    restore: (tagPath: string, slug: string, revisionId: string, by?: {
+        authorId?: string | null;
+    }) => Promise<SaveResult<B>>;
+    remove: (tagPath: string, slug: string) => Promise<boolean>;
+    verify: (tagPath: string, slug: string) => Promise<boolean>;
+};
+export type WikiStore<B extends DiffBlock = DiffBlock> = ReturnType<typeof wikiStore<B>>;

package/dist/store.js

@@ -0,0 +1,237 @@
+// store.ts – a wiki's pages and revisions, over the app's own connection.
+//
+// Three wikis each kept their own copy of this layer, on three schemas that had
+// drifted apart: `pages(tag_path, slug)` with cuid ids, `wiki_pages(caper_id,
+// tag_path, slug)` with int ids and no version, `WikiPage(section, slug)` with
+// no author. Each copy wrote its page and its revision its own way, and two of
+// them read the page, diffed it, and wrote it back with nothing to stop a
+// second editor's save landing in between and being overwritten.
+//
+// The tables are now the package's (`prisma/wiki.prisma`, copied by the
+// `prisma-models` bin), so the SQL is too. The app supplies one `Sql` function
+// and, in a multi-tenant app, the site the store reads and writes. Caching
+// stays with the caller, because each framework spells it differently.
+//
+// A write is one statement: the page update and its revision row are a
+// data-modifying CTE guarded on the version the save read, so a save that lost
+// a race writes nothing and says so (409) instead of erasing the other edit.
+import { computeRevisionDiff } from './revisions.js';
+import { bump } from './versioning.js';
+import { withChanges } from './history.js';
+import { proseSql, escapeLikeTerm, HEADLINE_OPTIONS, FTS_RANK_NORMALIZATION } from './search.js';
+import { openingText, matchSnippet } from './text.js';
+import { describe } from './metadata.js';
+import { decodeEntities } from './markdown.js';
+import { HttpError } from './http.js';
+const PAGE = '"WikiPage"';
+const REVISION = '"WikiRevision"';
+const COLUMNS = `id, "siteId", "tagPath", slug, title, content, metadata, version, "authorId", "lastVerifiedAt", "createdAt", "updatedAt"`;
+const REVISION_COLUMNS = `id, "pageId", title, content, version, "changeType", message, "authorId", "createdAt"`;
+const REVISION_COUNT = `(SELECT count(*)::int FROM ${REVISION} r WHERE r."pageId" = p.id) AS "revisionCount"`;
+const INITIAL_VERSION = '1.0.0';
+/** A row as a listing carries it, for an app that runs a listing query of its own. */
+export function toListing(row) {
+    const { content, ...rest } = row;
+    return { ...rest, snippet: describe(openingText(content)) };
+}
+const conflict = (message) => new HttpError(409, message);
+/** Re-order rows to match an id list, dropping ids that no longer resolve. */
+export function orderByIds(rows, ids) {
+    const byId = new Map(rows.map(row => [row.id, row]));
+    return ids.map(id => byId.get(id)).filter((row) => row !== undefined);
+}
+export function wikiStore(o) {
+    const site = o.siteId ?? '';
+    const opening = o.snippet ?? ((page) => describe(openingText(page.content)));
+    const listing = (row) => {
+        const { content: _, ...rest } = row;
+        return { ...rest, snippet: opening(row) };
+    };
+    const hidden = [...(o.hidden ?? [])];
+    const rows = async (query, ...values) => (await o.sql(query, ...values));
+    const one = async (query, ...values) => (await rows(query, ...values))[0] ?? null;
+    const isHidden = (tagPath) => hidden.some(h => tagPath === h || tagPath.startsWith(`${h}/`));
+    /** A page with how many revisions it has, which every article's foot states. */
+    const get = (tagPath, slug) => one(`SELECT ${COLUMNS}, ${REVISION_COUNT} FROM ${PAGE} p WHERE "siteId" = $1 AND "tagPath" = $2 AND slug = $3`, site, tagPath, slug);
+    const getById = (id) => one(`SELECT ${COLUMNS}, ${REVISION_COUNT} FROM ${PAGE} p WHERE "siteId" = $1 AND id = $2`, site, id);
+    const ORDER = {
+        title: 'title ASC',
+        recent: '"updatedAt" DESC',
+        // A post or an event is as recent as the day it is about.
+        date: `NULLIF(metadata->>'date', '') DESC NULLS LAST, "updatedAt" DESC`,
+    };
+    /** A category's pages, its hub article (the empty slug) excepted: the hub heads the page, it is not a card in it. */
+    const list = async (tagPath, { sort = 'title', limit = 200, offset = 0 } = {}) => (await rows(`SELECT ${COLUMNS} FROM ${PAGE} WHERE "siteId" = $1 AND "tagPath" = $2 AND slug <> '' ORDER BY ${ORDER[sort]} LIMIT $3::int OFFSET $4::int`, site, tagPath, limit, offset)).map(listing);
+    /** A category's pages with their content, for a listing that reads the bodies (a reading time, a word count). */
+    const articles = (tagPath, { sort = 'title', limit = 200, offset = 0 } = {}) => rows(`SELECT ${COLUMNS} FROM ${PAGE} WHERE "siteId" = $1 AND "tagPath" = $2 AND slug <> '' ORDER BY ${ORDER[sort]} LIMIT $3::int OFFSET $4::int`, site, tagPath, limit, offset);
+    /** Every page under a category, by title: the card that lists a subcategory's articles. */
+    const subtree = (tagPath) => rows(`SELECT "tagPath", slug, title FROM ${PAGE}
+        WHERE "siteId" = $1 AND "tagPath" LIKE $2 AND slug <> '' AND NOT ("tagPath" = ANY($3::text[]))
+        ORDER BY title ASC`, site, `${escapeLikeTerm(tagPath)}/%`, hidden);
+    /**
+     * The newest pages. One that names a path gets that path, hidden or not; one
+     * that names none is asking what changed on the wiki, and the answer is
+     * article space.
+     */
+    const recent = async ({ tagPath, limit = 10 } = {}) => (await (tagPath !== undefined
+        ? rows(`SELECT ${COLUMNS} FROM ${PAGE} WHERE "siteId" = $1 AND "tagPath" = $2 ORDER BY "updatedAt" DESC LIMIT $3::int`, site, tagPath, limit)
+        : rows(`SELECT ${COLUMNS} FROM ${PAGE} WHERE "siteId" = $1 AND NOT ("tagPath" = ANY($2::text[])) ORDER BY "updatedAt" DESC LIMIT $3::int`, site, hidden, limit))).map(listing);
+    const byIds = async (ids) => ids.length
+        ? orderByIds((await rows(`SELECT ${COLUMNS} FROM ${PAGE} WHERE "siteId" = $1 AND id = ANY($2::text[])`, site, [...ids])).map(listing), ids)
+        : [];
+    /** Every page without its content: the sitemap, llms.txt and a site's page list. */
+    const refs = () => rows(`SELECT id, "siteId", "tagPath", slug, title, metadata, version, "authorId", "lastVerifiedAt", "createdAt", "updatedAt" FROM ${PAGE} WHERE "siteId" = $1 ORDER BY "tagPath", slug`, site);
+    /** Every page with its content, for a corpus export. Hidden paths are left out. */
+    const corpus = () => rows(`SELECT ${COLUMNS} FROM ${PAGE} WHERE "siteId" = $1 AND NOT ("tagPath" = ANY($2::text[])) ORDER BY "tagPath", slug`, site, hidden);
+    const stats = async () => {
+        const row = await one(`SELECT count(*)::int AS pages, max("updatedAt") AS updated FROM ${PAGE} WHERE "siteId" = $1`, site);
+        return { pages: row?.pages ?? 0, updated: row?.updated ?? null };
+    };
+    /**
+     * Ranked search over titles and prose, in four tiers:
+     *
+     *   0  title starts with the term
+     *   1  title contains it
+     *   2  prose contains it, literally
+     *   3  full-text match on `search_tsv`: stems, stopwords dropped, ranked
+     *
+     * The literal tiers keep identifiers, tickers and version strings working,
+     * which the english dictionary folds or splits; tier 3 is reached only by a
+     * query they could not answer, so it adds recall without displacing anything.
+     * Hidden paths are left out unless `tagPath` names one: a maintenance log
+     * quotes every edit and would head every body match. The home
+     * page is never a result. A tier-3 row's snippet is Postgres' own headline,
+     * because a stem match has no literal substring to window on.
+     */
+    const search = async (query, { tagPath = null, skip = 0, take = 25 } = {}) => {
+        const term = escapeLikeTerm(query);
+        if (!term)
+            return { items: [], total: 0 };
+        const prose = proseSql('p.content');
+        const found = await rows(`WITH q AS (SELECT websearch_to_tsquery('english', $1) AS tsq),
+       matched AS (
+         SELECT p.*, q.tsq,
+                CASE WHEN p.title ILIKE $2 THEN 0
+                     WHEN p.title ILIKE $3 THEN 1
+                     WHEN NOT (p."tagPath" = ANY($4::text[])) AND ${prose} ILIKE $3 THEN 2
+                     ELSE 3 END AS tier,
+                ts_rank_cd(p.search_tsv, q.tsq, ${FTS_RANK_NORMALIZATION}) AS fts
+           FROM ${PAGE} p CROSS JOIN q
+          WHERE p."siteId" = $5 AND NOT (p."tagPath" = '' AND p.slug = '')
+            AND ($6::text IS NOT NULL OR NOT (p."tagPath" = ANY($4::text[])))
+            AND ($6::text IS NULL OR p."tagPath" = $6)
+            AND (p.title ILIKE $3
+                 OR (NOT (p."tagPath" = ANY($4::text[]))
+                     AND (${prose} ILIKE $3 OR (q.tsq IS NOT NULL AND p.search_tsv @@ q.tsq))))
+       ),
+       paged AS (
+         SELECT *, count(*) OVER ()::int AS total FROM matched
+          ORDER BY tier, CASE WHEN tier = 0 THEN title END, CASE WHEN tier = 3 THEN fts END DESC, "updatedAt" DESC
+          LIMIT $7::int OFFSET $8::int
+       )
+       SELECT ${COLUMNS}, tier, total,
+              CASE WHEN tier = 3 THEN ts_headline('english', ${proseSql()}, tsq, '${HEADLINE_OPTIONS}') END AS headline
+         FROM paged
+        ORDER BY tier, CASE WHEN tier = 0 THEN title END, CASE WHEN tier = 3 THEN fts END DESC, "updatedAt" DESC`, query.trim(), `${term}%`, `%${term}%`, hidden, site, tagPath, take, skip);
+        const items = found.map(({ tier, total: _, headline, content, ...row }) => ({
+            ...row,
+            score: tier,
+            snippet: (headline ? decodeEntities(headline).replace(/\s+/g, ' ').trim() : '')
+                || matchSnippet(content, query, () => opening({ content: content, metadata: row.metadata })),
+        }));
+        return { items, total: found[0]?.total ?? 0 };
+    };
+    /**
+     * A page's revisions, newest first, each with what changed against the one
+     * before it. `limit` counts what is returned; one more is read so the oldest
+     * shown is diffed against its real predecessor, not against nothing.
+     */
+    const history = async (pageId, { limit = 50, offset = 0 } = {}) => {
+        const revisions = await rows(`SELECT ${REVISION_COLUMNS} FROM ${REVISION} WHERE "pageId" = $1 ORDER BY "createdAt" DESC, id DESC LIMIT $2::int OFFSET $3::int`, pageId, limit + 1, offset);
+        const entries = withChanges(revisions, { containers: o.containers });
+        return revisions.length > limit ? entries.slice(0, limit) : entries;
+    };
+    const revision = (pageId, revisionId) => one(`SELECT ${REVISION_COLUMNS} FROM ${REVISION} WHERE "pageId" = $1 AND id = $2`, pageId, revisionId);
+    const create = async (input) => {
+        if (input.title === undefined || input.content === undefined)
+            throw new HttpError(400, 'A new page needs a title and content');
+        const page = await one(`WITH up AS (
+         INSERT INTO ${PAGE} ("siteId", "tagPath", slug, title, content, metadata, version, "authorId", "lastVerifiedAt")
+         VALUES ($1, $2, $3, $4, $5::jsonb, $6::jsonb, $7, $8, CASE WHEN $9::boolean THEN now() END)
+         ON CONFLICT ("siteId", "tagPath", slug) DO NOTHING
+         RETURNING ${COLUMNS}
+       ), rev AS (
+         INSERT INTO ${REVISION} ("pageId", title, content, version, "changeType", message, "authorId")
+         SELECT id, title, content, version, 'major', $10::text, "authorId" FROM up
+       )
+       SELECT * FROM up`, site, input.tagPath, input.slug, input.title, JSON.stringify(input.content), JSON.stringify(input.metadata ?? {}), INITIAL_VERSION, input.authorId ?? null, input.verified === true, input.message ?? 'Initial version');
+        if (!page)
+            throw conflict('A page at that path was created while this one was being written');
+        return { page, created: true, changeType: 'major', summary: 'page created' };
+    };
+    /**
+     * Create or update a page, writing a revision whenever its title or blocks
+     * changed. The bump is the diff's (`major` for structure, `minor` for prose)
+     * unless `change` overrides it; a metadata-only save with no `change` moves no
+     * version and writes no revision, the way an infobox fix has always behaved.
+     */
+    const save = async (input) => {
+        const existing = await get(input.tagPath, input.slug);
+        if (!existing)
+            return create(input);
+        if (input.baseVersion !== undefined && input.baseVersion !== existing.version) {
+            throw conflict(`This page changed since it was opened: it is at v${existing.version} now, not v${input.baseVersion}. Reload it and apply the edit again.`);
+        }
+        const slug = input.newSlug && input.newSlug !== existing.slug ? input.newSlug : existing.slug;
+        if (slug !== existing.slug && (await get(existing.tagPath, slug)))
+            throw conflict('A page with that slug already exists in this category');
+        const title = input.title ?? existing.title;
+        const content = input.content ?? existing.content;
+        const diff = computeRevisionDiff({
+            currentVersion: existing.version,
+            oldContent: existing.content,
+            newContent: content,
+            oldTitle: existing.title,
+            newTitle: title,
+            containers: o.containers,
+        });
+        const changeType = input.change ?? diff.changeType;
+        const version = changeType === 'none' ? existing.version : bump(existing.version, changeType);
+        const page = await one(`WITH up AS (
+         UPDATE ${PAGE} SET title = $3, slug = $4, content = $5::jsonb, metadata = COALESCE($6::jsonb, metadata),
+                version = $7, "updatedAt" = now(),
+                "lastVerifiedAt" = CASE WHEN $8::boolean THEN now() ELSE "lastVerifiedAt" END
+          WHERE id = $1 AND version = $2
+          RETURNING ${COLUMNS}
+       ), rev AS (
+         INSERT INTO ${REVISION} ("pageId", title, content, version, "changeType", message, "authorId")
+         SELECT id, title, content, version, $9::text, $10::text, $11::text FROM up WHERE $9::text <> 'none'
+       )
+       SELECT * FROM up`, existing.id, existing.version, title, slug, JSON.stringify(content), input.metadata === undefined ? null : JSON.stringify(input.metadata), version, input.verified === true, changeType, input.message ?? diff.summary, input.authorId ?? null);
+        if (!page)
+            throw conflict('This page was saved by someone else while this edit was being written. Reload it and apply the edit again.');
+        return { page, created: false, changeType, summary: diff.summary };
+    };
+    /** Put a page back as a revision had it, as a major change of its own. */
+    const restore = async (tagPath, slug, revisionId, by = {}) => {
+        const page = await get(tagPath, slug);
+        if (!page)
+            throw new HttpError(404, 'Page not found');
+        const rev = await revision(page.id, revisionId);
+        if (!rev)
+            throw new HttpError(404, 'Revision not found');
+        return save({
+            tagPath, slug, title: rev.title, content: rev.content, authorId: by.authorId,
+            change: 'major', message: `Restored to v${rev.version}`, baseVersion: page.version,
+        });
+    };
+    /** Deletes a page and its history. True when there was one to delete. */
+    const remove = async (tagPath, slug) => (await rows(`DELETE FROM ${PAGE} WHERE "siteId" = $1 AND "tagPath" = $2 AND slug = $3 RETURNING id`, site, tagPath, slug)).length > 0;
+    /** Stamps a page's facts as checked without editing it. */
+    const verify = async (tagPath, slug) => (await rows(`UPDATE ${PAGE} SET "lastVerifiedAt" = now() WHERE "siteId" = $1 AND "tagPath" = $2 AND slug = $3 RETURNING id`, site, tagPath, slug)).length > 0;
+    return {
+        siteId: site, hidden, isHidden,
+        get, getById, list, articles, subtree, recent, byIds, refs, corpus, stats, search,
+        history, revision, save, restore, remove, verify,
+    };
+}

package/dist/taxonomy.d.ts

@@ -149,7 +149,11 @@ export interface Taxonomy {
     metadataRows: (tagPath: string, page: {
         metadata?: unknown;
     }) => MetadataRow[];
-    /** Whether a set has outgrown a grid and needs the A–Z index. */
+    /**
+     * Whether a set has outgrown a grid: the one size rule a hub's browsing
+     * controls read. `alphaControls` applies it; a sort toggle reads it too, with
+     * the same unfiltered count, so the two appear and vanish together.
+     */
     needsAlphaIndex: (pageCount: number) => boolean;
     href: (tagPath: string, state: CategoryState) => string;
     rankRelated: <T extends FacetablePage>(page: T, siblings: T[], tagPath: string, limit?: number) => RelatedRanking<T>;

package/dist/text.d.ts

@@ -28,6 +28,12 @@ export type BannerVariant = 'stub' | 'unsourced' | 'outdated' | 'promotional' |
  * the markdown twin and the MDX export all render the same six strings.
  */
 export declare const BANNER_LABELS: Record<BannerVariant, string>;
+/**
+ * The sentence under each banner when the block carries none of its own,
+ * naming no wiki, so any wiki may show it. A wiki that words a notice for its
+ * own subject (radix-wiki's names the Radix ecosystem) passes its own.
+ */
+export declare const BANNER_MESSAGES: Record<BannerVariant, string>;
 /**
  * The banner variants as an editor's option list, in the order a writer meets
  * them: the two that describe a gap first, then the three that describe a flaw.

package/dist/text.js

@@ -68,6 +68,19 @@ export const BANNER_LABELS = {
     cleanup: 'Needs cleanup',
     coi: 'Conflict of interest',
 };
+/**
+ * The sentence under each banner when the block carries none of its own,
+ * naming no wiki, so any wiki may show it. A wiki that words a notice for its
+ * own subject (radix-wiki's names the Radix ecosystem) passes its own.
+ */
+export const BANNER_MESSAGES = {
+    stub: 'This article is a stub. You can help by expanding it.',
+    unsourced: 'This article needs additional citations for verification. Please add references to reliable sources.',
+    outdated: 'Some information here may be out of date. Please help bring it up to date.',
+    promotional: 'This article may read like an advertisement. Please help rewrite it from a neutral point of view.',
+    cleanup: "This article may require cleanup to meet the wiki's quality standards.",
+    coi: 'This page may have been written by the subject it describes, and may need review for a neutral point of view.',
+};
 /**
  * The banner variants as an editor's option list, in the order a writer meets
  * them: the two that describe a gap first, then the three that describe a flaw.

package/dist/tree.d.ts

@@ -0,0 +1,95 @@
+import type { MetadataKeyDefinition } from './taxonomy.js';
+import type { ListSort } from './store.js';
+export interface WikiNode {
+    /** The path segment. A root node with the empty slug stands for the home page. */
+    slug: string;
+    name: string;
+    description?: string;
+    /** A glyph or an icon name; the app draws it. */
+    icon?: string;
+    /**
+     * The article that *is* this category's topic, as a full `tagPath/slug`. It
+     * need not live in the category. Inherited: the nearest declaration down the
+     * trail is the series a page under it belongs to.
+     */
+    mainArticle?: string;
+    /** Inherited: a node beneath a hidden one is back office too. */
+    hidden?: boolean;
+    /** A listing's default order. Inherited. */
+    sort?: ListSort;
+    /** Accumulated down the trail, in declaration order. */
+    metadataKeys?: readonly MetadataKeyDefinition[];
+    /** Slugs under this node in the order a listing should lead with; the rest follow. */
+    pages?: readonly string[];
+    children?: readonly WikiNode[];
+}
+export interface Resolved<N extends WikiNode> {
+    node: N | null;
+    /** Every node from the root to this one. Empty when the path is not in the tree. */
+    trail: N[];
+    valid: boolean;
+    hidden: boolean;
+    sort: ListSort;
+    mainArticle?: string;
+    metadataKeys: MetadataKeyDefinition[];
+}
+export interface TreePath<N extends WikiNode> {
+    path: string;
+    node: N;
+    hidden: boolean;
+    depth: number;
+}
+export interface TreeOptions {
+    /** Keys every page carries whatever its category, such as a quality grade. Listed after the trail's. */
+    globalKeys?: readonly MetadataKeyDefinition[];
+}
+export declare function createTree<N extends WikiNode>(nodes: readonly N[], opts?: TreeOptions): {
+    nodes: readonly N[];
+    resolve: (tagPath: string | readonly string[]) => Resolved<N>;
+    paths: () => TreePath<N>[];
+    /** Back-office paths, which a listing leaves out unless it names one. Pass to `wikiStore({ hidden })`. */
+    hiddenPaths: string[];
+    isValid: (tagPath: string | readonly string[]) => boolean;
+    node: (tagPath: string | readonly string[]) => N | null;
+    metadataKeys: (tagPath: string | readonly string[]) => MetadataKeyDefinition[];
+    /** A category's name, or its last segment unslugged when the tree does not know it. */
+    label: (tagPath: string | readonly string[]) => string;
+    /**
+     * One crumb per segment, so the trail can never be shorter than the URL. A
+     * segment the tree knows is a link to its category; one it does not is text.
+     */
+    crumbs: (tagPath: string | readonly string[]) => {
+        path: string;
+        label: string;
+        linked: boolean;
+    }[];
+};
+export type WikiTree<N extends WikiNode = WikiNode> = ReturnType<typeof createTree<N>>;
+/** The views a page or a category has beside itself, each a final path segment. */
+export declare const WIKI_MODES: readonly ["edit", "history"];
+export type WikiMode = (typeof WIKI_MODES)[number];
+export interface ParsedWikiPath<M extends string = WikiMode> {
+    type: 'home' | 'category' | 'page' | 'invalid';
+    tagPath: string;
+    slug: string;
+    mode: M | null;
+}
+/**
+ * What a path means: the home page, a category (its hub article is the empty
+ * slug), a page, or nothing, each optionally in one of `modes`. A path that is
+ * itself a category wins over a mode suffix, so a category named `history` is
+ * still reachable; `/<category>/edit` edits the category's hub.
+ *
+ * Static routes are the app's: check them before calling this.
+ */
+export declare function parseWikiPath<M extends string = WikiMode>(tree: Pick<WikiTree, 'isValid'>, segments?: readonly string[], { modes }?: {
+    modes?: readonly M[];
+}): ParsedWikiPath<M>;
+/**
+ * A slug no page in `tagPath` can hold, because `parseWikiPath` reads that URL
+ * as something else: a mode, or a child category. Creating a page treats it as
+ * taken.
+ */
+export declare function isReservedSlug(tree: Pick<WikiTree, 'isValid'>, tagPath: string, slug: string, modes?: readonly string[]): boolean;
+/** A page's path: the category for its hub, `/` for the home page. */
+export declare function wikiPath(tagPath: string, slug: string): string;