wiki-formant 0.60.0 → 0.61.0

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/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;

package/dist/tree.js

@@ -0,0 +1,122 @@
+// tree.ts – a wiki's category tree, and what a URL path means against it.
+//
+// Three wikis declared their tree three ways: radix-wiki's `TAG_HIERARCHY`
+// (slug + children, keys and sort inherited down the trail), caper's
+// `WIKI_CATEGORIES` (each node naming its full `tagPath`, with a `categoryTrail`
+// walk of its own) and acuiq's `WIKI_SECTIONS` (one flat level). Each then
+// re-derived the same answers by hand: is this a real category, which metadata
+// keys apply here, which article is this page "part of a series on", what sort
+// does a listing default to, which paths are back office.
+//
+// The node holds what every wiki reads; anything only one wiki reads (an XRD
+// threshold, a band, an icon set) rides on the node as an extra field, and the
+// app folds it from `trail`. Pure: no data access, so a client component and
+// the server route read paths through the same parser.
+const segmentsOf = (tagPath) => typeof tagPath === 'string' ? tagPath.split('/').filter(Boolean) : tagPath.filter(Boolean);
+export function createTree(nodes, opts = {}) {
+    const globalKeys = [...(opts.globalKeys ?? [])];
+    const cache = new Map();
+    function resolve(tagPath) {
+        const segments = segmentsOf(tagPath);
+        const key = segments.join('/');
+        const hit = cache.get(key);
+        if (hit)
+            return hit;
+        const trail = [];
+        const metadataKeys = [];
+        let level = nodes;
+        let sort = 'title';
+        let mainArticle;
+        let hidden = false;
+        for (const segment of segments) {
+            const node = level.find(n => n.slug === segment);
+            if (!node) {
+                const missing = { node: null, trail: [], valid: false, hidden: false, sort: 'title', metadataKeys: [] };
+                cache.set(key, missing);
+                return missing;
+            }
+            trail.push(node);
+            if (node.metadataKeys)
+                metadataKeys.push(...node.metadataKeys);
+            if (node.sort)
+                sort = node.sort;
+            if (node.mainArticle)
+                mainArticle = node.mainArticle;
+            hidden ||= !!node.hidden;
+            level = node.children ?? [];
+        }
+        metadataKeys.push(...globalKeys);
+        const resolved = { node: trail.at(-1) ?? null, trail, valid: trail.length > 0, hidden, sort, mainArticle, metadataKeys };
+        cache.set(key, resolved);
+        return resolved;
+    }
+    /** Every path in the tree, depth first, parents before children. */
+    function paths(level = nodes, parent = '', inherited = false, depth = 0) {
+        return level.flatMap(node => {
+            const path = parent ? `${parent}/${node.slug}` : node.slug;
+            const hidden = inherited || !!node.hidden;
+            return [{ path, node: node, hidden, depth }, ...paths(node.children ?? [], path, hidden, depth + 1)];
+        });
+    }
+    const all = paths();
+    return {
+        nodes,
+        resolve,
+        paths: () => all,
+        /** Back-office paths, which a listing leaves out unless it names one. Pass to `wikiStore({ hidden })`. */
+        hiddenPaths: all.filter(p => p.hidden && p.path).map(p => p.path),
+        isValid: (tagPath) => resolve(tagPath).valid,
+        node: (tagPath) => resolve(tagPath).node,
+        metadataKeys: (tagPath) => resolve(tagPath).metadataKeys,
+        /** A category's name, or its last segment unslugged when the tree does not know it. */
+        label: (tagPath) => resolve(tagPath).node?.name ?? (segmentsOf(tagPath).at(-1) ?? '').replace(/-/g, ' '),
+        /**
+         * 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) => {
+            const segments = segmentsOf(tagPath);
+            return segments.map((segment, i) => {
+                const path = segments.slice(0, i + 1).join('/');
+                const node = resolve(path).node;
+                return { path, label: node?.name ?? segment.replace(/-/g, ' '), linked: !!node };
+            });
+        },
+    };
+}
+/** The views a page or a category has beside itself, each a final path segment. */
+export const WIKI_MODES = ['edit', 'history'];
+/**
+ * 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 function parseWikiPath(tree, segments = [], { modes = WIKI_MODES } = {}) {
+    const parts = segments.filter(Boolean);
+    const last = parts.at(-1);
+    const mode = last && modes.includes(last) && !tree.isValid(parts) ? last : null;
+    const path = mode ? parts.slice(0, -1) : parts;
+    const invalid = { type: 'invalid', tagPath: '', slug: '', mode: null };
+    if (!path.length)
+        return { type: 'home', tagPath: '', slug: '', mode };
+    if (tree.isValid(path))
+        return { type: 'category', tagPath: path.join('/'), slug: '', mode };
+    if (path.length < 2 || !tree.isValid(path.slice(0, -1)))
+        return invalid;
+    return { type: 'page', tagPath: path.slice(0, -1).join('/'), slug: path.at(-1), mode };
+}
+/**
+ * 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 function isReservedSlug(tree, tagPath, slug, modes = WIKI_MODES) {
+    return modes.includes(slug) || tree.isValid([...segmentsOf(tagPath), slug]);
+}
+/** A page's path: the category for its hub, `/` for the home page. */
+export function wikiPath(tagPath, slug) {
+    return `/${[tagPath, slug].filter(Boolean).join('/')}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",
@@ -117,6 +117,16 @@
       "import": "./dist/search.js",
       "default": "./dist/search.js"
     },
+    "./store": {
+      "types": "./dist/store.d.ts",
+      "import": "./dist/store.js",
+      "default": "./dist/store.js"
+    },
+    "./tree": {
+      "types": "./dist/tree.d.ts",
+      "import": "./dist/tree.js",
+      "default": "./dist/tree.js"
+    },
     "./feed": {
       "types": "./dist/feed.d.ts",
       "import": "./dist/feed.js",
@@ -296,6 +306,7 @@
     "sanitize-html": "^2.17.7"
   },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.3.9",
     "@radixdlt/rola": "^2.1.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
@@ -308,12 +319,12 @@
     "typescript": "^5.9.0"
   },
   "peerDependencies": {
+    "@radixdlt/rola": ">=2",
+    "@vercel/blob": ">=2",
+    "jose": ">=6",
     "pg": ">=8",
     "react": ">=18",
-    "jose": ">=6",
-    "@radixdlt/rola": ">=2",
-    "sharp": ">=0.33",
-    "@vercel/blob": ">=2"
+    "sharp": ">=0.33"
   },
   "peerDependenciesMeta": {
     "react": {

package/prisma/wiki.prisma

@@ -0,0 +1,62 @@
+// Shipped by wiki-formant (`npx prisma-models`). Edit it there, not here:
+// `prisma-models --check` fails on a copy that has drifted.
+//
+// A wiki's pages and their revisions, read and written by wiki-formant/store.
+// Its SQL names these tables and columns as written, so they carry no @@map.
+// `siteId` is "" in an app that serves one wiki; a multi-tenant app keys every
+// row to its site, and caper keys a DAO's own layer to the DAO.
+//
+// A page lives at `tagPath` + `slug`. The empty slug is the category's own hub
+// article, and `''/''` the home page. Everything a page says beyond its blocks
+// and title is `metadata`: facet keys, an excerpt, a banner, a subtitle. Which
+// keys a listing may carry is the tree's answer, not the column's.
+//
+// Ids and timestamps default in the database, so the store's raw SQL and a
+// Prisma client write the same rows. `authorId` is the app's own user key, as
+// text; it has no relation because no two apps key their users alike.
+
+model WikiPage {
+  id             String         @id @default(dbgenerated("(gen_random_uuid())::text"))
+  siteId         String         @default("")
+  tagPath        String         @default("")
+  slug           String
+  title          String
+  content        Json           @default("[]")
+  metadata       Json           @default("{}")
+  version        String         @default("1.0.0")
+  authorId       String?
+  lastVerifiedAt DateTime?      @db.Timestamptz(3)
+  createdAt      DateTime       @default(now()) @db.Timestamptz(3)
+  updatedAt      DateTime       @default(now()) @db.Timestamptz(3)
+  // Title at weight A, block prose at B, GENERATED ALWAYS ... STORED by
+  // `npx fts-ddl '"WikiPage"'`. Declared only so `db push` leaves it alone:
+  // push must never create it, since Prisma would write a plain column that
+  // stays empty. Read only through raw SQL.
+  searchTsv      Unsupported("tsvector")? @map("search_tsv")
+  revisions      WikiRevision[]
+
+  @@unique([siteId, tagPath, slug])
+  @@index([siteId, tagPath, updatedAt])
+  @@index([siteId, updatedAt])
+  // Declared for the same reason: undeclared, push drops it.
+  @@index([searchTsv], type: Gin, map: "WikiPage_search_tsv_idx")
+}
+
+// One row per saved version, newest last. A revision holds the whole page as
+// it was saved; what changed is diffed from consecutive rows when it is read,
+// so a script's revision and the editor's carry the same history.
+model WikiRevision {
+  id         String   @id @default(dbgenerated("(gen_random_uuid())::text"))
+  pageId     String
+  title      String
+  content    Json
+  version    String
+  changeType String
+  message    String?
+  authorId   String?
+  createdAt  DateTime @default(now()) @db.Timestamptz(3)
+  page       WikiPage @relation(fields: [pageId], references: [id], onDelete: Cascade)
+
+  @@index([pageId, createdAt])
+  @@index([authorId, createdAt])
+}