narrarium-astro-reader 0.1.0

package/src/cli.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+import { stdin as input, stdout as output } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { scaffoldReaderSite } from "./scaffold.js";
+
+type ParsedArgs = {
+  targetDir?: string;
+  bookRoot?: string;
+  packageName?: string;
+  coreDependency?: string;
+  pagesDomain?: string;
+};
+
+const args = parseArgs(process.argv.slice(2));
+const resolved = await resolveInputs(args);
+const result = await scaffoldReaderSite(resolved.targetDir, {
+  bookRoot: resolved.bookRoot,
+  packageName: resolved.packageName,
+  coreDependency: resolved.coreDependency,
+  pagesDomain: resolved.pagesDomain,
+});
+
+output.write(
+  [
+    `Narrarium reader scaffolded at ${result.targetRoot}`,
+    `Book root default: ${result.bookRoot}`,
+    `Core dependency: ${result.coreDependency}`,
+    "",
+    "Next steps:",
+    `- cd ${result.targetRoot}`,
+    "- npm install",
+    "- copy .env.example to .env if you want a local override",
+    "- npm run dev",
+  ].join("\n"),
+);
+
+async function resolveInputs(args: ParsedArgs) {
+  if (args.targetDir) {
+    return {
+      targetDir: args.targetDir,
+      bookRoot: args.bookRoot ?? "..",
+      packageName: args.packageName,
+      coreDependency: args.coreDependency,
+      pagesDomain: args.pagesDomain,
+    };
+  }
+
+  if (!input.isTTY || !output.isTTY) {
+    throw new Error("Missing target directory. Use narrarium-reader-init <target-dir> [--book-root <path>] [--package-name <name>] [--pages-domain <domain>].");
+  }
+
+  const rl = createInterface({ input, output });
+  try {
+    const targetDir = (await rl.question("Reader folder [reader]: ")) || "reader";
+    const bookRoot = (await rl.question("Book root relative to reader [. . becomes ..] [..]: ")) || "..";
+    const packageName = (await rl.question("Package name (optional): ")) || undefined;
+    const coreDependency = (await rl.question("Core dependency [published latest compatible]: ")) || undefined;
+    const pagesDomain = (await rl.question("GitHub Pages custom domain (optional): ")) || undefined;
+    return { targetDir, bookRoot, packageName, coreDependency, pagesDomain };
+  } finally {
+    rl.close();
+  }
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const parsed: ParsedArgs = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (!token.startsWith("-")) {
+      if (!parsed.targetDir) parsed.targetDir = token;
+      continue;
+    }
+
+    switch (token) {
+      case "--book-root":
+        parsed.bookRoot = argv[++index];
+        break;
+      case "--package-name":
+        parsed.packageName = argv[++index];
+        break;
+      case "--core-dependency":
+        parsed.coreDependency = argv[++index];
+        break;
+      case "--pages-domain":
+        parsed.pagesDomain = argv[++index];
+        break;
+      default:
+        break;
+    }
+  }
+
+  return parsed;
+}

package/src/components/AssetFigure.astro

@@ -0,0 +1,17 @@
+---
+import type { ReaderFigure } from "../lib/assets";
+
+interface Props {
+  figure: ReaderFigure;
+  className?: string;
+}
+
+const { figure, className } = Astro.props;
+const ratioStyle = figure.aspectRatio.includes(":")
+  ? `aspect-ratio: ${figure.aspectRatio.replace(":", " / ")};`
+  : undefined;
+---
+
+<figure class:list={["media-frame", className]}>
+  <img src={figure.src} alt={figure.alt} loading="lazy" style={ratioStyle} />
+</figure>

package/src/components/ChapterPager.astro

