@intenttext/core

@intenttext/core

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

Install

npm install @intenttext/core

Quick Start

import { parseIntentText, renderHTML } from "@intenttext/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 "@intenttext/core";

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

Rendering

import { renderHTML, renderPrint } from "@intenttext/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 "@intenttext/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}} left as-is for the print renderer

Querying

import { queryBlocks } from "@intenttext/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 "@intenttext/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 "@intenttext/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

Style	Syntax
Bold	*text*
Italic	_text_
Strikethrough	~text~
Code	`code`
Highlight	^text^
Inline note	[[text]]
Footnote ref	{1}

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