narrarium-astro-reader 0.1.0

package/src/pages/locations/index.astro

@@ -0,0 +1,45 @@
+---
+import BaseLayout from "../../layouts/BaseLayout.astro";
+import { loadEntityIndexData } from "../../lib/book";
+import AssetFigure from "../../components/AssetFigure.astro";
+import { loadAssetFigure } from "../../lib/assets";
+
+const { ready, entities } = await loadEntityIndexData("location");
+const cards = await Promise.all(
+  entities.map(async (entity) => ({
+    ...entity,
+    figure: await loadAssetFigure(String(entity.metadata.id ?? `location:${entity.slug}`), String(entity.metadata.name ?? entity.slug)),
+  })),
+);
+---
+
+<BaseLayout title="Locations" description="Browse the book locations." activeSection="locations">
+  <section class="hero">
+    <p class="eyebrow">Canon Atlas</p>
+    <h1>Locations</h1>
+    <p class="lede">Track atmosphere, landmarks, risks, and narrative function across the world of the book.</p>
+  </section>
+
+  {ready ? (
+    <section class="section">
+      <div class="catalog-grid">
+        {cards.map((entity) => (
+          <article class="card catalog-card">
+            <a href={`locations/${entity.slug}/`}>
+              {entity.figure && <AssetFigure figure={entity.figure} className="catalog-media" />}
+              <div class="chapter-number">{String(entity.metadata.location_kind ?? "location")}</div>
+              <h2 class="chapter-title">{String(entity.metadata.name ?? entity.slug)}</h2>
+              <div class="chapter-meta">{String(entity.metadata.atmosphere ?? entity.metadata.function_in_book ?? "Open the entry to inspect place notes.")}</div>
+              <div class="chip-row">
+                {entity.metadata.region && <span class="chip">{String(entity.metadata.region)}</span>}
+                {entity.metadata.based_on_real_place && <span class="chip">real-world basis</span>}
+              </div>
+            </a>
+          </article>
+        ))}
+      </div>
+    </section>
+  ) : (
+    <div class="empty">No book repository detected for the reader.</div>
+  )}
+</BaseLayout>

package/src/pages/secrets/[slug].astro

@@ -0,0 +1,67 @@
+---
+import { marked } from "marked";
+import BaseLayout from "../../layouts/BaseLayout.astro";
+import { getBookRoot, loadEntityPageData } from "../../lib/book";
+import MetadataSection from "../../components/MetadataSection.astro";
+import RelatedLinks from "../../components/RelatedLinks.astro";
+import AssetFigure from "../../components/AssetFigure.astro";
+import { loadRelatedCanonLinks } from "../../lib/canon";
+import { loadAssetFigure } from "../../lib/assets";
+import { listEntities, pathExists } from "narrarium";
+import path from "node:path";
+
+export async function getStaticPaths() {
+  const root = getBookRoot();
+  const ready = await pathExists(path.join(root, "book.md"));
+  if (!ready) return [];
+
+  const entities = await listEntities(root, "secret");
+  return entities.map((entity) => ({ params: { slug: entity.slug }, props: { slug: entity.slug } }));
+}
+
+const { slug } = Astro.props;
+const entity = await loadEntityPageData("secret", slug);
+const html = await marked.parse(entity.body);
+const metaEntries = [
+  ["Kind", entity.metadata.secret_kind],
+  ["Function in book", entity.metadata.function_in_book],
+  ["Stakes", entity.metadata.stakes],
+  ["Holders", entity.metadata.holders],
+  ["Protected by", entity.metadata.protected_by],
+  ["False beliefs", entity.metadata.false_beliefs],
+  ["Reveal strategy", entity.metadata.reveal_strategy],
+  ["Reveal in", entity.metadata.reveal_in],
+  ["Known from", entity.metadata.known_from],
+  ["Timeline", entity.metadata.timeline_ref],
+].filter(([, value]) => value !== undefined && value !== null && (!Array.isArray(value) || value.length > 0));
+const relatedLinks = await loadRelatedCanonLinks(String(entity.metadata.id ?? `secret:${slug}`), [entity.metadata.refs, ...metaEntries.map(([, value]) => value)]);
+const figure = await loadAssetFigure(String(entity.metadata.id ?? `secret:${slug}`), String(entity.metadata.title ?? slug));
+---
+
+<BaseLayout title={String(entity.metadata.title ?? slug)} description={String(entity.metadata.function_in_book ?? entity.metadata.stakes ?? "Secret entry")} activeSection="secrets">
+  <section class="hero">
+    <p class="eyebrow">Secret</p>
+    <h1>{String(entity.metadata.title ?? slug)}</h1>
+    <p class="lede">{String(entity.metadata.function_in_book ?? entity.metadata.stakes ?? "Canonical secret entry.")}</p>
+    <div class="chapter-meta"><a href="secrets/">Back to secrets</a></div>
+    {figure && <AssetFigure figure={figure} className="hero-media" />}
+  </section>
+
+  <section class="section">
+    <div class="empty">Spoiler warning: this page exposes secret holders, reveal thresholds, and consequences.</div>
+  </section>
+
+  <section class="section">
+    <MetadataSection entries={metaEntries} />
+  </section>
+
+  {relatedLinks.length > 0 && (
+    <section class="section">
+      <RelatedLinks links={relatedLinks} />
+    </section>
+  )}
+
+  <section class="section">
+    <article class="scene prose" set:html={html} />
+  </section>
+</BaseLayout>

