@@ -0,0 +1,193 @@
1+# YoctoMarkdown Specification
2+
3+YoctoMarkdown is a small Bun-native Markdown highlighter for terminal output.
4+It reads Markdown and writes ANSI-colored text to stdout or returns it as a string.
5+The focus is simple, fast, incremental rendering for CLI and Programmatic use.
6+
7+## Overview
8+
9+YoctoMarkdown MUST:
10+
11+- accept Markdown from a complete string, a file, or a stream
12+- process input incrementally
13+- render supported Markdown syntax as ANSI-styled terminal text
14+- preserve unsupported or malformed Markdown as plain text
15+- avoid buffering the full document when used in streaming mode
16+
17+YoctoMarkdown is not a full CommonMark implementation.
18+It supports a small, practical subset intended for terminal display.
19+
20+## Dependencies
21+
22+YoctoMarkdown is intended to use:
23+
24+- **Bun** as the runtime, stream, and build tool
25+- **yoctocolors** from npm for ANSI color rendering - https://github.com/sindresorhus/yoctocolors
26+
27+## Supported Markdown
28+
29+Version 1 supports the following syntax:
30+
31+| Element | Syntax | Behavior |
32+| ----------------- | ------------------ | ------------------ |
33+| Heading 1 | `# Title` | styled heading |
34+| Heading 2 | `## Title` | styled heading |
35+| Heading 3 | `### Title` | styled heading |
36+| Bold | `**text**` | styled inline text |
37+| Italic | `*text*` | styled inline text |
38+| Inline code | `` `code` `` | styled inline code |
39+| Fenced code block | ` ``` ` | styled block code |
40+| Link | `[text](url)` | styled link text |
41+| Unordered list | `- item`, `* item` | styled marker |
42+| Ordered list | `1. item` | styled marker |
43+| Blockquote | `> quote` | styled marker |
44+| Horizontal rule | `---` | styled rule |
45+| Plain text | any other text | unchanged text |
46+
47+Unsupported syntax MUST be rendered as plain text.
48+
49+## Parsing Rules
50+
51+The parser is line-aware and incremental.
52+
53+### Block rules
54+
55+- Headings are recognized only at the start of a line.
56+- Only `#`, `##`, and `###` headings are supported.
57+- Fenced code blocks use triple backticks.
58+- Inside a fenced code block, all text is treated as code until a closing triple backtick fence is found.
59+- Horizontal rules are recognized only when the full trimmed line is `---`, `***`, or `___`.
60+- List and blockquote markers are recognized only at the start of a line.
61+
62+### Inline rules
63+
64+- Inline code has priority over other inline formatting.
65+- Links are recognized only in the form `[text](url)`.
66+- Bold uses `**text**`.
67+- Italic uses `*text*`.
68+- Nested or ambiguous inline formatting is not required to match full CommonMark behavior.
69+
70+### Malformed input
71+
72+- Incomplete inline constructs MAY remain buffered while more input is expected.
73+- At end of input, any unclosed inline construct MUST be emitted as plain text.
74+- An unclosed fenced code block MUST render as code until end of input.
75+
76+## Streaming Behavior
77+
78+Streaming mode MUST work chunk by chunk.
79+
80+For each chunk:
81+
82+1. append the chunk to an internal buffer
83+2. parse as much complete Markdown as possible
84+3. render completed output immediately
85+4. keep only unresolved trailing text in the buffer
86+
87+The implementation MUST preserve enough state to handle syntax split across chunk boundaries.
88+
89+## Rendering
90+
91+Rendering maps recognized Markdown elements to ANSI styles.
92+
93+The implementation MUST provide these built-in theme names:
94+
95+- `16`
96+- `256`
97+- `truecolor`
98+- `minimal`
99+- `none`
100+
101+Theme behavior:
102+
103+- headings MUST be visually distinct from plain text
104+- bold and italic SHOULD be visually distinct from plain text
105+- code and code blocks MUST be visually distinct from surrounding text
106+- links SHOULD be visually distinct from plain text
107+- list and blockquote markers MAY be styled independently
108+- `none` MUST disable ANSI styling entirely
109+
110+The exact colors are implementation-defined.
111+
112+## Configuration
113+
114+The implementation MUST support the following options:
115+
116+```ts
117+interface Options {
118+ theme?: "16" | "256" | "truecolor" | "minimal" | "none" | Theme;
119+ tabWidth?: number;
120+ wordWrap?: number | "auto" | 0;
121+ yieldEvery?: number;
122+}
123+```
124+
125+Default values:
126+
127+- `theme`: `'16'`
128+- `tabWidth`: `2`
129+- `wordWrap`: `'auto'`
130+- `yieldEvery`: `1000`
131+
132+### Word wrap
133+
134+If wrapping is enabled:
135+
136+- `'auto'` means terminal width when available, otherwise `80`
137+- `0` disables wrapping
138+- ANSI escape sequences MUST NOT count toward visible width
139+
140+## Library API
141+
142+The library MUST expose:
143+
144+```ts
145+highlightSync(input: string, options?: Options): string
146+createHighlighter(options?: Options): Highlighter
147+```
148+
149+```ts
150+interface Highlighter {
151+ write(chunk: string | Uint8Array): string;
152+ end(): string;
153+}
154+```
155+
156+Behavior:
157+
158+- `highlightSync()` returns the fully rendered ANSI string for a complete input string
159+- `createHighlighter()` returns an incremental highlighter
160+- `write()` returns rendered output for the provided chunk
161+- `end()` flushes any remaining buffered text
162+
163+## CLI
164+
165+The CLI command is:
166+
167+```text
168+yoctomarkdown [options] [file]
169+```
170+
171+If `file` is provided, the CLI reads that file.
172+Otherwise, it reads from stdin.
173+
174+Supported options:
175+
176+- `-t, --theme <name>`
177+- `-w, --wrap <n|auto|0>`
178+- `-h, --help`
179+
180+The CLI MUST:
181+
182+- write rendered output to stdout
183+- write diagnostics to stderr
184+- exit with status `0` on success
185+- exit with non-zero status on input or argument errors
186+
187+## Non-Goals
188+
189+- full CommonMark compliance
190+- GFM extensions such as tables, task lists, or strikethrough
191+- HTML rendering
192+- syntax highlighting inside code blocks
193+- AST generation