@html

@html provides compile-time HTML helpers as a builder source-backed package. It belongs to the Builder origin family with MothSource backing, so the compiler reads ordinary Moth source from packages/html/@mod.moth. See Package origins and backing for origin and backing rules.

@html ships as a skeleton. The current export surface covers common HTML tags, a few formatting helpers, table components and a thin canvas wrapper. It will grow as the language stabilises and the standard library expands.

Implicit scope for Moth template files

Exported compile-time constants from @html are visible inside .mtf files without an explicit dependency clause. This is the primary way authors use the helpers.

-- docs/intro.mtf
[p: A paragraph built from the @html p helper.]

[codeblock, $code("moth"): value = 42]

A .moth file that needs specific @html symbols can bind them explicitly:

@html table, th, td

Same-directory module root constants and @html constants don't shadow each other. If both surfaces expose the same visible name, compilation fails with a collision diagnostic. See Template scope for the full collision contract.

Exported constants

All helpers are compile-time #String constants that produce HTML strings. They fold at compile time and produce no runtime code.

HTML tags

Formatting helpers

Code and tables

Utility style inserts

These constants produce CSS property values for style slots.

The $code directive

$code renders a balanced template body as an HTML code block with lexical highlighting. The HTML builder registers it as a style directive; the frontend formatter registry executes the hook, so it is available in HTML-builder projects.

Supported aliases:

• text / txt
• html
• markdown / md
• toml
• json
• yaml / yml
• css
• c
• sql
• moth
• javascript / js
• typescript / ts
• python / py
• rust / rs
• bash / sh / shell

[codeblock, $code("moth"):
    render |name String| -> String:
        return ["Hello, ", name]
    ;
]

$code escapes HTML-sensitive characters and wraps the body in <code class='codeblock'>. Dynamic expression anchors pass through as sealed content without highlighting or escaping. Highlighting is lexical presentation only. It never validates the snippet, resolves names or reports diagnostics. Every language profile shares the same general role palette, and the Moth profile uses the compiler-owned source-word classification plus bounded lexical roles for contracts, functions, directives, dependency paths and the io namespace. Stateful template-body-aware highlighting stays deferred.

Canvas wrapper

@html exports a Canvas struct and two functions that wrap @web/canvas into a source-owned method-style API.

The Canvas struct provides receiver methods for drawing: set_fill_style, fill_rect, clear_rect and stroke_rect. Each takes ~Canvas (mutable receiver) and delegates to the underlying @web/canvas free functions.

@html get_canvas

canvas ~= get_canvas("my-canvas") catch:
    assert(false, "canvas not found")
;

~canvas.set_fill_style("red")
~canvas.fill_rect(10.0, 10.0, 50.0, 50.0)

Both get_canvas and get_canvas_context return through Error! because the underlying @web/canvas functions can fail when the canvas element does not exist or the browser denies a 2D context.

Backend behaviour

The compile-time constants need no runtime assets. They fold into HTML strings during compilation.

The canvas wrapper functions call through to @web/canvas, which emits JavaScript runtime assets when reachable. See @web/canvas for the runtime asset contract.

Unsupported source forms

• Direct symbol-path clauses such as @html/p face rejection. Use direct selections or a namespace clause.
• @html does not expose opaque types of its own. Canvas2d comes from @web/canvas.
• Only compile-time constants are visible inside .mtf files. Functions and types require an explicit dependency clause in .moth files.

Deferred surfaces

@html ships as a skeleton. Future expansions include richer tag coverage, form components, accessible widget helpers, layout primitives and broader style utilities. The package grows as the language stabilises and the standard library matures. See progress matrix for current status.

Related concepts

• For package origin and backing see Package origins and backing.
• For dependency-path rules see Dependency paths.
• For .mtf implicit scope see Template scope.
• For the @web/canvas runtime package see @web/canvas.