@khorsheed/dsh-reader 0.3.0 → 0.3.2

package/lib/types/notes-types.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The notes' wire and storage shapes (see `notes.ts` for the store). Kept in a
+ * module of their own so the Remote face, the browser half and the `./types`
+ * subpath can name them without pulling in the store's `node:` imports.
+ *
+ * @module @khorsheed/dsh-reader/notes-types
+ */
+/**
+ * Where a note sits in the article.
+ *
+ * `quote` is the source of truth: it is the ORIGINAL text, whichever view the
+ * reader selected in. `block` (0-based top-level block, the reading position's
+ * own unit) and `start` (characters into that block's original text) are
+ * hints that make finding it again cheap; when a refetch changed the article
+ * they may be wrong, and the quote is searched for instead.
+ */
+export interface ReaderNoteAnchor {
+    readonly block: number;
+    readonly start?: number;
+    readonly quote: string;
+    /** The translated text, when the selection was made in the translated view. */
+    readonly translated?: string;
+    /** A video / audio transcript paragraph's start (seconds): where ▶ plays from. */
+    readonly time?: number;
+}
+/**
+ * One line under a note: a conclusion a discussion reached, or the reader's
+ * own addition. Written by the model only when the reader asks for it.
+ */
+export interface ReaderNoteReply {
+    readonly by: 'agent' | 'user';
+    readonly text: string;
+    /** The conversation it came from, so the reader can go back to it. */
+    readonly sessionId?: string;
+    /** Set when the reader rewrote a line the model wrote. */
+    readonly editedFrom?: 'agent';
+    readonly at: string;
+}
+/** A canvas card a note (or discussion note) was synced to. */
+export interface ReaderSyncedCard {
+    readonly canvasId: string;
+    readonly cardId: string;
+    /** The canvas's title when it was synced (for the 「已在…」 mark). */
+    readonly canvasTitle: string;
+    readonly at: string;
+}
+/** One note: an excerpt and, optionally, what the reader thought of it. */
+export interface ReaderNote {
+    /** `n1`, `n2`… per article, never reused — the model cites notes by it. */
+    readonly id: string;
+    readonly anchor: ReaderNoteAnchor;
+    readonly comment?: string;
+    /** Conclusions and additions, oldest first. */
+    readonly replies?: readonly ReaderNoteReply[];
+    /** Canvas cards made from it (a later edit does not reach them). */
+    readonly syncedTo?: readonly ReaderSyncedCard[];
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+/** One point of a discussion note, with the paragraph it points back to. */
+export interface ReaderDiscussionPoint {
+    readonly text: string;
+    /** ¶ number (1-based), when the point cites the article. */
+    readonly para?: number;
+}
+/**
+ * A discussion note: what one conversation about the article came to.
+ *
+ * `check` is a 「让Agent考考我」 round — not an exam: no score, no retake; its
+ * points are what the reader had not yet got right, each with the explanation.
+ */
+export interface ReaderDiscussion {
+    /** `d1`, `d2`… per article, never reused. */
+    readonly id: string;
+    readonly kind: 'discussion' | 'check';
+    readonly sessionId?: string;
+    readonly title: string;
+    readonly points: readonly ReaderDiscussionPoint[];
+    /** One line for what went fine (「其余 2 题讲到位了」). */
+    readonly aside?: string;
+    /** Canvas cards made from it. */
+    readonly syncedTo?: readonly ReaderSyncedCard[];
+    readonly createdAt: string;
+}
+/** One conversation that discussed the article. */
+export interface ReaderEntrySession {
+    readonly sessionId: string;
+    readonly title?: string;
+    readonly lastAt: string;
+}
+/** Everything the reader authored about one article. */
+export interface ReaderEntryNotes {
+    readonly entryId: string;
+    readonly title: string;
+    readonly url?: string;
+    /** The source's display label (the feed's name, or the site). */
+    readonly source?: string;
+    readonly notes: readonly ReaderNote[];
+    readonly sessions: readonly ReaderEntrySession[];
+    /** Discussion notes, newest first. */
+    readonly discussions?: readonly ReaderDiscussion[];
+    /** The next note number; ids are never reused, so a deleted n3 stays deleted. */
+    readonly nextNote: number;
+    /** The next discussion number, never reused either. */
+    readonly nextDiscussion?: number;
+    readonly updatedAt: string;
+}
+/** One snapshot's index row (the text itself is a file of its own). */
+export interface ReaderSnapshotRecord {
+    readonly file: string;
+    readonly chars: number;
+    readonly capturedAt: string;
+}
+/** The notes document. */
+export interface ReaderNotesDoc {
+    readonly version: 1;
+    readonly entries: Readonly<Record<string, ReaderEntryNotes>>;
+    readonly snapshots: Readonly<Record<string, ReaderSnapshotRecord>>;
+}
+/** One article's text as the browser rendered it, for the model. */
+export interface ReaderEntrySnapshot {
+    readonly entryId: string;
+    readonly title: string;
+    readonly url?: string;
+    readonly source?: string;
+    /** One string per top-level block; ¶n is `paragraphs[n - 1]`. */
+    readonly paragraphs: readonly string[];
+    readonly truncated?: boolean;
+    readonly capturedAt: string;
+}
+/** What a note write answers. */
+export type ReaderNoteOutcome = 'ok' | 'not-found' | 'empty' | 'full';
+/** The article identity every write carries, so a note never lands on a nameless entry. */
+export interface ReaderEntryIdentity {
+    readonly entryId: string;
+    readonly title: string;
+    readonly url?: string;
+    readonly source?: string;
+}
+/** A note's input as the browser sends it, before bounding. */
+export interface ReaderNoteInput extends ReaderEntryIdentity {
+    readonly block: number;
+    readonly start?: number;
+    readonly quote: string;
+    readonly translated?: string;
+    readonly comment?: string;
+    readonly time?: number;
+}
+/** A discussion note's input, before bounding. */
+export interface ReaderDiscussionInput extends ReaderEntryIdentity {
+    readonly kind: 'discussion' | 'check';
+    readonly sessionId?: string;
+    /** The discussion note's own short title (`title` is the article's). */
+    readonly heading?: string;
+    readonly points: readonly ReaderDiscussionPoint[];
+    readonly aside?: string;
+}
+//# sourceMappingURL=notes-types.d.ts.map

package/lib/types/notes-types.js

@@ -0,0 +1,8 @@
+/**
+ * The notes' wire and storage shapes (see `notes.ts` for the store). Kept in a
+ * module of their own so the Remote face, the browser half and the `./types`
+ * subpath can name them without pulling in the store's `node:` imports.
+ *
+ * @module @khorsheed/dsh-reader/notes-types
+ */
+export {};

package/lib/types/notes.d.ts

@@ -0,0 +1,213 @@
+/**
+ * The reader's notes: excerpts the reader kept from an article, the comment on
+ * each, which conversations discussed the article, and the article text the
+ * model reads when it does.
+ *
+ * Notes are what the reader OWNS, so they live on the host next to the rest of
+ * the reader's state (the state-boundaries note, rule 1) — but in their own
+ * file, `notes.json`, not inside `state.json`'s per-entry annotations. An
+ * annotation is shaped around the body cache: `boundAnnotations` evicts by
+ * body, `normalizeAnnotations` drops entries that carry nothing it knows. A
+ * note must outlive every one of those (the excerpt carries its own text), and
+ * keeping it out of that machinery is what makes "the body was evicted" and
+ * "the note is gone" two unrelated events.
+ *
+ * The article text is a second, separate concern: the host never parses an
+ * article (the browser half does), and a feed entry's text never reaches the
+ * host at all. So the browser hands over a SNAPSHOT — the article's original
+ * prose, one string per top-level block, numbered the way the pane numbers its
+ * blocks — and the model reads that. Snapshots are capped and pruned; notes
+ * are never pruned.
+ *
+ * Persistence mirrors `store.ts`: native fs at the deployment's state root,
+ * atomic temp-file-and-rename writes, and an in-memory document when the root
+ * is not writable. Writes are serialized through one promise chain, so two
+ * gestures landing together never read the same version and lose one.
+ *
+ * @module @khorsheed/dsh-reader/notes
+ */
+import { ReaderPolishStore } from './polish.ts';
+import type { ReaderPolishView } from './types.ts';
+import type { ReaderDiscussion, ReaderDiscussionInput, ReaderDiscussionPoint, ReaderEntryIdentity, ReaderEntryNotes, ReaderEntrySnapshot, ReaderNote, ReaderNoteInput, ReaderNoteOutcome, ReaderNotesDoc } from './notes-types.ts';
+export type * from './notes-types.ts';
+/** The notes document's file name inside the state root. */
+export declare const READER_NOTES_FILE_NAME = "notes.json";
+/** Where article snapshots live, inside the state root. */
+export declare const READER_SNAPSHOTS_DIR = "snapshots";
+/** Most notes one article keeps (a cap against a runaway client, not a quota anyone reaches). */
+export declare const MAX_NOTES_PER_ENTRY = 500;
+/** Most conversations one article remembers. */
+export declare const MAX_SESSIONS_PER_ENTRY = 50;
+/** Snapshots kept for articles with no notes and no discussions (the most recent ones). */
+export declare const MAX_LOOSE_SNAPSHOTS = 30;
+/** The cap on one snapshot's total characters (a long paper fits; a book does not). */
+export declare const MAX_SNAPSHOT_CHARS = 400000;
+/** Most lines under one note. */
+export declare const MAX_REPLIES_PER_NOTE = 50;
+/** Most discussion notes one article keeps (the oldest go first). */
+export declare const MAX_DISCUSSIONS_PER_ENTRY = 100;
+/** Most points in one discussion note. */
+export declare const MAX_POINTS = 30;
+/** The cap on one reply or one discussion point. */
+export declare const MAX_POINT_CHARS = 4000;
+/** The cap on one excerpt. */
+export declare const MAX_QUOTE_CHARS = 2000;
+/** The cap on one comment. */
+export declare const MAX_COMMENT_CHARS = 4000;
+/** The empty document. */
+export declare function emptyNotesDoc(): ReaderNotesDoc;
+/** Bound a discussion's points: trimmed, capped, ¶ kept only when it is a positive integer. */
+export declare function boundPoints(points: readonly unknown[]): ReaderDiscussionPoint[];
+/**
+ * Coerce a parsed value into a notes document, dropping what it cannot read.
+ *
+ * @param value - the parsed file.
+ * @returns the document.
+ */
+export declare function normalizeNotesDoc(value: unknown): ReaderNotesDoc;
+/**
+ * Bound a snapshot's paragraphs: whitespace collapsed, empty blocks kept as
+ * empty strings (so ¶ numbers stay aligned with the pane's blocks), and the
+ * whole capped — cut at a paragraph boundary, with the cut reported.
+ *
+ * @param paragraphs - the blocks' original text.
+ * @returns the bounded paragraphs and whether anything was dropped.
+ */
+export declare function boundParagraphs(paragraphs: readonly unknown[]): {
+    paragraphs: string[];
+    truncated: boolean;
+};
+/** The reader's notes store. */
+export declare class ReaderNotesStore {
+    private readonly root;
+    private readonly file;
+    private readonly snapshotsDir;
+    private unwritable;
+    /** The document of record when the root is not writable. */
+    private memoryDoc;
+    /** Snapshots kept in memory when the root is not writable. */
+    private readonly memorySnapshots;
+    /** The write queue: every mutation runs after the previous one settled. */
+    private queue;
+    /** The agent's 润色 translations, per article (keyed to the snapshot's text). */
+    readonly polish: ReaderPolishStore;
+    /**
+     * @param config - the same state-root override the reader's main store takes.
+     */
+    constructor(config?: {
+        stateRoot?: string;
+    });
+    /** An article's 润色 layer, when it belongs to the text captured now. */
+    polishView(entryId: string): ReaderPolishView | undefined;
+    /** Turn one paragraph back to the machine translation, or to the 润色 again. */
+    setPolishOff(entryId: string, paragraph: number, off: boolean): ReaderPolishView | undefined;
+    /** Whether the notes persist (false means memory-only, for this process). */
+    get available(): boolean;
+    /** Read the document; a missing or unreadable file reads as empty. */
+    read(): ReaderNotesDoc;
+    /** Run one read-modify-write after every earlier one. */
+    private update;
+    /** One article's notes and discussions, oldest note first. */
+    entry(entryId: string): ReaderEntryNotes | undefined;
+    /** Every article that carries notes or discussions. */
+    entries(): ReaderEntryNotes[];
+    /** How many notes each article carries (the wall's badge). */
+    counts(): Record<string, number>;
+    /**
+     * Keep one excerpt.
+     *
+     * @param input - the article, the excerpt and where it sits, and the comment.
+     * @returns the new note, or why none was kept.
+     */
+    addNote(input: ReaderNoteInput): Promise<ReaderNote | 'empty' | 'full'>;
+    /** Change (or clear) one note's comment. */
+    updateNote(request: {
+        entryId: string;
+        noteId: string;
+        comment: string;
+    }): Promise<ReaderNoteOutcome>;
+    /** Delete one note (its id is not handed out again). */
+    deleteNote(request: {
+        entryId: string;
+        noteId: string;
+    }): Promise<ReaderNoteOutcome>;
+    /**
+     * Add one line under a note: a conclusion (by the model, when the reader asked
+     * for it) or the reader's own addition.
+     *
+     * @param request - the article, the note, the line and who wrote it.
+     */
+    addReply(request: {
+        entryId: string;
+        noteId: string;
+        text: string;
+        by: 'agent' | 'user';
+        sessionId?: string;
+    }): Promise<ReaderNoteOutcome>;
+    /**
+     * Rewrite (or, with empty text, remove) one line under a note. A line the
+     * model wrote becomes the reader's, marked as rewritten from the model's.
+     */
+    editReply(request: {
+        entryId: string;
+        noteId: string;
+        index: number;
+        text: string;
+    }): Promise<ReaderNoteOutcome>;
+    /**
+     * Keep one discussion note (newest first). The conversation it came from is
+     * remembered on the article too.
+     *
+     * @param input - the article, the kind, the points.
+     * @returns the new discussion note, or why none was kept.
+     */
+    addDiscussion(input: ReaderDiscussionInput): Promise<ReaderDiscussion | 'empty'>;
+    /**
+     * Remember that a note (or a discussion note) became a canvas card, so the
+     * notes face can say where it went and not offer the same sync twice blindly.
+     */
+    markSynced(request: {
+        entryId: string;
+        noteId?: string;
+        discussionId?: string;
+        canvasId: string;
+        cardId: string;
+        canvasTitle: string;
+    }): Promise<ReaderNoteOutcome>;
+    /** Delete one discussion note. */
+    deleteDiscussion(request: {
+        entryId: string;
+        discussionId: string;
+    }): Promise<ReaderNoteOutcome>;
+    /**
+     * The article this conversation discussed most recently, when there is one —
+     * where a model's write lands when it names no article.
+     */
+    sessionEntry(sessionId: string): string | undefined;
+    /**
+     * Remember that a conversation discussed this article (most recent first).
+     *
+     * @param request - the article and the conversation.
+     */
+    recordSession(request: ReaderEntryIdentity & {
+        sessionId: string;
+        sessionTitle?: string;
+    }): Promise<'ok' | 'empty'>;
+    /**
+     * Keep the article's text for the model, replacing the previous snapshot.
+     *
+     * Loose snapshots (articles with no notes and no discussions) are pruned to
+     * the {@link MAX_LOOSE_SNAPSHOTS} most recent; the rest are kept as long as
+     * their article carries anything.
+     *
+     * @param request - the article and its blocks' original text.
+     */
+    snapshot(request: ReaderEntryIdentity & {
+        paragraphs: readonly string[];
+    }): Promise<'ok' | 'empty'>;
+    /** The article's text as last captured, when there is one. */
+    readSnapshot(entryId: string): ReaderEntrySnapshot | undefined;
+    /** Every article with a snapshot, newest capture first. */
+    snapshotIds(): string[];
+}
+//# sourceMappingURL=notes.d.ts.map