@terrafirmagreg-team/guide 0.0.0-stage → 1.2.0

package/src/lib/markdown/book.ts

@@ -0,0 +1,74 @@
+import type {
+  GuideIndex,
+  GuidePage,
+  GuidePagePayload,
+} from '@terrafirmagreg-team/guide/types';
+import { guideBookHref } from '@terrafirmagreg-team/guide/lib/paths';
+import type { GuideMarkdownCtx } from './ctx';
+import { guidePageMarkdown } from './page';
+import { guideTextMarkdown } from './text';
+
+export function guideEntryMarkdown(
+  entry: { name?: string; pages?: GuidePage[] },
+  ctx: GuideMarkdownCtx,
+  payload?: Pick<GuidePagePayload, 'extras'>,
+): string {
+  const body = (entry.pages ?? [])
+    .map((page) => guidePageMarkdown(page, ctx, payload))
+    .filter(Boolean)
+    .join('\n\n');
+  return `# ${entry.name ?? 'Guide Entry'}\n\n${body}\n`;
+}
+
+export function guideOverviewMarkdown(
+  overview: GuideIndex,
+  ctx: GuideMarkdownCtx,
+): string {
+  const parts: string[] = [`# ${overview.book?.name ?? overview.bookId ?? 'Guide'}`];
+  if (overview.book?.landingText) {
+    const md = guideTextMarkdown(overview.book.landingText, ctx);
+    if (md) parts.push(md);
+  }
+  for (const cat of overview.categories) {
+    parts.push(`## ${cat.name}`);
+    const items = cat.entries.map((ref) => {
+      const href = guideBookHref(
+        ctx.dataset,
+        undefined,
+        overview.modId,
+        overview.bookPath ?? '',
+        ref.id,
+      );
+      return `- [${ref.name}](${href})`;
+    });
+    if (items.length) parts.push(items.join('\n'));
+  }
+  return `${parts.filter(Boolean).join('\\')}\n`;
+}
+
+export function guideCategoryMarkdown(
+  overview: GuideIndex,
+  categoryId: string,
+  ctx: GuideMarkdownCtx,
+): string {
+  const cat = overview.categories.find((item) => item.id === categoryId);
+  if (!cat) return '';
+  const parts: string[] = [`# ${cat.name}`];
+  if (cat.description) {
+    const md = guideTextMarkdown(cat.description, ctx);
+    if (md) parts.push(md);
+  }
+  const items = cat.entries.map((ref) => {
+    const href = guideBookHref(
+      ctx.dataset,
+      undefined,
+      overview.modId,
+      overview.bookPath ?? '',
+      ref.id,
+    );
+    return `- [${ref.name}](${href})`;
+  });
+  if (items.length) parts.push(items.join('\n'));
+  return `${parts.filter(Boolean).join('\\')}\n`;
+}
+

package/src/lib/markdown/ctx.ts

@@ -0,0 +1,28 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { GuideReferenceContext } from '@terrafirmagreg-team/guide/types';
+
+export type GuideMarkdownCtx = {
+  dataset: DatasetRef;
+  lang: Lang;
+  langMap: Record<string, string>;
+  keybinds?: Record<string, string>;
+  macros?: Record<string, string>;
+  questLinks?: Record<string, { filename: string; questId: string }>;
+  categoryByEntry: Map<string, string>;
+  entryNames?: Map<string, string>;
+  modId: string;
+  bookPath: string;
+};
+
+export function refCtx(ctx: GuideMarkdownCtx): GuideReferenceContext {
+  return {
+    dataset: ctx.dataset,
+    lang: ctx.lang,
+    modId: ctx.modId,
+    bookPath: ctx.bookPath,
+    categoryByEntry: ctx.categoryByEntry,
+    questLinks: ctx.questLinks,
+  };
+}
+

package/src/lib/markdown/index.ts

@@ -0,0 +1,9 @@
+export {
+  guideCategoryMarkdown,
+  guideEntryMarkdown,
+  guideOverviewMarkdown,
+} from './book';
+export type { GuideMarkdownCtx } from './ctx';
+export { guidePageMarkdown } from './page';
+export { guideTextMarkdown } from './text';
+

package/src/lib/markdown/page.ts

