DEV Community: Tosiiko

Wetask Is Opening Its Task Runtime to External Workers

Tosiiko — Thu, 30 Jul 2026 23:21:14 +0000

Wetask's next update brings durable, fenced external workers, atomic batch settlement, and first-party Go, TypeScript, and Python clients.

Wetask started with a simple goal: combine the pieces commonly assembled around
a background job system into one Go-based runtime.

That means a task queue, scheduler, cache, consensus, operational APIs, and
observability without requiring a separate broker, result backend, and schedule
service for every deployment.

The next Wetask update takes that idea beyond embedded handlers. Applications
will be able to run their own workers in another process, container, language,
or execution environment while Wetask remains responsible for durable task
state.

Bring your own workers

External workers are useful when execution cannot or should not happen inside
the Wetask server:

Python workers running machine-learning jobs
TypeScript workers calling application services
Go workers handling high-throughput backend work
GPU or memory-specialized worker pools
independently deployed workers with their own release cycle
workers isolated from the queue and control-plane process

The first-party Go, TypeScript, and Python clients expose the worker API, while
HTTP and gRPC remain available for custom integrations.

Workers can request batches by queue and task type, renew long-running work,
report success, or classify a failure as transient, permanent, or cancelled.
Credentials can be limited to specific queues and task types.

Fencing matters more than another Ack endpoint

At-least-once systems must assume a task can be delivered again. A worker can
pause, lose its connection, exceed its lease, and continue running after
another worker has received the same task.

Wetask gives every claimed attempt a one-time fencing token. Completion is
accepted only when the task, claim, token, principal, attempt, and coordinator
still match. Once an attempt expires or is superseded, the old worker cannot
complete it.

The token itself is returned only to the worker. Wetask stores its SHA-256 hash.

This does not make external side effects exactly once. A worker that charges a
card and crashes before acknowledging the task can still cause a retry.
Handlers must use the task ID and attempt to make downstream operations
idempotent.

What fencing does guarantee is that a stale worker cannot overwrite the state
of the current attempt.

Durable and idempotent settlement

Successful and failed settlements are persisted before Wetask returns their
receipts. Retrying the same acknowledgment returns the original receipt instead
of completing or retrying the task twice.

Failure handling is task-aware:

transient schedules another attempt when retries remain
permanent ends the task and records it in the dead-letter queue
cancelled ends execution without retrying
lease expiration applies the configured retry and DLQ policy automatically

Workers can acknowledge or reject a complete batch atomically. Wetask validates
every fence first. If one item is stale or invalid, none of the unsettled items
in that batch are changed.

Batch settlement also reduces durable storage overhead by recording the batch
with one WAL synchronization.

Benchmarks

We benchmarked the complete in-process lifecycle:

submit tasks
claim them as an external worker
acknowledge them

The benchmark does not execute application work, and it does not include HTTP
or gRPC network overhead. It measures the task runtime itself.

Environment:

Apple M3
macOS darwin/arm64
Go benchmark process reporting 8-way parallelism
batch sizes of 1, 8, and 32
three samples per scenario
three-second benchmark windows

Command:

go test ./internal/task \
  -run '^$' \
  -bench '^BenchmarkWorkerClaimAck($|Parallel$)' \
  -benchmem \
  -benchtime=3s \
  -count=3

In-memory lifecycle

The table reports median tasks per second:

Scenario	Earlier baseline	Current result	Difference
Batch 1	74,933	77,123	+2.9%
Batch 8	84,434	86,393	+2.3%
Batch 32	84,661	86,783	+2.5%
Parallel, single-task operations	64,429	63,443	-1.5%

Batch 32 completes the full lifecycle in about 11.52 microseconds per task.

The in-memory increase is intentionally modest. There is no disk barrier to
amortize, and every task still needs an ID, claim token, state transitions,
queue bookkeeping, result retention, metrics, and lifecycle events. The
parallel result is effectively flat and is included rather than hidden.

Durable lifecycle

Durable mode includes WAL synchronization for accepted submission, claim, and
settlement:

Scenario	Median throughput	Relative to earlier 86.34 tasks/s baseline
Batch 1	80.08 tasks/s	0.93x
Batch 8	645.7 tasks/s	7.5x
Batch 32	2,402 tasks/s	27.8x
Parallel, single-task operations	136.4 tasks/s	1.58x

At batch 32, durable processing costs approximately 416 microseconds per task.

The theoretical batching ceiling is 32x because the same durable barriers are
shared by 32 tasks. The measured 27.8x improvement reaches about 87% of that
ceiling. The remaining time covers WAL serialization, task state, metrics, and
the disk synchronization itself.

These are Wetask-only measurements, not claims that Wetask is faster than every
broker. A fair competitive benchmark must use equivalent payloads, transports,
batch sizes, persistence policies, replication, and acknowledgment semantics.

How Wetask compares

RabbitMQ quorum queues

RabbitMQ quorum queues are mature, Raft-replicated queues designed for data
safety and leader failover. Publisher confirms and manual consumer
acknowledgments provide a strong production foundation.

RabbitMQ remains ahead of Wetask in replicated queue durability, operational
history, protocol support, and ecosystem size.

Wetask aims at a more task-specific experience: results, retries, deadlines,
cancellation, dead letters, scheduling, cache facilities, and worker fencing
are available through one runtime and API.

Reference:
RabbitMQ quorum queues

NATS JetStream

JetStream is the closest protocol-level comparison. It offers pull and push
consumers, explicit Ack, Nak, delayed Nak, Term, in-progress acknowledgments,
AckWait, backoff, and maximum delivery counts.

JetStream is significantly more mature in clustered stream storage, pub/sub,
replication, and high-throughput messaging.

Wetask's distinction is strict attempt fencing. JetStream documents that a late
acknowledgment can be accepted after a message has already been redelivered to
another subscriber. Wetask rejects settlement from a superseded attempt.

Reference:
NATS JetStream consumers

AWS SQS and Google Cloud Pub/Sub

Managed queues remove most broker operations and provide elastic,
multi-availability-zone infrastructure.

SQS uses visibility timeouts and receipt handles. Standard queues remain
at-least-once and consumers must tolerate duplicate delivery.

Google Cloud Pub/Sub's exactly-once pull subscriptions provide a particularly
interesting comparison: only the latest acknowledgment ID remains valid after
redelivery. That is conceptually close to Wetask's fencing model.

Wetask is for teams that need self-hosting, portability, local deployment, and
task-specific state. Cloud queues are the stronger choice when a managed
service and provider-operated availability are more important.

References:

Apache Kafka

Kafka is an ordered, replayable event log. It is the better fit for event
streaming, large retained histories, partition ordering, and many independent
consumer groups.

Traditional Kafka consumers commit partition offsets rather than independently
settling arbitrary jobs. Retries for one record can affect partition progress,
and task results, per-task leases, and dead-letter behavior normally require
application conventions or additional topics.

Wetask is the more direct model for background jobs. Kafka is the stronger
model for durable event streams.

Reference:
Kafka delivery semantics

Celery with RabbitMQ

Celery remains a mature choice for Python applications. It has a large
ecosystem, familiar task decorators, retries, Canvas workflows, and years of
operational knowledge.

Its typical production shape combines Celery workers, a broker such as
RabbitMQ, a result backend, and Celery Beat for schedules.

Wetask's proposition is a smaller operational surface: one Go runtime provides
the queue, task state, scheduler, cache, APIs, and administration, while
external workers can still be written in Python, TypeScript, or Go.

Reference:
Celery documentation

Temporal

Temporal solves a larger problem than a task queue. It is designed for durable,
multi-step workflows that resume across process failures and infrastructure
outages.

