@particle-academy/last-word 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,326 @@
+/**
+ * Public document types — the LastWord JSON document model. Inputs are loose
+ * agent JSON, so most fields are optional and extra keys are tolerated; the
+ * Validator is the gate. Mirrors PHP `particle-academy/last-word`.
+ */
+type BlockType = "heading" | "paragraph" | "list" | "table" | "code" | "quote" | "image" | "pageBreak" | "hr";
+type Align = "left" | "center" | "right" | "justify";
+/** Inline text span. Only `text` is required; all flags optional. */
+interface Run {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    code?: boolean;
+    link?: string;
+    /** #RRGGBB */
+    color?: string;
+    /** #RRGGBB */
+    highlight?: string;
+    [key: string]: unknown;
+}
+interface ListItem {
+    runs: Run[];
+    children?: ListItem[];
+    [key: string]: unknown;
+}
+interface HeadingBlock {
+    type: "heading";
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    runs: Run[];
+}
+interface ParagraphBlock {
+    type: "paragraph";
+    runs: Run[];
+    align?: Align;
+}
+interface ListBlock {
+    type: "list";
+    ordered?: boolean;
+    items: ListItem[];
+}
+interface TableCell {
+    blocks: Block[];
+    [key: string]: unknown;
+}
+interface TableRow {
+    header?: boolean;
+    cells: TableCell[];
+    [key: string]: unknown;
+}
+interface TableBlock {
+    type: "table";
+    rows: TableRow[];
+}
+interface CodeBlock {
+    type: "code";
+    language?: string;
+    text: string;
+}
+interface QuoteBlock {
+    type: "quote";
+    blocks: Block[];
+}
+interface ImageBlock {
+    type: "image";
+    /** data:image/png;base64,… or data:image/jpeg;base64,… */
+    src: string;
+    widthPx?: number;
+    heightPx?: number;
+    alt?: string;
+}
+interface PageBreakBlock {
+    type: "pageBreak";
+}
+interface HrBlock {
+    type: "hr";
+}
+type Block = HeadingBlock | ParagraphBlock | ListBlock | TableBlock | CodeBlock | QuoteBlock | ImageBlock | PageBreakBlock | HrBlock;
+interface Doc {
+    title?: string;
+    blocks: Block[];
+    [key: string]: unknown;
+}
+/** Structured validation error. Empty array = valid. */
+interface ValidationError {
+    path: string;
+    message: string;
+}
+interface RepairResult {
+    ok: boolean;
+    schema: Doc;
+    errors: ValidationError[];
+}
+interface WriteResult {
+    path: string;
+    bytes: number;
+    blocks: number;
+}
+
+/**
+ * Agent — the structured-tool surface for LastWord. Mirrors PHP `Agent`.
+ * Universal methods are synchronous; file-touching methods (`write`) are async
+ * and Node-only (browsers have no sync FS).
+ */
+
+/** Feature-parity baseline with PHP last-word; bumped independently on npm. */
+declare const VERSION = "0.1.0";
+type Any$2 = any;
+declare const Agent: {
+    /** Validate a doc without writing. Empty array = valid. */
+    validate(doc: Any$2): ValidationError[];
+    /**
+     * Validate + apply heuristic repairs (coerce strings to runs, clamp heading
+     * levels, drop unknown block types with the error retained, default missing
+     * blocks to []). Returns `{ ok, schema, errors }` where `ok` is true when
+     * the repaired doc validates clean; `errors` retains anything the repair
+     * dropped plus any remaining validation errors.
+     */
+    validateAndRepair(doc: Any$2): RepairResult;
+    /** DOCX bytes for a doc (no temp file). Universal. Throws SchemaException if invalid. */
+    toBytes(doc: Any$2): Uint8Array;
+    /** Write a doc to disk as a .docx file (Node only). Throws SchemaException if invalid. */
+    write(doc: Any$2, path: string): Promise<WriteResult>;
+    /** Read .docx bytes back into the Doc model. Universal. */
+    read(input: Uint8Array | ArrayBuffer): Doc;
+    /** Alias for {@see read}. */
+    fromBytes(input: Uint8Array | ArrayBuffer): Doc;
+    /** Doc → GFM markdown (the Editor bridge). */
+    toMarkdown(doc: Any$2): string;
+    /** GFM markdown → Doc (the Editor bridge). */
+    fromMarkdown(markdown: string): Doc;
+    /** Plain-text summary of a doc: title, block counts by type, word count. */
+    describe(doc: Any$2): string;
+    /** JSON Schema export for LLM tool-use registration. */
+    jsonSchema(): Record<string, unknown>;
+    version(): string;
+};
+
+/** Thrown by Agent.write/toBytes when the schema is invalid. Mirrors PHP `SchemaException`. */
+declare class SchemaException extends Error {
+    readonly errors: ValidationError[];
+    constructor(message: string, errors: ValidationError[]);
+}
+
+type Any$1 = any;
+/** Liberal schema validator. Mirrors PHP `Schema\Validator`. */
+declare class Validator {
+    validate(doc: Any$1): ValidationError[];
+    validateBlock(block: Any$1, path: string): ValidationError[];
+    private validateRuns;
+    private validateRun;
+    private validateListItem;
+}
+
+type Any = any;
+/**
+ * Heuristic doc repair. Mirrors PHP `Schema\Repairer`. Never mutates input.
+ *
+ * Heuristics:
+ *  - missing / non-array `blocks` → `[]`
+ *  - bare strings in `blocks` → paragraphs; `runs: "text"` → `[{ text }]`;
+ *    string entries inside a runs array → `{ text }`
+ *  - heading levels clamped to 1..6 (non-numeric → 1)
+ *  - unknown block types dropped, with the error retained in `notes`
+ *  - list items given as strings → `{ runs: [{ text }] }`
+ */
+declare class Repairer {
+    /** Errors describing content the last `repair()` call had to drop. */
+    notes: ValidationError[];
+    repair(docInput: Any): Record<string, unknown>;
+    private repairBlocks;
+    private repairBlock;
+    private repairRuns;
+    private repairListItems;
+    private repairRows;
+}
+
+/**
+ * Schema constants describing the Doc shape. Mirrors PHP `Schema\Schema`.
+ */
+declare const Schema: {
+    VERSION: string;
+    BLOCK_TYPES: readonly ["heading", "paragraph", "list", "table", "code", "quote", "image", "pageBreak", "hr"];
+    ALIGNMENTS: readonly ["left", "center", "right", "justify"];
+    MAX_HEADING_LEVEL: number;
+    docRequiredKeys(): string[];
+    jsonSchema(): Record<string, unknown>;
+};
+
+/**
+ * DocxWriter — Doc JSON model → .docx bytes (OOXML / WordprocessingML).
+ * Deterministic: no timestamps, fixed zip entry order, rel ids assigned in
+ * traversal order. Mirrors PHP `Writer\DocxWriter`.
+ */
+
+/** EMUs per pixel at 96 dpi. */
+declare const EMU_PER_PX = 9525;
+/** Content width cap: 6.5in at 96 dpi. */
+declare const MAX_WIDTH_PX = 624;
+declare class DocxWriter {
+    private rels;
+    private hyperlinkIds;
+    private media;
+    private drawingId;
+    toBytes(doc: Doc): Uint8Array;
+    private renderBlocks;
+    private renderBlock;
+    private paragraph;
+    private pPr;
+    private renderRuns;
+    private renderRun;
+    private hyperlinkRel;
+    private renderList;
+    private renderTable;
+    private renderCode;
+    private renderQuote;
+    private renderImage;
+    private sectPr;
+    private contentTypesXml;
+    private packageRelsXml;
+    private coreXml;
+    private documentRelsXml;
+    private stylesXml;
+    private numberingXml;
+}
+/**
+ * Resolve the rendered pixel size of an image block: explicit px win, missing
+ * dimensions are derived from the intrinsic (sniffed) size keeping aspect,
+ * and everything is capped at 6.5in width.
+ */
+declare function resolveImageSize(block: {
+    widthPx?: number;
+    heightPx?: number;
+}, bytes: Uint8Array): {
+    width: number;
+    height: number;
+};
+
+/**
+ * DocxReader — .docx bytes → Doc JSON model. Handles this package's own
+ * writer output losslessly (round-trip) and tolerates Word-authored files:
+ * headings via pStyle Heading1-9 OR outlineLvl, numPr lists with ilvl nesting,
+ * hyperlinks via rels, images via blip r:embed, page breaks, bottom-border-only
+ * paragraphs → hr. Unknown constructs degrade to plain paragraphs, never throw.
+ * Mirrors PHP `Reader\DocxReader`.
+ */
+
+declare class DocxReader {
+    private parts;
+    private rels;
+    private numOrdered;
+    read(bytes: Uint8Array): Doc;
+    private partText;
+    private readTitle;
+    private loadRels;
+    private loadNumbering;
+    private walkBody;
+    private parseSdt;
+    private classifyParagraph;
+    /** Concatenated visible text of a paragraph (tabs and soft breaks included). */
+    private plainText;
+    private parseRuns;
+    private runFrom;
+    private buildLists;
+    private parseTable;
+    private parseDrawing;
+}
+/** Merge adjacent runs whose properties are identical (writer normalization). */
+declare function mergeRuns(runs: Run[]): Run[];
+
+/**
+ * Doc → GFM markdown — the Editor bridge. Hand-rolled (no external markdown
+ * dependency), mirroring PHP `Markdown\MarkdownBridge::toMarkdown`.
+ *
+ * Lossy by design where GFM has no syntax: underline / color / highlight
+ * decorations, paragraph alignment, image pixel sizes, and page breaks are
+ * dropped. Everything else round-trips through `fromMarkdown`.
+ */
+
+declare function toMarkdown(doc: Doc): string;
+
+/**
+ * GFM markdown → Doc — the Editor bridge. Hand-rolled line-based block parser
+ * plus an inline tokenizer (bold/italic/strike/code/links with backslash
+ * escapes). No external markdown dependency. Mirrors PHP
+ * `Markdown\MarkdownBridge::fromMarkdown`.
+ */
+
+declare function fromMarkdown(markdown: string): Doc;
+declare function parseInline(text: string): Run[];
+
+/**
+ * Intrinsic image dimension sniffing (PNG IHDR / JPEG SOF) + data-URL decode.
+ * Zero-dependency, isomorphic — used by the writer to size `wp:extent` when
+ * `widthPx` / `heightPx` are omitted.
+ */
+interface ImageSize {
+    width: number;
+    height: number;
+}
+interface DecodedDataUrl {
+    mime: string;
+    bytes: Uint8Array;
+}
+/** Decode a `data:image/…;base64,…` URL. Returns null for anything else. */
+declare function parseDataUrl(src: string): DecodedDataUrl | null;
+/** PNG IHDR width/height, or null when the bytes are not a PNG. */
+declare function pngSize(bytes: Uint8Array): ImageSize | null;
+/**
+ * JPEG width/height from the first SOF frame header (SOF0-SOF3, SOF5-SOF7,
+ * SOF9-SOF11, SOF13-SOF15), or null when the bytes are not a JPEG.
+ */
+declare function jpegSize(bytes: Uint8Array): ImageSize | null;
+/** Sniff intrinsic pixel dimensions from PNG or JPEG bytes. */
+declare function sniffImageSize(bytes: Uint8Array): ImageSize | null;
+
+interface ZipFile {
+    name: string;
+    data: Uint8Array;
+}
+declare function zipSync(files: ZipFile[]): Uint8Array;
+
+declare function unzipSync(data: Uint8Array): Record<string, Uint8Array>;
+
+export { Agent, type Align, type Block, type BlockType, type CodeBlock, type Doc, DocxReader, DocxWriter, EMU_PER_PX, type HeadingBlock, type HrBlock, type ImageBlock, type ListBlock, type ListItem, MAX_WIDTH_PX, type PageBreakBlock, type ParagraphBlock, type QuoteBlock, type RepairResult, Repairer, type Run, Schema, SchemaException, type TableBlock, type TableCell, type TableRow, VERSION, type ValidationError, Validator, type WriteResult, type ZipFile, fromMarkdown, jpegSize, mergeRuns, parseDataUrl, parseInline, pngSize, resolveImageSize, sniffImageSize, toMarkdown, unzipSync, zipSync };

