narrarium-astro-reader 0.1.0

package/src/lib/book.ts

@@ -0,0 +1,116 @@
+import path from "node:path";
+import {
+  listChapters,
+  listEntities,
+  pathExists,
+  readBook,
+  readChapter,
+  readEntity,
+  readTimelineMain,
+} from "narrarium";
+import { defaultBookRoot } from "./book-config.js";
+
+type ReaderEntityKind =
+  | "character"
+  | "location"
+  | "faction"
+  | "item"
+  | "secret"
+  | "timeline-event";
+
+export function getBookRoot(): string {
+  const configured = process.env.NARRARIUM_BOOK_ROOT ?? process.env.GHOSTWRITER_BOOK_ROOT;
+  if (configured) return path.resolve(configured);
+  return path.resolve(process.cwd(), defaultBookRoot);
+}
+
+export async function loadHomePageData() {
+  const root = getBookRoot();
+  const hasBook = await pathExists(path.join(root, "book.md"));
+
+  if (!hasBook) {
+    return {
+      ready: false,
+      root,
+      book: null,
+      chapters: [],
+      characters: [],
+      locations: [],
+      factions: [],
+      items: [],
+      secrets: [],
+      timelineEvents: [],
+    };
+  }
+
+  const [book, chapters, characters, locations, factions, items, secrets, timelineEvents] = await Promise.all([
+    readBook(root),
+    listChapters(root),
+    listEntities(root, "character"),
+    listEntities(root, "location"),
+    listEntities(root, "faction"),
+    listEntities(root, "item"),
+    listEntities(root, "secret"),
+    listEntities(root, "timeline-event"),
+  ]);
+
+  return {
+    ready: true,
+    root,
+    book,
+    chapters,
+    characters,
+    locations,
+    factions,
+    items,
+    secrets,
+    timelineEvents,
+  };
+}
+
+export async function loadChapterPageData(chapterSlug: string) {
+  const root = getBookRoot();
+  return readChapter(root, chapterSlug);
+}
+
+export async function loadEntityIndexData(kind: ReaderEntityKind) {
+  const root = getBookRoot();
+  const ready = await pathExists(path.join(root, "book.md"));
+
+  if (!ready) {
+    return { ready: false, root, entities: [] };
+  }
+
+  return {
+    ready: true,
+    root,
+    entities: await listEntities(root, kind),
+  };
+}
+
+export async function loadEntityPageData(kind: ReaderEntityKind, slug: string) {
+  const root = getBookRoot();
+  return readEntity(root, kind, slug);
+}
+
+export async function loadTimelinePageData() {
+  const root = getBookRoot();
+  const ready = await pathExists(path.join(root, "book.md"));
+
+  if (!ready) {
+    return {
+      ready: false,
+      root,
+      main: null,
+      events: [],
+    };
+  }
+
+  const [main, events] = await Promise.all([readTimelineMain(root), listEntities(root, "timeline-event")]);
+  return {
+    ready: true,
+    root,
+    main,
+    events,
+  };
+}

package/src/lib/canon.ts