@@ -0,0 +1,153 @@
+import type {
+  GuidePage,
+  GuidePagePayload,
+} from '@terrafirmagreg-team/guide/types';
+import { classify, isIndexPage, pageTexts } from '@terrafirmagreg-team/guide/lib/page-kind';
+import { guideLink } from '@terrafirmagreg-team/guide/lib/reference';
+import { bareId } from '@terrafirmagreg-team/guide/lib/paths';
+import { guideEmbeds } from '@terrafirmagreg-team/guide/lib/embeds';
+import { texturePublicUrl } from '@terrafirmagreg-team/dump/lib/dump/assets/urls';
+import { collectItemIds } from '@terrafirmagreg-team/guide/lib/data/parse';
+import { stackDisplayName } from '@terrafirmagreg-team/dump/lib/dump/assets/lang/names';
+import { type GuideMarkdownCtx, refCtx } from './ctx';
+import { guideTextMarkdown } from './text';
+import { tableMarkdown } from './table';
+
+function blockTitle(page: GuidePage): string {
+  return typeof page.title === 'string' && page.title
+    ? page.title
+    : typeof page.name === 'string'
+      ? page.name
+      : '';
+}
+
+export function guidePageMarkdown(
+  page: GuidePage,
+  ctx: GuideMarkdownCtx,
+  payload?: Pick<GuidePagePayload, 'extras'>,
+): string {
+  const kind = classify(page.type);
+  const title = blockTitle(page);
+  const parts: string[] = [];
+  if (title && kind !== 'text') parts.push(`### ${title}`);
+
+  switch (kind) {
+    case 'empty':
+      break;
+    case 'text': {
+      if (title) parts.push(`### ${title}`);
+      if (isIndexPage(page, ctx.langMap)) {
+        for (const raw of pageTexts(page)) {
+          const lines = guideTextMarkdown(raw, ctx).split('\n').filter(Boolean);
+          parts.push(lines.map((l) => (l.startsWith('- ') ? l : `- ${l}`)).join('\n'));
+        }
+      } else {
+        for (const raw of pageTexts(page)) {
+          const md = guideTextMarkdown(raw, ctx);
+          if (md) parts.push(md);
+        }
+      }
+      break;
+    }
+    case 'image': {
+      const images = [
+        ...(page.images ?? []),
+        ...(typeof page.image === 'string' ? [page.image] : []),
+      ];
+      for (const id of images) {
+        const url = texturePublicUrl(ctx.dataset, id);
+        if (url) parts.push(`![${title || id}](${url})`);
+      }
+      for (const raw of pageTexts(page)) parts.push(guideTextMarkdown(raw, ctx));
+      break;
+    }
+    case 'recipe': {
+      const ids = [
+        ...(page.recipes ?? []),
+        ...(typeof page.recipe === 'string' ? [page.recipe] : []),
+      ];
+      for (const id of ids) {
+        const recipe = payload?.extras?.recipes[id];
+        const label = recipe ? guideEmbeds().recipe?.title(recipe, ctx.langMap) : id;
+        parts.push(`- [${label}](${guideEmbeds().recipe?.href(ctx.dataset, undefined, { id })})`);
+      }
+      for (const raw of pageTexts(page)) parts.push(guideTextMarkdown(raw, ctx));
+      break;
+    }
+    case 'spotlight': {
+      const ids = collectItemIds(page.item);
+      for (const id of ids) {
+        const name = stackDisplayName(ctx.langMap, id, 'item');
+        parts.push(`**${name}**`);
+      }
+      for (const raw of pageTexts(page)) parts.push(guideTextMarkdown(raw, ctx));
+      break;
+    }
+    case 'entity': {
+      const id = typeof page.entity === 'string' ? page.entity : '';
+      const name =
+        (id ? payload?.extras?.entityNames[id] : undefined) ??
+        (id ? stackDisplayName(ctx.langMap, id, 'entity') : id);
+      if (name) parts.push(`**${name}**`);
+      for (const raw of pageTexts(page)) parts.push(guideTextMarkdown(raw, ctx));
+      break;
+    }
+    case 'multiblock':
+    case 'multimultiblock': {
+      for (const raw of pageTexts(page)) parts.push(guideTextMarkdown(raw, ctx));
+      break;
+    }
+    case 'link': {
+      const target = page.url || page.link || page.entry;
+      const label =
+        (typeof page.link_text === 'string' && page.link_text) ||
+        (typeof page.text === 'string' && page.text) ||
+        target ||
+        '';
+      const { href } = guideLink(
+        { link: typeof target === 'string' ? target : undefined },
+        refCtx(ctx),
+      );
+      parts.push(href ? `[${label}](${href})` : label);
+      break;
+    }
+    case 'relations': {
+      for (const target of page.entries ?? []) {
+        const { href } = guideLink({ link: target }, refCtx(ctx));
+        const label =
+          ctx.entryNames?.get(target) ??
+          ctx.entryNames?.get(bareId(target)) ??
+          target;
+        parts.push(`- [${label}](${href ?? ''})`);
+      }
+      break;
+    }
+    case 'quest': {
+      const id = page.trigger || page.quest || page.link || '';
+      const { href } = guideLink({ link: id }, refCtx(ctx));
+      const hit = id ? ctx.questLinks?.[id] : undefined;
+      const url =
+        href ??
+        (hit
+          ? guideEmbeds().quest?.href(ctx.dataset, undefined, {
+              category: hit.filename,
+              id: hit.questId,
+            })
+          : undefined);
+      parts.push(url ? `- [${id}](${url})` : `- ${id}`);
+      for (const raw of pageTexts(page)) parts.push(guideTextMarkdown(raw, ctx));
+      break;
+    }
+    case 'table': {
+      const md = tableMarkdown(page, ctx);
+      if (md) parts.push(md);
+      break;
+    }
+    default: {
+      for (const raw of pageTexts(page)) parts.push(guideTextMarkdown(raw, ctx));
+      break;
+    }
+  }
+  return parts.filter(Boolean).join('\n\n');
+}
+