Temporal is the stronger choice for long-running business processes, sagas,
durable timers, and workflow histories. Wetask is intentionally simpler for
ordinary asynchronous jobs, scheduled work, and application caching.

Reference:
Temporal documentation

Where Wetask fits

Wetask is not trying to replace every messaging system.

Choose Kafka when the log is the product. Choose Temporal when durable workflow
orchestration is the product. Choose a managed cloud queue when outsourcing
operations is the priority. Choose RabbitMQ or JetStream when a mature,
replicated messaging foundation matters more than an integrated application
runtime.

Wetask is for teams that want:

a compact self-hosted task platform
durable background jobs
workers outside the server process
strict stale-worker rejection
task results, retries, deadlines, and DLQ management
scheduling and cache capabilities without another service stack
HTTP, gRPC, Go, TypeScript, and Python integration

Availability

External workers are planned for the next Wetask alpha release. The first
release will focus on durable single-node use and controlled production pilots.
Multi-node coordination exists, but task queue WAL ownership is currently
per-node; replicated task ownership and permanent-node-loss recovery remain
future hardening work.

That boundary is deliberate. The goal of the alpha is to put the complete
worker experience into real projects, publish reproducible evidence, and let
production feedback shape the next stage.

If you are evaluating background job infrastructure, the most useful feedback
is not "which benchmark number is largest?" It is: which failure semantics,
operational model, and worker experience match the system you actually need to
run?

WeTask v0.1.0-rc.1 vs Redis benchmark report

Tosiiko — Fri, 24 Jul 2026 22:22:51 +0000

Run date: 2026-07-25 (Africa/Kampala)

Outcome

All recorded benchmark cells completed with zero operation errors. Redis was
faster than WeTask on comparable network cache operations and on the controlled
mixed pipeline matrix. WeTask pipeline throughput improved substantially as the
pipeline size increased, reaching a three-trial median of about 402k operations
per second for 1,000-operation pipelines at concurrency 16; Redis reached about
886k operations per second in the same cell.

Queue-ingress numbers are not equivalence claims. WeTask SubmitTask enters its
task lifecycle and the release's fallback handler executes the task. Redis
LPUSH only appends bytes to a non-persistent list. The repository's Celery
probe also measures producer enqueue only, with no worker, acknowledgement,
retry, or result measurement.

Environment

Host: MacBook Air, Apple M3, 8 host cores, 16 GiB RAM
OS: macOS 15.7.3, Darwin 24.6.0, arm64
Docker Desktop: 4.66.1; Docker Engine 29.3.1, Linux arm64
Docker allocation: 4 CPUs, 8,573,693,952 bytes RAM
WeTask network target: published wetask-io/wetask:v0.1.0-rc.1 (820859d, built 2026-07-11), standalone, consensus disabled
WeTask source benchmarks: worktree commit d6131019163f31c94022eafc65cf318ce163ba73
Redis: 7.4.9, standalone, save "", appendonly no, no memory limit, noeviction, one I/O thread
Container limits: neither container had a per-container CPU or memory limit
Clients: Go 1.26.5, go-redis/v9 9.12.1; Python 3.14.4, redis-py 6.4.0, Celery 5.6.3; Node 25.4.0
Network: one Go process on the macOS host to both containers over Docker-published loopback TCP ports
Execution: workloads were run serially to avoid intentional cross-load

Controlled network cache results

Each unary cell used 1,000 measured operations per worker after 25 unmeasured
warm-up calls per worker. Workers reused one distinct hot key each with a
60-second TTL.

Payload	Concurrency	Operation	WeTask ops/s	Redis ops/s	Redis/WeTask	WeTask p95	Redis p95
64 B	1	SET	1,621	3,532	2.18x	1.38 ms	0.31 ms
64 B	1	GET hit	1,916	3,498	1.83x	1.15 ms	0.31 ms
64 B	16	SET	6,956	20,176	2.90x	4.18 ms	1.54 ms
64 B	16	GET hit	6,412	18,853	2.94x	4.63 ms	1.52 ms
64 B	64	SET	9,581	30,422	3.18x	13.48 ms	3.55 ms
64 B	64	GET hit	9,294	32,345	3.48x	14.23 ms	3.20 ms
1,024 B	1	SET	1,672	3,288	1.97x	1.34 ms	0.34 ms
1,024 B	1	GET hit	1,924	3,444	1.79x	1.18 ms	0.32 ms
1,024 B	16	SET	6,866	18,861	2.75x	4.46 ms	1.61 ms
1,024 B	16	GET hit	6,582	17,761	2.70x	4.91 ms	1.64 ms
1,024 B	64	SET	8,606	23,802	2.77x	15.25 ms	5.39 ms
1,024 B	64	GET hit	6,999	23,397	3.34x	20.21 ms	4.98 ms

These are single recorded unary samples. Redis was consistently faster, but the
exact ratios should not be treated as stable capacity limits.

Controlled mixed pipeline results

Both products executed the same ordered, non-transactional
SET / GET / DELETE mix using 64-byte values. Each worker issued 100 measured
pipelines per cell after 25 warm-up pipelines (five for size 1,000). Values are
the median of three complete trials; all trials had zero errors.

Pipeline operations	Concurrency	WeTask ops/s	Redis ops/s	Redis/WeTask	WeTask p95/pipeline	Redis p95/pipeline
10	1	15,859	32,554	2.05x	1.20 ms	0.33 ms
10	16	74,135	160,198	2.16x	3.75 ms	1.91 ms
100	1	116,655	175,639	1.51x	1.59 ms	1.28 ms
100	16	256,634	727,032	2.83x	13.87 ms	4.33 ms
1,000	1	221,638	434,694	1.96x	6.31 ms	3.55 ms
1,000	16	402,175	886,477	2.20x	87.58 ms	26.22 ms

The repository's independent packaged-client pipeline harness also passed all
six cells with zero errors. Its one-run WeTask range was 15.6k ops/s
(size 10, concurrency 1) through 394.2k ops/s (size 1,000, concurrency 16).

Queue-ingress probes

The controlled Go probe used a printable 64-byte payload, 500 measured submits
per worker, 25 warm-up submits per worker, a fresh WeTask volume, and a flushed
Redis database.

Concurrency	WeTask SubmitTask	Redis LPUSH	WeTask p95	Redis p95
1	334 ops/s	3,340 ops/s	4.03 ms	0.34 ms
16	301 ops/s	19,037 ops/s	66.51 ms	1.83 ms

The documented Celery producer probe submitted 10,000 tasks at 728 tasks/s
sequentially. It used Redis as broker but no Celery worker or result backend.
The documented Redis cache probe completed 30,000 sequential SET/GET/TTL
operations at 2,696 operations/s.

WeTask-only documented benchmark coverage

Official five-second Phase 9 baseline: 23 rows, including task, scheduler, cache, cache replication, consensus commit, failover, rolling restart, and node resource snapshots.
In-process task submit: 2.05 million ops/s; task completion: 157.9k ops/s.
In-process cache SET: 753k ops/s; GET hit: 3.19 million ops/s.
Consensus commit: 5.44 ms/op; failover: 258 ms; rolling restart: 976 ms.
Fast-cache server path: unary GET 628 ns/op, unary SET 1.56 microseconds/op; pipeline service path 4.74 microseconds for 10 operations, 51.1 microseconds for 100, and 400 microseconds for 1,000.
Live release HTTP cache, 10,000 operations each: concurrency 1 produced 1.55k SET, 2.04k GET, and 2.00k DELETE ops/s; concurrency 64 produced 2.74k SET, 3.42k GET, and 4.39k DELETE ops/s.
Release task matrix: 12 concurrency/payload/handler-duration cells, with zero errors. Concurrency was 1/16/64, payload was 0/1,024 bytes, and handler delay was 0/50 ms.
Documented competitive suite: 14 Go rows and all three required competitor probes passed; no probe was skipped.

