@particle-academy/last-word 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @particle-academy/last-word
+
+[![Fancy UI suite](art/fancy-ui.svg)](https://particle.academy)
+
+Zero-dependency, **isomorphic** (browser + Node) `.docx` writer + reader for
+agentic word-processing documents — a JSON document model with **markdown
+bridges**. The Node/TypeScript mirror of the PHP
+[`particle-academy/last-word`](https://github.com/Particle-Academy/last-word).
+Sister to [`holy-sheet`](https://github.com/Particle-Academy/holy-sheet-js)
+(xlsx) and [`dark-slide`](https://github.com/Particle-Academy/dark-slide-js)
+(pptx).
+
+The point is the **Editor round-trip**: a WYSIWYG editor (react-fancy
+`Editor`) speaks markdown; Word speaks `.docx`. LastWord bridges the two
+through one JSON model — `fromMarkdown → toBytes` to export a real Word file,
+`read → toMarkdown` to import one — with no converter sandwich
+(mammoth/turndown/docx) in between.
+
+```ts
+import { Agent } from "@particle-academy/last-word";
+
+// Markdown in…
+const doc = Agent.fromMarkdown(`# Q3 Report
+
+Revenue was **up 12%** — see the [dashboard](https://example.com).
+
+- Wins
+  - Enterprise renewals
+- Risks
+`);
+
+// …Word file out.
+const bytes: Uint8Array = Agent.toBytes(doc); // universal
+await Agent.write(doc, "report.docx"); // Node only
+
+// And back: .docx → model → markdown for the editor.
+const imported = Agent.read(bytes);
+const markdown = Agent.toMarkdown(imported);
+```
+
+## The document model
+
+A `Doc` is `{ title?, blocks }`. Blocks are JSON-friendly discriminated
+unions — exactly what an agent emits:
+
+| Block | Shape |
+| --- | --- |
+| heading | `{ type: "heading", level: 1-6, runs }` |
+| paragraph | `{ type: "paragraph", runs, align? }` |
+| list | `{ type: "list", ordered?, items: [{ runs, children? }] }` (nesting ≥ 3 deep) |
+| table | `{ type: "table", rows: [{ header?, cells: [{ blocks }] }] }` |
+| code | `{ type: "code", language?, text }` |
+| quote | `{ type: "quote", blocks }` |
+| image | `{ type: "image", src: "data:image/png;base64,…", widthPx?, heightPx?, alt? }` |
+| pageBreak | `{ type: "pageBreak" }` |
+| hr | `{ type: "hr" }` |
+
+A `Run` is an inline span: `{ text, bold?, italic?, underline?, strike?,
+code?, link?, color?, highlight? }` (colors are `#RRGGBB`).
+
+## API
+
+`Agent` (static) mirrors the PHP surface:
+
+- `validate(doc)` → structured errors `{path, message}[]` (empty = valid)
+- `validateAndRepair(doc)` → `{ok, schema, errors}` (coerces strings to runs,
+  clamps heading levels, drops unknown block types with the error retained)
+- `toBytes(doc)` → `Uint8Array` (universal, deterministic output)
+- `write(doc, path)` → `{path, bytes, blocks}` (Node only)
+- `read(bytes)` / `fromBytes(bytes)` → `Doc` (universal; tolerates
+  Word-authored files — outlineLvl headings, named highlights, unknown
+  constructs degrade to paragraphs, never throw)
+- `toMarkdown(doc)` / `fromMarkdown(md)` → the Editor bridge (GFM: headings,
+  `**`/`*`/`~~`, inline code, links, nested lists, tables, fenced code,
+  blockquotes, images, `---`)
+- `describe(doc)` → plain-text summary (title, block counts, word count)
+- `jsonSchema()` → JSON Schema for LLM tool-use
+- `version()` → package version
+
+Markdown is lossy only where GFM has no syntax: underline / color / highlight
+decorations, paragraph alignment, image pixel sizes, and page breaks are
+dropped on `toMarkdown`; everything else round-trips.
+
+Images are embedded from data URLs (PNG/JPEG); when `widthPx`/`heightPx` are
+omitted the intrinsic size is sniffed from the bytes (PNG IHDR / JPEG SOF)
+and capped at 6.5in width keeping aspect.
+
+---
+
+## ⭐ Star Fancy UI
+
+If this package is useful to you, a quick ⭐ on the repo really helps us build a better kit. Thank you!