@@ -0,0 +1,40 @@
+---
+interface ChapterItem {
+  slug: string;
+  metadata: {
+    number: number;
+    title: string;
+  };
+}
+
+interface Props {
+  currentSlug: string;
+  chapters: ChapterItem[];
+}
+
+const { currentSlug, chapters } = Astro.props;
+const currentIndex = chapters.findIndex((chapter) => chapter.slug === currentSlug);
+const previousChapter = currentIndex > 0 ? chapters[currentIndex - 1] : null;
+const nextChapter = currentIndex >= 0 && currentIndex < chapters.length - 1 ? chapters[currentIndex + 1] : null;
+---
+
+<nav class="chapter-pager" aria-label="Chapter navigation">
+  <a class:list={["pager-link", !previousChapter && "is-disabled"]} href={previousChapter ? `chapters/${previousChapter.slug}/` : undefined} aria-disabled={!previousChapter}>
+    {previousChapter ? `Previous: ${previousChapter.metadata.title}` : "Start of book"}
+  </a>
+
+  <label class="pager-jump">
+    <span class="label">Jump To</span>
+    <select onchange="if (this.value) window.location.href = this.value">
+      {chapters.map((chapter) => (
+        <option value={`chapters/${chapter.slug}/`} selected={chapter.slug === currentSlug}>
+          {`Chapter ${String(chapter.metadata.number).padStart(3, "0")} - ${chapter.metadata.title}`}
+        </option>
+      ))}
+    </select>
+  </label>
+
+  <a class:list={["pager-link", !nextChapter && "is-disabled"]} href={nextChapter ? `chapters/${nextChapter.slug}/` : undefined} aria-disabled={!nextChapter}>
+    {nextChapter ? `Next: ${nextChapter.metadata.title}` : "End of book"}
+  </a>
+</nav>

package/src/components/LinkedValue.astro

@@ -0,0 +1,18 @@
+---
+import { resolveValueParts } from "../lib/canon";
+
+interface Props {
+  value: unknown;
+}
+
+const { value } = Astro.props;
+const parts = await resolveValueParts(value);
+---
+
+{parts.map((part) =>
+  part.href ? (
+    <a href={part.href}>{part.text}</a>
+  ) : (
+    part.text
+  ),
+)}

package/src/components/MetadataSection.astro

@@ -0,0 +1,22 @@
+---
+import LinkedValue from "./LinkedValue.astro";
+
+interface Props {
+  entries: Array<[string, unknown]>;
+  heading?: string;
+}
+
+const { entries, heading = "Metadata" } = Astro.props;
+---
+
+<div class="scene">
+  <h2>{heading}</h2>
+  <div class="meta-list">
+    {entries.map(([key, value]) => (
+      <div class="meta-row">
+        <div class="meta-key">{key}</div>
+        <div class="meta-value"><LinkedValue value={value} /></div>
+      </div>
+    ))}
+  </div>
+</div>

package/src/components/ReaderRuntime.astro