Reproducible commands

WETASK_PHASE9_BENCHTIME=5s WETASK_PHASE9_BENCH_QUIET=1 \
  ./scripts/benchmark-phase9.sh /tmp/wetask-redis-comparison-20260725/phase9-baseline-full

WETASK_BENCH_QUIET=1 go test -run '^$' -bench BenchmarkFastCache \
  -benchmem -benchtime=5s ./internal/network

WETASK_HTTP_BASE=http://127.0.0.1:38081 \
WETASK_LIVE_WORKLOADS=cache WETASK_LIVE_CACHE_OPS=10000 \
WETASK_LIVE_CACHE_CONCURRENCY=64 \
  node scripts/benchmark-phase9-live-http.mjs

go run ./examples/go-client/cache-pipeline-benchmark \
  -address 127.0.0.1:38080 -sizes 10,100,1000 \
  -concurrency 1,16 -iterations 100 -json

WETASK_HTTP_BASE=http://127.0.0.1:38081 \
WETASK_GRPC_ADDRESS=127.0.0.1:38080 \
WETASK_PIPELINE_ITERATIONS=100 WETASK_MATRIX_TASK_OPS=200 \
  ./scripts/benchmark-release-matrix.sh \
  /tmp/wetask-redis-comparison-20260725/release-matrix

PATH=/tmp/wetask-bench-venv/bin:/usr/local/go/bin:/opt/homebrew/bin:/usr/bin:/bin \
WETASK_PHASE9_BENCHTIME=5s WETASK_PHASE9_COMPETITOR_OPS=10000 \
WETASK_PHASE9_REDIS_URL=redis://127.0.0.1:6380/0 \
WETASK_PHASE9_CELERY_BROKER_URL=redis://127.0.0.1:6380/0 \
WETASK_PHASE9_REQUIRE_COMPETITORS=1 \
  ./scripts/benchmark-phase9-competitive.sh \
  /tmp/wetask-redis-comparison-20260725/competitive-documented-full

/tmp/wetask-redis-comparison-20260725/network-compare/network-compare \
  -wetask 127.0.0.1:38080 -redis 127.0.0.1:6380 \
  -unary-iterations 1000 -pipeline-iterations 100 \
  -queue-iterations 500 -warmup 25

Limitations and conclusion

In-process Go numbers are implementation baselines and must not be compared directly with network Redis numbers.
Redis persistence was disabled. This is appropriate for a cache-path speed baseline but not equivalent to a durable task broker.
WeTask used standalone mode with consensus disabled. No clustered Redis, WeTask replication, cross-host latency, TLS/auth, eviction pressure, permanent-node loss, or multi-tenant load was benchmarked.
The machine was not lab-isolated, Docker shared four CPUs, and most cells have one recorded sample. Pipeline cells have three trials and report medians.
WeTask remains technically functional and error-free in this local run, but Redis has a clear cache/pipeline performance advantage here. These results do not remove the integration blocker: the published WeTask release still needs a supported Python worker/execution bridge before it can replace Celery workers.

Wetask: a unified runtime for distributed tasks, scheduling, and caching

Tosiiko — Sat, 11 Jul 2026 07:09:54 +0000

Today I’m releasing Wetask v0.1.0-rc.1, the first public release candidate of a system I’ve been building in Go.

Wetask combines several backend responsibilities into one deployable runtime:

Distributed task execution
Scheduled jobs
Integrated caching
Durable queue recovery
High availability and leader election
Health checks, metrics, administration, and operational tooling

The goal is straightforward: reduce the number of separate components teams need to operate for background jobs, scheduling, caching, and failover.

Current release status

This is a controlled pilot release candidate, not yet a general-availability enterprise release.

The release includes compiled binaries for:

Linux amd64 and arm64
macOS Intel and Apple Silicon
Windows amd64

The implementation source remains private. The public repository contains only compiled releases, installation tooling, checksums, licenses, and package metadata.

Install Wetask

On macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/tosiiko/wetask-releases/main/install.sh \
  | sh -s -- --yes --version v0.1.0-rc.1

The installer detects the operating system and architecture, downloads the appropriate archive, and verifies its SHA-256 checksum before installation.
You can also download the archives directly:
https://github.com/tosiiko/wetask-releases/releases/tag/v0.1.0-rc.1
Reliability work
Before this release, I ran unit, integration, race, chaos, upgrade, recovery, load, and direct client-pipeline tests.
The direct gRPC pipeline benchmark processed 8,991,000 mixed cache operations with zero client errors. Peak throughput reached approximately 753,000 operations per second in a container-local benchmark.
I also fixed and regression-tested a lock-order deadlock affecting concurrent durable task submission and result waiting.
What comes next
The next milestones are:
A dedicated Homebrew tap
Multi-architecture container publishing
Secured three-node staging validation
Live failover and restore exercises
Feedback from controlled production pilots
If you test Wetask, installation problems and reproducible binary issues can be reported through the public repository. Please use private vulnerability reporting for security issues.
Release:
https://github.com/tosiiko/wetask-releases/releases/tag/v0.1.0-rc.1
I’d especially value feedback from teams operating task queues, schedulers, caching systems, or combinations of those components.

I built Wetask: a unified runtime for distributed tasks, scheduling, and caching

Tosiiko — Sat, 11 Jul 2026 07:07:51 +0000

Today I’m releasing Wetask v0.1.0-rc.1, the first public release candidate of a system I’ve been building in Go.

Wetask combines several backend responsibilities into one deployable runtime:

Distributed task execution
Scheduled jobs
Integrated caching
Durable queue recovery
High availability and leader election
Health checks, metrics, administration, and operational tooling

The goal is straightforward: reduce the number of separate components teams need to operate for background jobs, scheduling, caching, and failover.

Current release status

This is a controlled pilot release candidate, not yet a general-availability enterprise release.

The release includes compiled binaries for:

Linux amd64 and arm64
macOS Intel and Apple Silicon
Windows amd64

The implementation source remains private. The public repository contains only compiled releases, installation tooling, checksums, licenses, and package metadata.

Install Wetask

On macOS or Linux:


bash
curl -fsSL https://raw.githubusercontent.com/tosiiko/wetask-releases/main/install.sh \
  | sh -s -- --yes --version v0.1.0-rc.1

Every MDL behavior attribute for htmx and TypeScript

Tosiiko — Thu, 11 Jun 2026 21:46:16 +0000

MDL has two small behavior paths:

MDL behavior attributes -> htmx hx-* output
MDL event attributes    -> exported JavaScript or TypeScript handlers

That means the source can stay compact:

form@api(post /api/profile)@result(profileResult)@swap(replace)@trigger(submit)@loading(profileBusy):
  .input@id(profileName)@name(name)@required
  .btn-primary@type(submit)(Save)
  status@id(profileBusy):
    Saving.

With the htmx adapter enabled, MDL emits validated htmx attributes:

<form
  class="mdl-form"
  hx-post="/api/profile"
  hx-target="#profileResult"
  hx-swap="outerHTML"
  hx-trigger="submit"
  hx-indicator="#profileBusy">
</form>

And with configured JavaScript or TypeScript modules, event attributes call
exported functions by name:

card@id(plannerPanel)@mount(mountPlanner):
  .btn-primary@click(addTask)(Add task)

export function mountPlanner(element: HTMLElement) {
  element.dataset.ready = "true";
}

export function addTask(event: MouseEvent) {
  event.preventDefault();
}

Enable the htmx adapter

Configure htmx as the behavior adapter in mdl.json:

{
  "head_scripts": [
    "https://cdn.jsdelivr.net/npm/htmx.org@2.0.10/dist/htmx.min.js"
  ],
  "behavior": {
    "adapter": "htmx",
    "version": "2"
  }
}

