@lapis-notes/lapis-plugin-docs 0.0.0-stage → 0.1.0

package/dist/docs-workspace.svelte

@@ -0,0 +1,394 @@
+<script lang="ts">
+  import type { App } from "@lapis-notes/api";
+  import { Button } from "@lapismd/design-core/shadcn/button";
+  import { ScrollArea } from "@lapismd/design-core/shadcn/scroll-area";
+  import { Mira } from "@lapismd/mira";
+  import "@lapismd/mira/styles.css";
+  import "@lapismd/mira/themes/obsidian.css";
+  import { onMount } from "svelte";
+  import type { DocsRepository } from "./docs-repository";
+  import {
+    DEFAULT_DOCS_PLUGIN_SETTINGS,
+    type DocsPluginSettings,
+  } from "./docs-settings";
+  import type { DocsSettingsSource } from "./docs-view";
+  import DocsFlipCard from "./docs/DocsFlipCard.svelte";
+  import {
+    REVIEW_RATINGS,
+    REVIEW_RATING_LABELS,
+    buildDocsReviewQueue,
+    buildDocsWorkspace,
+    renderDocsNoteMarkdown,
+    reviewDocsCard,
+    type DocsCard,
+    type DocsNote,
+    type DocsReviewQueueItem,
+    type DocsReviewRating,
+  } from "./model";
+
+  let {
+    app,
+    repository,
+    clock = () => new Date(),
+    settingsSource,
+    mode = "workspace" as "workspace" | "cards" | "review",
+  }: {
+    app: App;
+    repository: DocsRepository;
+    clock?: () => Date;
+    settingsSource?: DocsSettingsSource;
+    mode?: "workspace" | "cards" | "review";
+  } = $props();
+
+  let settings = $state<DocsPluginSettings>(DEFAULT_DOCS_PLUGIN_SETTINGS);
+  let notes = $state<DocsNote[]>([]);
+  let selectedId = $state<string | null>(null);
+  let panel = $state<"display" | "cards" | "review">("display");
+  let loadError = $state<string | null>(null);
+  let flipped = $state(false);
+  let reviewIndex = $state(0);
+
+  const selected = $derived(
+    notes.find((note) => note.id === selectedId) ?? notes[0] ?? null,
+  );
+  const coreCards = $derived(
+    (selected?.cards ?? []).filter(
+      (card) => card.type === "basic" || card.type === "cloze",
+    ),
+  );
+  const markdown = $derived(
+    selected ? renderDocsNoteMarkdown(selected) : "",
+  );
+  const workspace = $derived(buildDocsWorkspace(notes));
+  const reviewQueue = $derived(buildDocsReviewQueue(notes, clock()));
+  const activeReview = $derived(
+    reviewQueue[reviewIndex] ?? reviewQueue[0] ?? null,
+  );
+
+  async function refresh() {
+    try {
+      notes = await repository.listNotes(settings.docsRoot);
+      if (!selectedId && notes[0]) selectedId = notes[0].id;
+      loadError = null;
+    } catch (error) {
+      loadError = error instanceof Error ? error.message : String(error);
+    }
+  }
+
+  async function rate(rating: DocsReviewRating) {
+    if (!activeReview) return;
+    const note = notes.find((entry) => entry.id === activeReview.noteId);
+    if (!note) return;
+    const cardIndex = note.cards.findIndex(
+      (card) => card.id === activeReview.card.id,
+    );
+    if (cardIndex < 0) return;
+    const reviewed = reviewDocsCard(note.cards[cardIndex]!, rating, clock());
+    const nextCards = note.cards.slice();
+    nextCards[cardIndex] = reviewed;
+    const nextNote: DocsNote = {
+      ...note,
+      cards: nextCards,
+      updatedAt: clock().toISOString(),
+    };
+    await repository.writeNote(nextNote);
+    await refresh();
+    flipped = false;
+    reviewIndex = Math.min(reviewIndex, Math.max(0, reviewQueue.length - 1));
+  }
+
+  onMount(() => {
+    if (mode === "cards") panel = "cards";
+    else if (mode === "review") panel = "review";
+    settings = settingsSource?.get() ?? DEFAULT_DOCS_PLUGIN_SETTINGS;
+    const unsubscribe = settingsSource?.subscribe((next) => {
+      settings = next;
+      void refresh();
+    });
+    void refresh();
+    return () => unsubscribe?.();
+  });
+</script>
+
+<div
+  class="docs-workspace"
+  data-ui-component="docs-workspace"
+  data-mode={mode}
+  data-docs-ready={notes.length > 0 ? "true" : "false"}
+  data-app-owned={app ? "true" : "false"}
+>
+  <aside class="docs-workspace__sidebar">
+    <header class="docs-workspace__sidebar-header">
+      <h2>Docs</h2>
+      <p>{notes.length} notes · {workspace.reviewQueue.length} due</p>
+    </header>
+    <div class="docs-workspace__scroll">
+      <ScrollArea>
+        <ul class="docs-workspace__list">
+          {#each notes as note (note.id)}
+            <li>
+              <button
+                type="button"
+                class="docs-workspace__note"
+                data-selected={selected?.id === note.id ? "true" : "false"}
+                onclick={() => {
+                  selectedId = note.id;
+                  flipped = false;
+                  if (note.sourcePath) {
+                    const file = app.vault.getFileByPath(note.sourcePath);
+                    if (file) {
+                      const leaf = app.workspace.getLeaf("tab");
+                      void leaf.openFile(file).then(() => {
+                        app.workspace.setActiveLeaf(leaf, { focus: true });
+                      });
+                    }
+                  }
+                }}
+              >
+                <span class="docs-workspace__note-title">{note.title}</span>
+                <span class="docs-workspace__note-meta">{note.docType}</span>
+              </button>
+            </li>
+          {/each}
+        </ul>
+      </ScrollArea>
+    </div>
+  </aside>
+
+  <section class="docs-workspace__main">
+    <header class="docs-workspace__toolbar">
+      <div class="docs-workspace__tabs" role="tablist" aria-label="Docs panels">
+        <Button
+          variant={panel === "display" ? "default" : "outline"}
+          size="sm"
+          onclick={() => (panel = "display")}
+        >
+          Display
+        </Button>
+        <Button
+          variant={panel === "cards" ? "default" : "outline"}
+          size="sm"
+          onclick={() => (panel = "cards")}
+        >
+          Cards
+        </Button>
+        <Button
+          variant={panel === "review" ? "default" : "outline"}
+          size="sm"
+          onclick={() => (panel = "review")}
+        >
+          Review
+        </Button>
+      </div>
+      {#if selected}
+        <p class="docs-workspace__summary">{selected.summary}</p>
+      {/if}
+    </header>
+
+    {#if loadError}
+      <p class="docs-workspace__error" role="alert">{loadError}</p>
+    {:else if !selected}
+      <p class="docs-workspace__empty">No Docs notes under `{settings.docsRoot}`.</p>
+    {:else if panel === "display"}
+      <div class="docs-workspace__scroll docs-workspace__scroll--padded">
+        <ScrollArea>
+          <Mira
+            value={markdown}
+            mode="preview"
+            readonly
+            toolbar={false}
+            theme="obsidian"
+            colorMode="inherit"
+            spellcheck={false}
+            blockControls={false}
+          />
+        </ScrollArea>
+      </div>
+    {:else if panel === "cards"}
+      <div class="docs-workspace__scroll docs-workspace__scroll--padded">
+        <ScrollArea>
+          <div class="docs-workspace__cards">
+            {#each coreCards as card (card.id)}
+              <article class="docs-workspace__card">
+                <h3>{card.prompt}</h3>
+                <p>{card.answer}</p>
+                <p class="docs-workspace__note-meta">{card.type} · {card.status}</p>
+              </article>
+            {:else}
+              <p class="docs-workspace__empty">No basic or cloze cards on this note.</p>
+            {/each}
+          </div>
+        </ScrollArea>
+      </div>
+    {:else}
+      <div class="docs-workspace__review">
+        {#if activeReview}
+          {@const card: DocsCard = activeReview.card}
+          {@const item: DocsReviewQueueItem = activeReview}
+          <p class="docs-workspace__note-meta">
+            {item.noteTitle} · {reviewQueue.length} due
+          </p>
+          <DocsFlipCard bind:flipped front={card.prompt} back={card.answer} />
+          <div class="docs-workspace__ratings">
+            {#each REVIEW_RATINGS as rating (rating)}
+              <Button
+                variant="outline"
+                size="sm"
+                onclick={() => void rate(rating)}
+              >
+                {REVIEW_RATING_LABELS[rating]}
+              </Button>
+            {/each}
+          </div>
+        {:else}
+          <p class="docs-workspace__empty">No cards are due for review.</p>
+        {/if}
+      </div>
+    {/if}
+  </section>
+</div>
+
+<style>
+  .docs-workspace {
+    box-sizing: border-box;
+    display: grid;
+    grid-template-columns: minmax(14rem, 18rem) minmax(0, 1fr);
+    width: 100%;
+    height: 100%;
+    min-height: 0;
+    overflow: hidden;
+    background: var(--ui-docs-background);
+    color: var(--ui-docs-foreground);
+  }
+
+  .docs-workspace__sidebar,
+  .docs-workspace__main {
+    display: flex;
+    min-height: 0;
+    min-width: 0;
+    flex-direction: column;
+  }
+
+  .docs-workspace__sidebar {
+    border-inline-end: 1px solid var(--ui-docs-border);
+    background: var(--ui-docs-muted);
+  }
+
+  .docs-workspace__sidebar-header,
+  .docs-workspace__toolbar {
+    padding: 0.75rem 1rem;
+    border-block-end: 1px solid var(--ui-docs-border);
+  }
+
+  .docs-workspace__sidebar-header h2,
+  .docs-workspace__sidebar-header p,
+  .docs-workspace__summary,
+  .docs-workspace__empty,
+  .docs-workspace__error,
+  .docs-workspace__note-meta {
+    margin: 0;
+  }
+
+  .docs-workspace__sidebar-header p,
+  .docs-workspace__summary,
+  .docs-workspace__note-meta {
+    color: var(--ui-docs-muted-foreground);
+    font-size: 0.8125rem;
+  }
+
+  .docs-workspace__scroll {
+    flex: 1 1 auto;
+    min-height: 0;
+  }
+
+  .docs-workspace__scroll--padded {
+    padding: 1rem;
+  }
+
+  .docs-workspace__list {
+    margin: 0;
+    padding: 0.5rem;
+    list-style: none;
+  }
+
+  .docs-workspace__note {
+    display: flex;
+    width: 100%;
+    flex-direction: column;
+    gap: 0.15rem;
+    margin: 0 0 0.35rem;
+    padding: 0.65rem 0.75rem;
+    border: 1px solid transparent;
+    border-radius: var(--ui-docs-radius);
+    background: transparent;
+    color: inherit;
+    text-align: start;
+    cursor: pointer;
+  }
+
+  .docs-workspace__note[data-selected="true"] {
+    border-color: var(--ui-docs-border);
+    background: var(--ui-docs-card);
+  }
+
+  .docs-workspace__note-title {
+    font-weight: 600;
+  }
+
+  .docs-workspace__toolbar {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.75rem 1rem;
+  }
+
+  .docs-workspace__tabs {
+    display: flex;
+    gap: 0.5rem;
+  }
+
+  .docs-workspace__cards {
+    display: grid;
+    gap: 0.75rem;
+  }
+
+  .docs-workspace__card {
+    padding: 1rem;
+    border: 1px solid var(--ui-docs-border);
+    border-radius: var(--ui-docs-radius);
+    background: var(--ui-docs-card);
+  }
+
+  .docs-workspace__card h3,
+  .docs-workspace__card p {
+    margin: 0;
+  }
+
+  .docs-workspace__card h3 {
+    margin-block-end: 0.5rem;
+  }
+
+  .docs-workspace__review {
+    display: flex;
+    flex: 1 1 auto;
+    min-height: 0;
+    flex-direction: column;
+    gap: 1rem;
+    padding: 1rem;
+  }
+
+  .docs-workspace__ratings {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+  }
+
+  .docs-workspace__empty,
+  .docs-workspace__error {
+    padding: 1rem;
+  }
+
+  .docs-workspace__error {
+    color: var(--ui-destructive, #b91c1c);
+  }
+</style>

package/dist/docs-workspace.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { App } from "@lapis-notes/api";
+import "@lapismd/mira/styles.css";
+import "@lapismd/mira/themes/obsidian.css";
+import type { DocsRepository } from "./docs-repository";
+import type { DocsSettingsSource } from "./docs-view";
+type $$ComponentProps = {
+    app: App;
+    repository: DocsRepository;
+    clock?: () => Date;
+    settingsSource?: DocsSettingsSource;
+    mode?: "workspace" | "cards" | "review";
+};
+declare const DocsWorkspace: import("svelte").Component<$$ComponentProps, {}, "">;
+type DocsWorkspace = ReturnType<typeof DocsWorkspace>;
+export default DocsWorkspace;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { DOCS_DOCUMENT_VIEW_TYPE, DOCS_EXTENSIONS, DOCS_FILE_GLOB, DOCS_FILENAME_PATTERNS, docsDocumentExtension, isDocsDocumentPath, } from "./docs-path";
+export { DocsDocumentView } from "./docs-document-view";
+export { DocsPlugin, DOCS_PLUGIN_ID, default } from "./docs-plugin";
+export { DOCS_VIEW_TYPE, DocsView, type DocsSettingsSource, } from "./docs-view";
+export { DOCS_CARDS_VIEW_TYPE, DocsCardsView, } from "./docs-cards-view";
+export { DOCS_REVIEW_VIEW_TYPE, DocsReviewView, } from "./docs-review-view";
+export { DEFAULT_DOCS_PLUGIN_SETTINGS, DOCS_PLUGIN_DATA_VERSION, cloneDocsPluginSettings, mergeDocsPluginSettings, migrateDocsPluginData, normalizeDocsRoot, patchDocsPluginSettings, type DocsPluginDataV1, type DocsPluginSettings, type DocsPluginSettingsPatch, } from "./docs-settings";
+export { DocsRepository, createVaultDocsFileStore, type DocsFileStore, } from "./docs-repository";
+export { DOCS_NOTE_PROJECTION_FIELDS, DOCS_NOTE_PROJECTION_ID, DOCS_NOTE_PROJECTION_VERSION, createDocsProjectionRegistration, } from "./docs-index";
+export { default as DocsWorkspace } from "./docs-workspace.svelte";
+export { default as DocsFlipCard } from "./docs/DocsFlipCard.svelte";
+export * from "./model";

package/dist/index.js

@@ -0,0 +1,12 @@
+export { DOCS_DOCUMENT_VIEW_TYPE, DOCS_EXTENSIONS, DOCS_FILE_GLOB, DOCS_FILENAME_PATTERNS, docsDocumentExtension, isDocsDocumentPath, } from "./docs-path";
+export { DocsDocumentView } from "./docs-document-view";
+export { DocsPlugin, DOCS_PLUGIN_ID, default } from "./docs-plugin";
+export { DOCS_VIEW_TYPE, DocsView, } from "./docs-view";
+export { DOCS_CARDS_VIEW_TYPE, DocsCardsView, } from "./docs-cards-view";
+export { DOCS_REVIEW_VIEW_TYPE, DocsReviewView, } from "./docs-review-view";
+export { DEFAULT_DOCS_PLUGIN_SETTINGS, DOCS_PLUGIN_DATA_VERSION, cloneDocsPluginSettings, mergeDocsPluginSettings, migrateDocsPluginData, normalizeDocsRoot, patchDocsPluginSettings, } from "./docs-settings";
+export { DocsRepository, createVaultDocsFileStore, } from "./docs-repository";
+export { DOCS_NOTE_PROJECTION_FIELDS, DOCS_NOTE_PROJECTION_ID, DOCS_NOTE_PROJECTION_VERSION, createDocsProjectionRegistration, } from "./docs-index";
+export { default as DocsWorkspace } from "./docs-workspace.svelte";
+export { default as DocsFlipCard } from "./docs/DocsFlipCard.svelte";
+export * from "./model";

package/dist/model/book.d.ts

@@ -0,0 +1,6 @@
+import type { DocsBookChapterNavigation, DocsBookNavigation, DocsNote } from "./types";
+export declare function buildDocsBooks(notes: DocsNote[]): {
+    books: DocsBookNavigation[];
+    bookChaptersByNoteId: Record<string, DocsBookChapterNavigation>;
+};
+export declare function resolveDocsBookNavigation(books: DocsBookNavigation[], chapterNavigation: DocsBookChapterNavigation | null | undefined): DocsBookNavigation | null;

package/dist/model/book.js

@@ -0,0 +1,101 @@
+function compareSourcePath(left, right) {
+    const sourceCompare = left.sourcePath.localeCompare(right.sourcePath);
+    if (sourceCompare !== 0)
+        return sourceCompare;
+    return left.id.localeCompare(right.id);
+}
+function chapterFromRef(noteId, index, notesById) {
+    const note = notesById.get(noteId);
+    if (!note) {
+        return {
+            index,
+            noteId,
+            title: noteId,
+            summary: "",
+            sourcePath: "",
+            resolved: false,
+            completed: false,
+        };
+    }
+    const completedAt = note.completedAt?.trim() || undefined;
+    return {
+        index,
+        noteId,
+        title: note.title,
+        summary: note.summary,
+        sourcePath: note.sourcePath,
+        resolved: true,
+        completed: Boolean(completedAt),
+        ...(completedAt ? { completedAt } : {}),
+    };
+}
+function bookProgress(chapters) {
+    const resolvedChapters = chapters.filter((chapter) => chapter.resolved);
+    const completedCount = resolvedChapters.filter((chapter) => chapter.completed).length;
+    const resolvedCount = resolvedChapters.length;
+    const progressPercent = resolvedCount === 0 ? 0 : Math.round((completedCount / resolvedCount) * 100);
+    return { completedCount, resolvedCount, progressPercent };
+}
+function navigationForChapter(book, resolvedChapters, resolvedIndex) {
+    return {
+        bookId: book.id,
+        bookIndexNoteId: book.indexNoteId,
+        bookTitle: book.title,
+        progressPercent: book.progressPercent,
+        completedCount: book.completedCount,
+        resolvedCount: book.resolvedCount,
+        chapter: resolvedChapters[resolvedIndex],
+        previousChapter: resolvedChapters[resolvedIndex - 1],
+        nextChapter: resolvedChapters[resolvedIndex + 1],
+    };
+}
+export function buildDocsBooks(notes) {
+    const notesById = new Map(notes.map((note) => [note.id, note]));
+    const indexNotes = notes
+        .filter((note) => note.book?.chapters.length)
+        .sort(compareSourcePath);
+    const books = indexNotes.map((note) => {
+        const chapters = note.book?.chapters.map((chapter, index) => chapterFromRef(chapter.noteId, index, notesById)) ?? [];
+        return {
+            id: note.id,
+            indexNoteId: note.id,
+            title: note.title,
+            summary: note.summary,
+            sourcePath: note.sourcePath,
+            chapters,
+            ...bookProgress(chapters),
+        };
+    });
+    const booksById = new Map(books.map((book) => [book.id, book]));
+    const bookChaptersByNoteId = {};
+    // Explicit bookId wins when the note appears in that book's TOC.
+    for (const note of notes) {
+        const bookId = note.bookId?.trim();
+        if (!bookId)
+            continue;
+        const book = booksById.get(bookId);
+        if (!book)
+            continue;
+        const resolvedChapters = book.chapters.filter((chapter) => chapter.resolved);
+        const resolvedIndex = resolvedChapters.findIndex((chapter) => chapter.noteId === note.id);
+        if (resolvedIndex < 0)
+            continue;
+        bookChaptersByNoteId[note.id] = navigationForChapter(book, resolvedChapters, resolvedIndex);
+    }
+    // Legacy / remaining: first TOC membership in book sourcePath order.
+    for (const book of books) {
+        const resolvedChapters = book.chapters.filter((chapter) => chapter.resolved);
+        for (let resolvedIndex = 0; resolvedIndex < resolvedChapters.length; resolvedIndex += 1) {
+            const chapter = resolvedChapters[resolvedIndex];
+            if (bookChaptersByNoteId[chapter.noteId])
+                continue;
+            bookChaptersByNoteId[chapter.noteId] = navigationForChapter(book, resolvedChapters, resolvedIndex);
+        }
+    }
+    return { books, bookChaptersByNoteId };
+}
+export function resolveDocsBookNavigation(books, chapterNavigation) {
+    if (!chapterNavigation)
+        return null;
+    return books.find((book) => book.id === chapterNavigation.bookId) ?? null;
+}

package/dist/model/coding-runtime.d.ts

@@ -0,0 +1,4 @@
+import type { DocsCodingLanguage } from "./types";
+/** Parse-time defaults for coding-drill metadata. Practice UI is out of Core Docs scope. */
+export declare const CODING_RUNTIME_VERSIONS: Record<DocsCodingLanguage, string>;
+export declare function codingRuntimeVersion(language: DocsCodingLanguage): string;

package/dist/model/coding-runtime.js

@@ -0,0 +1,9 @@
+/** Parse-time defaults for coding-drill metadata. Practice UI is out of Core Docs scope. */
+export const CODING_RUNTIME_VERSIONS = {
+    python: "3.14.6",
+    java: "25.0.3",
+    kotlin: "2.4.0",
+};
+export function codingRuntimeVersion(language) {
+    return CODING_RUNTIME_VERSIONS[language];
+}

package/dist/model/docs-card-context.d.ts

@@ -0,0 +1,32 @@
+import type { DocsNote, DocsRevisionBlock } from "./types";
+export type ResolvedCardBlockRef = {
+    ref: string;
+    block: DocsRevisionBlock;
+};
+export type MissingCardBlockRef = {
+    ref: string;
+    reason: "missing";
+};
+export type CardBlockRefResolution = {
+    resolved: ResolvedCardBlockRef[];
+    missing: MissingCardBlockRef[];
+};
+export declare function resolveCardBlockRefs(note: Pick<DocsNote, "blocks">, blockRefs: string[]): CardBlockRefResolution;
+export declare function cardHasBackMatter(card: Pick<import("./types").DocsCard, "blockRefs">): boolean;
+export declare function docsBlockPlainText(block: DocsRevisionBlock): string;
+export declare function docsBlockSnippet(block: DocsRevisionBlock, limit?: number): string;
+export declare function docsBlockRefMarker(id: string): string;
+export declare function docsBlockIdFromRef(ref: string): string;
+export declare function docsBlockReferenceIndex(blocks: DocsRevisionBlock[]): {
+    references: {
+        id: string;
+        ref: string;
+        marker: string;
+        path: string;
+        type: string;
+        label: string;
+        excerpt: string;
+        duplicate: boolean;
+    }[];
+    duplicates: {};
+};

package/dist/model/docs-card-context.js

@@ -0,0 +1,89 @@
+const BLOCK_REF_MARKER = /^\[\^([a-z0-9][a-z0-9-]{0,79})\]$/;
+const BLOCK_TYPE_LABELS = {
+    text: "Text",
+    markdown: "Markdown",
+    concept: "Concept",
+    procedure: "Procedure",
+    prompt: "Prompt",
+    code: "Code",
+    table: "Table",
+    callout: "Callout",
+    story: "Story",
+    resources: "Resources",
+};
+export function resolveCardBlockRefs(note, blockRefs) {
+    const byId = new Map(note.blocks.map((block) => [block.id, block]));
+    const resolved = [];
+    const missing = [];
+    const seen = new Set();
+    for (const ref of blockRefs) {
+        const trimmed = ref.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        const block = byId.get(trimmed);
+        if (block)
+            resolved.push({ ref: trimmed, block });
+        else
+            missing.push({ ref: trimmed, reason: "missing" });
+    }
+    return { resolved, missing };
+}
+export function cardHasBackMatter(card) {
+    return card.blockRefs.some((ref) => ref.trim());
+}
+function plain(value) {
+    return (value ?? "").replace(/\s+/g, " ").trim();
+}
+export function docsBlockPlainText(block) {
+    switch (block.type) {
+        case "text":
+        case "markdown":
+        case "callout":
+            return plain(block.body);
+        case "concept":
+            return plain([block.summary, ...block.keyPoints, block.details].join(" "));
+        case "procedure":
+            return plain([...block.steps, block.notes].join(" "));
+        case "prompt":
+            return plain(block.problem);
+        case "code":
+            return plain(block.caption || block.code);
+        case "table":
+            return plain(block.rows[0]?.join(", ") || block.columns.join(", "));
+        case "story":
+            return plain(block.situation || block.action || block.result);
+        case "resources":
+            return plain(block.items
+                .map((item) => item.title || item.notes)
+                .filter(Boolean)
+                .join(" · "));
+    }
+}
+export function docsBlockSnippet(block, limit = 140) {
+    const text = docsBlockPlainText(block);
+    if (text.length <= limit)
+        return text;
+    return `${text.slice(0, limit - 1).trimEnd()}…`;
+}
+export function docsBlockRefMarker(id) {
+    return `[^${id}]`;
+}
+export function docsBlockIdFromRef(ref) {
+    return BLOCK_REF_MARKER.exec(ref.trim())?.[1] ?? ref.trim();
+}
+export function docsBlockReferenceIndex(blocks) {
+    return {
+        references: blocks.map((block) => ({
+            id: block.id,
+            ref: docsBlockRefMarker(block.id),
+            marker: block.id,
+            path: block.id,
+            type: BLOCK_TYPE_LABELS[block.type],
+            label: block.title?.trim() || BLOCK_TYPE_LABELS[block.type],
+            excerpt: docsBlockSnippet(block),
+            duplicate: false,
+        })),
+        duplicates: {},
+    };
+}