@opencxh/domain 1.234.0 → 1.236.0

package/dist/platform/document-blocks.d.ts

@@ -0,0 +1,240 @@
+/**
+ * The blocks a document is built from — the one vocabulary for every document in this platform.
+ *
+ * An artifact, a knowledge base article, a quote, a work order: one list of these. The name says
+ * document rather than artifact because the assistant was only the first writer — see
+ * `plans/DOCUMENTS-2026-09-14.md`. `entities/artifact/blocks.ts` keeps the old names as aliases.
+ *
+ * This is a **document** vocabulary, not the row vocabulary of the timeline
+ * (`../entities/activity/blocks.ts`). Those two look alike and deliberately are not: a timeline row sits
+ * among dozens of others and may therefore hold only ten blocks, has no paragraphs or headings,
+ * and its text nodes are *paths* into an activity. An artifact is a document — it has headings,
+ * paragraphs, a table and a KPI row, and its text is just text.
+ *
+ * What is carried over is that file's *discipline*, because it proved itself:
+ *
+ * - an optional `block_id`, so a block can be pointed at without rewriting the whole document;
+ * - {@link normalizeDocumentBlocks} **prunes instead of refusing** — one bad block must not make a
+ *   whole document disappear — and reports *every* drop, because silent pruning makes "why is my
+ *   table missing?" unanswerable;
+ * - unknown block types are skipped, so a newer writer can coexist with an older renderer;
+ * - semantic tones only, no free colours, so dark mode keeps working.
+ *
+ * **The inert boundary.** An artifact is stored data, not a program, and that is a property of the
+ * *model* rather than the outcome of a filter afterwards. Block texts are **markdown, never
+ * HTML**: the renderer hands them to ui-kit's `RichText` with `as="markdown"`, and that branch
+ * (react-markdown + remark-gfm) emits no raw HTML, so a `<script>` in the text reaches the screen
+ * as literal characters. Hence no tag stripping here — that would break "a < b" and win nothing.
+ * What *is* stripped is the only thing markdown itself makes dangerous: a link to a scheme outside
+ * {@link ALLOWED_LINK_SCHEMES}, and inline images. See {@link sanitizeInline}.
+ */
+/** Semantic colour. No free colours, so dark mode and the tokens keep working. */
+export type DocumentTone = "info" | "success" | "warning" | "destructive";
+/**
+ * One line in a list.
+ *
+ * `lead` exists because a findings list puts its point up front in bold ("**Yealink outages
+ * dominate.** 14 of the 184 calls..."). Without a field of its own the writer has to invent
+ * markdown asterisks in a place where the formatting is supposed to be fixed — and then the text
+ * shows whether someone forgot.
+ */
+export interface DocumentListItem {
+    lead?: string;
+    text: string;
+}
+export interface DocumentTableColumn {
+    label: string;
+    /** Numbers right. Left by default. */
+    align?: "left" | "right";
+}
+export interface DocumentKpiItem {
+    /** Already formatted by the writer ("1u 12m", "184", "-12%"). */
+    value: string;
+    label: string;
+    /** Only set when this number stands out; a tint on every tile is wallpaper. */
+    tone?: DocumentTone;
+}
+/** One line of a {@link DocumentBlock} letterhead: `{ label: "Nummer", value: "2026-0412" }`. */
+export interface DocumentLetterheadField {
+    /** Machine key, so a template can address one field without matching on its label. */
+    key: string;
+    label?: string;
+    value: string;
+}
+/** One line in a totals block. Amounts arrive **already formatted**; this layer never computes. */
+export interface DocumentTotalsRow {
+    label: string;
+    amount: string;
+    /** The line that carries the eye — a subtotal or the final total. At most one is usual. */
+    emphasis?: boolean;
+}
+export type DocumentBlock = {
+    block_id?: string;
+    type: "heading";
+    level: 1 | 2 | 3;
+    text: string;
+} | {
+    block_id?: string;
+    type: "paragraph";
+    text: string;
+} | {
+    block_id?: string;
+    type: "list";
+    style: "bulleted" | "numbered";
+    items: DocumentListItem[];
+} | {
+    block_id?: string;
+    type: "quote";
+    text: string;
+} | {
+    block_id?: string;
+    type: "code";
+    lang?: string;
+    text: string;
+} | {
+    block_id?: string;
+    type: "divider";
+} | {
+    block_id?: string;
+    type: "table";
+    columns: DocumentTableColumn[];
+    rows: string[][];
+    caption?: string;
+} | {
+    block_id?: string;
+    type: "kpi";
+    items: DocumentKpiItem[];
+} | {
+    block_id?: string;
+    type: "callout";
+    tone: DocumentTone;
+    title?: string;
+    text: string;
+}
+/**
+ * A picture, by URL.
+ *
+ * Only an explicitly placed block — inline `![](…)` in text stays stripped by
+ * {@link sanitizeInline}, and for the reason given there: a URL inside written text is a back
+ * door that tells an external host who opened the document. Here the author put it there, and
+ * the scheme is checked on the way in.
+ *
+ * The URL has to be one the reader can actually load. The storage app has no publicly readable
+ * URL, so an uploaded file cannot be shown to a reader without a session — the help centre
+ * already hits that wall (`renderBlocks.tsx:212`).
+ */
+ | {
+    block_id?: string;
+    type: "image";
+    url: string;
+    alt?: string;
+    caption?: string;
+}
+/**
+ * The head of a letter: who it is to, and the handful of facts that identify it.
+ *
+ * Fields rather than named columns because no two documents carry the same set — a work order
+ * has no due date, a letter has no number. The sender and the house style are **not** here:
+ * those belong to the organisation and are drawn around the document, not in it.
+ */
+ | {
+    block_id?: string;
+    type: "letterhead";
+    fields: DocumentLetterheadField[];
+    /** Address lines, already formatted; the renderer sets them, it does not compose them. */
+    recipient?: string[];
+}
+/**
+ * The money block: subtotal, tax per rate, total.
+ *
+ * Not a `table`, and the difference matters. A table is text in cells; this aligns on the
+ * decimal, keeps the tax rows visually between subtotal and total, and never breaks across a
+ * page. Amounts are strings the writer formatted — see {@link DocumentKpiItem.value}.
+ */
+ | {
+    block_id?: string;
+    type: "totals";
+    rows: DocumentTotalsRow[];
+    taxRows?: DocumentTotalsRow[];
+}
+/**
+ * Break the page here when printing; a thin marker on screen.
+ *
+ * The only pagination an author gets. Everything else is the renderer's job — see
+ * `plans/DOCUMENTS-2026-09-14.md` §6 for what browser print can and cannot do.
+ */
+ | {
+    block_id?: string;
+    type: "pagebreak";
+};
+export type DocumentBlockType = DocumentBlock["type"];
+/**
+ * Ceilings. Wider than the timeline (which sits at 10 blocks) because this is a document, but not
+ * unlimited: the body travels as JSON through the same invoke channel as everything else and ends
+ * up in a single column.
+ */
+export declare const DOCUMENT_MAX_BLOCKS = 200;
+export declare const DOCUMENT_MAX_LIST_ITEMS = 100;
+export declare const DOCUMENT_MAX_TABLE_ROWS = 200;
+export declare const DOCUMENT_MAX_TABLE_COLUMNS = 12;
+export declare const DOCUMENT_MAX_KPI_ITEMS = 4;
+export declare const DOCUMENT_MAX_LETTERHEAD_FIELDS = 10;
+export declare const DOCUMENT_MAX_RECIPIENT_LINES = 8;
+export declare const DOCUMENT_MAX_TOTALS_ROWS = 12;
+export declare const DOCUMENT_MAX_TEXT_LEN = 4000;
+export declare const DOCUMENT_MAX_CELL_LEN = 500;
+/**
+ * Hard upper bound on the serialized body.
+ *
+ * A megabyte is some eighty thousand words — nobody writes that, and the headroom is what lets a
+ * knowledge base article be stored as blocks instead of as markdown (blocks run roughly one and a
+ * half to two times the bytes). One ceiling for every writer: a second constant is more code than
+ * a bigger number.
+ *
+ * Keep it **below** whatever the invoke channel itself accepts, so an oversized document fails
+ * with this readable error rather than as a truncated payload three layers down.
+ */
+export declare const DOCUMENT_MAX_BODY_BYTES: number;
+/**
+ * Schemes a link in an artifact may carry.
+ *
+ * `javascript:` and `data:` are not among them, and that is the entire reason this list exists:
+ * those two are the only way markdown gets something executable into the document.
+ */
+export declare const ALLOWED_LINK_SCHEMES: readonly ["http:", "https:", "mailto:", "tel:"];
+/**
+ * Makes one piece of inline markdown safe while keeping it readable.
+ *
+ * Three interventions, in this order:
+ *
+ * 1. **Inline images disappear**, with their alt text as replacement. This version has no `image`
+ *    block precisely because the product has no publicly loadable URL (bytes come through the
+ *    invoke channel as base64). An inline `![](…)` would open that gap through the back door and
+ *    tell an external host who opens the document.
+ * 2. **Links to a forbidden scheme become plain text** — the label stays. Dropping the label would
+ *    break the sentence over the link.
+ * 3. **Reference definitions to a forbidden scheme disappear.** Without this step `[click][x]`
+ *    with `[x]: javascript:…` below it escapes step 2.
+ */
+export declare function sanitizeInline(text: string): string;
+/**
+ * Prunes a written block list down to something a renderer can safely draw.
+ *
+ * Always returns **new** objects: the input comes from a model or an API client, and the sanitized
+ * text must not leak back into the original.
+ *
+ * `onDrop` should log or report back to the writer — a tool losing its table because it sent zero
+ * columns has to be able to hear that.
+ */
+export declare function normalizeDocumentBlocks(blocks: unknown, onDrop?: (reason: string) => void): DocumentBlock[];
+/** How many bytes this body costs on the wire. */
+export declare function documentBodyBytes(blocks: DocumentBlock[]): number;
+/**
+ * A short summary of what is inside, for the thumbnail on a card and for what the assistant sees
+ * when it wants to update an artifact without reading the whole body.
+ */
+export declare function documentOutline(blocks: DocumentBlock[]): {
+    blocks: number;
+    types: DocumentBlockType[];
+    headings: string[];
+};