package/src/pages/secrets/index.astro

@@ -0,0 +1,46 @@
+---
+import BaseLayout from "../../layouts/BaseLayout.astro";
+import { loadEntityIndexData } from "../../lib/book";
+import AssetFigure from "../../components/AssetFigure.astro";
+import { loadAssetFigure } from "../../lib/assets";
+
+const { ready, entities } = await loadEntityIndexData("secret");
+const cards = await Promise.all(
+  entities.map(async (entity) => ({
+    ...entity,
+    figure: await loadAssetFigure(String(entity.metadata.id ?? `secret:${entity.slug}`), String(entity.metadata.title ?? entity.slug)),
+  })),
+);
+---
+
+<BaseLayout title="Secrets" description="Browse the spoiler vault of the book." activeSection="secrets">
+  <section class="hero">
+    <p class="eyebrow">Canon Atlas</p>
+    <h1>Secrets</h1>
+    <p class="lede">Spoiler-facing vault for hidden truths, reveal strategy, and narrative stakes across the repository.</p>
+  </section>
+
+  {ready ? (
+    <section class="section">
+      <div class="empty">Warning: this section is spoiler-heavy and surfaces canonical secrets directly.</div>
+      <div class="catalog-grid">
+        {cards.map((entity) => (
+          <article class="card catalog-card">
+            <a href={`secrets/${entity.slug}/`}>
+              {entity.figure && <AssetFigure figure={entity.figure} className="catalog-media" />}
+              <div class="chapter-number">{String(entity.metadata.secret_kind ?? "secret")}</div>
+              <h2 class="chapter-title">{String(entity.metadata.title ?? entity.slug)}</h2>
+              <div class="chapter-meta">{String(entity.metadata.function_in_book ?? entity.metadata.stakes ?? "Open the entry to inspect holders, thresholds, and consequences.")}</div>
+              <div class="chip-row">
+                {entity.metadata.reveal_in && <span class="chip">{String(entity.metadata.reveal_in)}</span>}
+                {entity.metadata.known_from && <span class="chip">{String(entity.metadata.known_from)}</span>}
+              </div>
+            </a>
+          </article>
+        ))}
+      </div>
+    </section>
+  ) : (
+    <div class="empty">No book repository detected for the reader.</div>
+  )}
+</BaseLayout>

package/src/pages/timeline/[slug].astro