@@ -0,0 +1,212 @@
+import path from "node:path";
+import { listChapters, listEntities, listRelatedCanon, readChapter, toPosixPath } from "narrarium";
+import { getBookRoot } from "./book.js";
+
+type ReaderEntityKind =
+  | "character"
+  | "location"
+  | "faction"
+  | "item"
+  | "secret"
+  | "timeline-event";
+
+export type CanonLink = {
+  href: string;
+  label: string;
+  kind: string;
+};
+
+export type ValuePart =
+  | { text: string; href?: undefined }
+  | { text: string; href: string };
+
+type ReferenceIndex = Map<string, CanonLink>;
+
+const entityKinds: ReaderEntityKind[] = ["character", "location", "faction", "item", "secret", "timeline-event"];
+
+let referenceIndexPromise: Promise<ReferenceIndex> | null = null;
+
+export async function resolveValueParts(value: unknown): Promise<ValuePart[]> {
+  const strings = Array.isArray(value) ? value : [value];
+  const parts: ValuePart[] = [];
+
+  for (const entry of strings) {
+    if (entry === undefined || entry === null || entry === "") continue;
+    if (parts.length > 0) parts.push({ text: ", " });
+
+    if (typeof entry === "string") {
+      const link = await resolveReference(entry);
+      if (link) {
+        parts.push({ text: link.label, href: link.href });
+        continue;
+      }
+    }
+
+    parts.push({ text: String(entry) });
+  }
+
+  return parts;
+}
+
+export async function loadRelatedCanonLinks(id: string, values: unknown): Promise<CanonLink[]> {
+  const explicitRefs = collectReferenceStrings(values);
+  const [resolvedRefs, relatedHits] = await Promise.all([
+    Promise.all(explicitRefs.map((value) => resolveReference(value))),
+    id ? listRelatedCanon(getBookRoot(), id, { limit: 8 }) : Promise.resolve([]),
+  ]);
+
+  const links: CanonLink[] = [];
+  const seen = new Set<string>();
+
+  for (const link of resolvedRefs) {
+    if (!link || seen.has(link.href)) continue;
+    seen.add(link.href);
+    links.push(link);
+  }
+
+  for (const hit of relatedHits) {
+    const href = resolveContentPathToHref(hit.path);
+    if (!href || seen.has(href)) continue;
+    seen.add(href);
+    links.push({ href, label: hit.title, kind: hit.type });
+  }
+
+  return links;
+}
+
+export async function resolveReference(value: string): Promise<CanonLink | null> {
+  const normalized = value.trim();
+  if (!normalized) return null;
+
+  const index = await loadReferenceIndex();
+  const exact = index.get(normalized.toLowerCase());
+  if (exact) return exact;
+
+  return buildFallbackReference(normalized);
+}
+
+function collectReferenceStrings(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.flatMap((entry) => collectReferenceStrings(entry));
+  }
+
+  if (typeof value !== "string") return [];
+
+  return isSupportedReference(value) ? [value] : [];
+}
+
+async function loadReferenceIndex(): Promise<ReferenceIndex> {
+  referenceIndexPromise ??= buildReferenceIndex();
+  return referenceIndexPromise;
+}
+
+async function buildReferenceIndex(): Promise<ReferenceIndex> {
+  const index: ReferenceIndex = new Map();
+  const root = getBookRoot();
+  const entitiesByKind = await Promise.all(entityKinds.map((kind) => listEntities(root, kind)));
+
+  entitiesByKind.forEach((entities, offset) => {
+    const kind = entityKinds[offset];
+
+    for (const entity of entities) {
+      const label = String(entity.metadata.name ?? entity.metadata.title ?? entity.slug);
+      const href = entityHref(kind, entity.slug);
+      const id = String(entity.metadata.id ?? `${kind}:${entity.slug}`);
+      setReference(index, id, { href, label, kind });
+      setReference(index, `${kind}:${entity.slug}`, { href, label, kind });
+    }
+  });
+
+  const chapters = await listChapters(root);
+  for (const chapter of chapters) {
+    const chapterId = String(chapter.metadata.id ?? `chapter:${chapter.slug}`);
+    const chapterLink = { href: `chapters/${chapter.slug}/`, label: chapter.metadata.title, kind: "chapter" };
+    setReference(index, chapterId, chapterLink);
+    setReference(index, `chapter:${chapter.slug}`, chapterLink);
+
+    const chapterData = await readChapter(root, chapter.slug);
+    for (const paragraph of chapterData.paragraphs) {
+      const paragraphSlug = path.basename(paragraph.path, ".md");
+      const href = `chapters/${chapter.slug}/#scene-${paragraphSlug}`;
+      const label = paragraph.metadata.title;
+      setReference(index, String(paragraph.metadata.id), { href, label, kind: "paragraph" });
+      setReference(index, `paragraph:${chapter.slug}:${paragraphSlug}`, { href, label, kind: "paragraph" });
+    }
+  }
+
+  return index;
+}
+
+function setReference(index: ReferenceIndex, key: string, link: CanonLink) {
+  index.set(key.toLowerCase(), link);
+}
+
+function entityHref(kind: ReaderEntityKind, slug: string): string {
+  switch (kind) {
+    case "timeline-event":
+      return `timeline/${slug}/`;
+    default:
+      return `${kind}s/${slug}/`;
+  }
+}
+
+function resolveContentPathToHref(filePath: string): string | null {
+  const normalized = toPosixPath(filePath);
+
+  const entityMatch = normalized.match(/^(characters|locations|factions|items|secrets|timelines\/events)\/([^/]+)\.md$/);
+  if (entityMatch) {
+    const section = entityMatch[1] === "timelines/events" ? "timeline" : entityMatch[1];
+    return `${section}/${entityMatch[2]}/`;
+  }
+
+  const chapterMatch = normalized.match(/^chapters\/([^/]+)\/chapter\.md$/);
+  if (chapterMatch) {
+    return `chapters/${chapterMatch[1]}/`;
+  }
+
+  const paragraphMatch = normalized.match(/^chapters\/([^/]+)\/([^/]+)\.md$/);
+  if (paragraphMatch) {
+    return `chapters/${paragraphMatch[1]}/#scene-${paragraphMatch[2]}`;
+  }
+
+  return null;
+}
+
+function buildFallbackReference(value: string): CanonLink | null {
+  if (value.startsWith("chapter:")) {
+    const slug = value.slice("chapter:".length);
+    return { href: `chapters/${slug}/`, label: humanizeSlug(slug), kind: "chapter" };
+  }
+
+  if (value.startsWith("paragraph:")) {
+    const [, chapterSlug, paragraphSlug] = value.split(":");
+    if (!chapterSlug || !paragraphSlug) return null;
+    return {
+      href: `chapters/${chapterSlug}/#scene-${paragraphSlug}`,
+      label: humanizeSlug(paragraphSlug),
+      kind: "paragraph",
+    };
+  }
+
+  for (const kind of entityKinds) {
+    const prefix = `${kind}:`;
+    if (!value.startsWith(prefix)) continue;
+    const slug = value.slice(prefix.length);
+    return { href: entityHref(kind, slug), label: humanizeSlug(slug), kind };
+  }
+
+  return null;
+}
+
+function isSupportedReference(value: string): boolean {
+  return value.startsWith("chapter:") || value.startsWith("paragraph:") || entityKinds.some((kind) => value.startsWith(`${kind}:`));
+}
+
+function humanizeSlug(value: string): string {
+  return value
+    .replace(/^[0-9]+-/, "")
+    .split("-")
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}