@@ -0,0 +1,310 @@
+---
+import type { GlossaryEntry } from "../lib/glossary";
+
+interface Props {
+  glossary: GlossaryEntry[];
+}
+
+const { glossary } = Astro.props;
+const glossaryJson = JSON.stringify(glossary).replace(/</g, "\\u003c");
+---
+
+<div class="canon-overlay" data-canon-overlay hidden>
+  <button type="button" class="canon-overlay__backdrop" data-canon-close aria-label="Close canon popup"></button>
+  <aside class="canon-overlay__panel" aria-live="polite" aria-modal="true" role="dialog">
+    <button type="button" class="canon-overlay__close" data-canon-close aria-label="Close canon popup">x</button>
+    <p class="eyebrow" data-canon-kind></p>
+    <h2 data-canon-title></h2>
+    <div class="canon-tabs" data-canon-tabs>
+      <button type="button" class="canon-tab is-active" data-canon-tab="overview">Overview</button>
+      <button type="button" class="canon-tab" data-canon-tab="notes">Notes</button>
+      <button type="button" class="canon-tab" data-canon-tab="metadata">Metadata</button>
+      <button type="button" class="canon-tab" data-canon-tab="image">Image</button>
+    </div>
+    <section class="canon-panel is-active" data-canon-panel="overview">
+      <div class="chip-row" data-canon-meta></div>
+      <p class="chapter-meta" data-canon-summary></p>
+      <div class="canon-related" data-canon-mentions-wrap hidden>
+        <p class="label">Mentioned In</p>
+        <div class="chip-row" data-canon-mentions></div>
+      </div>
+    </section>
+    <section class="canon-panel" data-canon-panel="notes">
+      <div class="prose canon-overlay__body" data-canon-body></div>
+    </section>
+    <section class="canon-panel" data-canon-panel="metadata">
+      <div class="meta-list" data-canon-metadata></div>
+    </section>
+    <section class="canon-panel" data-canon-panel="image">
+      <div class="canon-overlay__image-panel" data-canon-image-panel></div>
+    </section>
+    <a class="chip" data-canon-link href="./">Open full entry</a>
+  </aside>
+</div>
+
+<script type="application/json" id="canon-glossary-data" set:html={glossaryJson}></script>
+
+<script is:inline>
+  const themeStorageKey = "narrarium-reader-theme";
+  const glossaryDataElement = document.getElementById("canon-glossary-data");
+  const glossaryEntries = glossaryDataElement ? JSON.parse(glossaryDataElement.textContent || "[]") : [];
+  const glossaryById = new Map(glossaryEntries.map((entry) => [entry.id, entry]));
+
+  initializeThemeToggle();
+  initializeCanonMentions();
+
+  function initializeThemeToggle() {
+    const root = document.documentElement;
+    const toggle = document.querySelector("[data-theme-toggle]");
+    if (!toggle) return;
+
+    const saved = localStorage.getItem(themeStorageKey);
+    const initialTheme = saved || (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
+    applyTheme(initialTheme);
+
+    toggle.addEventListener("click", () => {
+      applyTheme(root.dataset.theme === "dark" ? "light" : "dark", true);
+    });
+  }
+
+  function applyTheme(theme, persist) {
+    document.documentElement.dataset.theme = theme;
+    const toggle = document.querySelector("[data-theme-toggle]");
+    if (toggle) {
+      toggle.textContent = theme === "dark" ? "Light mode" : "Dark mode";
+      toggle.setAttribute("aria-label", theme === "dark" ? "Switch to light mode" : "Switch to dark mode");
+    }
+    if (persist) {
+      localStorage.setItem(themeStorageKey, theme);
+    }
+  }
+
+  function initializeCanonMentions() {
+    if (glossaryEntries.length === 0) return;
+
+    const termMap = new Map();
+    for (const entry of glossaryEntries) {
+      for (const term of entry.terms || []) {
+        const normalized = String(term || "").trim();
+        if (!normalized || normalized.length < 3) continue;
+        const key = normalized.toLowerCase();
+        if (!termMap.has(key)) {
+          termMap.set(key, entry.id);
+        }
+      }
+    }
+
+    const terms = [...termMap.keys()].sort((left, right) => right.length - left.length);
+    if (terms.length === 0) return;
+
+    const pattern = new RegExp(`(^|[^\\p{L}\\p{N}])(${terms.map(escapeRegex).join("|")})(?=$|[^\\p{L}\\p{N}])`, "giu");
+
+    enhanceCanonRoot(document, pattern, termMap);
+
+    initializeCanonOverlay(pattern, termMap);
+  }
+
+  function enhanceCanonRoot(root, pattern, termMap) {
+    const containers = root instanceof Document
+      ? root.querySelectorAll(".prose p, .prose li, .prose blockquote")
+      : root.matches?.(".prose")
+        ? root.querySelectorAll("p, li, blockquote")
+        : root.querySelectorAll(".prose p, .prose li, .prose blockquote");
+
+    containers.forEach((container) => {
+      if (container.dataset.canonEnhanced === "true") return;
+      container.dataset.canonEnhanced = "true";
+      const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
+      const textNodes = [];
+      while (walker.nextNode()) {
+        textNodes.push(walker.currentNode);
+      }
+
+      for (const node of textNodes) {
+        enhanceTextNode(node, pattern, termMap);
+      }
+    });
+  }
+
+  function enhanceTextNode(textNode, pattern, termMap) {
+    const parent = textNode.parentElement;
+    if (!parent || parent.closest("a, button, code, pre, h1, h2, h3, h4, h5, h6, [data-no-canon]")) {
+      return;
+    }
+
+    const raw = textNode.textContent || "";
+    pattern.lastIndex = 0;
+    if (!pattern.test(raw)) {
+      return;
+    }
+    pattern.lastIndex = 0;
+
+    const fragment = document.createDocumentFragment();
+    let cursor = 0;
+    let match;
+
+    while ((match = pattern.exec(raw))) {
+      const boundary = match[1] || "";
+      const term = match[2] || "";
+      const entryId = termMap.get(term.toLowerCase());
+      const start = match.index;
+
+      if (start > cursor) {
+        fragment.append(raw.slice(cursor, start));
+      }
+
+      if (boundary) {
+        fragment.append(boundary);
+      }
+
+      if (entryId) {
+        const button = document.createElement("button");
+        button.type = "button";
+        button.className = "canon-mention";
+        button.dataset.canonId = entryId;
+        button.textContent = term;
+        fragment.append(button);
+      } else {
+        fragment.append(term);
+      }
+
+      cursor = start + boundary.length + term.length;
+    }
+
+    if (cursor < raw.length) {
+      fragment.append(raw.slice(cursor));
+    }
+
+    textNode.replaceWith(fragment);
+  }
+
+  function initializeCanonOverlay(pattern, termMap) {
+    const overlay = document.querySelector("[data-canon-overlay]");
+    if (!overlay || overlay.dataset.bound === "true") return;
+    overlay.dataset.bound = "true";
+
+    const title = overlay.querySelector("[data-canon-title]");
+    const kind = overlay.querySelector("[data-canon-kind]");
+    const summary = overlay.querySelector("[data-canon-summary]");
+    const meta = overlay.querySelector("[data-canon-meta]");
+    const link = overlay.querySelector("[data-canon-link]");
+    const body = overlay.querySelector("[data-canon-body]");
+    const metadata = overlay.querySelector("[data-canon-metadata]");
+    const imagePanel = overlay.querySelector("[data-canon-image-panel]");
+    const mentions = overlay.querySelector("[data-canon-mentions]");
+    const mentionsWrap = overlay.querySelector("[data-canon-mentions-wrap]");
+
+    document.addEventListener("click", (event) => {
+      const target = event.target;
+      if (!(target instanceof Element)) return;
+
+      const trigger = target.closest("[data-canon-id]");
+      if (trigger instanceof HTMLElement) {
+        const entry = glossaryById.get(trigger.dataset.canonId || "");
+        if (!entry) return;
+        event.preventDefault();
+        title.textContent = entry.label;
+        kind.textContent = entry.kindLabel;
+        summary.textContent = entry.summary;
+        link.href = entry.href;
+        body.innerHTML = entry.bodyHtml || "";
+        enhanceCanonRoot(body, pattern, termMap);
+        metadata.replaceChildren(...(entry.metadataEntries || []).map((item) => {
+          const row = document.createElement("div");
+          row.className = "meta-row";
+          const key = document.createElement("div");
+          key.className = "meta-key";
+          key.textContent = item.label;
+          const value = document.createElement("div");
+          value.className = "meta-value";
+          value.textContent = item.value;
+          row.append(key, value);
+          return row;
+        }));
+        meta.replaceChildren(...(entry.meta || []).map((value) => {
+          const span = document.createElement("span");
+          span.className = "chip";
+          span.textContent = value;
+          return span;
+        }));
+        mentions.replaceChildren(...(entry.mentions || []).map((item) => {
+          const anchor = document.createElement("a");
+          anchor.className = "chip";
+          anchor.href = item.href;
+          anchor.textContent = item.label;
+          return anchor;
+        }));
+        mentionsWrap.hidden = !(entry.mentions && entry.mentions.length > 0);
+
+        if (entry.imageSrc) {
+          const wrap = document.createElement("div");
+          wrap.className = "canon-overlay__media";
+          const img = document.createElement("img");
+          img.src = entry.imageSrc;
+          img.alt = entry.imageAlt || entry.label;
+          wrap.append(img);
+          imagePanel.replaceChildren(wrap);
+        } else {
+          imagePanel.replaceChildren();
+        }
+
+        syncCanonTabs(overlay, {
+          notes: Boolean(entry.bodyHtml),
+          metadata: Boolean(entry.metadataEntries?.length),
+          image: Boolean(entry.imageSrc),
+        });
+
+        overlay.hidden = false;
+        document.body.classList.add("has-overlay");
+        return;
+      }
+
+      const tabTrigger = target.closest("[data-canon-tab]");
+      if (tabTrigger instanceof HTMLElement) {
+        activateCanonTab(overlay, tabTrigger.dataset.canonTab || "overview");
+        return;
+      }
+
+      if (target.closest("[data-canon-close]")) {
+        closeCanonOverlay();
+      }
+    });
+
+    document.addEventListener("keydown", (event) => {
+      if (event.key === "Escape") {
+        closeCanonOverlay();
+      }
+    });
+  }
+
+  function closeCanonOverlay() {
+    const overlay = document.querySelector("[data-canon-overlay]");
+    if (!overlay) return;
+    overlay.hidden = true;
+    document.body.classList.remove("has-overlay");
+  }
+
+  function syncCanonTabs(overlay, availability) {
+    overlay.querySelectorAll("[data-canon-tab]").forEach((button) => {
+      const key = button.dataset.canonTab;
+      const enabled = key === "overview" || availability[key];
+      button.hidden = !enabled;
+      button.disabled = !enabled;
+    });
+    activateCanonTab(overlay, "overview");
+  }
+
+  function activateCanonTab(overlay, key) {
+    const nextKey = overlay.querySelector(`[data-canon-tab="${key}"]`)?.hidden ? "overview" : key;
+    overlay.querySelectorAll("[data-canon-tab]").forEach((button) => {
+      button.classList.toggle("is-active", button.dataset.canonTab === nextKey);
+    });
+    overlay.querySelectorAll("[data-canon-panel]").forEach((panel) => {
+      panel.classList.toggle("is-active", panel.dataset.canonPanel === nextKey);
+    });
+  }
+
+  function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+</script>

package/src/components/RelatedLinks.astro

@@ -0,0 +1,19 @@
+---
+import type { CanonLink } from "../lib/canon";
+
+interface Props {
+  links: CanonLink[];
+  heading?: string;
+}
+
+const { links, heading = "Related canon" } = Astro.props;
+---
+
+<div class="scene">
+  <h2>{heading}</h2>
+  <div class="chip-row">
+    {links.map((link) => (
+      <a class="chip" href={link.href}>{link.label}</a>
+    ))}
+  </div>
+</div>

package/src/components/SiteSearch.astro

@@ -0,0 +1,91 @@
+---
+import type { SearchEntry } from "../lib/search";
+
+interface Props {
+  entries: SearchEntry[];
+}
+
+const { entries } = Astro.props;
+const entriesJson = JSON.stringify(entries).replace(/</g, "\\u003c");
+---
+
+<div class="site-search" data-site-search>
+  <label class="site-search__field">
+    <span class="label">Search</span>
+    <input type="search" placeholder="Search chapters, scenes, and canon..." data-search-input />
+  </label>
+  <div class="site-search__results" data-search-results hidden></div>
+</div>
+
+<script type="application/json" id="reader-search-data" set:html={entriesJson}></script>
+
+<script is:inline>
+  const searchDataElement = document.getElementById("reader-search-data");
+  const searchEntries = searchDataElement ? JSON.parse(searchDataElement.textContent || "[]") : [];
+  const searchRoot = document.querySelector("[data-site-search]");
+
+  if (searchRoot) {
+    const input = searchRoot.querySelector("[data-search-input]");
+    const results = searchRoot.querySelector("[data-search-results]");
+
+    const renderResults = (value) => {
+      const query = String(value || "").trim().toLowerCase();
+      if (!query) {
+        results.hidden = true;
+        results.replaceChildren();
+        return;
+      }
+
+      const matches = searchEntries
+        .map((entry) => ({ entry, score: scoreSearchEntry(entry, query) }))
+        .filter((entry) => entry.score > 0)
+        .sort((left, right) => right.score - left.score)
+        .slice(0, 8);
+
+      results.replaceChildren(...matches.map(({ entry }) => {
+        const anchor = document.createElement("a");
+        anchor.className = "site-search__result";
+        anchor.href = entry.href;
+        const kind = document.createElement("span");
+        kind.className = "chip";
+        kind.textContent = entry.kind;
+        const title = document.createElement("strong");
+        title.textContent = entry.title;
+        const summary = document.createElement("span");
+        summary.className = "chapter-meta";
+        summary.textContent = entry.summary;
+        anchor.append(kind, title, summary);
+        return anchor;
+      }));
+
+      results.hidden = matches.length === 0;
+    };
+
+    input.addEventListener("input", () => renderResults(input.value));
+    input.addEventListener("focus", () => renderResults(input.value));
+    document.addEventListener("click", (event) => {
+      if (!(event.target instanceof Node) || searchRoot.contains(event.target)) return;
+      results.hidden = true;
+    });
+    document.addEventListener("keydown", (event) => {
+      if ((event.key === "/" && document.activeElement !== input) || ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k")) {
+        event.preventDefault();
+        input.focus();
+      }
+    });
+  }
+
+  function scoreSearchEntry(entry, query) {
+    const title = String(entry.title || "").toLowerCase();
+    const summary = String(entry.summary || "").toLowerCase();
+    const keywords = Array.isArray(entry.keywords) ? entry.keywords.join(" ").toLowerCase() : "";
+
+    let score = 0;
+    if (title === query) score += 120;
+    if (title.startsWith(query)) score += 80;
+    if (title.includes(query)) score += 45;
+    if (keywords.includes(query)) score += 20;
+    if (summary.includes(query)) score += 10;
+    return score;
+  }
+</script>