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

package/dist/model/types.d.ts

@@ -0,0 +1,328 @@
+export declare const DOCS_NOTE_SCHEMA_VERSION = "cvstudio.docs.note.v4";
+export type DocsDocType = "revision" | "coding-drill" | "system-design" | "story-bank" | "index" | "freeform";
+export type DocsCardType = "basic" | "cloze" | "coding";
+export type DocsCardStatus = "active" | "suspended";
+export type DocsReviewRating = "again" | "hard" | "good" | "easy";
+export type DocsNotePanel = "note" | "display" | "cards" | "review" | "practice";
+export type DocsFsrsStateName = "New" | "Learning" | "Review" | "Relearning";
+export type DocsCalloutTone = "note" | "tip" | "warning" | "critical";
+export type DocsCodingLanguage = "python" | "java" | "kotlin";
+export type DocsCodingDifficulty = "easy" | "medium" | "hard";
+export type DocsCodingValueType = "int" | "long" | "boolean" | "string" | "int[]" | "long[]" | "boolean[]" | "string[]" | "int[][]" | "long[][]" | "boolean[][]" | "string[][]";
+export type DocsCodingLiteral = string | number | boolean | DocsCodingLiteral[];
+export type DocsCodingParameter = {
+    name: string;
+    type: DocsCodingValueType;
+};
+export type DocsCodingSignature = {
+    className: string;
+    methodName: string;
+    parameters: DocsCodingParameter[];
+    returnType: DocsCodingValueType;
+};
+export type DocsCodingLanguageTemplate = {
+    language: DocsCodingLanguage;
+    version: string;
+    fileName: string;
+    starterCode: string;
+};
+export type DocsCodingExample = {
+    id: string;
+    title?: string;
+    arguments: DocsCodingLiteral[];
+    expected: DocsCodingLiteral;
+    explanation?: string;
+};
+export type DocsCodingHint = {
+    id: string;
+    title: string;
+    body: string;
+};
+export type DocsCodingSolution = {
+    language: DocsCodingLanguage;
+    explanation?: string;
+    code: string;
+};
+export type DocsCodingExercise = {
+    id: string;
+    difficulty: DocsCodingDifficulty;
+    description: string;
+    constraints: string[];
+    signature: DocsCodingSignature;
+    languages: DocsCodingLanguageTemplate[];
+    examples: DocsCodingExample[];
+    hints: DocsCodingHint[];
+    solutions: DocsCodingSolution[];
+};
+export type DocsRevisionBlockBase = {
+    id: string;
+    title?: string;
+};
+export type DocsTextBlock = DocsRevisionBlockBase & {
+    type: "text";
+    body: string;
+};
+export type DocsMarkdownBlock = DocsRevisionBlockBase & {
+    type: "markdown";
+    body: string;
+};
+export type DocsConceptBlock = DocsRevisionBlockBase & {
+    type: "concept";
+    summary: string;
+    keyPoints: string[];
+    details: string;
+};
+export type DocsProcedureBlock = DocsRevisionBlockBase & {
+    type: "procedure";
+    steps: string[];
+    notes: string;
+};
+export type DocsPromptBlock = DocsRevisionBlockBase & {
+    type: "prompt";
+    problem: string;
+    requirements: string[];
+    approach: string;
+    traps: string[];
+    tests: string[];
+    answer: string;
+};
+export type DocsCodeBlock = DocsRevisionBlockBase & {
+    type: "code";
+    language: string;
+    code: string;
+    caption: string;
+};
+export type DocsTableBlock = DocsRevisionBlockBase & {
+    type: "table";
+    columns: string[];
+    rows: string[][];
+};
+export type DocsCalloutBlock = DocsRevisionBlockBase & {
+    type: "callout";
+    tone: DocsCalloutTone;
+    body: string;
+};
+export type DocsStoryBlock = DocsRevisionBlockBase & {
+    type: "story";
+    useFor: string[];
+    situation: string;
+    task: string;
+    action: string;
+    result: string;
+    metrics: string[];
+};
+export type DocsResourceItem = {
+    title: string;
+    url: string;
+    kind: string;
+    notes: string;
+};
+export type DocsResourcesBlock = DocsRevisionBlockBase & {
+    type: "resources";
+    items: DocsResourceItem[];
+};
+export type DocsRevisionBlock = DocsTextBlock | DocsMarkdownBlock | DocsConceptBlock | DocsProcedureBlock | DocsPromptBlock | DocsCodeBlock | DocsTableBlock | DocsCalloutBlock | DocsStoryBlock | DocsResourcesBlock;
+export type DocsBookChapterRef = {
+    noteId: string;
+};
+export type DocsBookMetadata = {
+    chapters: DocsBookChapterRef[];
+};
+export type DocsFsrsState = {
+    due: string;
+    stability: number;
+    difficulty: number;
+    elapsedDays: number;
+    scheduledDays: number;
+    learningSteps: number;
+    reps: number;
+    lapses: number;
+    state: DocsFsrsStateName;
+    lastReview?: string;
+};
+export type DocsReviewLog = {
+    id: string;
+    rating: DocsReviewRating;
+    reviewedAt: string;
+    state: DocsFsrsStateName;
+    due: string;
+    stability: number;
+    difficulty: number;
+    elapsedDays: number;
+    scheduledDays: number;
+    learningSteps: number;
+};
+export type DocsCard = {
+    id: string;
+    type: DocsCardType;
+    status: DocsCardStatus;
+    prompt: string;
+    answer: string;
+    tags: string[];
+    blockRefs: string[];
+    fsrs?: DocsFsrsState;
+    reviews: DocsReviewLog[];
+    /** Required when type is coding; coding cards do not enter the FSRS queue. */
+    exercise?: DocsCodingExercise;
+};
+export type DocsNote = {
+    id: string;
+    title: string;
+    docType: DocsDocType;
+    summary: string;
+    learningGoal: string;
+    aliases: string[];
+    tags: string[];
+    book?: DocsBookMetadata;
+    /** Index note id when this note is a chapter of a book. */
+    bookId?: string;
+    blocks: DocsRevisionBlock[];
+    cards: DocsCard[];
+    body: string;
+    /** ISO timestamp when the note was marked complete for reading progress. */
+    completedAt?: string;
+    createdAt: string;
+    updatedAt: string;
+    sourcePath: string;
+};
+/** Sidebar / index payload without bodies, blocks, or card content. */
+export type DocsNoteSummary = {
+    id: string;
+    title: string;
+    docType: DocsDocType;
+    summary: string;
+    aliases: string[];
+    tags: string[];
+    sourcePath: string;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    cardCount: number;
+    blockCount: number;
+    dueCardCount?: number;
+    book?: DocsBookMetadata;
+    bookId?: string;
+};
+export type DocsMarkdownFile = {
+    path: string;
+    content: string;
+};
+export type DocsWikiLink = {
+    sourceNoteId: string;
+    raw: string;
+    target: string;
+    label?: string;
+    resolvedNoteId?: string;
+    ambiguousNoteIds?: string[];
+    index: number;
+};
+export type DocsBacklink = {
+    sourceNoteId: string;
+    sourceTitle: string;
+    raw: string;
+    label?: string;
+    excerpt: string;
+};
+export type DocsGraph = {
+    links: DocsWikiLink[];
+    backlinks: Record<string, DocsBacklink[]>;
+    unresolvedLinks: DocsWikiLink[];
+    ambiguousLinks: DocsWikiLink[];
+    tags: DocsTagSummary[];
+};
+export type DocsTagSummary = {
+    tag: string;
+    noteCount: number;
+    cardCount: number;
+};
+export type DocsReviewQueueItem = {
+    noteId: string;
+    noteTitle: string;
+    noteSourcePath?: string;
+    cardId: string;
+    card: DocsCard;
+    dueAt: string;
+};
+export type DocsBookChapter = {
+    index: number;
+    noteId: string;
+    title: string;
+    summary: string;
+    sourcePath: string;
+    resolved: boolean;
+    completed: boolean;
+    completedAt?: string;
+};
+export type DocsBookNavigation = {
+    id: string;
+    indexNoteId: string;
+    title: string;
+    summary: string;
+    sourcePath: string;
+    chapters: DocsBookChapter[];
+    completedCount: number;
+    resolvedCount: number;
+    progressPercent: number;
+};
+/** Slim chapter membership — resolve full TOC via `books` + `bookId`. */
+export type DocsBookChapterNavigation = {
+    bookId: string;
+    bookIndexNoteId: string;
+    bookTitle: string;
+    progressPercent: number;
+    completedCount: number;
+    resolvedCount: number;
+    chapter: DocsBookChapter;
+    previousChapter?: DocsBookChapter;
+    nextChapter?: DocsBookChapter;
+};
+/**
+ * Due-card queue for the index payload. Includes full cards (queue is small)
+ * so review UI works without loading every note body.
+ */
+export type DocsReviewQueueSummaryItem = DocsReviewQueueItem;
+/** Workspace list payload without full note bodies. */
+export type DocsWorkspaceIndex = {
+    notes: DocsNoteSummary[];
+    graph: DocsGraph;
+    reviewQueue: DocsReviewQueueSummaryItem[];
+    tags: DocsTagSummary[];
+    books: DocsBookNavigation[];
+    bookChaptersByNoteId: Record<string, DocsBookChapterNavigation>;
+};
+export type DocsCardStackMode = "browse" | "study";
+export type DocsReviewScope = "note" | "workspace";
+export type DocsCardStackItem = {
+    key: string;
+    card: DocsCard;
+    noteId?: string;
+    noteTitle: string;
+    noteSourcePath?: string;
+    noteBlocks?: DocsRevisionBlock[];
+    dueAt?: string;
+};
+export type DocsWorkspace = {
+    notes: DocsNote[];
+    graph: DocsGraph;
+    reviewQueue: DocsReviewQueueItem[];
+    tags: DocsTagSummary[];
+    books: DocsBookNavigation[];
+    bookChaptersByNoteId: Record<string, DocsBookChapterNavigation>;
+};
+export type CreateDocsNoteInput = {
+    id?: string;
+    title?: string;
+    docType?: DocsDocType;
+    summary?: string;
+    learningGoal?: string;
+    aliases?: string[];
+    tags?: string[];
+    book?: DocsBookMetadata;
+    bookId?: string;
+    blocks?: Partial<DocsRevisionBlock>[];
+    body?: string;
+    cards?: Partial<DocsCard>[];
+    completedAt?: string;
+    createdAt?: string;
+    updatedAt?: string;
+};