package/src/lib/glossary.ts

@@ -0,0 +1,247 @@
+import { listEntities, listRelatedCanon, readEntity, toPosixPath } from "narrarium";
+import { marked } from "marked";
+import { loadAssetFigure } from "./assets.js";
+import { getBookRoot } from "./book.js";
+
+type ReaderEntityKind =
+  | "character"
+  | "location"
+  | "faction"
+  | "item"
+  | "secret"
+  | "timeline-event";
+
+export type GlossaryEntry = {
+  id: string;
+  kind: ReaderEntityKind;
+  kindLabel: string;
+  label: string;
+  href: string;
+  terms: string[];
+  summary: string;
+  meta: string[];
+  metadataEntries: Array<{ label: string; value: string }>;
+  mentions: Array<{ label: string; href: string }>;
+  bodyHtml?: string;
+  imageSrc?: string;
+  imageAlt?: string;
+};
+
+const entityKinds: ReaderEntityKind[] = ["character", "location", "faction", "item", "secret", "timeline-event"];
+
+let glossaryPromise: Promise<GlossaryEntry[]> | null = null;
+
+export async function loadCanonGlossary(): Promise<GlossaryEntry[]> {
+  glossaryPromise ??= buildCanonGlossary();
+  return glossaryPromise;
+}
+
+async function buildCanonGlossary(): Promise<GlossaryEntry[]> {
+  const root = getBookRoot();
+  const groups = await Promise.all(entityKinds.map((kind) => listEntities(root, kind)));
+  const entries = await Promise.all(
+    groups.flatMap((entities, offset) =>
+      entities.map(async (entity) => {
+        const kind = entityKinds[offset];
+        const id = String(entity.metadata.id ?? `${kind}:${entity.slug}`);
+        const label = String(entity.metadata.name ?? entity.metadata.title ?? entity.slug);
+        const fullEntry = await readEntity(root, kind, entity.slug);
+        const related = await listRelatedCanon(root, id, { limit: 8 });
+        const figure = await loadAssetFigure(id, label);
+
+        return {
+          id,
+          kind,
+          kindLabel: kindLabel(kind),
+          label,
+          href: entityHref(kind, entity.slug),
+          terms: uniqueStrings([label, ...readAliases(entity.metadata.aliases)]),
+          summary: summaryFor(kind, entity.metadata),
+          meta: metaFor(kind, entity.metadata),
+          metadataEntries: metadataEntriesFor(kind, entity.metadata),
+          mentions: mentionLinksFor(related),
+          bodyHtml: fullEntry.body ? await marked.parse(fullEntry.body) : undefined,
+          imageSrc: figure?.src,
+          imageAlt: figure?.alt,
+        } satisfies GlossaryEntry;
+      }),
+    ),
+  );
+
+  return entries.sort((left, right) => left.label.localeCompare(right.label));
+}
+
+function mentionLinksFor(hits: Array<{ path: string; title: string }>): Array<{ label: string; href: string }> {
+  const seen = new Set<string>();
+  const links: Array<{ label: string; href: string }> = [];
+
+  for (const hit of hits) {
+    const href = readerHrefFromPath(hit.path);
+    if (!href || seen.has(href)) continue;
+    seen.add(href);
+    links.push({ label: hit.title, href });
+  }
+
+  return links;
+}
+
+function readerHrefFromPath(filePath: string): string | null {
+  const normalized = toPosixPath(filePath);
+  const chapterMatch = normalized.match(/^chapters\/([^/]+)\/chapter\.md$/);
+  if (chapterMatch) {
+    return `chapters/${chapterMatch[1]}/`;
+  }
+
+  const paragraphMatch = normalized.match(/^chapters\/([^/]+)\/([^/]+)\.md$/);
+  if (paragraphMatch && paragraphMatch[2] !== "chapter") {
+    return `chapters/${paragraphMatch[1]}/#scene-${paragraphMatch[2]}`;
+  }
+
+  return null;
+}
+
+function entityHref(kind: ReaderEntityKind, slug: string): string {
+  switch (kind) {
+    case "timeline-event":
+      return `timeline/${slug}/`;
+    default:
+      return `${kind}s/${slug}/`;
+  }
+}
+
+function kindLabel(kind: ReaderEntityKind): string {
+  switch (kind) {
+    case "timeline-event":
+      return "Timeline Event";
+    default:
+      return kind.charAt(0).toUpperCase() + kind.slice(1);
+  }
+}
+
+function summaryFor(kind: ReaderEntityKind, metadata: Record<string, unknown>): string {
+  switch (kind) {
+    case "character":
+      return String(metadata.function_in_book ?? metadata.story_role ?? metadata.background_summary ?? "Canonical character entry.");
+    case "location":
+      return String(metadata.atmosphere ?? metadata.function_in_book ?? "Canonical location entry.");
+    case "faction":
+      return String(metadata.function_in_book ?? metadata.mission ?? metadata.ideology ?? "Canonical faction entry.");
+    case "item":
+      return String(metadata.function_in_book ?? metadata.purpose ?? metadata.significance ?? "Canonical item entry.");
+    case "secret":
+      return String(metadata.function_in_book ?? metadata.stakes ?? metadata.reveal_strategy ?? "Canonical secret entry.");
+    case "timeline-event":
+      return String(metadata.significance ?? metadata.function_in_book ?? "Canonical timeline event.");
+  }
+}
+
+function metaFor(kind: ReaderEntityKind, metadata: Record<string, unknown>): string[] {
+  switch (kind) {
+    case "character":
+      return compactStrings([metadata.role_tier, metadata.story_role, metadata.home_location]);
+    case "location":
+      return compactStrings([metadata.location_kind, metadata.region, metadata.timeline_ref]);
+    case "faction":
+      return compactStrings([metadata.faction_kind, metadata.base_location, metadata.public_image]);
+    case "item":
+      return compactStrings([metadata.item_kind, metadata.owner, metadata.introduced_in]);
+    case "secret":
+      return compactStrings([metadata.secret_kind, metadata.reveal_in, metadata.known_from]);
+    case "timeline-event":
+      return compactStrings([metadata.date, metadata.function_in_book]);
+  }
+}
+
+function metadataEntriesFor(kind: ReaderEntityKind, metadata: Record<string, unknown>): Array<{ label: string; value: string }> {
+  switch (kind) {
+    case "character":
+      return compactEntries([
+        ["Role tier", metadata.role_tier],
+        ["Story role", metadata.story_role],
+        ["Occupation", metadata.occupation],
+        ["Origin", metadata.origin],
+        ["Home", metadata.home_location],
+        ["Introduced in", metadata.introduced_in],
+      ]);
+    case "location":
+      return compactEntries([
+        ["Kind", metadata.location_kind],
+        ["Region", metadata.region],
+        ["Timeline", metadata.timeline_ref],
+        ["Real world basis", metadata.based_on_real_place],
+      ]);
+    case "faction":
+      return compactEntries([
+        ["Kind", metadata.faction_kind],
+        ["Base", metadata.base_location],
+        ["Public image", metadata.public_image],
+        ["Historical", metadata.historical],
+      ]);
+    case "item":
+      return compactEntries([
+        ["Kind", metadata.item_kind],
+        ["Owner", metadata.owner],
+        ["Introduced in", metadata.introduced_in],
+        ["Significance", metadata.significance],
+      ]);
+    case "secret":
+      return compactEntries([
+        ["Kind", metadata.secret_kind],
+        ["Reveal in", metadata.reveal_in],
+        ["Known from", metadata.known_from],
+        ["Holders", metadata.holders],
+      ]);
+    case "timeline-event":
+      return compactEntries([
+        ["Date", metadata.date],
+        ["Participants", metadata.participants],
+        ["Function", metadata.function_in_book],
+        ["Consequences", metadata.consequences],
+      ]);
+  }
+}
+
+function compactStrings(values: unknown[]): string[] {
+  return values
+    .map((value) => (typeof value === "string" ? value.trim() : ""))
+    .filter(Boolean);
+}
+
+function compactEntries(entries: Array<[string, unknown]>): Array<{ label: string; value: string }> {
+  return entries.flatMap(([label, value]) => {
+    const normalized = normalizeEntryValue(value);
+    return normalized ? [{ label, value: normalized }] : [];
+  });
+}
+
+function normalizeEntryValue(value: unknown): string {
+  if (Array.isArray(value)) {
+    const normalized = value
+      .map((entry) => normalizeEntryValue(entry))
+      .filter(Boolean)
+      .join(", ");
+    return normalized;
+  }
+
+  if (typeof value === "boolean") {
+    return value ? "Yes" : "No";
+  }
+
+  if (value === undefined || value === null) {
+    return "";
+  }
+
+  return String(value).trim();
+}
+
+function readAliases(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0);
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}

