apexfile 1.1.0

package/LICENSE

@@ -0,0 +1,94 @@
+MIT License
+
+Copyright (c) 2026 Boniface Njuguna
+
+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.
+
+───────────────────────────────────────────────────────────────────────────────
+
+ADDITIONAL GRANT — APEXDOC FORMAT SPECIFICATION
+
+The ApexDoc document format specification (the ".apx format"), including its
+syntax rules, block definitions, token types, AST structure, and all associated
+format documentation, is hereby declared open and permanently free.
+
+This additional grant clarifies and extends the permissions above specifically
+for the purpose of format interoperability:
+
+1. IMPLEMENTATION FREEDOM
+   Any person or organization may implement a parser, renderer, tokenizer,
+   editor, validator, converter, or any other tool that reads, writes, or
+   processes files in the ApexDoc (.apx) format without requiring permission,
+   payment, license fees, or attribution to this project, subject only to
+   the condition in clause 3 below.
+
+2. COMPATIBLE IMPLEMENTATIONS
+   Any implementation that correctly parses and renders a superset or subset
+   of the ApexDoc format specification may call itself "ApexDoc-compatible"
+   provided it documents clearly which parts of the specification it supports
+   and which it does not.
+
+3. FORMAT SPECIFICATION ATTRIBUTION
+   Implementations that claim full compliance with the ApexDoc format
+   specification must reference the authoritative specification at
+   https://github.com/bonifacenjuguna/apexdoc as the source of that
+   specification. Partial implementations need not do so but are encouraged to.
+
+4. FORKING THE SPECIFICATION
+   You may fork the ApexDoc specification and create a derived format. A
+   derived format may not be called "ApexDoc" without permission from the
+   original author, but may be called anything else including "Based on
+   ApexDoc", "ApexDoc-derived", or any entirely new name.
+
+5. DOCUMENT FILES
+   Files in the ApexDoc format (.apx files) authored by any person are owned
+   entirely by their author. This license does not claim ownership of, or
+   impose any restrictions on, document files created using the ApexDoc format
+   or this software.
+
+───────────────────────────────────────────────────────────────────────────────
+
+THIRD-PARTY ACKNOWLEDGEMENTS
+
+ApexDoc draws syntactic inspiration from the following open-source projects
+and standards. No code from these projects is included in this distribution,
+but their design philosophies shaped the ApexDoc format:
+
+- Markdown (John Gruber, 2004) — heading, list, emphasis, and link syntax
+- CommonMark Specification (various authors) — Markdown formalization
+- AsciiDoc (Stuart Rackham, 2002) — directive/block syntax inspiration
+- LaTeX (Leslie Lamport, 1984) — mathematical notation and academic structure
+- SCSS / Sass (Hampton Catlin, 2007) — CSS variable and nesting conventions
+- Jinja2 (Armin Ronacher, 2008) — template logic syntax (@if, @each, @set)
+- Mermaid.js (Knut Sveidqvist, 2014) — diagram-from-text philosophy
+- MDX (various authors, 2018) — component-in-document concept
+- Reveal.js (Hakim El Hattab, 2011) — presentation mode conventions
+
+Their work made the document tooling ecosystem what it is today. ApexDoc
+exists to build on that foundation and push it further.
+
+───────────────────────────────────────────────────────────────────────────────
+
+CONTACT
+
+Boniface Njuguna
+GitHub:  https://github.com/bonifacenjuguna
+npm:     https://npmjs.com/~bonifacenjuguna
+Email:   hello@apex.run
+Website: https://apex.run

package/README.md