package/dist/model/types.js

@@ -0,0 +1 @@
+export const DOCS_NOTE_SCHEMA_VERSION = "cvstudio.docs.note.v4";

package/dist/model/workspace.d.ts

@@ -0,0 +1,6 @@
+import type { DocsNote, DocsNoteSummary, DocsWorkspace, DocsWorkspaceIndex } from "./types";
+export declare function docsNoteToSummary(note: DocsNote, dueCardCount?: number): DocsNoteSummary;
+export declare function buildDocsWorkspace(notes: DocsNote[], now?: Date): DocsWorkspace;
+export declare function buildDocsWorkspaceIndex(notes: DocsNote[], now?: Date): DocsWorkspaceIndex;
+/** Expand summaries to stub notes for APIs that still expect DocsNote[]. */
+export declare function docsSummariesToStubNotes(summaries: DocsNoteSummary[]): DocsNote[];

package/dist/model/workspace.js

@@ -0,0 +1,81 @@
+import { buildDocsBooks } from "./book";
+import { buildDocsReviewQueue } from "./fsrs";
+import { buildDocsGraph } from "./graph";
+export function docsNoteToSummary(note, dueCardCount = 0) {
+    return {
+        id: note.id,
+        title: note.title,
+        docType: note.docType,
+        summary: note.summary,
+        aliases: note.aliases,
+        tags: note.tags,
+        sourcePath: note.sourcePath,
+        createdAt: note.createdAt,
+        updatedAt: note.updatedAt,
+        ...(note.completedAt ? { completedAt: note.completedAt } : {}),
+        cardCount: note.cards.length,
+        blockCount: note.blocks.length,
+        ...(dueCardCount > 0 ? { dueCardCount } : {}),
+        ...(note.book ? { book: note.book } : {}),
+        ...(note.bookId ? { bookId: note.bookId } : {}),
+    };
+}
+export function buildDocsWorkspace(notes, now = new Date()) {
+    const sortedNotes = [...notes].sort((left, right) => left.title.localeCompare(right.title));
+    const graph = buildDocsGraph(sortedNotes);
+    const { books, bookChaptersByNoteId } = buildDocsBooks(sortedNotes);
+    return {
+        notes: sortedNotes,
+        graph,
+        reviewQueue: buildDocsReviewQueue(sortedNotes, now),
+        tags: graph.tags,
+        books,
+        bookChaptersByNoteId,
+    };
+}
+export function buildDocsWorkspaceIndex(notes, now = new Date()) {
+    const workspace = buildDocsWorkspace(notes, now);
+    const dueByNote = new Map();
+    for (const item of workspace.reviewQueue) {
+        dueByNote.set(item.noteId, (dueByNote.get(item.noteId) ?? 0) + 1);
+    }
+    return {
+        notes: workspace.notes.map((note) => docsNoteToSummary(note, dueByNote.get(note.id) ?? 0)),
+        graph: workspace.graph,
+        // Keep due cards in the index — the queue is small vs full note bodies.
+        reviewQueue: workspace.reviewQueue,
+        tags: workspace.tags,
+        books: workspace.books,
+        bookChaptersByNoteId: workspace.bookChaptersByNoteId,
+    };
+}
+/** Expand summaries to stub notes for APIs that still expect DocsNote[]. */
+export function docsSummariesToStubNotes(summaries) {
+    return summaries.map((summary) => ({
+        id: summary.id,
+        title: summary.title,
+        docType: summary.docType,
+        summary: summary.summary,
+        learningGoal: "",
+        aliases: summary.aliases,
+        tags: summary.tags,
+        ...(summary.book ? { book: summary.book } : {}),
+        ...(summary.bookId ? { bookId: summary.bookId } : {}),
+        blocks: [],
+        cards: Array.from({ length: summary.cardCount }, (_, index) => ({
+            id: `stub-card-${index + 1}`,
+            type: "basic",
+            status: "active",
+            prompt: "",
+            answer: "",
+            tags: [],
+            blockRefs: [],
+            reviews: [],
+        })),
+        body: "",
+        ...(summary.completedAt ? { completedAt: summary.completedAt } : {}),
+        createdAt: summary.createdAt,
+        updatedAt: summary.updatedAt,
+        sourcePath: summary.sourcePath,
+    }));
+}

