The examples, and what each one is for
There are twenty-six programs in examples/. All of them
pass zdc check and produce a bundle from zdc build.
STATUS.md also has a table of these files. It is a different document on
purpose: it records what the compiler manages, file by file, as evidence.
This one is ordered by what you want to learn, which is not the same
order and rarely the same sentence.
Every example is a working program. Run any of them:
./target/release/zdc build examples/guestbook.zd -o dist
Start here
Three files, in this order, and you will have seen the whole idea.
| File | What it teaches |
|---|---|
hello.zd | The smallest program there is: one piece of client state, one view. No build config, no bundler entry point, no framework import — the file is the program. |
counter.zd | starting declares state you set directly; from declares state the compiler recomputes. There is no dependency array: doubled re-derives because it reads count, and the compiler knows that from the signal graph. |
guestbook.zd | The whole point of the language in one file. Three placements, no fetch, no API route, no schema, no migration, no deploy config. You declare where state lives and the compiler derives the network. |
If you read only one, read guestbook.zd. It is also the file the README
uses to demonstrate that apiKey reaches no client output — a claim checked
by grepping the built bundle rather than asserted.
Placement: where state lives
The language's one sentence is that placement is a property of state. These are the files where that does the work.
| File | What it teaches |
|---|---|
tally.zd | durable state that is not a counter. guestbook.zd's visits is a Whole, and a store that only ever holds numbers is not much of a store; this is the same three-line story with a Map of Text to Whole, which is the shape most real durable state has. |
writing.zd | The static placement, running. Content is computed at build time and inlined, and the program emits rss.xml into the bundle as a file rather than an endpoint. |
voting-board.zd | A live voting board. Every construct in the language appears here — useful as a reference sheet once the basics are familiar, and dense as a first read. |
Content, routing, and modules
| File | What it teaches |
|---|---|
blog.zd | The static placement reading real files off disk through the build capabilities, then rendering the markdown inside the compiler. Verified to build with an empty PATH, so no toolchain is consulted. |
site.zd | A multi-page site: five URLs out of one program, one emitted document per URL. A route is a choice plus a bijection onto URLs, so when page dispatches exactly as any when does. |
content.zd | The posts site.zd publishes. A module is a unit of naming rather than of deployment, so the static list a route parameter ranges over can live in its own file. |
layout.zd | The two components blog.zd composes its pages out of — a component in one file, the view that uses it in another. |
model.zd | What a module is. Nothing marks a declaration exportable: every top-level declaration is importable, and the importing file decides what it wants by naming it after for. |
Composition and the view
| File | What it teaches |
|---|---|
components.zd | User-defined components and modules. Written before the implementation existed, to test the design — building the compiler against it found four things wrong, all listed at the bottom of the file and corrected there. |
disclosure.zd | Components that render, as opposed to components that only describe. |
page.zd | A page a content site would actually serve. Every element in it was unreachable before the element vocabulary opened up — the language could emit div, span, h2, button and input, so a portfolio could not render a paragraph, a list, an image, or a link. |
events.zd | What a handler receives. on click used to emit a zero-argument arrow: a handler could say that something happened and never what. |
terminal-help.zd | A multi-line text literal, and what it replaces. Ported from a real help command in the portfolio this language is measured against. |
Collections and the standard library
| File | What it teaches |
|---|---|
leaderboard.zd | The pipeline, conditionals, and nested types. Un-writable until the standard library landed. table at player.name yields Option of Whole, because indexing is bounds-checked — unlike TypeScript's unchecked lookup. |
todo.zd | The canonical UI benchmark. It is the acceptance test for type declarations, the membership verbs, and the collection and record literals: every one of them appears in it. |
Algorithms — programs whose answers are not obvious
These compute rather than demonstrate. Each has a working interface, and each
was written partly as evidence about what the language cannot yet do. The
first six are the set STATUS.md counts as the algorithm examples;
dungeon.zd is grouped here because it computes too, but it began as a port
of existing TypeScript rather than as evidence.
| File | What it teaches |
|---|---|
graph-traversal.zd | Depth-first and breadth-first over a declared graph. The first example here whose answer is not obvious from reading it. |
shortest-path.zd | Dijkstra over a weighted graph — and the priority queue that is not there. The cheapest route is not the shortest one, which is why it is a separate file rather than a flag on the last one. |
queens.zd | A backtracking search over a state space, with the state space on the page. |
knapsack.zd | What to take when the bag is too small for everything: eight items, 256 subsets. |
edit-distance.zd | Levenshtein distance, the table it needs, and the two-dimensional structure the language does not have. |
sorting.zd | Two sorts written in the language, beside the one the language provides, all three over the same twenty numbers. |
dungeon.zd | An accumulator that survives across iterations, ported from real TypeScript. |
The edges
| File | What it teaches |
|---|---|
gauge.zd | A foreign that owns a DOM node. Every other example renders through elements the compiler knows; this one hands a <div> to JavaScript and lets it draw, which is the only way a canvas, a chart, a map or a WebGL scene can exist in a ZDeceptron program. |
What the examples are evidence against
Several of these files exist to record a limit rather than a feature, and they say so in their own comments. This is the fastest way to learn where the language currently stops:
shortest-path.zd— there is no heap in the prelude and no way to write one better than a scan, so three linear passes replace a binary heap's one logarithmic one. It says plainly that this is why the graph has seven towns.edit-distance.zd— a dynamic-programming table has to be built in the order the recurrence visits it, and flat, because there was no way to write into an inner list. It caps its inputs at twelve characters for that reason.components.zd— kept as written-before-the-implementation, with the four things the compiler found wrong listed at the bottom.
For the current boundary in one place, see Where it stops in the
README.