package/src/lib/markdown/table.ts

@@ -0,0 +1,36 @@
+import type { GuidePage } from '@terrafirmagreg-team/guide/types';
+import type { GuideTableCell } from '@terrafirmagreg-team/guide/lib/data/dto';
+import type { GuideMarkdownCtx } from './ctx';
+import { guideTextMarkdown } from './text';
+
+function cellText(cell: string | GuideTableCell | undefined): string {
+  if (typeof cell === 'string') return cell;
+  if (!cell || typeof cell !== 'object') return '';
+  const lines = Array.isArray(cell.texts)
+    ? cell.texts
+    : cell.text
+      ? [cell.text]
+      : [];
+  return lines.filter(Boolean).join(' ');
+}
+
+export function tableMarkdown(page: GuidePage, ctx: GuideMarkdownCtx): string {
+  const strings = page.strings ?? [];
+  const rows = strings
+    .map((row) => (Array.isArray(row) ? row : [row]))
+    .filter((row) => row.length);
+  const columns = Array.isArray(page.columns)
+    ? page.columns.map((c) => String(c))
+    : [];
+  const all = columns.length ? [columns, ...rows.map((r) => r.map(cellText))] : rows.map((r) => r.map(cellText));
+  if (!all.length) return '';
+  const width = Math.max(...all.map((row) => row.length));
+  const norm = (row: unknown[]) =>
+    Array.from({ length: width }, (_v, i) =>
+      guideTextMarkdown(String(row[i] ?? ''), ctx).replace(/\|/g, '\\|').replace(/\n+/g, ' '),
+    );
+  const lines = all.map((row) => `| ${norm(row).join(' | ')} |`);
+  lines.splice(1, 0, `| ${Array.from({ length: width }, () => '---').join(' | ')} |`);
+  return lines.join('\n');
+}
+

package/src/lib/markdown/text.ts