package/dist/index.d.ts

@@ -0,0 +1,326 @@
+/**
+ * Public document types — the LastWord JSON document model. Inputs are loose
+ * agent JSON, so most fields are optional and extra keys are tolerated; the
+ * Validator is the gate. Mirrors PHP `particle-academy/last-word`.
+ */
+type BlockType = "heading" | "paragraph" | "list" | "table" | "code" | "quote" | "image" | "pageBreak" | "hr";
+type Align = "left" | "center" | "right" | "justify";
+/** Inline text span. Only `text` is required; all flags optional. */
+interface Run {
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strike?: boolean;
+    code?: boolean;
+    link?: string;
+    /** #RRGGBB */
+    color?: string;
+    /** #RRGGBB */
+    highlight?: string;
+    [key: string]: unknown;
+}
+interface ListItem {
+    runs: Run[];
+    children?: ListItem[];
+    [key: string]: unknown;
+}
+interface HeadingBlock {
+    type: "heading";
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    runs: Run[];
+}
+interface ParagraphBlock {
+    type: "paragraph";
+    runs: Run[];
+    align?: Align;
+}
+interface ListBlock {
+    type: "list";
+    ordered?: boolean;
+    items: ListItem[];
+}
+interface TableCell {
+    blocks: Block[];
+    [key: string]: unknown;
+}
+interface TableRow {
+    header?: boolean;
+    cells: TableCell[];
+    [key: string]: unknown;
+}
+interface TableBlock {
+    type: "table";
+    rows: TableRow[];
+}
+interface CodeBlock {
+    type: "code";
+    language?: string;
+    text: string;
+}
+interface QuoteBlock {
+    type: "quote";
+    blocks: Block[];
+}
+interface ImageBlock {
+    type: "image";
+    /** data:image/png;base64,… or data:image/jpeg;base64,… */
+    src: string;
+    widthPx?: number;
+    heightPx?: number;
+    alt?: string;
+}
+interface PageBreakBlock {
+    type: "pageBreak";
+}
+interface HrBlock {
+    type: "hr";
+}
+type Block = HeadingBlock | ParagraphBlock | ListBlock | TableBlock | CodeBlock | QuoteBlock | ImageBlock | PageBreakBlock | HrBlock;
+interface Doc {
+    title?: string;
+    blocks: Block[];
+    [key: string]: unknown;
+}
+/** Structured validation error. Empty array = valid. */
+interface ValidationError {
+    path: string;
+    message: string;
+}
+interface RepairResult {
+    ok: boolean;
+    schema: Doc;
+    errors: ValidationError[];
+}
+interface WriteResult {
+    path: string;
+    bytes: number;
+    blocks: number;
+}
+
+/**
+ * Agent — the structured-tool surface for LastWord. Mirrors PHP `Agent`.
+ * Universal methods are synchronous; file-touching methods (`write`) are async
+ * and Node-only (browsers have no sync FS).
+ */
+
+/** Feature-parity baseline with PHP last-word; bumped independently on npm. */
+declare const VERSION = "0.1.0";
+type Any$2 = any;
+declare const Agent: {
+    /** Validate a doc without writing. Empty array = valid. */
+    validate(doc: Any$2): ValidationError[];
+    /**
+     * Validate + apply heuristic repairs (coerce strings to runs, clamp heading
+     * levels, drop unknown block types with the error retained, default missing
+     * blocks to []). Returns `{ ok, schema, errors }` where `ok` is true when
+     * the repaired doc validates clean; `errors` retains anything the repair
+     * dropped plus any remaining validation errors.
+     */
+    validateAndRepair(doc: Any$2): RepairResult;
+    /** DOCX bytes for a doc (no temp file). Universal. Throws SchemaException if invalid. */
+    toBytes(doc: Any$2): Uint8Array;
+    /** Write a doc to disk as a .docx file (Node only). Throws SchemaException if invalid. */
+    write(doc: Any$2, path: string): Promise<WriteResult>;
+    /** Read .docx bytes back into the Doc model. Universal. */
+    read(input: Uint8Array | ArrayBuffer): Doc;
+    /** Alias for {@see read}. */
+    fromBytes(input: Uint8Array | ArrayBuffer): Doc;
+    /** Doc → GFM markdown (the Editor bridge). */
+    toMarkdown(doc: Any$2): string;
+    /** GFM markdown → Doc (the Editor bridge). */
+    fromMarkdown(markdown: string): Doc;
+    /** Plain-text summary of a doc: title, block counts by type, word count. */
+    describe(doc: Any$2): string;
+    /** JSON Schema export for LLM tool-use registration. */
+    jsonSchema(): Record<string, unknown>;
+    version(): string;
+};
+
+/** Thrown by Agent.write/toBytes when the schema is invalid. Mirrors PHP `SchemaException`. */
+declare class SchemaException extends Error {
+    readonly errors: ValidationError[];
+    constructor(message: string, errors: ValidationError[]);
+}
+
+type Any$1 = any;
+/** Liberal schema validator. Mirrors PHP `Schema\Validator`. */
+declare class Validator {
+    validate(doc: Any$1): ValidationError[];
+    validateBlock(block: Any$1, path: string): ValidationError[];
+    private validateRuns;
+    private validateRun;
+    private validateListItem;
+}
+
+type Any = any;
+/**
+ * Heuristic doc repair. Mirrors PHP `Schema\Repairer`. Never mutates input.
+ *
+ * Heuristics:
+ *  - missing / non-array `blocks` → `[]`
+ *  - bare strings in `blocks` → paragraphs; `runs: "text"` → `[{ text }]`;
+ *    string entries inside a runs array → `{ text }`
+ *  - heading levels clamped to 1..6 (non-numeric → 1)
+ *  - unknown block types dropped, with the error retained in `notes`
+ *  - list items given as strings → `{ runs: [{ text }] }`
+ */
+declare class Repairer {
+    /** Errors describing content the last `repair()` call had to drop. */
+    notes: ValidationError[];
+    repair(docInput: Any): Record<string, unknown>;
+    private repairBlocks;
+    private repairBlock;
+    private repairRuns;
+    private repairListItems;
+    private repairRows;
+}
+
+/**
+ * Schema constants describing the Doc shape. Mirrors PHP `Schema\Schema`.
+ */
+declare const Schema: {
+    VERSION: string;
+    BLOCK_TYPES: readonly ["heading", "paragraph", "list", "table", "code", "quote", "image", "pageBreak", "hr"];
+    ALIGNMENTS: readonly ["left", "center", "right", "justify"];
+    MAX_HEADING_LEVEL: number;
+    docRequiredKeys(): string[];
+    jsonSchema(): Record<string, unknown>;
+};
+
+/**
+ * DocxWriter — Doc JSON model → .docx bytes (OOXML / WordprocessingML).
+ * Deterministic: no timestamps, fixed zip entry order, rel ids assigned in
+ * traversal order. Mirrors PHP `Writer\DocxWriter`.
+ */
+
+/** EMUs per pixel at 96 dpi. */
+declare const EMU_PER_PX = 9525;
+/** Content width cap: 6.5in at 96 dpi. */
+declare const MAX_WIDTH_PX = 624;
+declare class DocxWriter {
+    private rels;
+    private hyperlinkIds;
+    private media;
+    private drawingId;
+    toBytes(doc: Doc): Uint8Array;
+    private renderBlocks;
+    private renderBlock;
+    private paragraph;
+    private pPr;
+    private renderRuns;
+    private renderRun;
+    private hyperlinkRel;
+    private renderList;
+    private renderTable;
+    private renderCode;
+    private renderQuote;
+    private renderImage;
+    private sectPr;
+    private contentTypesXml;
+    private packageRelsXml;
+    private coreXml;
+    private documentRelsXml;
+    private stylesXml;
+    private numberingXml;
+}
+/**
+ * Resolve the rendered pixel size of an image block: explicit px win, missing
+ * dimensions are derived from the intrinsic (sniffed) size keeping aspect,
+ * and everything is capped at 6.5in width.
+ */
+declare function resolveImageSize(block: {
+    widthPx?: number;
+    heightPx?: number;
+}, bytes: Uint8Array): {
+    width: number;
+    height: number;
+};
+
+/**
+ * DocxReader — .docx bytes → Doc JSON model. Handles this package's own
+ * writer output losslessly (round-trip) and tolerates Word-authored files:
+ * headings via pStyle Heading1-9 OR outlineLvl, numPr lists with ilvl nesting,
+ * hyperlinks via rels, images via blip r:embed, page breaks, bottom-border-only
+ * paragraphs → hr. Unknown constructs degrade to plain paragraphs, never throw.
+ * Mirrors PHP `Reader\DocxReader`.
+ */
+
+declare class DocxReader {
+    private parts;
+    private rels;
+    private numOrdered;
+    read(bytes: Uint8Array): Doc;
+    private partText;
+    private readTitle;
+    private loadRels;
+    private loadNumbering;
+    private walkBody;
+    private parseSdt;
+    private classifyParagraph;
+    /** Concatenated visible text of a paragraph (tabs and soft breaks included). */
+    private plainText;
+    private parseRuns;
+    private runFrom;
+    private buildLists;
+    private parseTable;
+    private parseDrawing;
+}
+/** Merge adjacent runs whose properties are identical (writer normalization). */
+declare function mergeRuns(runs: Run[]): Run[];
+
+/**
+ * Doc → GFM markdown — the Editor bridge. Hand-rolled (no external markdown
+ * dependency), mirroring PHP `Markdown\MarkdownBridge::toMarkdown`.
+ *
+ * Lossy by design where GFM has no syntax: underline / color / highlight
+ * decorations, paragraph alignment, image pixel sizes, and page breaks are
+ * dropped. Everything else round-trips through `fromMarkdown`.
+ */
+
+declare function toMarkdown(doc: Doc): string;
+
+/**
+ * GFM markdown → Doc — the Editor bridge. Hand-rolled line-based block parser
+ * plus an inline tokenizer (bold/italic/strike/code/links with backslash
+ * escapes). No external markdown dependency. Mirrors PHP
+ * `Markdown\MarkdownBridge::fromMarkdown`.
+ */
+
+declare function fromMarkdown(markdown: string): Doc;
+declare function parseInline(text: string): Run[];
+
+/**
+ * Intrinsic image dimension sniffing (PNG IHDR / JPEG SOF) + data-URL decode.
+ * Zero-dependency, isomorphic — used by the writer to size `wp:extent` when
+ * `widthPx` / `heightPx` are omitted.
+ */
+interface ImageSize {
+    width: number;
+    height: number;
+}
+interface DecodedDataUrl {
+    mime: string;
+    bytes: Uint8Array;
+}
+/** Decode a `data:image/…;base64,…` URL. Returns null for anything else. */
+declare function parseDataUrl(src: string): DecodedDataUrl | null;
+/** PNG IHDR width/height, or null when the bytes are not a PNG. */
+declare function pngSize(bytes: Uint8Array): ImageSize | null;
+/**
+ * JPEG width/height from the first SOF frame header (SOF0-SOF3, SOF5-SOF7,
+ * SOF9-SOF11, SOF13-SOF15), or null when the bytes are not a JPEG.
+ */
+declare function jpegSize(bytes: Uint8Array): ImageSize | null;
+/** Sniff intrinsic pixel dimensions from PNG or JPEG bytes. */
+declare function sniffImageSize(bytes: Uint8Array): ImageSize | null;
+
+interface ZipFile {
+    name: string;
+    data: Uint8Array;
+}
+declare function zipSync(files: ZipFile[]): Uint8Array;
+
+declare function unzipSync(data: Uint8Array): Record<string, Uint8Array>;
+
+export { Agent, type Align, type Block, type BlockType, type CodeBlock, type Doc, DocxReader, DocxWriter, EMU_PER_PX, type HeadingBlock, type HrBlock, type ImageBlock, type ListBlock, type ListItem, MAX_WIDTH_PX, type PageBreakBlock, type ParagraphBlock, type QuoteBlock, type RepairResult, Repairer, type Run, Schema, SchemaException, type TableBlock, type TableCell, type TableRow, VERSION, type ValidationError, Validator, type WriteResult, type ZipFile, fromMarkdown, jpegSize, mergeRuns, parseDataUrl, parseInline, pngSize, resolveImageSize, sniffImageSize, toMarkdown, unzipSync, zipSync };