Implementation status — 1.0.0
The Python package is runnable. This file distinguishes implemented contracts from the broader descriptions in the original component catalogue.
Notes release
The 0.2.0 implementation adds all fifteen note-taking areas from the notes brief: minimal notes mode; layered emphasis; relative placement; personal shorthand; tolerant live editing; anchored annotations; concise relationship diagrams; persistent content connections; keyboard mathematics; worked derivations; thinking structures; section rearrangement; personal visual styles; scratch work; and optional recall interactions. NOTES.md defines their supported syntax and limits.
The local editor is started with hmk edit. It preserves source files as plain text and provides explicit saving, revision conflict detection, local draft recovery, and undo. Notes do not execute arbitrary code. The 1.0 release supports the contracts and limits below.
Implemented
- Indented blocks, inline components, multiline arguments, raw content, comments, source spans, and structured diagnostics.
- Typed units and expressions; defaults, aliases, styles, themes, profiles, custom components, content slots, local imports, data sources, and bounded repetition.
- Semantic prose, headings, links, lists, code highlighting, captions, tables, notes, numeric citations, bibliographies, indexes, glossaries, and generated navigation.
- Paged and pageless HTML; shared Chromium PDF rendering; fixed page dimensions; running headers and footers; page numbering; page references; explicit page breaks; page masters; footnotes.
- Rows, stacks, wrapping, columns, grids, named areas, fixed canvases, layers, positioned elements, SVG primitives, masks, clipping, shape-wrapped floats, and CSS transforms.
- Named text flowing across unequal rectangular frames, with overflow failures and preserved inline markup.
- Dependency-ordered anchor constraints, including edge, centre, and baseline attachment.
- SVG bar, line, scatter, and pie charts; directed node diagrams; timelines; equirectangular GeoJSON maps.
- MathJax mathematics and mhchem reactions; RDKit SMILES structures; Pint quantity formatting and conversions.
- Self-contained GLB/glTF viewing; audio/video; captions and transcripts; static PDF fallbacks; downloadable resources.
- Accessible local form controls and disclosure widgets.
- Live preview with dependency watching and page reloads; CLI validation and syntax inspection; component introspection.
- Stdio LSP with syntax/name diagnostics, component completion, hover, document symbols, and conservative formatting.
- Deterministic
.hmkpsource bundles, checked paths, checksums, and verified extraction. - Installable wheel and source distribution; pinned browser libraries and bundled fonts; automated language, browser, and PDF tests.
Contracts with deliberate limits
| Area | Current contract |
|---|---|
| Layout fidelity | Web page surfaces and PDF use the same renderer. Different browser engines, viewport widths, font substitutions, colour profiles, and rasterizers can still differ. |
| Named flows | Rectangular frames with explicit heights, source-order flow, word-boundary text splitting. No automatic generation of additional frames or arbitrary polygonal frame interiors. |
| Constraints | One anchor relation per target axis, topologically resolved. No nonlinear equations, strength priorities, or general optimization solver. |
| Grid and pagination | CSS Grid plus Paged.js fragmentation. Prefer keeping complex grids together and break large editorial compositions into page-sized sections. |
| Page masters | Named page dimensions and repeated decorative overlays. Running headers/footers are document-wide; independently selected running furniture per master is not yet implemented. |
| Numbering | Document/page and object counters; page origins, sequence restarts, and Decimal/Roman/roman/Alpha/alpha page numbers. Full book-style counter scopes and arbitrary numeral-format languages are not yet implemented. |
| Citations | Numeric references from JSON records, with locators. No CSL style processor, BibTeX parser, or automatic DOI lookup. |
| Tables | Header/footer groups, spans, structured data, and browser fragmentation. Complex auto-sized spanning tables should be checked in final PDF output. |
| Charts | One series and categorical x positions. Scatter currently uses categorical x spacing, not independent numerical x coordinates. |
| Diagrams | Directed edges and sequential or explicit node positions. No force-directed, orthogonal, or general graph-routing engine. |
| Maps | GeoJSON Point, LineString, Polygon, and MultiPolygon with an equirectangular projection. No tile servers or geocoding. |
| Font resources | Regular, bold, italic, and bold-italic source declarations. Default bundled fonts cover Latin; variable-font axes and advanced font-feature controls are not exposed yet. |
| Interactive | Built-in media, local forms, and details disclosures. No arbitrary host code, general embedded application runtime, remote form actions, or interactive PDF controls. |
| Static media | Explicit poster/transcript/fallback. Automatic camera-frame capture for model posters is not part of the compiler. |
| Packaging | Verified local source bundles and local modules. No remote package registry, dependency solver, selective local imports, or versioned public package ecosystem. |
| Editor support | Stdio LSP core plus syntax grammar. Semantic diagnostics across a complete imported project, completion of custom parameters, refactoring, and full document design tooling remain future work. A local notes editor is included. |
| Formatting | Source-preserving line-ending normalization. No canonical pretty-printer for arbitrary expressions and comments. |
| Print production | Chromium tagged PDF and links. PDF/X, PDF/A, PDF/UA certification, spot colours, CMYK separation, and printer-specific bleed/registration workflows are not certified. |
The catalogue's final exploratory list—music notation, collaborative editing, advanced animation, procedural shaders, CAD, and package-defined inspectors—remains design work. The compiler does not claim those features are available.
Validation and limits
Source files are UTF-8 and limited to 8 MB. Expression and block nesting have explicit limits. Repetition is capped at 10,000 items, expanded documents at 50,000 nodes, and individual local assets at 64 MB. Source and resources must stay within the selected project root after symlink resolution. There is no Python eval, Python exec, shell execution, or unrestricted network access from source documents.
Browser render failures remain visible in the web page and cause PDF export to fail. Unknown component names and properties produce compiler errors. Some properties in the original design catalogue have narrower semantics or backend-specific support; consult docs/SYNTAX.md and inspect the actual output for complex compositions.
Evidence
tests/test_language.py, tests/test_components.py, and tests/test_packages.py cover language behavior, supported component contracts, invalid input, source isolation, and package verification. tests/test_browser.py checks actual page geometry, running furniture, footnotes, flow content preservation, constraints, mobile reflow, form interactions, model rotation with external requests blocked, static fallbacks, and PDF text, links, dimensions, and tags.
The examples in examples/ are executable fixtures. Generated previews, PDFs, and visual checks are stored under output/ and are not source files.