@@ -0,0 +1,40 @@
+import type { GuideFormatNode } from '@terrafirmagreg-team/guide/types';
+import { formatGuide, keybindLabels } from '@terrafirmagreg-team/guide/lib/format';
+import { guideLink } from '@terrafirmagreg-team/guide/lib/reference';
+import { type GuideMarkdownCtx, refCtx } from './ctx';
+
+function wrap(text: string, mark: string): string {
+  return text.replace(/^(\s*)(.*?)(\s*)$/s, (_m, a, b, c) =>
+    b ? `${a}${mark}${b}${mark}${c}` : `${a}${c}`,
+  );
+}
+
+function nodeMarkdown(node: GuideFormatNode, ctx: GuideMarkdownCtx): string {
+  if (node.type === 'break') return '\n';
+  if (node.type === 'keybind') {
+    return `\`${keybindLabels(node.value, ctx.langMap, ctx.keybinds ?? {}).label}\``;
+  }
+  if (node.type === 'command') return `\`${node.value}\``;
+  let text = node.value;
+  if (node.styles.includes('bold')) text = wrap(text, '**');
+  if (node.styles.includes('italic')) text = wrap(text, '_');
+  if (node.styles.includes('strike')) text = wrap(text, '~~');
+  if (node.link) {
+    const { href } = guideLink(node, refCtx(ctx));
+    if (href) text = `[${text.trim() || node.link}](${href})`;
+  }
+  return text;
+}
+
+export function guideTextMarkdown(
+  raw: string,
+  ctx: GuideMarkdownCtx,
+): string {
+  return formatGuide(raw, { macros: ctx.macros })
+    .map((node) => nodeMarkdown(node, ctx))
+    .join('')
+    .replace(/(^|\n)(\s*)• /g, '$1$2- ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+

package/src/lib/markdown-page.ts

@@ -0,0 +1,74 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { registerMarkdownProvider } from '@terrafirmagreg-team/mdx/lib/markdown';
+import { loadClientGuidePayload } from '@terrafirmagreg-team/guide/lib/client-payload';
+import { clientDumpLang } from '@terrafirmagreg-team/dump/lib/dump/client/dump';
+import { categoryMap } from '@terrafirmagreg-team/guide/lib/breadcrumb';
+import {
+  guideCategoryMarkdown,
+  guideEntryMarkdown,
+  guideOverviewMarkdown,
+  type GuideMarkdownCtx,
+} from '@terrafirmagreg-team/guide/lib/markdown';
+import type { GuideIndex } from '@terrafirmagreg-team/guide/types';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+
+export async function guideMarkdown(
+  req: Request,
+  dataset: DatasetRef | undefined,
+  lang: Lang,
+): Promise<Response | undefined> {
+  if (!dataset) return undefined;
+  const search = new URL(req.url).searchParams;
+  const langMap = await clientDumpLang(dataset, lang);
+  const payload = await loadClientGuidePayload(
+    dataset,
+    lang,
+    search.get('book') ?? undefined,
+    search.get('entry') ?? undefined,
+    search.get('cat') ?? undefined,
+    langMap,
+    {},
+  );
+  if (!payload) return undefined;
+  const overview: GuideIndex = {
+    status: 'ready',
+    root: '',
+    modId: payload.bookModId ?? payload.modId ?? '',
+    bookPath: payload.bookPath,
+    book: payload.book ?? null,
+    categories: payload.categories ?? [],
+    entries: payload.entries ?? [],
+    language: lang,
+    isFallback: false,
+  };
+  const ctx: GuideMarkdownCtx = {
+    dataset,
+    lang,
+    langMap,
+    keybinds: payload.extras?.keybinds,
+    macros: payload.book?.macros,
+    questLinks: payload.questLinks,
+    categoryByEntry: categoryMap(payload.categories ?? []),
+    entryNames: new Map(
+      (payload.entries ?? []).flatMap((row) =>
+        row.name ? [[row.id, row.name]] : [],
+      ),
+    ),
+    modId: overview.modId,
+    bookPath: payload.bookPath ?? '',
+  };
+  const markdown =
+    payload.kind === 'entry' && payload.entry
+      ? guideEntryMarkdown(payload.entry, ctx, payload)
+      : payload.kind === 'category' && payload.categoryId
+        ? guideCategoryMarkdown(overview, payload.categoryId, ctx)
+        : guideOverviewMarkdown(overview, ctx);
+  return new Response(markdown, {
+    headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
+  });
+}
+
+registerMarkdownProvider('guide', (req, { slugs, lang }) =>
+  guideMarkdown(req, slugs[0] ? { id: slugs[0] } : undefined, lang),
+);
+

package/src/lib/messages.ts

@@ -0,0 +1,14 @@
+export function guideMessage(
+  messages: Record<string, string>,
+  key: string,
+  vars?: Record<string, string | number>,
+): string {
+  let text = messages[key] ?? key;
+  if (vars) {
+    for (const [name, value] of Object.entries(vars)) {
+      text = text.replaceAll(`{${name}}`, String(value));
+    }
+  }
+  return text;
+}
+

package/src/lib/meta.ts

@@ -0,0 +1,10 @@
+import type { GuideMultiblock } from '@terrafirmagreg-team/guide/lib/data/dto';
+
+export function asMultiblock(
+  value: string | GuideMultiblock | undefined,
+): { id?: string; data?: GuideMultiblock } {
+  if (!value) return {};
+  if (typeof value === 'string') return { id: value };
+  return { data: value };
+}
+

package/src/lib/multiblock/index.ts

@@ -0,0 +1,9 @@
+import type { GuideMultiblock } from '@terrafirmagreg-team/guide/types';
+
+export function multiblockKey(
+  spec: { id?: string; data?: GuideMultiblock } | undefined,
+): string | undefined {
+  if (!spec) return undefined;
+  return spec.id ?? (spec.data ? `data:${JSON.stringify(spec.data)}` : undefined);
+}
+

package/src/lib/multiblock/url.ts

@@ -0,0 +1,75 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { asRecord, asString } from '@terrafirmagreg-team/dump/lib/dump/contract/read';
+import { splitDumpId } from '@terrafirmagreg-team/dump/lib/dump/paths';
+import { modelPublicUrl } from '@terrafirmagreg-team/dump/lib/dump/assets/urls';
+import {
+  clientDumpJson,
+  dumpModelUrl,
+} from '@terrafirmagreg-team/dump/lib/dump/client/dump';
+import { loadDatasetDump } from '@terrafirmagreg-team/dump/lib/dump/mods/load';
+import { createDatasetCache } from '@terrafirmagreg-team/dump/lib/dump/reader';
+import { loadMultiblockNameIndex } from '@terrafirmagreg-team/guide/lib/client/guides';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { GuideMultiblock } from '@terrafirmagreg-team/guide/types';
+
+async function sha256Hex(text: string): Promise<string> {
+  const bytes = new TextEncoder().encode(text);
+  const digest = await crypto.subtle.digest('SHA-256', bytes);
+  return [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+function inlineMultiblockHash(data: unknown): Promise<string> {
+  return sha256Hex(JSON.stringify(data));
+}
+
+const multiblockIndex = createDatasetCache(async (dataset: DatasetRef) => {
+  const dump = await loadDatasetDump(dataset);
+  const entries = await Promise.all(
+    (dump?.mods ?? []).map(async (ns) => {
+      const index = asRecord(
+        await clientDumpJson(
+          dataset,
+          `data/${ns.namespace}/models/multiblock.json`,
+        ),
+      );
+      return Object.entries(index ?? {}).map(
+        ([id, rel]) => [id, { ns: ns.namespace, rel: asString(rel) }] as const,
+      );
+    }),
+  );
+  return Object.fromEntries(entries.flat());
+});
+
+export async function glbFor(
+  dataset: DatasetRef,
+  _bookModId: string,
+  spec: { id?: string; data?: GuideMultiblock },
+  lang?: string,
+): Promise<string | null> {
+  if (spec.id) {
+    const direct = await dumpModelUrl(dataset, spec.id);
+    if (direct) return direct;
+    if (lang) {
+      const names = await loadMultiblockNameIndex(dataset, lang as Lang);
+      const named = names[spec.id.trim().toLowerCase()];
+      if (named) return glbFor(dataset, _bookModId, { data: named }, lang);
+    }
+    return null;
+  }
+  if (!spec.data) return null;
+  const hash = await inlineMultiblockHash(spec.data);
+  const index = await multiblockIndex(dataset);
+  for (const [id, { ns, rel }] of Object.entries(index)) {
+    if (id.includes(hash) || rel?.includes(hash)) {
+      return (
+        (await dumpModelUrl(dataset, id)) ??
+        modelPublicUrl(dataset, splitDumpId(id)?.ns ?? ns, rel) ??
+        null
+      );
+    }
+  }
+  return null;
+}
+

package/src/lib/names.ts

@@ -0,0 +1,37 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import type { AtlasBundle } from '@terrafirmagreg-team/dump/lib/dump/assets/atlas/dto';
+import { lookupSpriteInBundle } from '@terrafirmagreg-team/dump/lib/dump/assets/atlas/lookup';
+import { stackDisplayName } from '@terrafirmagreg-team/game/lib/entry/display';
+import { matchGuideEntryKey } from '@terrafirmagreg-team/guide/lib/reference/resolver';
+import type { GuideEntryRef } from '@terrafirmagreg-team/guide/types';
+
+export function spriteName(
+  dataset: DatasetRef,
+  langMap: Record<string, string>,
+  atlases: Record<string, AtlasBundle> | undefined,
+  id: string,
+): string {
+  const mod = id.replace(/^#/, '').split(':', 2)[0];
+  const langKey =
+    mod && !id.startsWith('#')
+      ? lookupSpriteInBundle(atlases?.[mod], id)?.sprite.langKey
+      : undefined;
+  return stackDisplayName(langMap, id, undefined, langKey);
+}
+
+export function entryRef(
+  refs: Map<string, GuideEntryRef>,
+  id: string,
+): GuideEntryRef | undefined {
+  const key = matchGuideEntryKey(refs.keys(), id);
+  return key !== undefined ? refs.get(key) : undefined;
+}
+
+export function entryLabel(
+  refs: Map<string, GuideEntryRef>,
+  langMap: Record<string, string>,
+  id: string,
+): string {
+  return entryRef(refs, id)?.name ?? stackDisplayName(langMap, id);
+}
+

package/src/lib/page-kind.ts

@@ -0,0 +1,118 @@
+import type { GuidePage } from '@terrafirmagreg-team/guide/types';
+import { langString } from '@terrafirmagreg-team/dump/lib/dump/assets/lang/names';
+
+export type PageKind =
+  | 'empty'
+  | 'text'
+  | 'image'
+  | 'recipe'
+  | 'spotlight'
+  | 'entity'
+  | 'multiblock'
+  | 'multimultiblock'
+  | 'link'
+  | 'relations'
+  | 'quest'
+  | 'table'
+  | 'unknown';
+
+const RECIPE_TYPES = new Set([
+  'recipe',
+  'crafting',
+  'smelting',
+  'blasting',
+  'smoking',
+  'campfire',
+  'smithing',
+  'stonecutting',
+  'knapping',
+  'anvil',
+  'welding',
+  'barrel',
+  'quern',
+  'loom',
+  'heat',
+  'drying',
+  'glassworking',
+]);
+
+export function classify(type: string | undefined): PageKind {
+  const raw = (type ?? '').toLowerCase().trim();
+  const value = raw.includes(':') ? raw.slice(raw.indexOf(':') + 1) : raw;
+  if (!value || value === 'text') return 'text';
+  if (value === 'empty') return 'empty';
+  if (value === 'image') return 'image';
+  if (value === 'spotlight') return 'spotlight';
+  if (value === 'entity') return 'entity';
+  if (value === 'multiblock') return 'multiblock';
+  if (value === 'multimultiblock') return 'multimultiblock';
+  if (value === 'link') return 'link';
+  if (value === 'relations') return 'relations';
+  if (value === 'quest') return 'quest';
+  if (value === 'table' || value === 'table_small') return 'table';
+  if (value.endsWith('_recipe') || RECIPE_TYPES.has(value)) return 'recipe';
+  return 'unknown';
+}
+
+export function pageTexts(page: GuidePage): string[] {
+  if (Array.isArray(page.texts)) {
+    return page.texts.filter(
+      (text): text is string => typeof text === 'string' && Boolean(text),
+    );
+  }
+  return typeof page.text === 'string' && page.text ? [page.text] : [];
+}
+
+const INDEX_BULLET = /\$\(li\d*\)/;
+const INDEX_BULLET_ALL = /\$\(li\d*\)/g;
+const MACRO = /\$\([^)]*\)/g;
+const INDEX_LABEL_MAX = 48;
+
+function linkListOnly(text: string): boolean {
+  if (!INDEX_BULLET.test(text)) return false;
+  const items = text.split(INDEX_BULLET_ALL);
+  const head = (items[0] ?? '').replace(MACRO, '').trim();
+  if (head) return false;
+  const entries = items.slice(1).filter((item) => item.trim());
+  return (
+    entries.length > 0 &&
+    entries.every((item) => {
+      const plain = item.replace(MACRO, '').trim();
+      return (
+        plain.length <= INDEX_LABEL_MAX &&
+        (item.includes('$(l:') ||
+          item.includes('$(url:') ||
+          !/[.!?]/.test(plain))
+      );
+    })
+  );
+}
+
+export function isIndexPage(
+  page: {
+    anchor?: unknown;
+    type?: unknown;
+    text?: unknown;
+    texts?: unknown;
+  },
+  langMap: Record<string, string> = {},
+): boolean {
+  if (page.anchor === 'index') return true;
+  if (classify(typeof page.type === 'string' ? page.type : undefined) !== 'text') {
+    return false;
+  }
+  const rawTexts = Array.isArray(page.texts)
+    ? page.texts
+    : typeof page.text === 'string'
+      ? [page.text]
+      : [];
+  const texts = rawTexts.filter(
+    (text): text is string => typeof text === 'string' && Boolean(text),
+  );
+  if (!texts.length) return false;
+  return texts.every((raw) => {
+    const text = langString(langMap, raw) ?? raw;
+    return linkListOnly(text);
+  });
+}
+