package/dist/platform/document-blocks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/platform/document-markdown.d.ts

@@ -0,0 +1,6 @@
+import { DocumentBlock } from './document-blocks';
+/**
+ * The whole document as markdown. `title` goes on top as an H1 when the blocks carry none
+ * themselves — an export without a title cannot be found back in a downloads folder.
+ */
+export declare function documentToMarkdown(blocks: DocumentBlock[], title?: string): string;

package/dist/platform/document-markdown.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/platform/document-parse.d.ts

@@ -0,0 +1,2 @@
+import { DocumentBlock } from './document-blocks';
+export declare function markdownToDocument(md: string): DocumentBlock[];

package/dist/platform/document-text.d.ts

@@ -0,0 +1,14 @@
+import { DocumentBlock } from './document-blocks';
+/**
+ * The document as plain text: what an embedding and a keyword search should see.
+ *
+ * Markdown and plain text are not the same job. `**Yealink**` embeds as three tokens where two of
+ * them are punctuation, a table's pipes are noise in a cosine, and a search for "reset" should
+ * match `## Reset` without the reader having typed a hash. So this strips the markers markdown put
+ * there and keeps the words they wrapped.
+ *
+ * Built on top of {@link documentToMarkdown} rather than beside it: one place decides what a block
+ * says and in which order, and a second walk over the union would drift from it on the first new
+ * block type.
+ */
+export declare function documentToText(blocks: DocumentBlock[], title?: string): string;

package/dist/platform/document-text.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencxh/domain",
-  "version": "1.234.0",
+  "version": "1.236.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",