@@ -0,0 +1,58 @@
+---
+import { marked } from "marked";
+import BaseLayout from "../../layouts/BaseLayout.astro";
+import { getBookRoot, loadEntityPageData } from "../../lib/book";
+import MetadataSection from "../../components/MetadataSection.astro";
+import RelatedLinks from "../../components/RelatedLinks.astro";
+import AssetFigure from "../../components/AssetFigure.astro";
+import { loadRelatedCanonLinks } from "../../lib/canon";
+import { loadAssetFigure } from "../../lib/assets";
+import { listEntities, pathExists } from "narrarium";
+import path from "node:path";
+
+export async function getStaticPaths() {
+  const root = getBookRoot();
+  const ready = await pathExists(path.join(root, "book.md"));
+  if (!ready) return [];
+
+  const entities = await listEntities(root, "timeline-event");
+  return entities.map((entity) => ({ params: { slug: entity.slug }, props: { slug: entity.slug } }));
+}
+
+const { slug } = Astro.props;
+const entity = await loadEntityPageData("timeline-event", slug);
+const html = await marked.parse(entity.body);
+const metaEntries = [
+  ["Date", entity.metadata.date],
+  ["Participants", entity.metadata.participants],
+  ["Significance", entity.metadata.significance],
+  ["Function in book", entity.metadata.function_in_book],
+  ["Consequences", entity.metadata.consequences],
+].filter(([, value]) => value !== undefined && value !== null && (!Array.isArray(value) || value.length > 0));
+const relatedLinks = await loadRelatedCanonLinks(String(entity.metadata.id ?? `timeline-event:${slug}`), [entity.metadata.refs, ...metaEntries.map(([, value]) => value)]);
+const figure = await loadAssetFigure(String(entity.metadata.id ?? `timeline-event:${slug}`), String(entity.metadata.title ?? slug));
+---
+
+<BaseLayout title={String(entity.metadata.title ?? slug)} description={String(entity.metadata.significance ?? entity.metadata.function_in_book ?? "Timeline event") } activeSection="timeline">
+  <section class="hero">
+    <p class="eyebrow">Timeline Event</p>
+    <h1>{String(entity.metadata.title ?? slug)}</h1>
+    <p class="lede">{String(entity.metadata.significance ?? entity.metadata.function_in_book ?? "Canonical timeline event.")}</p>
+    <div class="chapter-meta"><a href="timeline/">Back to timeline</a></div>
+    {figure && <AssetFigure figure={figure} className="hero-media" />}
+  </section>
+
+  <section class="section">
+    <MetadataSection entries={metaEntries} />
+  </section>
+
+  {relatedLinks.length > 0 && (
+    <section class="section">
+      <RelatedLinks links={relatedLinks} />
+    </section>
+  )}
+
+  <section class="section">
+    <article class="scene prose" set:html={html} />
+  </section>
+</BaseLayout>

package/src/pages/timeline/index.astro

@@ -0,0 +1,52 @@
+---
+import { marked } from "marked";
+import BaseLayout from "../../layouts/BaseLayout.astro";
+import { loadTimelinePageData } from "../../lib/book";
+import AssetFigure from "../../components/AssetFigure.astro";
+import { loadAssetFigure } from "../../lib/assets";
+
+const { ready, main, events } = await loadTimelinePageData();
+const mainHtml = main?.body ? await marked.parse(main.body) : "";
+const cards = await Promise.all(
+  events.map(async (entity) => ({
+    ...entity,
+    figure: await loadAssetFigure(String(entity.metadata.id ?? `timeline-event:${entity.slug}`), String(entity.metadata.title ?? entity.slug)),
+  })),
+);
+---
+
+<BaseLayout title="Timeline" description="Browse the chronology of the book." activeSection="timeline">
+  <section class="hero">
+    <p class="eyebrow">Canon Atlas</p>
+    <h1>Timeline</h1>
+    <p class="lede">Follow the main chronology and inspect event notes used to anchor continuity.</p>
+  </section>
+
+  {ready ? (
+    <>
+      {main && (
+        <section class="section">
+          <article class="scene prose" set:html={mainHtml} />
+        </section>
+      )}
+
+      <section class="section">
+        <h2>Events</h2>
+        <div class="catalog-grid">
+          {cards.map((entity) => (
+            <article class="card catalog-card">
+              <a href={`timeline/${entity.slug}/`}>
+                {entity.figure && <AssetFigure figure={entity.figure} className="catalog-media" />}
+                <div class="chapter-number">{String(entity.metadata.date ?? "timeline event")}</div>
+                <h2 class="chapter-title">{String(entity.metadata.title ?? entity.slug)}</h2>
+                <div class="chapter-meta">{String(entity.metadata.significance ?? entity.metadata.function_in_book ?? "Open the event for chronology and consequences.")}</div>
+              </a>
+            </article>
+          ))}
+        </div>
+      </section>
+    </>
+  ) : (
+    <div class="empty">No book repository detected for the reader.</div>
+  )}
+</BaseLayout>