package/src/lib/search.ts

@@ -0,0 +1,74 @@
+import path from "node:path";
+import { listChapters, readChapter } from "narrarium";
+import { getBookRoot } from "./book.js";
+import { loadCanonGlossary } from "./glossary.js";
+
+export type SearchEntry = {
+  title: string;
+  href: string;
+  kind: string;
+  summary: string;
+  keywords: string[];
+};
+
+let searchIndexPromise: Promise<SearchEntry[]> | null = null;
+
+export async function loadSearchIndex(): Promise<SearchEntry[]> {
+  searchIndexPromise ??= buildSearchIndex();
+  return searchIndexPromise;
+}
+
+async function buildSearchIndex(): Promise<SearchEntry[]> {
+  const root = getBookRoot();
+  const glossary = await loadCanonGlossary();
+  const chapters = await listChapters(root);
+
+  const chapterEntries = await Promise.all(
+    chapters.flatMap(async (chapter) => {
+      const chapterData = await readChapter(root, chapter.slug);
+      const chapterEntry: SearchEntry = {
+        title: chapter.metadata.title,
+        href: `chapters/${chapter.slug}/`,
+        kind: "Chapter",
+        summary: String(chapter.metadata.summary ?? "Read this chapter."),
+        keywords: compactStrings([chapter.metadata.summary, ...(chapter.metadata.tags ?? []), ...(chapter.metadata.pov ?? [])]),
+      };
+
+      const sceneEntries = chapterData.paragraphs.map((paragraph) => ({
+        title: paragraph.metadata.title,
+        href: `chapters/${chapter.slug}/#scene-${path.basename(paragraph.path, ".md")}`,
+        kind: "Scene",
+        summary: String(paragraph.metadata.summary ?? `Scene in ${chapter.metadata.title}.`),
+        keywords: compactStrings([chapter.metadata.title, paragraph.metadata.viewpoint, paragraph.metadata.summary]),
+      } satisfies SearchEntry));
+
+      return [chapterEntry, ...sceneEntries];
+    }),
+  );
+
+  return [
+    ...glossary.map((entry) => ({
+      title: entry.label,
+      href: entry.href,
+      kind: entry.kindLabel,
+      summary: entry.summary,
+      keywords: [...entry.terms, ...entry.meta, ...entry.metadataEntries.map((item) => item.value)],
+    })),
+    ...chapterEntries.flat(),
+  ];
+}
+
+function compactStrings(values: unknown[]): string[] {
+  return values.flatMap((value) => {
+    if (Array.isArray(value)) {
+      return compactStrings(value);
+    }
+
+    if (value === undefined || value === null) {
+      return [];
+    }
+
+    const normalized = String(value).trim();
+    return normalized ? [normalized] : [];
+  });
+}