package/dist/storybook.css

@@ -0,0 +1,52 @@
+body.sb-main-fullscreen #storybook-root {
+  min-height: 100vh;
+  box-sizing: border-box;
+  padding: 1.5rem;
+}
+
+.docs-story {
+  overflow: visible !important;
+}
+
+.docs-story .sb-story {
+  box-sizing: border-box;
+  padding: 1rem 2.5rem;
+}
+
+.docs-story-frame {
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 24rem;
+  overflow: hidden;
+  border: 1px solid var(--ui-docs-border);
+  border-radius: var(--ui-docs-radius);
+  background: var(--ui-docs-background);
+}
+
+body.sb-main-fullscreen #storybook-root:has(.docs-story-shell-stage) {
+  padding: 0;
+}
+
+.docs-story-shell-stage {
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 70rem;
+  height: 100vh;
+  min-height: 42rem;
+  overflow: hidden;
+  padding: 1.5rem;
+  background: var(--ui-docs-muted);
+}
+
+.docs-story-shell-stage__surface {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+  overflow: hidden;
+  border: 1px solid var(--ui-docs-border);
+  border-radius: var(--ui-docs-radius);
+  background: var(--ui-docs-background);
+}

package/dist/styles.css

@@ -0,0 +1 @@
+@import "./docs/docs.tokens.css";

