@dotit/core

Parser, HTML renderer, and document generation engine for IntentText (.it) — a structured interchange format for AI agents and humans.

Install

npm install @dotit/core

Quick Start

import { parseIntentText, renderHTML } from "@dotit/core";

const doc = parseIntentText(`
title: Sprint Planning — Week 12
summary: Tasks and decisions for the week.

section: Action Items
task: Write migration script | owner: Sarah | due: Wednesday
task: Update CI pipeline | owner: Dev Team | due: Friday
done: Security audit complete

section: Notes
note: Next demo on Friday 3pm.
info: New staging environment is live.
`);

console.log(doc.version); // "1.4"
console.log(doc.blocks.length); // 8

const html = renderHTML(doc); // Styled HTML output

Pure TypeScript — no native or WASM dependency. Runs unchanged in Node and the browser. (The earlier Rust/WASM engine was removed in v4; the TS parser is the single canonical implementation. See SPEC.md.)

API

Parsing

import { parseIntentText } from "@dotit/core";

const doc = parseIntentText(source);
// Returns: IntentDocument { version, metadata, blocks, diagnostics }

Rendering

import { renderHTML, renderPrint } from "@dotit/core";

// Inline HTML fragment (for embedding in a page)
const html = renderHTML(doc);

// Full print-optimized HTML document with embedded CSS
// Reads font: and page: blocks for dynamic typography and layout
const printHtml = renderPrint(doc);

Template Merge

Resolve {{variable}} placeholders in a parsed document using a JSON data object.

import { mergeData, parseAndMerge } from "@dotit/core";

const data = {
  company: { name: "Acme Corp" },
  invoice_number: "INV-2026-001",
  total: "17,325 QAR",
};

// Merge after parsing
const merged = mergeData(doc, data);

// Parse + merge in one step
const result = parseAndMerge(templateString, data);

• Dot notation: {{company.name}} → data.company.name
• Array indices: {{items.0.description}} → data.items[0].description
• System variables: {{date}}, {{year}} resolved automatically
• Runtime variables: {{page}}, {{pages}} become CSS page counters in renderPrint
• Missing fields: parseAndMerge(src, data, { missing: "blank" }) renders an unresolved {{field}} empty — use for finished documents so an invoice never prints a literal {{customer.phone}} (default "keep" aids template authoring)

Server-side PDFs

For real PDF bytes on a server (email attachments, archiving, batch runs) use the opt-in companion @dotit/pdf — issuePDF(template, data, { signer }) runs merge → seal (tamper-evident SHA-256) → PDF in one call. Core itself stays zero-dependency.

Querying

import { queryBlocks } from "@dotit/core";

const result = queryBlocks(doc, "type:task owner:Ahmed sort:due:asc limit:5");
console.log(result.blocks); // Filtered & sorted blocks

Trust — sign, seal, verify

.it documents are tamper-evident. sealDocument records a signer and freezes the content with a SHA-256 hash; verifyDocument recomputes it and reports integrity.

import { sealDocument, verifyDocument } from "@dotit/core";

const sealed = sealDocument(source, { signer: "Sarah Chen", role: "Legal" });
const result = verifyDocument(sealed.source);
console.log(result.intact); // true — false if a single character changed

The hashing rules are open and documented in SPEC.md, so anyone with the library can verify independently.

Converters

import { convertMarkdownToIntentText } from "@dotit/core";

const itSource = convertMarkdownToIntentText(markdownString);

Syntax Overview

Structure & Content

title: My Document
section: Chapter One
sub: Details
note: A standalone fact.
task: Do something | owner: Ahmed | due: Friday
done: Already finished | time: Monday
quote: Be concise. | by: Strunk
info: Informational callout.
---

Agentic Workflows (v2.0+)

agent: deploy-agent | model: claude-sonnet-4
step: Run tests | tool: ci.test | timeout: 300000
decision: Pass? | if: tests == "pass" | then: step-2 | else: step-3
gate: Approve deploy | approver: ops-lead | timeout: 24h
handoff: Transfer | from: deploy-agent | to: monitor-agent
emit: Complete | phase: deploy | level: success

Document Generation (v2.5)

font: | family: Palatino Linotype | size: 12pt | leading: 1.8
page: | size: A5 | margins: 25mm | footer: Page {{page}} of {{pages}}

title: *Chapter One*
dedication: To the builders who write before they code.
byline: Ahmed Al-Rashid | role: Author
epigraph: The tools we build shape the thoughts we can think. | source: Kenneth Iverson
toc: | depth: 2 | title: Contents

section: Introduction
caption: Figure 1 — The parsing pipeline
footnote: 1 | See chapter 3 for details.
break:

Inline Formatting

Styling (three layers)

1. Theme — renderHTML(doc, { theme: "corporate" }) (8 built-in document classes)
2. style: rules (v4.3) — house styling per block type, declared once: style: section | color: #0a7 | weight: 600 (targets: title, summary, section, sub, text, quote, callout/info, table, table-header, metric, contact, divider; same constrained style keys — never arbitrary CSS, content stays queryable)
3. Per-line props / inline spans — exceptions: text: hi | color: red, [word]{ size: 1.2em } (most-specific wins)

CLI

node cli.js document.it                          # Parse to JSON
node cli.js document.it --html                   # Render HTML
node cli.js template.it --data data.json --html  # Merge + render
node cli.js template.it --data data.json --print # Print-optimized HTML
node cli.js template.it --data data.json --pdf out.pdf  # PDF via Puppeteer

Test Suite

869 tests covering parser, renderer, query engine, converters, agentic blocks, document generation, trust/seal, and round-trip serialization.

pnpm test

Links

• Full Specification
• Usage Guide
• Changelog
• Example Templates

License

MIT