stunning-md 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -230,6 +230,12 @@ type JudgeOptions = {
     confidence?: number;
     /** The theme the document's own keywords point to, if any (see `matchTheme`). */
     themeHint?: PaletteId;
+    /** Leave the theme question out — for a document whose theme is already settled. */
+    skipTheme?: boolean;
+    /** Ask the theme question and nothing else. */
+    themeOnly?: boolean;
+    /** What the document was written in answer to, if anything — it helps place the subject. */
+    context?: string;
     /** Requests in flight at once. Default 3. */
     concurrency?: number;
     /** Upper bound on tables sent for a form judgement. */
@@ -256,8 +262,154 @@ type JudgeProgress = {
  */
 declare function judgeDocument(plan: DocumentPlan, prose: string, classify: Classify, options?: JudgeOptions): Promise<Judgements>;
 
+type ChatMessage = {
+    role: "system" | "user" | "assistant";
+    content: string;
+};
+/**
+ * Anything that answers a conversation with a stream of text: usually
+ * `createChat` pointed at an OpenAI-compatible endpoint or at your own proxy.
+ */
+type Chat = (messages: ChatMessage[], signal?: AbortSignal) => AsyncIterable<string>;
+/**
+ * A chat function for an OpenAI-compatible `chat/completions` endpoint, read as
+ * a stream. Point it at a route on your own server when the provider needs a key
+ * (see `createChatHandler` in `stunning-md/server`); a key in browser code is public.
+ */
+declare function createChat(options: {
+    endpoint: string;
+    model?: string;
+    headers?: Record<string, string>;
+}): Chat;
+/**
+ * The address of an OpenAI-compatible chat endpoint, given either the full
+ * `…/chat/completions` address or just the API's base (`…/v1`).
+ */
+declare function chatCompletionsUrl(url: string): string;
+type BlockKind = "heading" | "paragraph" | "other";
+type ReplyBlock = {
+    text: string;
+    kind: BlockKind;
+    /** Heading level, for headings. */
+    depth?: number;
+};
+/**
+ * Cuts markdown, as it streams in, into the blocks a reader would recognise:
+ * paragraphs, headings, lists, tables, code. A block is released once it is
+ * known to be complete — at the blank line after it, or at the end.
+ */
+declare class BlockSplitter {
+    private pending;
+    private lines;
+    private fence;
+    private math;
+    private flush;
+    private take;
+    /** Feed more text; returns the blocks that are now complete. */
+    push(text: string): ReplyBlock[];
+    /** The stream is over; returns whatever was still open. */
+    end(): ReplyBlock[];
+}
+/**
+ * How much of a markdown text that is still being written is ready to be laid
+ * out. Given the text so far, returns the part that will not change shape as
+ * more arrives, and the heading of the section being written.
+ *
+ * A section is ready once the next one starts, so its layout is decided once.
+ * Text before the first heading, and the opening under a `# Title`, is ready a
+ * block at a time. A line, code fence or frontmatter block that is not yet
+ * closed is never included.
+ */
+declare function settledMarkdown(text: string): {
+    markdown: string;
+    writing: string | null;
+};
+type TurnEvent = 
+/** Something the assistant said about its answer, not part of it. */
+{
+    type: "commentary";
+    text: string;
+}
+/** The answer so far: every section that is complete, as one markdown document. */
+ | {
+    type: "content";
+    markdown: string;
+}
+/** What is being written now — the heading of the section in progress, if it has one. */
+ | {
+    type: "writing";
+    heading: string | null;
+}
+/**
+ * Whether the reply is an answer at all. Sent with `false` when the model
+ * opens by saying it does not know, cannot help or needs to ask something —
+ * there will be nothing for the page — and with `true` if content follows after all.
+ */
+ | {
+    type: "answer";
+    answered: boolean;
+};
+type TurnResult = {
+    /** Everything the model said, untouched. */
+    raw: string;
+    /** The answer only, without commentary. */
+    content: string;
+};
+/**
+ * Whether a message asks for something for the page — as opposed to a greeting,
+ * thanks or small talk, whose reply belongs in the conversation alone. Asked
+ * before the reply arrives, so the page need not make room for an answer that
+ * is never coming. The classifier answers this reliably; without one, only
+ * messages that are plainly small talk are taken as such.
+ */
+declare function wantsContent(request: string, classify?: Classify, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Reads a model's reply as it streams and sorts it, block by block, into
+ * commentary (remarks to the user) and content (the thing that was asked for).
+ *
+ * Headings, lists, tables, code and images are content. Plain paragraphs are
+ * judged by where they sit and how they read: remarks to the user come at the
+ * start or the end of a reply and usually announce themselves ("Sure, here
+ * is…", "Let me know…"). The classifier is asked about the unclear ones.
+ * Without a classifier, the first paragraph of the reply is taken as
+ * commentary, and so is the last.
+ *
+ * Content is released a section at a time, once the section is complete, so a
+ * section's layout is decided once and does not shift as it grows. Text that
+ * comes before any heading is released paragraph by paragraph.
+ */
+declare function sortReply(options: {
+    stream: AsyncIterable<string>;
+    /** What the user asked — needed to judge whether the reply answers it. */
+    request?: string;
+    /**
+     * The user was only making conversation (see `wantsContent`): the reply is
+     * taken as conversation too, unless it turns out to carry content after all.
+     */
+    smallTalk?: boolean | Promise<boolean>;
+    classify?: Classify;
+    signal?: AbortSignal;
+    onEvent: (event: TurnEvent) => void;
+}): Promise<TurnResult>;
+/** How the assistant is asked to write, so its answer can be laid out as a page. */
+declare const CHAT_INSTRUCTIONS: string;
+
 type StunningMarkdownProps = {
+    /** The document to show. May be empty when `chat` is given: the page then starts blank. */
     markdown: string;
+    /**
+     * The text is still being written — by a model, say — and `markdown` will
+     * keep growing. The page is then laid out as the text arrives: a section at a
+     * time, as each is completed, in a theme chosen once from the opening. Pass
+     * the text so far on every update, and `false` (or nothing) when it is done.
+     */
+    streaming?: boolean;
+    /**
+     * Turns the page into a conversation: a floating input sends requests to this
+     * function, and each answer is laid out below as content while the model's
+     * remarks about it stay in the sidebar.
+     */
+    chat?: Chat;
     /**
      * Answers the judgement calls structure cannot settle (theme, typography,
      * ambiguous tables, hero image). Without it everything is decided by rules.
@@ -265,6 +417,13 @@ type StunningMarkdownProps = {
     classifier?: Classify;
     /** Fixes parts of the theme — palette, typefaces or corner style — overriding everything else. */
     theme?: Partial<ThemeChoice>;
+    /**
+     * Choose a theme to suit each document and each answer. Default `true`. Set
+     * it to `false` to stay on one theme throughout — `theme.palette` if given,
+     * otherwise `paper` — with nothing asked of the classifier about it. The
+     * reader can switch it either way from the theme menu.
+     */
+    autoTheme?: boolean;
     /** `auto` follows the reader's system setting. */
     appearance?: Appearance | "auto";
     /** Maps URLs in the markdown (e.g. relative image paths) to loadable ones. */
@@ -285,6 +444,11 @@ type StunningMarkdownProps = {
      * sections have stopped moving. Default 8000.
      */
     maxWaitMs?: number;
+    /**
+     * A control of your own — a single button or link with an icon — shown as a
+     * round button to the left of the chat input.
+     */
+    chatAccessory?: React.ReactNode;
     className?: string;
     /** Called whenever the plan or theme changes — useful for debugging and tooling. */
     onPlan?: (plan: DocumentPlan, theme: ThemeChoice) => void;
@@ -292,7 +456,8 @@ type StunningMarkdownProps = {
 /**
  * Renders a markdown string as a designed, responsive page: a hero, sections
  * laid out by the shape of their content, charts for tabular data, a contents
- * menu, and a theme chosen to suit the text.
+ * menu, and a theme chosen to suit the text. With `chat`, the page also takes
+ * requests, and lays each answer out below as it is written.
  */
 declare function StunningMarkdown(props: StunningMarkdownProps): react.JSX.Element;
 
@@ -310,6 +475,11 @@ type PlanInput = {
     /** Natural image sizes keyed by the URL written in the markdown. */
     images?: ImageMetaMap;
     judgements?: Judgements;
+    /**
+     * Put in front of every id the plan generates. Needed when several documents
+     * share one page, so their section anchors cannot collide.
+     */
+    idPrefix?: string;
 };
 /** Every image URL in the document, for size probing. */
 declare function collectImageUrls(root: Root): string[];
@@ -353,6 +523,15 @@ type PaletteTokens = {
     border: string;
     accent: string;
     accentFg: string;
+    /**
+     * A second colour, where the theme has one: quotations are set in it — a band
+     * across the page for a quotation that is a section of its own, a block for one
+     * inside an article — so the page has more than one note to play.
+     */
+    highlight?: {
+        bg: string;
+        fg: string;
+    };
 };
 /**
  * Chart drawing styles: `linework` is monochrome print-style ink with hatching,
@@ -360,12 +539,31 @@ type PaletteTokens = {
  * gradients and depth, and `flat` is plain solid colour.
  */
 type ChartStyle = "linework" | "instrument" | "soft" | "flat";
+/**
+ * How a text-led hero is set: `wash` tints the page with a soft glow of the
+ * accent; `block` is a cover in the accent colour itself; `ink` is a cover in
+ * the theme's darkest tone, the page's colours reversed.
+ */
+type HeroTone = "wash" | "block" | "ink";
+/** The families the themes fall into by subject — how the picker is arranged. */
+type ThemeTopic = "writing" | "official" | "technology" | "lifestyle" | "wellbeing" | "culture";
+declare const themeTopics: {
+    id: ThemeTopic;
+    name: string;
+}[];
 type Theme = {
     id: PaletteId;
     name: string;
-    /** The kinds of document this theme suits. */
+    /** The family of subjects it belongs to. */
+    topic: ThemeTopic;
+    /**
+     * The kinds of document this theme suits — and all the classifier reads when
+     * choosing one. Name subjects, not moods: measured against documents of known
+     * subject, subjects alone choose better, and in half the time, than subjects
+     * with colours and typefaces beside them.
+     */
     description: string;
-    /** Its key colours in a few plain words — read by the classifier alongside the description. */
+    /** Its key colours in a few plain words, for people reading the list. */
     look: string;
     /** Typography used unless the caller picks another. */
     fonts: FontPairingId;
@@ -373,6 +571,8 @@ type Theme = {
     formality: number;
     /** How charts are drawn under this theme. */
     chart: ChartStyle;
+    /** How the opening of the page is set off from the rest. */
+    hero: HeroTone;
     /** Fallback matching when no classifier is configured. */
     keywords: RegExp;
     light: PaletteTokens;
@@ -397,9 +597,8 @@ type FontPairing = {
 declare const fontPairings: Record<FontPairingId, FontPairing>;
 declare const fontPairingList: FontPairing[];
 /**
- * What the classifier reads when choosing a theme: the content it suits, its
- * key colours and its typeface, so the choice can weigh appearance as well as
- * subject. Kept terse on purpose — classifier latency grows with every
+ * What the classifier reads when choosing a theme: the subjects it suits, and
+ * nothing else. Kept terse on purpose — classifier latency grows with every
  * character here, across every theme.
  */
 declare function describeTheme(theme: Theme): string;
@@ -427,4 +626,4 @@ declare function guessTheme(text: string, stats: {
  */
 declare function themeVars(choice: ThemeChoice, appearance: Appearance): CSSProperties;
 
-export { type Appearance, type Block, type ChartSpec, type ClassifierAnswer, type ClassifierAnswers, type ClassifierQuestion, type ClassifierRequest, type Classify, type ColumnType, type DocumentPlan, type FontPairing, type FontPairingId, type Frontmatter, type Hero, type HeroVariant, type ImageMeta, type ImageMetaMap, type ImageRef, type JudgeOptions, type JudgeProgress, type Judgements, type ListVariant, type MediaVariant, type PaletteId, type ParsedMarkdown, type PlanInput, type QuoteVariant, type Section, type SectionLayout, type SectionTone, StunningMarkdown, type StunningMarkdownProps, type TableColumn, type TableModel, type TableRow, type Theme, type ThemeChoice, type TocEntry, type VizKind, type VizPlan, buildTableModel, collectImageUrls, createClassifier, describeTheme, documentDigest, fontPairingList, fontPairings, formatValue, guessTheme, judgeDocument, matchTheme, parseDate, parseMarkdown, parseNumber, planDocument, planViz, probeImages, themeChoice, themeList, themeVars, themes, withVizKind };
+export { type Appearance, type Block, BlockSplitter, CHAT_INSTRUCTIONS, type ChartSpec, type Chat, type ChatMessage, type ClassifierAnswer, type ClassifierAnswers, type ClassifierQuestion, type ClassifierRequest, type Classify, type ColumnType, type DocumentPlan, type FontPairing, type FontPairingId, type Frontmatter, type Hero, type HeroTone, type HeroVariant, type ImageMeta, type ImageMetaMap, type ImageRef, type JudgeOptions, type JudgeProgress, type Judgements, type ListVariant, type MediaVariant, type PaletteId, type PaletteTokens, type ParsedMarkdown, type PlanInput, type QuoteVariant, type ReplyBlock, type Section, type SectionLayout, type SectionTone, StunningMarkdown, type StunningMarkdownProps, type TableColumn, type TableModel, type TableRow, type Theme, type ThemeChoice, type ThemeTopic, type TocEntry, type TurnEvent, type TurnResult, type VizKind, type VizPlan, buildTableModel, chatCompletionsUrl, collectImageUrls, createChat, createClassifier, describeTheme, documentDigest, fontPairingList, fontPairings, formatValue, guessTheme, judgeDocument, matchTheme, parseDate, parseMarkdown, parseNumber, planDocument, planViz, probeImages, settledMarkdown, sortReply, themeChoice, themeList, themeTopics, themeVars, themes, wantsContent, withVizKind };