package/manifest.json

@@ -0,0 +1,11 @@
+{
+  "id": "docs",
+  "name": "Docs",
+  "version": "0.1.0",
+  "minAppVersion": "0.0.1",
+  "description": "Vault-native Docs notes, books, cards, and FSRS review.",
+  "author": "Lapis Notes",
+  "distribution": "first-party-external",
+  "provenance": "official",
+  "enabledByDefault": true
+}

package/package.json

@@ -1,6 +1,149 @@
 {
   "name": "@lapis-notes/lapis-plugin-docs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Lapis Notes Docs workspace: notes, books, cards, and FSRS review",
+  "license": "AGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lapismd/lapis-plugin-docs.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@10.32.1",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "pnpm run prepack",
+    "check": "pnpm spec:validate && pnpm check:app-ownership && pnpm check:no-tailwind && pnpm check:svelte && pnpm check:types",
+    "check:app-ownership": "vitest run --project unit src/lib/application-ownership.test.ts",
+    "check:no-tailwind": "node scripts/check-no-tailwind.mjs",
+    "check:svelte": "svelte-check --tsconfig ./tsconfig.app.json --fail-on-warnings --output human",
+    "check:types": "tsc -p tsconfig.node.json --noEmit",
+    "test": "vitest run --project unit --passWithNoTests",
+    "test:storybook": "vitest run --project storybook",
+    "build-storybook": "NODE_OPTIONS=\"${NODE_OPTIONS:---max-old-space-size=8192}\" storybook build --config-dir .storybook --output-dir storybook-static",
+    "publint": "publint",
+    "prepack": "svelte-package --tsconfig ./tsconfig.pack.json && publint",
+    "spec:build": "spec-validator build",
+    "spec:check": "spec-validator check && pnpm check:app-ownership",
+    "spec:first": "spec-validator first",
+    "spec:validate": "spec-validator validate",
+    "storybook": "WATCHPACK_POLLING=250 node scripts/storybook-run.mjs --no-open --config-dir .storybook",
+    "storybook:stop": "bash scripts/storybook-stop.sh",
+    "storybook:restart": "bash scripts/storybook-restart.sh",
+    "validation:check": "vitest run --project unit scripts/ci.test.mjs",
+    "validation:smoke": "node scripts/validation/smoke.mjs",
+    "changeset": "changeset",
+    "release:version": "node scripts/release.mjs version",
+    "release:prepare": "node scripts/release.mjs prepare",
+    "release:attest": "node scripts/release.mjs attest",
+    "release:publish": "node scripts/release.mjs publish",
+    "release:verify": "node scripts/release.mjs verify"
+  },
+  "files": [
+    "dist",
+    "manifest.json",
+    "CHANGELOG.md",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*",
+    "!dist/**/*.stories.*",
+    "!dist/**/*.example-sources.*",
+    "!dist/**/*.story-play.*"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "dependencies": {
+    "@internationalized/date": "3.12.2",
+    "@libsql/client": "^0.18.0",
+    "@lucide/svelte": "^0.523.0",
+    "fflate": "^0.8.3",
+    "ts-fsrs": "^5.4.1",
+    "yaml": "^2.9.0"
+  },
+  "peerDependencies": {
+    "@lapis-notes/api": "^0.2.6",
+    "@lapismd/design-core": "^0.12.1",
+    "@lapismd/mira": "~0.1.4",
+    "@lapismd/mira-editor": "~0.0.3",
+    "svelte": "5.56.10"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.3",
+    "@codemirror/autocomplete": "6.20.3",
+    "@codemirror/commands": "6.10.4",
+    "@codemirror/lang-markdown": "6.5.2",
+    "@codemirror/lang-yaml": "6.1.3",
+    "@codemirror/language": "6.12.4",
+    "@codemirror/lint": "6.9.7",
+    "@codemirror/search": "6.7.1",
+    "@codemirror/state": "6.7.1",
+    "@codemirror/view": "6.43.8",
+    "@fontsource-variable/dm-sans": "^5.2.8",
+    "@fontsource-variable/source-code-pro": "5.2.7",
+    "@lapis-notes/api": "0.2.6",
+    "@lapis-notes/file-explorer": "0.2.2",
+    "@lapis-notes/markdown": "0.2.2",
+    "@lapis-notes/search": "0.1.5",
+    "@lapis-notes/ui": "0.1.7",
+    "@lapis-notes/workspace": "0.3.4",
+    "@lapismd/design-core": "0.12.1",
+    "@lapismd/mira": "0.1.4",
+    "@lapismd/mira-editor": "~0.0.3",
+    "@lapismd/spec-validator": "^0.2.0",
+    "@lezer/common": "1.5.2",
+    "@lezer/highlight": "1.2.3",
+    "@lezer/lr": "1.4.10",
+    "@lezer/markdown": "1.7.2",
+    "@storybook/addon-a11y": "10.5.7",
+    "@storybook/addon-docs": "10.5.7",
+    "@storybook/addon-svelte-csf": "5.1.2",
+    "@storybook/addon-themes": "10.5.7",
+    "@storybook/addon-vitest": "10.5.7",
+    "@storybook/svelte-vite": "10.5.7",
+    "@sveltejs/package": "2.5.0",
+    "@sveltejs/vite-plugin-svelte": "5.1.1",
+    "@tailwindcss/vite": "4.1.12",
+    "@tsconfig/svelte": "5.0.5",
+    "@types/node": "^22.15.0",
+    "@vitest/browser": "4.1.10",
+    "@vitest/browser-playwright": "4.1.10",
+    "aria-query": "5.3.2",
+    "bits-ui": "2.20.2",
+    "publint": "0.3.12",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "sigstore": "4.1.1",
+    "storybook": "10.5.7",
+    "svelte": "5.56.10",
+    "svelte-check": "4.3.1",
+    "tailwindcss": "4.1.12",
+    "typescript": "~5.8.3",
+    "vite": "6.4.3",
+    "vitest": "4.1.10"
+  },
+  "pnpm": {
+    "overrides": {
+      "@lapismd/design-core": "0.12.1"
+    },
+    "peerDependencyRules": {
+      "allowedVersions": {
+        "@lapismd/design-core": "0.12"
+      }
+    }
+  }
+}