@@ -0,0 +1,415 @@
+<div align="center">
+
+<img src="./icons/apex-logo.svg" width="120" alt="ApexDoc Logo" />
+
+# ApexDoc
+
+### One file. Every format. No compromises.
+
+[![npm](https://img.shields.io/badge/npm-1.1.0-00f5d4?style=flat-square&logo=npm&logoColor=white)](https://npmjs.com/package/apexdoc)
+[![pip](https://img.shields.io/badge/pip-1.1.0-3776AB?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/apexdoc)
+[![license](https://img.shields.io/badge/license-MIT-7b2fff?style=flat-square)](./LICENSE)
+[![tests](https://img.shields.io/badge/tests-86%2F86%20passing-00c896?style=flat-square)](#)
+[![VS Code](https://img.shields.io/badge/VS%20Code-Extension-007ACC?style=flat-square&logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=bonifacenjuguna.apexdoc)
+
+**[Get Started](#quick-start) · [Full Syntax Reference](./SPEC.md) · [Plugins](./PLUGINS.md) · [Themes](./THEMES.md) · [Playground](https://apex.run/play)**
+
+</div>
+
+---
+
+## What is ApexDoc?
+
+ApexDoc is an open document format — file extension `.apx` — that unifies everything writers, developers, scientists, and designers need into a single, human-readable file.
+
+Where Markdown stops at basic formatting, ApexDoc keeps going. Where LaTeX handles math beautifully but nothing else, ApexDoc handles everything. Where HTML gives you full power but demands full expertise, ApexDoc gives you the same power with a syntax anyone can learn in an afternoon.
+
+A single `.apx` file can simultaneously be:
+
+- A **technical document** with full LaTeX math, theorems, and chemical equations
+- A **data dashboard** with live charts, stat cards, and real-time feeds
+- A **presentation** with slide transitions, speaker notes, and presenter timer
+- A **design system** with CSS variables, named themes, and custom color palettes
+- An **interactive application** with polls, quizzes, kanban boards, and countdowns
+- An **animated experience** with scroll-triggered effects and particle backgrounds
+
+All from one file. All with a clean, readable syntax. All exportable to HTML, PDF, Markdown, slides, and plain text — without touching the source.
+
+---
+
+## The Problem with Document Formats
+
+Every format ever designed was built to solve one specific problem. As a result, every format created several new ones.
+
+**Markdown** is elegant for notes and READMEs. Try adding a LaTeX equation, a bar chart, a switchable dark-mode theme, or an interactive quiz. You cannot. You are now outside Markdown, stitching five tools together and paying the maintenance cost of that decision forever.
+
+**HTML** can do everything Markdown cannot. But the moment you want a source file that a non-developer can read, write, and maintain — let alone version-control meaningfully — HTML becomes an obstacle, not a tool.
+
+**LaTeX** is the gold standard for mathematics and academic typesetting. It cannot be read without compilation. It has no concept of themes, live data, or interactivity. Setup takes hours, mastery takes months.
+
+**PDF** is the most universally portable format on earth. It also cannot be edited in place, reflowed to different screen sizes, or made interactive without specialized tooling.
+
+The real problem is not any single format. The real problem is that the world has accepted a reality where every document type demands a different tool, a different syntax, a different mental model, and a different export pipeline — and we maintain separate versions of the same content in five formats simultaneously.
+
+ApexDoc is the answer to this fragmentation. Not by being acceptable at everything, but by being genuinely excellent — absorbing the best syntax conventions from each major format and unifying them under one coherent, learnable design.
+
+---
+
+## Features
+
+### Document & Content
+Familiar Markdown-style syntax for headings, paragraphs, lists, blockquotes, footnotes, horizontal rules, and tables. Callout blocks — notes, tips, warnings, dangers — in a single line. Collapsible sections, tabbed panels, multi-column grids, reusable component definitions, and cross-document imports.
+
+### Mathematics & Science
+Full LaTeX math, inline (`$E = mc^2$`) and block (`%%math`). Chemical notation with `%%chem`. AsciiMath as a simpler alternative. Theorem, proof, lemma, and corollary blocks with automatic numbering. Greek symbols, calculus operators, matrix rendering, summations, integrals. Everything a scientist or engineer needs, zero external dependencies.
+
+### Design & Theming
+A CSS-variable system lets you define your entire visual language inside `%%style`. Switch between named themes — `dark-ocean`, `neon-city`, `sunset`, `minimal-light`, `terminal` — with one line. Build custom themes. Every color, font, spacing unit, shadow, and radius is a variable you own.
+
+### Data & Charts
+Embed JSON or CSV data inline. Fetch from live REST APIs with configurable refresh intervals. Render bar, line, pie, scatter, area, donut, and heatmap charts directly from your data. Display stat cards and KPI dashboards. Animate counters and progress bars on scroll.
+
+### Animations
+Fade, slide, zoom, bounce, flip, blur, glitch — apply to any block. Trigger on load, scroll, hover, or click. Stagger children with timing delays. Define custom `@keyframe` sequences. Import Lottie JSON animations. Scatter particles across backgrounds.
+
+### Live & Interactive
+Embed a live clock. Countdown to any date. Pull WebSocket streams and render them live. Add polls readers can vote in. Create quizzes with instant feedback. Build kanban boards, event timelines, rating widgets, interactive sliders, signature pads, and modal popups — all in `.apx` syntax, zero JavaScript knowledge required.
+
+### Presentation Mode
+One metadata field — `mode: presentation` — turns every `%%slide` block into a slide. Full transition effects, speaker notes, presenter timer, slide thumbnails, and remote control via QR code. Export to standalone HTML slides or PDF.
+
+### Logic & Variables
+Define variables with `@set`. Write `@if`/`@elseif`/`@else` conditionals. Loop with `@each`. Evaluate expressions inline — `{price * 1.1 | currency}`. Call built-in functions: `{today()}`, `{uuid()}`, `{wordCount()}`, `{random(1,100)}`. Apply pipe filters for formatting and transformation.
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+# Global CLI — the fastest way to start
+npm install -g apexdoc
+
+# As a library in your project
+npm install apexdoc
+
+# Python
+pip install apexdoc
+```
+
+### Your First Document
+
+Save this as `hello.apx`:
+
+```
+%%meta
+  title:  "Hello, ApexDoc"
+  author: "Your Name"
+  theme:  dark-ocean
+%%end
+
+%%style
+  --primary: #00f5d4
+  --bg:      #0d0d0d
+%%end
+
+%%body
+
+# Hello, ApexDoc {color: var(--primary)}
+
+A paragraph with **bold**, _italic_, and $E = mc^2$ inline math.
+
+%%note
+  This is a note callout. It supports **any** inline formatting.
+%%end
+
+- [x] Math rendering
+- [x] Themes and color variables
+- [x] Charts and live data
+- [~] Your imagination
+
+%%chart {type: bar, data: [40,80,60,95], labels: [Q1,Q2,Q3,Q4], title: "Revenue", animated: true}%%end
+
+%%end
+```
+
+```bash
+apex serve hello.apx          # Live preview at http://localhost:3000
+apex build hello.apx          # Compile to hello.html
+apex export hello.apx --to pdf
+```
+
+### API — Node.js
+
+```js
+const apex = require('apexdoc');
+
+// One line
+const html = apex.compile('./report.apx', 'html');
+
+// Step by step
+const ast  = apex.parse('./report.apx');
+const html = apex.render(ast, 'html');
+const text = apex.render(ast, 'text');
+const json = apex.render(ast, 'json');
+
+// Write to file
+apex.export('./report.apx', 'html', './dist/report.html');
+
+// Validate
+const { valid, errors, warnings } = apex.lint('./report.apx');
+```
+
+### API — Python
+
+```python
+import apexdoc
+
+html = apexdoc.compile("report.apx", target="html")
+
+ast  = apexdoc.parse("report.apx")
+html = apexdoc.render(ast, target="html")
+
+apexdoc.export("report.apx", target="pdf", output="./dist/report.pdf")
+
+result = apexdoc.lint("report.apx")
+print(result["valid"], result["errors"])
+```
+
+---
+
+## Syntax Overview
+
+> The complete format specification — every block, every prop, every token, every error code — lives in **[SPEC.md](./SPEC.md)**.
+
+### File Structure
+
+```
+%%meta    ← document configuration
+%%style   ← CSS variables, themes, fonts
+%%body    ← all content
+```
+
+All three sections are optional. A file with no sections is treated as a bare `%%body`.
+
+### Inline Formatting
+
+| Syntax | Output |
+|---|---|
+| `**bold**` | bold |
+| `_italic_` | italic |
+| `__underline__` | underline |
+| `~~strikethrough~~` | strikethrough |
+| `` `code` `` | inline code |
+| `==highlight==` | highlighted |
+| `^^super^^` | superscript |
+| `,,sub,,` | subscript |
+| `$E = mc^2$` | LaTeX math |
+| `{today()}` | current date |
+| `[text](url)` | hyperlink |
+| `[red]{color: red}` | styled span |
+| `[word]{tooltip: "hint"}` | tooltip |
+
+### Block Syntax
+
+```
+%%blockname {prop: value, prop: value}
+  Content here. Supports all inline formatting.
+  Supports nesting.
+%%end
+
+%%selfclosing {prop: value}%%end
+```
+
+### Logic
+
+```
+@set price  = 49.99
+@set users  = ["Alice", "Bob", "Carol"]
+
+Total: ${price * 1.1 | currency("USD")}
+
+@if price == 0
+  Free tier.
+@else
+  Paid: {price}
+@end
+
+@each user in users
+  - {user}
+@end
+```
+
+---
+
+## Block Types
+
+50+ blocks ship with ApexDoc. A selection:
+
+| Block | Renders |
+|---|---|
+| `%%box` | Styled container — bg, border, radius, padding |
+| `%%note` / `%%tip` / `%%warning` / `%%danger` | Callout blocks with icons |
+| `%%code` | Syntax-highlighted code, copy button, line numbers |
+| `%%math` | LaTeX block equation with optional numbering |
+| `%%chem` | Chemical equation notation |
+| `%%theorem` / `%%proof` / `%%lemma` | Academic math blocks |
+| `%%table` | Striped, sortable, bordered tables |
+| `%%chart` | Bar, line, pie, scatter, donut, heatmap |
+| `%%data` | Inline JSON/CSV or live API data source |
+| `%%stats` | Stat cards and KPI dashboard |
+| `%%tabs` | Tabbed content panels |
+| `%%collapse` | Expandable/collapsible section |
+| `%%grid` | Responsive multi-column layout |
+| `%%animate` | Any block with scroll or load animation |
+| `%%stagger` | Children animate in sequence |
+| `%%slide` | Presentation slide |
+| `%%timeline` | Vertical/horizontal event timeline |
+| `%%kanban` | Task board |
+| `%%poll` | Live voting widget |
+| `%%quiz` | Multiple-choice quiz with feedback |
+| `%%countdown` | Live countdown to a date |
+| `%%clock` | Live digital clock |
+| `%%qr` | QR code from URL or text |
+| `%%terminal` | Styled terminal output |
+| `%%diff` | Code diff — added/removed lines |
+| `%%gallery` | Image grid with lightbox |
+| `%%mindmap` | Tree diagram |
+| `%%flowchart` | Flow diagram from text |
+| `%%modal` | Popup dialog |
+
+---
+
+## Themes
+
+| Theme | Character |
+|---|---|
+| `dark-ocean` | Deep blue — the ApexDoc signature |
+| `neon-city` | Cyberpunk neons on near-black |
+| `sunset` | Warm oranges and deep reds |
+| `minimal-light` | Clean white, professional |
+| `forest` | Deep greens, organic |
+| `candy` | Pastel, playful, colorful |
+| `terminal` | Classic green-on-black |
+| `academic` | Serif, print-ready, formal |
+| `newspaper` | High-contrast editorial |
+
+Add a runtime theme switcher:
+
+```
+%%theme-switcher {themes: [dark-ocean, neon-city, minimal-light]}%%end
+```
+
+Build your own theme in `%%style`:
+
+```
+@theme my-brand {
+  --bg:      #0a0014
+  --primary: #a855f7
+  --text:    #f3e8ff
+  --font:    "Outfit", sans-serif
+}
+```
+
+> See **[THEMES.md](./THEMES.md)** for the complete theme authoring guide and how to publish themes.
+
+---
+
+## VS Code Extension
+
+The ApexDoc VS Code extension provides a complete editing experience for `.apx` files.
+
+**Install:** Open VS Code → Extensions (`Ctrl+Shift+X`) → search **ApexDoc** → Install.
+
+**What you get:**
+- Syntax highlighting with 41 token scope mappings — every part of the syntax has its own color
+- **Live preview** — open with `Ctrl+Shift+V` / `Cmd+Shift+V`, updates as you type
+- Inline **lint diagnostics** — errors and warnings shown as squiggles in your editor
+- **30+ snippets** — type `%%` to trigger block completions
+- **Dark Ocean** editor theme — matching ApexDoc's default aesthetic
+- `.apx` file icon in the file explorer
+- Export to HTML directly from the Command Palette
+
+---
+
+## Compared to the Alternatives
+
+### vs. Markdown
+Markdown excels at simple notes. ApexDoc is built for when Markdown ends. If you've ever added raw HTML tags to a Markdown file, used a separate LaTeX renderer for equations, or given up on adding a chart — ApexDoc removes every one of those friction points.
+
+### vs. MDX
+MDX embeds React inside Markdown. ApexDoc requires no framework, no build pipeline, and no JavaScript knowledge. A scientist, a writer, and a data analyst can all author `.apx` files without knowing what JSX is.
+
+### vs. LaTeX
+ApexDoc uses LaTeX's math notation exactly — `$E = mc^2$`, `\int_{-\infty}^{\infty}`, `\begin{pmatrix}` — so you never relearn the math syntax you already know. It then adds everything LaTeX lacks: themes, live data, charts, animations, and source files you can read without compiling.
+
+### vs. Notion / Confluence
+Those are collaboration platforms with proprietary document formats. ApexDoc is an open, plain-text format — version-controlled, diffable, scriptable, and owned entirely by you. Your `.apx` files live on your filesystem.
+
+### vs. PowerPoint / Keynote
+Presentation software produces binary files you cannot meaningfully diff or generate with code. An ApexDoc presentation is plain text — scriptable, version-controllable, renderable anywhere with `apex serve`.
+
+---
+
+## Ecosystem
+
+| Package | Description |
+|---|---|
+| `apexdoc` (npm) | Core parser and renderer — Node.js |
+| `apexdoc` (pip) | Python port — identical API |
+| `apexdoc-vscode` | VS Code extension |
+| `apex` (CLI) | Build, serve, export, lint |
+| `apex.run` | Playground and documentation |
+
+### Plugin System
+
+ApexDoc has a first-class plugin API. Plugins can add custom block types, inline tags, export targets, and lifecycle hooks.
+
+```bash
+apex plugin install apexdoc-katex     # Faster math via KaTeX
+apex plugin install apexdoc-mermaid   # Mermaid diagrams
+```
+
+> See **[PLUGINS.md](./PLUGINS.md)** for how to build and publish plugins.
+
+---
+
+## Documentation Index
+
+| File | Contents |
+|---|---|
+| **README.md** | This file — overview, features, quick start |
+| **[SPEC.md](./SPEC.md)** | Complete format specification — all syntax, all blocks, all props |
+| **[PLUGINS.md](./PLUGINS.md)** | Plugin development guide |
+| **[THEMES.md](./THEMES.md)** | Theme authoring and publishing guide |
+| **[CONTRIBUTING.md](./CONTRIBUTING.md)** | How to contribute to ApexDoc |
+| **[CHANGELOG.md](./CHANGELOG.md)** | Version history |
+| **[SECURITY.md](./SECURITY.md)** | Security policy and vulnerability reporting |
+| **[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)** | Community standards |
+
+---
+
+## Contributing
+
+ApexDoc is open source and welcomes contributions — new block types, export targets, themes, plugins, documentation improvements, and bug fixes.
+
+Read [CONTRIBUTING.md](./CONTRIBUTING.md) to get started. The project has an 86-test suite that must pass fully before any merge.
+
+---
+
+## License
+
+MIT © 2026 [Boniface Njuguna](https://github.com/bonifacenjuguna)
+
+The ApexDoc format specification is permanently open. Anyone may implement a parser, renderer, editor, or tooling for `.apx` files without restriction or royalty.
+
+---
+
+<div align="center">
+
+**[apex.run](https://apex.run) · [npm](https://npmjs.com/package/apexdoc) · [PyPI](https://pypi.org/project/apexdoc) · [GitHub](https://github.com/bonifacenjuguna/apexdoc) · [VS Code](https://marketplace.visualstudio.com/items?itemName=bonifacenjuguna.apexdoc)**
+
+*The last document format you'll ever need.*
+
+</div>