package/src/scaffold.ts

@@ -0,0 +1,232 @@
+import { cp, copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+type ScaffoldOptions = {
+  bookRoot?: string;
+  packageName?: string;
+  coreDependency?: string;
+  pagesDomain?: string;
+};
+
+export async function scaffoldReaderSite(targetDir: string, options: ScaffoldOptions = {}) {
+  const targetRoot = path.resolve(targetDir);
+  const packageRoot = path.dirname(fileURLToPath(new URL("../package.json", import.meta.url)));
+  const bookRoot = options.bookRoot ?? "..";
+  const packageName = options.packageName ?? inferPackageName(targetRoot);
+  const coreDependency = options.coreDependency ?? `^${await readCurrentPackageVersion(packageRoot)}`;
+  const pagesDomain = options.pagesDomain?.trim() || undefined;
+
+  await mkdir(path.join(targetRoot, "src", "layouts"), { recursive: true });
+  await mkdir(path.join(targetRoot, "src", "lib"), { recursive: true });
+  await mkdir(path.join(targetRoot, "src", "pages"), { recursive: true });
+  await mkdir(path.join(targetRoot, "src", "components"), { recursive: true });
+  await mkdir(path.join(targetRoot, "scripts"), { recursive: true });
+  await mkdir(path.join(targetRoot, ".github", "workflows"), { recursive: true });
+  await mkdir(path.join(targetRoot, "public", "downloads"), { recursive: true });
+
+  await Promise.all([
+    copyFile(path.join(packageRoot, "astro.config.mjs"), path.join(targetRoot, "astro.config.mjs")),
+    copyFile(path.join(packageRoot, "tsconfig.json"), path.join(targetRoot, "tsconfig.json")),
+    cp(path.join(packageRoot, "src", "components"), path.join(targetRoot, "src", "components"), { recursive: true }),
+    cp(path.join(packageRoot, "src", "lib"), path.join(targetRoot, "src", "lib"), { recursive: true }),
+    cp(path.join(packageRoot, "src", "layouts"), path.join(targetRoot, "src", "layouts"), { recursive: true }),
+    cp(path.join(packageRoot, "src", "pages"), path.join(targetRoot, "src", "pages"), { recursive: true }),
+  ]);
+
+  await writeFile(
+    path.join(targetRoot, "package.json"),
+    JSON.stringify(
+      {
+        name: packageName,
+        private: true,
+        type: "module",
+        scripts: {
+          "export:epub": "node ./scripts/export-epub.mjs",
+          dev: "npm run export:epub && astro dev",
+          build: "npm run export:epub && astro build",
+          preview: "astro preview",
+        },
+        dependencies: {
+          "narrarium": coreDependency,
+          astro: "^5.14.1",
+          marked: "^16.3.0",
+        },
+        devDependencies: {
+          "@types/node": "^24.6.0",
+          typescript: "^5.9.3",
+        },
+      },
+      null,
+      2,
+    ) + "\n",
+    "utf8",
+  );
+
+  await writeFile(
+    path.join(targetRoot, "src", "lib", "book-config.ts"),
+    `export const defaultBookRoot = ${JSON.stringify(toPosix(bookRoot))};\n`,
+    "utf8",
+  );
+
+  await writeFile(path.join(targetRoot, "scripts", "export-epub.mjs"), buildExportEpubScript(bookRoot), "utf8");
+  await writeFile(
+    path.join(targetRoot, ".github", "workflows", "deploy-pages.yml"),
+    buildPagesWorkflow(pagesDomain),
+    "utf8",
+  );
+
+  if (pagesDomain) {
+    await writeFile(path.join(targetRoot, "public", "CNAME"), `${pagesDomain}\n`, "utf8");
+  }
+
+  await writeFile(path.join(targetRoot, ".env.example"), `NARRARIUM_BOOK_ROOT=${toPosix(bookRoot)}\n`, "utf8");
+  await writeFile(path.join(targetRoot, ".gitignore"), "node_modules/\ndist/\n.astro/\n.env\npublic/downloads/\n", "utf8");
+  await writeFile(
+    path.join(targetRoot, "README.md"),
+    buildReaderReadme(bookRoot),
+    "utf8",
+  );
+
+  return {
+    targetRoot,
+    packageName,
+    coreDependency,
+    bookRoot,
+  };
+}
+
+function buildReaderReadme(bookRoot: string): string {
+  return `# Narrarium Reader Site
+
+This site was scaffolded from \`narrarium-astro-reader\`.
+
+## Configure
+
+Set the book root in a local environment file:
+
+\`\`\`bash
+NARRARIUM_BOOK_ROOT=${toPosix(bookRoot)}
+\`\`\`
+
+## Run
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+The dev server exports a fresh EPUB to \`public/downloads/book.epub\` before Astro starts.
+
+## Build
+
+\`\`\`bash
+npm run build
+\`\`\`
+
+The build also refreshes the EPUB automatically and ships a ready-to-deploy static site.
+
+## GitHub Pages
+
+A starter workflow already exists in \`.github/workflows/deploy-pages.yml\`.
+By default it deploys to standard GitHub Pages using the repository name as the base path.
+`;
+}
+
+function buildExportEpubScript(bookRoot: string): string {
+  return `import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { exportEpub } from "narrarium";
+
+const configured = process.env.NARRARIUM_BOOK_ROOT ?? process.env.GHOSTWRITER_BOOK_ROOT;
+const root = path.resolve(process.cwd(), configured ?? ${JSON.stringify(toPosix(bookRoot))});
+const outputPath = path.resolve(process.cwd(), "public", "downloads", "book.epub");
+
+await mkdir(path.dirname(outputPath), { recursive: true });
+const result = await exportEpub(root, { outputPath });
+console.log(\`Exported EPUB with \${result.chapterCount} chapters to \${result.outputPath}\`);
+`;
+}
+
+function buildPagesWorkflow(pagesDomain?: string): string {
+  const envBlock = pagesDomain
+    ? ["          SITE_BASE: /", `          SITE_URL: https://${pagesDomain}`].join("\n")
+    : "          SITE_BASE: /${{ github.event.repository.name }}/";
+
+  return `name: Deploy Reader To GitHub Pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - master
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Build site
+        env:
+${envBlock}
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4
+`;
+}
+
+function toPosix(value: string): string {
+  return value.split(path.sep).join("/");
+}
+
+function inferPackageName(targetRoot: string): string {
+  const base = path.basename(targetRoot)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "narrarium-reader-site";
+  return base;
+}
+
+async function readCurrentPackageVersion(packageRoot: string): Promise<string> {
+  const raw = await readFile(path.join(packageRoot, "package.json"), "utf8");
+  const parsed = JSON.parse(raw) as { version?: string };
+  return parsed.version ?? "0.1.0";
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "baseUrl": "."
+  }
+}