MDL source should use MDL behavior attributes such as @api(...),
@result(...), and @swap(...). Raw @hx-post(...), @hx-target(...), and
other raw htmx attributes are not emitted.

htmx behavior attribute map

These are the MDL behavior attributes supported by the htmx adapter.

MDL attribute	htmx output	Example
`@api(get /api/search)`	`hx-get="/api/search"`	`get`, `post`, `put`, `patch`, `delete`
`@result(searchResults)`	`hx-target="#searchResults"`	Targets `this`, `id`, `#id`, or `.class`
`@swap(inner)`	`hx-swap="innerHTML"`	See swap values below
`@trigger(input)`	`hx-trigger="input"`	Uses a known trigger event
`@loading(searchBusy)`	`hx-indicator="#searchBusy"`	Also accepts `this` or `#id`
`@confirm(Save changes?)`	`hx-confirm="Save changes?"`	Plain text prompt, max 200 chars
`@include(csrfToken)`	`hx-include="#csrfToken"`	Also accepts `this` or `#id`
`@select(resultFragment)`	`hx-select="#resultFragment"`	Selects one response fragment
`@select-oob(toast)`	`hx-select-oob="#toast"`	Selects one out-of-band fragment
`@swap-oob(true)`	`hx-swap-oob="true"`	Also accepts known swap values
`@push(false)`	`hx-push-url="false"`	`true`, `false`, or safe root path
`@replace(/profile)`	`hx-replace-url="/profile"`	`true`, `false`, or safe root path
`@history(false)`	`hx-history="false"`	`true` or `false`
`@history-elt(true)`	`hx-history-elt="true"`	Emits only for `true`
`@boost(true)`	`hx-boost="true"`	Only on safe local links/forms
`@disabled(saveButton)`	`hx-disabled-elt="#saveButton"`	Also accepts `this` or `#id`
`@disinherit(target swap)`	`hx-disinherit="hx-target hx-swap"`	Allows known htmx attrs or `*`
`@encoding(multipart)`	`hx-encoding="multipart/form-data"`	Also supports urlencoded form encoding
`@inherit(trigger)`	`hx-inherit="hx-trigger"`	Allows known htmx attrs
`@params(name email)`	`hx-params="name,email"`	Explicit names or `none`
`@preserve(true)`	`hx-preserve="true"`	Requires a safe `@id(...)`
`@prompt(Security code?)`	`hx-prompt="Security code?"`	Plain text prompt, max 200 chars
`@request(timeout=5000)`	`hx-request="{"timeout":5000}"`	Timeout from `1` to `60000` ms
`@sync(profileForm:queue-last)`	`hx-sync="#profileForm:queue last"`	Coordinates concurrent requests
`@validate(true)`	`hx-validate="true"`	`true` or `false`

Supported `@api(...)` methods

get
post
put
patch
delete

@api(...) only emits same-origin-safe paths. External API URLs are not
emitted from this attribute.

Supported `@swap(...)` values

MDL gives short names to the htmx swap values:

MDL	htmx
`inner`	`innerHTML`
`inner-html`	`innerHTML`
`innerhtml`	`innerHTML`
`replace`	`outerHTML`
`outer`	`outerHTML`
`outer-html`	`outerHTML`
`outerhtml`	`outerHTML`
`append`	`beforeend`
`prepend`	`afterbegin`
`before`	`beforebegin`
`after`	`afterend`
`none`	`none`

@swap-oob(...) supports true plus the same known swap values. false is not
emitted for @swap-oob(...).

Supported `@trigger(...)` values

submit
click
change
input
load
revealed
intersect
keyup
keydown
focus
blur
mouseenter
mouseleave

MDL intentionally does not emit htmx trigger filters or JavaScript-like trigger
expressions from @trigger(...).

Supported `@encoding(...)` values

multipart
multipart/form-data
form
urlencoded
application/x-www-form-urlencoded

These normalize to either multipart/form-data or
application/x-www-form-urlencoded.

Supported `@sync(...)` strategies

drop
abort
replace
queue
queue-first
queue-last
queue-all

You can pass the strategy by itself:

form@sync(queue-last):

Or scope it to one explicit target:

form@sync(profileForm:queue-last):

Supported `@inherit(...)` and `@disinherit(...)` names

These attributes accept MDL names or htmx names. MDL normalizes them to htmx
attribute names.

target / result       -> hx-target
swap                  -> hx-swap
trigger               -> hx-trigger
indicator / loading   -> hx-indicator
confirm               -> hx-confirm
include               -> hx-include
select                -> hx-select
select-oob            -> hx-select-oob
swap-oob              -> hx-swap-oob
push / push-url       -> hx-push-url
replace / replace-url -> hx-replace-url
history               -> hx-history
history-elt           -> hx-history-elt
boost                 -> hx-boost
disabled / disabled-elt -> hx-disabled-elt
disinherit            -> hx-disinherit
encoding              -> hx-encoding
inherit               -> hx-inherit
params                -> hx-params
preserve              -> hx-preserve
prompt                -> hx-prompt
request               -> hx-request
sync                  -> hx-sync
validate              -> hx-validate
get                   -> hx-get
post                  -> hx-post
put                   -> hx-put
patch                 -> hx-patch
delete                -> hx-delete

@disinherit(*) is also supported. @inherit(*) is not.

Configure TypeScript handlers

MDL scripts can point at JavaScript or TypeScript module entries:

{
  "scripts": [
    "scripts/app.ts"
  ]
}

During mdl build, MDL compiles local .ts module scripts to browser-ready
JavaScript:

scripts/app.ts -> dist/scripts/app.js

The generated HTML imports the JavaScript URL:

<script type="module">
import * as mdlModule0 from "./scripts/app.js";
</script>

During mdl serve, the browser still asks for ./scripts/app.js, and the dev
server serves JavaScript compiled from scripts/app.ts.

Configured TypeScript entries can import local TypeScript trees:

scripts/app.ts
scripts/state/store.ts
scripts/dom/render.ts
scripts/utils/format.ts

MDL preserves the folder tree in output:

dist/scripts/app.js
dist/scripts/state/store.js
dist/scripts/dom/render.js
dist/scripts/utils/format.js

Local TypeScript imports may use .ts, omit the extension, or use the
browser-facing .js extension:

import { snapshot } from "./state/store.ts";
import { renderTaskList } from "./dom/render.js";
import { formatCount } from "./utils/format";
import type { Task } from "./state/model.ts";

MDL does not create package.json, node_modules, or tsconfig.json for this.
It is transpile-only behavior support, not a bundler or project type checker.

Inline TypeScript blocks are not supported yet:

script ts:
  // not supported yet

Use inline JavaScript:

script js:
  document.body.dataset.ready = "true"

Or an external configured .ts module.

TypeScript event attributes

Event attributes compile to data-mdl-on-* markers, and MDL's generated module
runtime calls exported handlers by name.

form@submit(createTaskFromForm):
  .input@input(updateDraftPreview)
  .btn-primary@click(saveTask)(Save)

canvas@id(scene)@mount(drawScene):

<form class="mdl-form" data-mdl-on-submit="createTaskFromForm">
  <input class="mdl-input" data-mdl-on-input="updateDraftPreview">
  <button class="mdl-btn-primary" data-mdl-on-click="saveTask">Save</button>
</form>
<canvas class="mdl-canvas" id="scene" data-mdl-on-mount="drawScene"></canvas>

@mount(handler) is not a browser event. It runs once after configured modules
are imported and receives the mounted element.

All other handlers receive the browser event.

Complete event alias list

These event attributes can be handled from JavaScript or TypeScript modules:

@click              @dblclick           @auxclick          @contextmenu
@command
@submit             @reset              @formdata          @beforeinput
@input              @change             @invalid           @search
@select
@compositionstart   @compositionupdate  @compositionend
@focus              @blur               @focusin           @focusout
@keydown            @keypress           @keyup
@mousedown          @mouseup            @mousemove         @mouseover
@mouseout           @mouseenter         @mouseleave
@pointerdown        @pointerup          @pointermove       @pointerover
@pointerout         @pointerenter       @pointerleave      @pointercancel
@pointerrawupdate   @gotpointercapture  @lostpointercapture
@touchstart         @touchmove          @touchend          @touchcancel
@wheel              @scroll             @scrollend
@load               @error              @abort             @resize
@canplay            @canplaythrough     @play              @playing
@pause              @ended              @durationchange    @emptied
@loadeddata         @loadedmetadata     @loadstart         @progress
@ratechange         @seeked             @seeking           @stalled
@suspend            @timeupdate         @volumechange      @waiting
@dragstart          @drag               @dragenter         @dragover
@dragleave          @drop               @dragend
@copy               @cut                @paste
@cuechange          @slotchange
@toggle             @beforetoggle       @beforematch       @close
@cancel             @contextlost        @contextrestored
@securitypolicyviolation
@fullscreenchange   @fullscreenerror
@animationstart     @animationiteration @animationend      @animationcancel
@transitionrun      @transitionstart    @transitioncancel  @transitionend

TypeScript handler example

form@id(taskForm)@submit(createTaskFromForm):
  .input@id(taskTitle)@name(title)@type(text)@required@input(updateDraftPreview)
  .btn-primary@type(submit)(Add task)

card@id(plannerPanel)@mount(mountPlanner):
  status@id(boardStatus)@aria-live(polite):
    Waiting for TypeScript.

export function mountPlanner(element: HTMLElement) {
  element.dataset.ready = "true";
}

export function createTaskFromForm(event: SubmitEvent) {
  event.preventDefault();

  const form = event.currentTarget;
  if (!(form instanceof HTMLFormElement)) return;

  const data = new FormData(form);
  const title = String(data.get("title") ?? "").trim();
  if (!title) return;

  // Update app state, then render.
}

export function updateDraftPreview(event: Event) {
  const input = event.currentTarget;
  if (!(input instanceof HTMLInputElement)) return;

  const preview = document.querySelector("#draftPreview");
  if (preview) preview.textContent = input.value;
}

General MDL attribute rules

Normal HTML attributes are still direct:

.input@id(email)@name(email)@type(email)@required@autocomplete(email)

That emits:

<input class="mdl-input" id="email" name="email" type="email" required autocomplete="email">

The core rules are:

@attr(value) emits attr="value".
@attr emits a boolean attribute.
@class(...) appends author classes after the generated mdl-* class.
Raw browser event attributes such as @onclick(...) are not emitted.
Raw htmx attributes such as @hx-post(...) are not emitted.
Inline @style(...) and iframe @srcdoc(...) are not emitted.
URL attributes are filtered to safe URL shapes.

The reason is boring in the best way: MDL keeps authoring short, but the output
should remain inspectable and hard to accidentally turn into a script sink.

Try the examples

The htmx example app:

node examples/htmx/server.mjs
target/debug/mdl serve examples/htmx

Open:

http://127.0.0.1:4010

The TypeScript example:

cd examples/typescript
../../bin/mdl serve

Open:

http://127.0.0.1:3996

MDL 0.1.9: optional TypeScript behavior scripts without a TypeScript project setup

Tosiiko — Thu, 11 Jun 2026 20:19:47 +0000

MDL 0.1.9 adds optional external TypeScript behavior scripts.

The important word is optional.

MDL is still:

.mdl  -> structure and content
.css  -> layout and design
.js   -> optional behavior
HTML  -> compiler output

This release does not turn MDL into a JavaScript-app workflow. It does not make
TypeScript a requirement for normal MDL sites. It simply means that if you want
typed behavior modules, MDL can compile local .ts files for the browser during
build and serve.

What changed

Before this release, an MDL project config could include JavaScript module
scripts:

{
  "scripts": [
    "scripts/app.js"
  ]
}

mdl build copied those files unchanged, and generated HTML imported them as
module scripts.

In 0.1.9, the same scripts array can also point at a local TypeScript entry:

{
  "scripts": [
    "scripts/app.ts"
  ]
}

During mdl build, MDL transpiles that entry to JavaScript:

scripts/app.ts -> dist/scripts/app.js

The generated document imports the browser-ready JavaScript URL:

<script type="module">
import * as mdlModule0 from "./scripts/app.js";
</script>

During mdl serve, the page still imports ./scripts/app.js. The dev server
serves that compiled JavaScript from the configured TypeScript source, so the
development URL matches the production URL.

TypeScript trees are supported

The first pass is not limited to a single file. A configured TypeScript entry
can import other local TypeScript modules:

scripts/app.ts
scripts/state/store.ts
scripts/state/model.ts
scripts/dom/forms.ts
scripts/dom/render.ts
scripts/utils/id.ts

MDL follows the local static import/export graph, preserves the folder tree, and
emits matching JavaScript modules:

dist/scripts/app.js
dist/scripts/state/store.js
dist/scripts/state/model.js
dist/scripts/dom/forms.js
dist/scripts/dom/render.js
dist/scripts/utils/id.js

Local TypeScript imports may use .ts, omit the extension, or use the
browser-facing .js extension. MDL rewrites local TypeScript module specifiers
to emitted .js URLs.

For example, this is valid in source:

import { snapshot } from "./state/store.ts";
import { renderTaskList } from "./dom/render.js";
import { byId } from "./dom/query";
import type { TaskFilter } from "./state/model.ts";

The emitted JavaScript uses browser-safe JavaScript module URLs for the local
TypeScript files.

Type-only imports stay type-only. They do not become runtime dependencies.

What MDL does not do

This is transpile-only support for behavior modules.

MDL does not:

scaffold package.json
create node_modules
create tsconfig.json
require users to install TypeScript
require deployed sites to carry TypeScript
bundle npm packages
type-check the project yet

Bare package imports and external URLs are left alone. MDL is not trying to be
a bundler in this release.

The TypeScript parser/transpiler lives inside MDL tooling, so a site can use a
configured .ts behavior module without becoming a TypeScript project.

Inline scripts stay JavaScript for now

Inline JavaScript blocks keep working:

script js:
  const form = document.querySelector("#loginForm")
  form?.classList.add("ready")

Inline TypeScript is still unsupported:

script ts:
  // not supported yet

For TypeScript, use an external configured module:

{
  "scripts": [
    "scripts/app.ts"
  ]
}

Event bindings still work the same way

Full-document MDL output imports configured modules and binds exported functions
to MDL behavior attributes:

form@id(taskForm)@submit(createTaskFromForm):
  .input@id(taskTitle)@name(title)@type(text)@input(updateDraftPreview)
  .btn-primary@type(submit)(Add task)

card@id(plannerPanel)@mount(mountPlanner):
  status@id(boardStatus):
    Waiting for the TypeScript module tree.

Your TypeScript module exports the handlers:

export function mountPlanner(element: HTMLElement) {
  element.dataset.ready = "true";
  refresh("Planner mounted from compiled TypeScript.");
}

export function createTaskFromForm(event: SubmitEvent) {
  event.preventDefault();
  // read the form, update state, re-render
}

export function updateDraftPreview(event: Event) {
  // update live preview while the user types
}

MDL handles the wiring. The browser receives JavaScript modules.

New example: `examples/typescript`

This release adds a more advanced TypeScript example:

examples/typescript

It is a small typed task planner with:

a configured scripts/app.ts entry
nested state, DOM, and utility modules
import type usage
imports that use .ts, .js, and extensionless specifiers
@mount, @submit, @input, @change, and @click handlers
dashboard metrics
task filters
form parsing
toast updates
generated dist/scripts/*.js output

Run it:

cd examples/typescript
../../bin/mdl serve

Open:

http://127.0.0.1:3996

Build it:

../../bin/mdl build

The example intentionally has no package.json, no node_modules, and no
tsconfig.json.

Why this shape?

I want MDL to keep a narrow architecture:

MDL source + CSS + optional behavior scripts -> static browser output

Some pages only need HTML and CSS. Some need a little inline JavaScript. Some
need external JavaScript modules. And some behavior is easier to maintain with
TypeScript types.

0.1.9 supports that last case without changing the default model.

The output is still plain browser assets. The project is still inspectable. The
site is still deployable as static files.

Try MDL

Install locally in a project:

mkdir my-mdl-site
cd my-mdl-site
npm install @tosiiko/mdl
npm exec -- mdl init
source bin/activate
mdl serve

Or install globally:

npm install -g @tosiiko/mdl
mdl new my-mdl-site
cd my-mdl-site
mdl serve

Useful commands:

mdl check
mdl format --check
mdl build
mdl serve

Links

Website: https://getmdl.site
Repository: https://github.com/tosiiko/mdl-code
npm package: https://www.npmjs.com/package/@tosiiko/mdl
TypeScript example: examples/typescript
Script spec: docs/spec/SCRIPTS.md

MDL is still early, but 0.1.9 makes optional behavior code easier to grow:
JavaScript still works exactly as before, TypeScript can live in local external
modules, and deployed sites only need the compiled JavaScript.

MDL 0.1.8: htmx examples, safer npm binaries, and portable static builds

Tosiiko — Sat, 06 Jun 2026 11:53:19 +0000

MDL 0.1.8 is a release focused on two things:

Making hypermedia workflows easier to see and copy.
Making the npm CLI package easier to inspect and trust.

MDL is a small authoring language for building clean HTML without writing raw
HTML by hand. You write .mdl files, regular CSS, and optional JavaScript; the
CLI checks, builds, and serves the project.

.mdl  -> structure and content
.css  -> layout and design
HTML  -> compiler output

New: Complete htmx Example App

This release adds a complete htmx example under:

examples/htmx

The app demonstrates MDL behavior attributes compiled through the htmx
adapter. Instead of writing raw hx-* attributes in MDL source, you describe
the intent:

form@api(get /api/search)@result(searchResults)@swap(inner)@trigger(input)@loading(searchBusy):
  field:
    label@for(searchQuery):
      Search cookbook entries
    .input@id(searchQuery)@name(q)@type(search)@placeholder(Type card, form, swap, or history)
  status@id(searchBusy)@class(indicator):
    Searching.

With the htmx adapter enabled, MDL emits the corresponding hx-* output:

<form
  class="mdl-form"
  hx-get="/api/search"
  hx-target="#searchResults"
  hx-swap="innerHTML"
  hx-trigger="input"
  hx-indicator="#searchBusy">
</form>

The example app includes:

live search
todo list swaps
cart updates
profile form validation
out-of-band toast updates
request indicators
disabled submit buttons
parameter filtering
request timeouts
sync behavior
prompted requests
preserved islands
boosted safe forms

Run the API server:

node examples/htmx/server.mjs

In another terminal:

target/debug/mdl serve examples/htmx

Then open:

http://127.0.0.1:4010

The example uses htmx 2.0.10 from a pinned CDN URL in mdl.json, and you can
vendor that script locally if you want an offline demo.

Behavior Adapters

MDL now has a clearer adapter story:

{
  "behavior": {
    "adapter": "htmx",
    "version": "2"
  }
}

Supported behavior adapters are:

static: normal HTML behavior where possible.
mdl: data-mdl-api-* attributes for future MDL runtimes.
htmx: validated hx-* output for htmx v2.

The important bit is that MDL source stays framework-neutral. You write
attributes such as:

@api(post /api/profile)
@result(profileResult)
@swap(replace)
@trigger(submit)
@loading(profileBusy)
@select-oob(toast)
@request(timeout=5000)
@sync(profileForm:queue-last)
@validate(true)

The adapter decides how that intent becomes HTML.

Safer npm Package

The npm package is also hardened in this release.

@tosiiko/mdl ships a small Node launcher and prebuilt Rust binaries for
supported platforms. That is convenient, but native binaries deserve a clear
audit trail.

0.1.8 adds:

SECURITY.md in the npm package
BINARY-PROVENANCE.md in the npm package
SHASUMS256.txt in the staged public package
runtime checksum verification before executing the selected binary
explicit shell: false process spawning in the launcher
provenance-enabled GitHub publishing with npm publish --provenance

The package still has:

no runtime npm dependencies
no npm lifecycle or install scripts
no install-time binary downloads
no runtime binary downloads

The launcher selects a binary from vendor/<platform>/, verifies its SHA-256
checksum when SHASUMS256.txt is present, and only then starts the CLI.

Portable Static Builds

This release also includes routing.links in mdl.json.

Use root links when deploying from a site root:

{
  "routing": {
    "links": "root"
  }
}

Use relative links when publishing dist/ under a subfolder or opening the
generated files directly:

{
  "routing": {
    "links": "relative"
  }
}

Relative mode rewrites local page and asset links so the output is easier to
move between static hosts.

Try MDL

Install locally in a project:

mkdir my-mdl-site
cd my-mdl-site
npm install @tosiiko/mdl
npm exec -- mdl init
source bin/activate
mdl serve

Or install globally:

npm install -g @tosiiko/mdl
mdl new my-mdl-site
cd my-mdl-site
mdl serve

Useful commands:

mdl check
mdl format --check
mdl build
mdl serve

Links

Website: https://getmdl.site
Repository: https://github.com/tosiiko/mdl-code
npm package: https://www.npmjs.com/package/@tosiiko/mdl
htmx examples: examples/htmx

MDL is still early, but 0.1.8 makes the project much easier to evaluate: you
can inspect the generated HTML, run a real htmx example, check the package
contents, and build static output that fits more hosting setups.

# Next MDL Update: Security-First Adapters and HTMX Support

Tosiiko — Sat, 06 Jun 2026 09:35:46 +0000

In the last update, I introduced MDL as an HTML-first language for building websites and apps with less noise.

This update is about the next layer: adapters.

The goal is simple:

MDL source should describe intent. Adapters decide how that intent becomes deployable HTML.

Why adapters?

I don’t want MDL to become locked into one frontend framework.

Instead, the same MDL structure should be able to target different deployment styles:

static HTML
MDL-native runtime attributes
HTMX
future template or framework adapters

So this:

form@api(post /api/login)@result(loginResult)@swap(replace):
  .input@type(email)@required
  .btn-primary@type(submit)(Sign in)

  status@id(loginResult):
    Waiting.

Can become plain HTML:

html

<form method="post" action="/api/login">

Or HTMX:

html

<form hx-post="/api/login" hx-target="#loginResult" hx-swap="outerHTML">

Security before convenienceThe important part is that MDL does not pass behavior attributes through blindly.
Raw HTMX attributes like this are blocked:

mdl

form@hx-post(/api/login):

Instead, MDL uses intent-based attributes:

mdl

form@api(post /api/login):

Then the adapter validates and translates it.
Current safety rules include:
external api(...) URLs are rejected
raw @hx-* attributes are blocked
raw browser events like onclick(...) are blocked
unsafe URL schemes like javascript: are blocked
broad form inclusion like @params() is blocked
@inherit() is blocked
@disinherit(*) is allowed because disabling inherited behavior is safer
That means MDL can support HTMX without making MDL source depend directly on HTMX’s full raw surface area.
New HTMX adapter attributesThe HTMX v2 adapter now supports more behavior attributes:

mdl

@select-oob(...)
@swap-oob(...)
@disabled(...)
@disinherit(...)
@encoding(...)
@history-elt(...)
@inherit(...)
@params(...)
@preserve(...)
@prompt(...)
@replace(...)
@request(...)
@sync(...)
@validate(...)

Example:

mdl

form@api(post /api/profile)@result(profileResult)@swap(replace)@params(email csrfToken)@disabled(saveButton):
  .input@name(email):
  .input@name(csrfToken):
  .btn-primary@id(saveButton)@type(submit)(Save)

  status@id(profileResult):
    Waiting.

With the HTMX adapter, MDL can emit:

html

<form
  hx-post="/api/profile"
  hx-target="#profileResult"
  hx-swap="outerHTML"
  hx-params="email,csrfToken"
  hx-disabled-elt="#saveButton">

Notice that @params(email csrfToken) is explicit. MDL does not allow @params(*), because accidentally sending extra form fields is exactly the kind of thing a language layer should help prevent.

I Built MDL: A Small Language for Writing Static Websites as Readable Outlines

Tosiiko — Mon, 01 Jun 2026 18:10:50 +0000

HTML is an excellent output format.

As an authoring format, though, it can become noisy when you're building simple documentation sites, landing pages, examples, or other static content.

I wanted something that let me write pages as readable outlines while still producing normal HTML at build time.

So I built MDL.

MDL is a small authoring language that compiles to clean static HTML.

It does not replace HTML, CSS, or JavaScript.

Instead, it sits one step above them and lets you write page structure in a format that is easier to scan and maintain.

What MDL Looks Like

A simple MDL page might look like this:

page:
  hero:
    .badge(New)
    # Build clean static sites

    Write readable page structure,
    then compile to HTML.

    actions:
      .href@href(/docs.html)@class(primary)
      (Read the docs)

  section:
    ## Why MDL?

    Keep content readable.
    Keep styling in CSS.
    Add JavaScript only when behavior belongs.

And it compiles to ordinary HTML:

<main class="mdl-page">
  <div class="mdl-hero">
    <span class="mdl-badge">New</span>
    <h1>Build clean static sites</h1>
  </div>
</main>

The output is intentionally boring.

That is the goal.

No runtime.
No framework lock-in.
No custom browser behavior.

Just static HTML.

Why I Built It

I kept finding myself wanting a format that felt closer to writing a structured note than writing a template.

For many sites I don't need:

Component systems
Hydration
Build-time JavaScript frameworks
Large configuration layers

I just want to describe the page structure clearly and generate predictable HTML.

MDL is my attempt at that.

The Browser Platform Stays Visible

One thing that mattered to me from the start:

CSS is still CSS
JavaScript is still JavaScript
HTML is still the final artifact

MDL is only the authoring layer.

You can inspect the generated pages and immediately understand what is happening.

Getting Started

Install from npm:

mkdir my-mdl-site
cd my-mdl-site

npm install @tosiiko/mdl

npm exec -- mdl init

source bin/activate

mdl serve

Then open:

http://127.0.0.1:3999

CLI Commands

mdl init
mdl new my-site
mdl check
mdl format
mdl build
mdl serve

Recent Improvements

Current release: 0.1.7

Some highlights:

Public documentation site is now live
Improved static hosting support
Routing control via mdl.json
Better package and editor metadata alignment
Expanded documentation
Deployment guidance and examples

Example routing configuration:

{
  "routing": {
    "links": "relative"
  }
}

This makes generated sites work cleanly when hosted under subfolders or served directly as static files.

For root-domain hosting:

{
  "routing": {
    "links": "root"
  }
}

Where I Think MDL Fits

MDL is especially useful for:

Documentation sites
Product pages
Landing pages
Project websites
Examples and demos
Small static sites

If you're already happy writing HTML directly, that's great.

If you've ever wished your page source looked more like an outline and less like markup, MDL might be interesting.

Feedback Welcome

The project is still early and I'm actively improving:

Documentation
Editor support
Templates
Diagnostics
Real-world examples

I'd love feedback from people who enjoy static sites, small tools, Markdown-style authoring, and clean HTML.

Documentation:

Links

Documentation: https://getmdl.site
npm package: https://www.npmjs.com/package/@tosiiko/mdl
GitHub: https://github.com/tosiiko/mdl-code

Package:

npm install @tosiiko/mdl

Questions, criticism, feature requests, and ideas are all welcome.

What's coming in MDL 0.1.3 — source maps, metadata, diagnostics, and more

Tosiiko — Sun, 31 May 2026 18:55:26 +0000

I've been building MDL — a tiny authoring language that compiles to clean HTML. If you haven't seen it yet:

page:
  hero:
    ## Sign in
    Welcome back.

  form@id(loginForm)@submit(handleLogin):
    field:
      label:
        Email
      .input@type(email)@id(email)@required

    actions:
      .btn-primary@id(loginBtn)(Sign in)
      .btn-ghost@click(handleForgot)(Forgot password?)

Compiles to clean, semantic HTML. No angle brackets written by hand. CSS owns all layout. JS handles all logic.

Install: npm install -g @tosiiko/mdl

What's already shipped in 0.1.x

Before getting into what's coming — here's what's already working:

Indentation-based sections that compile to semantic HTML (page: → <main>, nav: → <nav>, form: → <form>)
Full CommonMark Markdown inside every section — headings, lists, tables, code blocks, blockquotes
Dot inline elements — .badge(text), .btn-primary(text), .input@type(email)
Attributes — @id(value), @required, @placeholder(text), @submit(fn), @click(fn)
CSS bundling — multiple CSS files merged into one app.css
JavaScript event wiring — @submit(handleLogin) compiles to a proper addEventListener
Live reload dev server — mdl serve at localhost:3999
Multi-page projects via mdl.json
mdl init and mdl new — scaffold a full project in one command
mdl check and mdl format — lint and auto-format
VS Code extension with syntax highlighting — already on the marketplace
Prebuilt Rust binary distributed via npm — no Rust toolchain needed

That's 0.1. Here's what's coming next.

Source maps

Every compiled HTML page will write a JSON sidecar map:

pages/login.mdl  →  dist/login.html
                 →  dist/login.html.mdlmap.json

The map links every generated HTML element back to the MDL source line that produced it:

{
  "version": 1,
  "source": "pages/login.mdl",
  "output": "login.html",
  "mappings": [
    {
      "generated": { "line": 12, "column": 1, "end_line": 31, "end_column": 8 },
      "source": { "line": 6, "column": 3, "end_line": 6, "end_column": 39 },
      "kind": "section",
      "name": "form"
    }
  ]
}

This unlocks editor navigation, error overlays with exact MDL line and column, and eventually go-to-source from generated HTML back to the .mdl file that produced it — the same way browser source maps let you debug TypeScript instead of compiled JS.

A project-level dist/mdl-manifest.json links every route to its source and source map:

{
  "route": "/login",
  "source": "login.mdl",
  "output": "login.html",
  "source_map": "login.html.mdlmap.json"
}

Document metadata

Right now metadata lives in mdl.json. The next release formalises and extends this with a complete metadata system:

{
  "lang": "en",
  "title": "My Site",
  "description": "A small MDL site.",
  "canonical": "https://example.com/",
  "favicon": "assets/favicon.svg",
  "social": {
    "enabled": true,
    "image": "assets/social-card.png",
    "twitter_site": "@mysite"
  }
}

The social preset derives Open Graph and Twitter card tags automatically from title, description, and canonical. One config, full social sharing coverage:

<meta property="og:title" content="My Site">
<meta property="og:description" content="A small MDL site.">
<meta property="og:image" content="assets/social-card.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@mysite">

mdl check validates all local file references — favicon, social image, manifest links — at build time, not when a user finds a broken image in production.

Better diagnostics

mdl check is getting significantly smarter. The next release adds:

Accessibility checks:

Missing alt on images
Missing title on iframes
Duplicate IDs
Unlabeled form controls
Invalid or empty aria-* attributes
Missing ARIA references
Landmark ordering issues

Form checks:

Label and input pairing mistakes
Missing label targets
Ungrouped radio buttons
Missing autocomplete hints

Asset checks:

Broken .link() and .href() targets
Missing local images and media files
Recursive CSS url() and @import validation
Font file references

Machine-readable output:

mdl check --json

Outputs structured diagnostics with 1-based line and column ranges — ready for editor integrations, CI pipelines, and language server consumers.

Multi-app workspaces

One install, multiple apps:

mdl init --app admin --port 4001
mdl serve apps/admin

Each app owns its own mdl.json, pages, CSS, and scripts. They share the same MDL install and environment. Useful for projects with a public site and a separate admin panel, or a marketing page and a docs site.

Advanced browser primitives

The next release adds first-class MDL sections for:

canvas:      →  <canvas>   WebGL, charts, custom drawing
frame:       →  <iframe>   embedded content
picture:     →  <picture>  responsive images
progress:    →  <progress> loading bars
meter:       →  <meter>    scalar measurements
template:    →  <template> inert DOM templates
slot:        →  <slot>     web component slots
island:      →  <div>      hydrated JS island host
component:   →  <div>      custom component host

With @mount(handler) wiring for JS initialisation:

canvas@id(scene)@mount(drawScene):

Compiles to a <canvas> that calls drawScene() from your configured scripts on mount.

What I'm building toward

MDL's goal is simple: you should be able to build a complete, production-quality web page without writing a single HTML tag. Structure in .mdl. Design in .css. Logic in .js. The compiler handles everything else.

The next release gets closer to that by making the tooling smarter — better errors, better source maps, better metadata, better workspace support.

Try it now

npm install -g @tosiiko/mdl
mdl new my-site
cd my-site
mdl serve

npm — https://www.npmjs.com/package/@tosiiko/mdl/v/0.1.2
VS Code — https://marketplace.visualstudio.com/items?itemName=MDLLanguageSupport.mdl-language
GitHub — https://github.com/tosiiko/mdl-code

Would love to hear what you think — and what you'd want to see in MDL before you'd use it on a real project.

npm i @tosiiko/mdl

Tosiiko — Sat, 30 May 2026 10:44:07 +0000

The parser is written in Rust using pulldown-cmark for Markdown. It ships as a prebuilt binary via npm so no Rust toolchain is needed.

npm: https://www.npmjs.com/package/@tosiiko/mdl/v/0.1.2
VS Code: https://marketplace.visualstudio.com/items?itemName=MDLLanguageSupport.mdl-language
GitHub: https://github.com/tosiiko/mdl-code

I built MDL — a tiny authoring language so you never write raw HTML again

Tosiiko — Sat, 30 May 2026 10:35:39 +0000

The problem

Every web project starts the same way. You open a blank file and start typing angle brackets.

HTML is fine. But writing it by hand is noisy, repetitive, and forces you to think about tags instead of content.

What I built

MDL (Markdown Language) is a tiny authoring language that compiles to clean, semantic HTML.

The idea is three rules:

.mdl files handle structure and content
.css files handle layout and design
.js files handle logic

You never write a single HTML tag.

What it looks like

page:
  hero:
    ## Sign in
    Welcome back.

  form@id(loginForm)@submit(handleLogin):
    field:
      label:
        Email
      .input@type(email)@id(email)@required

    actions:
      .btn-primary@id(loginBtn)(Sign in)
      .btn-ghost@click(handleForgot)(Forgot password?)

That compiles to:

<main class="mdl-page">
  <div class="mdl-hero">
    <h2>Sign in</h2>
    <p>Welcome back.</p>
  </div>
  <form class="mdl-form" id="loginForm" data-mdl-on-submit="handleLogin">
    <div class="mdl-field">
      <label class="mdl-label">Email</label>
      <input class="mdl-input" type="email" id="email" required>
    </div>
    <div class="mdl-actions">
      <button class="mdl-btn-primary" id="loginBtn">Sign in</button>
      <button class="mdl-btn-ghost" data-mdl-on-click="handleForgot">Forgot password?</button>
    </div>
  </form>
</main>

Clean, semantic HTML. No divs you didn't ask for. No inline styles. Every element has a predictable .mdl-* class that CSS can target.

How CSS and JS talk to it

CSS targets .mdl-* classes directly. No configuration needed.

JS uses standard DOM APIs. The @id() attribute compiles to a real HTML id. The @submit() and @click() attributes wire events to functions in your external JS file.

// scripts/auth.js
export async function handleLogin(e) {
  e.preventDefault()
  const email = document.querySelector('#email').value
  // your logic here
}

No framework. No runtime. No magic. Just the platform.

How to install

npm install -g @tosiiko/mdl
mdl --help

The CLI is a prebuilt Rust binary. Fast, no dependencies, works on Mac, Linux, and Windows.

DEV Community: Tosiiko

Wetask Is Opening Its Task Runtime to External Workers

Bring your own workers

Fencing matters more than another Ack endpoint

Durable and idempotent settlement

Benchmarks

In-memory lifecycle

Durable lifecycle

How Wetask compares

RabbitMQ quorum queues

NATS JetStream

AWS SQS and Google Cloud Pub/Sub

Apache Kafka

Celery with RabbitMQ

Temporal

Where Wetask fits

Availability

WeTask v0.1.0-rc.1 vs Redis benchmark report

Outcome

Environment

Controlled network cache results

Controlled mixed pipeline results

Queue-ingress probes

WeTask-only documented benchmark coverage

Reproducible commands

Limitations and conclusion

Wetask: a unified runtime for distributed tasks, scheduling, and caching

Current release status

Install Wetask

I built Wetask: a unified runtime for distributed tasks, scheduling, and caching

Current release status

Install Wetask

Every MDL behavior attribute for htmx and TypeScript

Enable the htmx adapter

htmx behavior attribute map

Supported @api(...) methods

Supported @swap(...) values

Supported @trigger(...) values

Supported @encoding(...) values

Supported @sync(...) strategies

Supported @inherit(...) and @disinherit(...) names

Configure TypeScript handlers

TypeScript event attributes

Complete event alias list

TypeScript handler example

General MDL attribute rules

Try the examples

Links

MDL 0.1.9: optional TypeScript behavior scripts without a TypeScript project setup

What changed

TypeScript trees are supported

What MDL does not do

Inline scripts stay JavaScript for now

Event bindings still work the same way

New example: examples/typescript

Why this shape?

Try MDL

Links

MDL 0.1.8: htmx examples, safer npm binaries, and portable static builds

New: Complete htmx Example App

Behavior Adapters

Safer npm Package

Portable Static Builds

Try MDL

Links

# Next MDL Update: Security-First Adapters and HTMX Support

Why adapters?

I Built MDL: A Small Language for Writing Static Websites as Readable Outlines

What MDL Looks Like

Why I Built It

The Browser Platform Stays Visible

Getting Started

CLI Commands

Recent Improvements

Where I Think MDL Fits

Feedback Welcome

Links

What's coming in MDL 0.1.3 — source maps, metadata, diagnostics, and more

What's already shipped in 0.1.x

Source maps

Supported `@api(...)` methods

Supported `@swap(...)` values

Supported `@trigger(...)` values

Supported `@encoding(...)` values

Supported `@sync(...)` strategies

Supported `@inherit(...)` and `@disinherit(...)` names

New example: `examples/typescript`