# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Entries for unreleased work are not written here directly. Each issue drops a fragment in [`changelog.d/`](https://github.com/riddler/statifier_blocks/blob/v0.35.1/changelog.d/README.md); the fragments are assembled into a version section at release. See that README for the format and for when a change warrants an entry at all. ## [0.44.1] 2026-10-20 Docs release: 0.44.1 changes documentation only. The README is cut to a short introduction with a Basic usage block and a Documentation map, the guides and reference pages that map links are published on HexDocs, and the teaching examples are re-cut to patron registration. No function body, typespec or option changes; apart from the `@compiler_version` string, `lib/` and the stylesheet change only in `@moduledoc` and `@doc` text, doctest literals and comments. No function answers differently from 0.44.0, except that `StatifierBlocks.Compiler.compiler_version/0` answers the new package version and a compiled record carries it as its compiler version. The package gains no Hex dependency. ### Added - New how-to pages: build a block document and compile it to a chart, register your own block types, publish a document, validate a document against the schema from any language, embed the editor in a LiveView host, and mount the Map. Each is in the HexDocs "How-to guides" group. - New reference pages: the config fields and the handlers this package ships, and the editor assigns and host seams. The seam table also lists `Edit.Targets.admits_at?/5` and `accepted_types_at/5`, `Edit.Session.refusal/1`, the 32-character cap on badges and summary chips, and the `event` attr on `config_form/1`. - A cheatsheet for the calls a host makes (the document, the palette, compile, publish and the editor mount), in the "Reference" group. - An explanation page on documents, revisions, charts and executions, and why a document of blocks compiles to a chart, in the "Explanation" group. - The existing pages for flow patterns, migrating documents from 0.27 to 0.34, host validators, profiles, theming, typing a palette and the block-level flow graph are now published on HexDocs, in groups, and the package carries them. ### Changed - The README is now an introduction: what the package is, why it exists, how to install it, one executed Basic usage block, and a Documentation map that links every page under four questions (learn, do, look up, understand). The sections it held moved to the pages above, with the design records folded into the map's Understand list. - The publish page corrects what it moved from the README: it names the compile stages step 1 runs, says why a refused document is not compiled, says the blank await event's `:error` appears twice in the list, names `Graph.consumers_broken/2` as the call that pairs each finding with the parent's document id, says an undeclared datamodel path is `:error` when the document declares its own datamodel roots and `:info` when only the host declares, and names the release that added `check_accepts/2`. - The describing-a-document page opens with a small patron registration document and takes the rewording of one edge by its endpoints. - The host validators, theming, profiles and typing-a-palette pages, and the `InvokeStep` moduledoc and `Environment` doctests, teach in patron registration instead of card processing. The typing-a-palette page also carries the field-signature snippet and the `StatifierDatamodel.Types.satisfies/3` read check. - The `StatifierBlocks` moduledoc points to the build-and-compile guide instead of the README's worked example. ## [0.44.0] 2026-10-19 0.44.0 adds two optional surfaces and checks more before publish. Under Added: `core.await` takes an optional `capture` map with `core.on_event`'s semantics, and the editor takes an optional `advisories` assign through which a host raises findings of its own. The changes to existing answers are under Changed: `StatifierBlocks.Publish.findings/3` answers an undeclared datamodel path at `:error` in a document that declares its own datamodel roots; a `StatifierBlocks.Graph` finding on a reference a composite's expansion placed is anchored on the composite block, where the compiled `interface` now records that reference with `expanded_from`; a `core.map` whose `collect_type` the supplied `:datamodel` does not declare is reported unchecked, with a new `unresolved_reason`; and the Map's how-to-read paragraph, its abandon end, its Finish edge and its key's dashed-ring line read new sentences. Under Fixed: a face finding on a selected card spans the card, the Expand gesture writes members at their type's current version, the read-only config form renders a passed `class`, and a drafts shelf that fails to lay out no longer blanks the map. 0.44.0 is a minor, because it adds surface and what existing functions answer changes. The package gains no Hex dependency. ### Added - `StatifierBlocks.Editor` takes an optional `advisories` assign: a one-argument function the editor calls with the document on every rebuild, returning `{anchor, message}` or `{anchor, message, opts}` as a `DocumentValidator` does, and each becomes a `:lint` finding at `:warning` unless its `opts` say otherwise, so a host that holds a `core.map`'s child chart can raise a `:warning` on `collect_type` when `BlockType.agrees?/3` says the pair disagrees; `findings_count/3` takes the same function as its `:advisories` option. With the assign unset the editor draws exactly what it drew before. - `core.await` takes an optional `capture` map with `core.on_event`'s semantics: each pair writes a value out of the awaited event's `_event.data`, or a `["const", value]` literal, into a datamodel path on the transition the event selects, and the editor draws the same "Capture from the event" rows for it. An await with no `capture` compiles to the same bytes as before; an await that already stored a `capture` key, which was ignored until now, compiles to its assigns, and a malformed one is refused. Since the editor draws those rows for every await, the first time its form posts an edit to an await that holds no `capture`, the block's config gains an empty `capture` map, which compiles to the same bytes as an absent one. ### Changed - The map's how-to-read paragraph now says a caption sits on a branch's band, or under a group's rules column with its explanation beneath, in place of "a one-line caption". - The map's abandon end, the Finish edge into it and the key's dashed-ring line now say an interrupt rule abandons "a group at the end of its flow" in place of "its last step", since a group deeper in the document's tail draws its own abandon end. - `StatifierBlocks.Publish.findings/3` answers an undeclared datamodel path at `:error`, not `:info`, when the document declares its own datamodel roots (its `datamodel` key holds an entry), so a host's publish step that refuses on `:error` now refuses such a document; the finding keeps the advisory's anchor, `:lint` source and message, and the editor still shows it at `:info`. A document that declares no roots is unchanged: with only a host-supplied `:datamodel` or `:declare` roots the advisory stays `:info` and refuses nothing, and with nothing declared anywhere there is no advisory. - A `StatifierBlocks.Graph` finding on a `core.subchart` or `core.map` that a composite's expansion placed is now anchored `{:block, composite_id}` on the composite block the stored document holds, and the compiled `interface` records that reference under the composite with the expanded member's id as `expanded_from`, in place of the member's id, which the stored document does not hold. - A `core.map` whose `collect_type` names a type the compile's `:datamodel` does not declare is now marked `unresolved` in the compiled `interface`, with a new `unresolved_reason` (`:not_declared`, or `:no_datamodel` for a compile without `:datamodel`), and `StatifierBlocks.Graph.check/2` and `consumers_broken/2` report its done-data read as unchecked with the same `:graph` `:warning` a compile without `:datamodel` gets, its message saying the supplied datamodel does not declare the name; before, the read passed without a finding. It is never an `:error`, so a publish step refusing on errors does not refuse on it. ### Fixed - A drafts shelf that fails to lay out on its own no longer replaces the whole map with the error pane: the drawer is left out and the path is drawn. - `Editor.ConfigForm.config_form/1` now renders a `class` a host passes on its read-only form as well as on the editable one, beside the form's own `sb-form sb-form--readonly`. - A face finding on a selected card now spans the card's full inner width below the title row, where it had been squeezed to a column about one character wide once the card's controls were revealed. - The editor's Expand gesture now writes each member of a composite at its block type's current version, so a member past version 1 (`core.send`, `core.wait`) is stored as authored at that version, instead of being stored at version 1 and migrated on the next compile: with a duration in an accepted spelling the expanded document compiles to the same chart the composite did, and with one in a retired spelling the composite and the expanded document both refuse the same field with the same message. ## [0.43.1] 2026-10-19 0.43.1 widens the `predicator` requirement so that it admits 9.5: a host moving to a `statifier` that requires `predicator` 9.5 takes this release. No function answers differently from 0.43.0, except that a compiled record carries the new package version as its compiler version, and the package gains no Hex dependency. ### Changed - The `predicator` requirement now admits 9.5 (`~> 9.4 and >= 9.4.1`), keeping the 9.4.1 floor and the 9.x cap, so a host that moves to a `statifier` requiring `predicator` 9.5 can resolve this package beside it. ## [0.43.0] 2026-10-10 0.43.0 changes what the Map draws and says, so that a reader can follow a document from its start to its ends. The start dot comes first, at the top, marked Start; every end ring is marked End; a legend beside the drawing says what each of its marks means; a drafts shelf moves into a drawer under the drawing; and a group's caption is its type's whole first sentence. The changes to existing answers are under Changed: the graph `StatifierBlocks.Map.graph/2` answers gains the start dot at its top level, the Start and End labels, a `legend`, a `drafts` field, abandon ends deeper in the tail, a rules column caption and indented arm entries; the descriptions `StatifierBlocks.Map.Info` answers gain a "Finishes with" fact and a "Legend" fact and read new sentences; and a list of datamodel paths gets the advisory and the suggestions a single path gets. Under Fixed: the Map hook draws the first layout when its second fails, and a blank timer or interrupt event reads "its event". 0.43.0 is a minor, because what existing functions answer changes. The package gains no Hex dependency. ### Changed - The Map's start edge description reads as two sentences, what starts the document and then the step that runs first: `StatifierBlocks.Map.Info.elements/6` answers the start edge's `sentence` as "Starts when the system is told to. First: Wait 21 days." where it answered "Starts when told to, Wait 21 days". The first step's line closes with one full stop, which a line already ending in one keeps. The edge's facts ("What starts it", "First step") and the caption drawn on the edge are unchanged. - The Map draws a drafts shelf in a drawer under the drawing rather than as a box in the path's column, and lays the path out as though the shelf were not there. The drawer is a native disclosure element whose row reads "Drafts: N steps not wired in" ("1 step" for one), holding the shelf's own drawing: closed on a page that cannot edit, opening in place on a click on its row, and drawn open on a page that can edit. The shelf's steps in an open drawer select and arm inserts as the drawing's do. `StatifierBlocks.Map.graph/2` marks the shelf's node with a new `drafts` field, `%{"count" => count, "label" => label}`, and its `legend` gains a last `drafts` entry whose line is that row; the node stays where it was, so `StatifierBlocks.Map.nodes/1` is unchanged. A host drawing the graph itself finds the shelf by that field, and a host that matches the idle description's "Legend" fact reads the new line on a document with a shelf. - On a document whose root body holds only a drafts shelf, the graph's start edge now runs into the root's box rather than into the shelf. - `StatifierBlocks.Map.graph/2` places the start dot first in reading order: the dot is now the graph's first node, ahead of the document's root box rather than inside it, and its start edge is the graph's own, so the map draws the dot and its caption at the top, above the root box's title and every box label. A host that reads the graph's shape finds the dot and its edge at the graph's top level, beside the root box; the edge still runs into the first step of the document's flow, and the type names stay on the boxes. `StatifierBlocks.Map.Info.elements/6`, which lists elements in the order a walk of the graph meets them, now lists the start dot before the root box and the start edge after the root's own elements and edges. - `StatifierBlocks.Map.Info.idle/4`'s `explanation`, the paragraph on how to read the map, opens with "A plain box is a step, drawn inside the step that holds it, with its type's name on top and what it does under it." in place of a sentence that called every box a step. The sentence on shaded boxes no longer names a group's interrupt rules; a new sentence after it says "A column beside a group holds the rules that watch it, or the step that runs when it fails." A host that matches the explanation text reads the new sentences. - A timer edge's explanation in `StatifierBlocks.Map.Info.elements/6` now says the delayed event arrives at the interrupt rule or the hourglass step that hears it, the words the Map's key uses for the dotted arrow, where it said the rule or the wait it points at hears it. - The Map draws a key of its marks beside the drawing, at its top right: the start dot, the end rings, solid, dashed and dotted arrows, the fork, the join, the hourglass and the clock, each with the drawing's own glyph and one line saying what it means, and only the marks the drawing uses. `StatifierBlocks.Map.graph/2` answers it as a new top-level `legend` list, one `%{"mark" => mark, "line" => line, "lines" => lines}` per mark, which the Map hook draws; the hook widens the SVG to hold it. A host drawing the graph itself finds the key there. - `StatifierBlocks.Map.Info.idle/4` answers the key's lines as a new last fact, `{"Legend", lines}`, since the map is hidden from assistive technology, and its `explanation`, the paragraph on how to read the map, is shorter: what each mark means moves to the key, and the paragraph points at it. `StatifierBlocks.Editor.MapRegions.description_region/1` shows the fact with a map beside it and leaves it out with `map={false}`, as it leaves out the paragraph. A host that matches the idle description's facts or its explanation text reads the new values. - The Map's key of its marks is titled "Legend", and `StatifierBlocks.Map.Info.idle/4` answers the key's lines as its last fact under the label "Legend" rather than "Key"; `StatifierBlocks.Editor.MapRegions.description_region/1` with `map={false}` leaves that fact out as before. The key's lines and the paragraph on how to read the map are unchanged. A host that matches the idle description's facts by label reads "Legend". - The Map hook now holds the SVG wide enough for a timer edge between two steps of one column, the run it draws past their right sides and its delay, when the drawing has no key; before, only a key beside the drawing widened the SVG for it. - `StatifierBlocks.Map.caption/1` now answers the whole first sentence of the type's explanation for a branch and the two group types, never cut to one line and ended in "..." as a group's was; a host that drew `caption/1` itself should expect the longer text. - A group's rules column in `StatifierBlocks.Map.graph/2` now carries `caption` "Rules: watch the steps while they run" in place of the group's sentence, and a new `explanation_lines` field, that sentence wrapped to a box's line; the Map hook draws the caption under the column's label and the lines under it, and the column grows to hold them. - The Map hook draws a resume edge clear of its own rule's box when the middle of the head of the group's body is not well above the rule's top: the edge still leaves the top of the rule and ends on the head's side, but it now goes up a short way, left past the rule's side and down to the head's height before it turns in, where it ran straight down through the rule's box. A resume edge whose head stands well above the rule is drawn as before. Only the hook's drawing moves; `StatifierBlocks.Map.graph/2` answers the same graph. - A `{:list, {:path, opts}}` field's rows now get what a `{:path, opts}` field gets: `StatifierBlocks.Datamodel.findings/4` returns the `:info` undeclared-path advisory for each undeclared row, anchored on the list field's key, and the editor binds each row's input to a `` of `path_candidates`; `BlockType.datamodel_path?/1` still answers false for a list. - `StatifierBlocks.Map.graph/2` sets a wrapped arm entry apart on a branch's header: every line after the entry's first now starts with no-break spaces as wide as the entry's number (`"1. "`, `"10. "`), so the map draws it indented under the arm's label and a wrapped condition no longer reads as an entry of its own. An entry that fits on one line, and every other box's lines, are unchanged. A host that reads a branch node's `lines` finds the indent at the start of each continuation line. - The Map's start dot now carries the word Start and every end mark the word End, whichever outcome it ends with; the outcome stays the caption on the arrow into the mark. In `StatifierBlocks.Map.graph/2` the start node and each end node carry the word as their one ELK `labels` entry, with `layoutOptions` asking the layout to place it outside the mark on its right, and the Map hook draws it there; a host drawing the graph itself finds the word in that label. The Map's legend lines name the dot marked Start and the ring marked End. - The Map's start caption names who starts the document: `StatifierBlocks.Map.start_text/0` answers "Starts when the system is told to" where it answered "Starts when told to", the same sentence on every document, so the caption on the start edge `StatifierBlocks.Map.graph/2` answers, the "What starts it" fact and the start edge's description sentence `StatifierBlocks.Map.Info` answers ("Starts when the system is told to. First: Wait 21 days.") read it too. A host drawing the graph itself finds the longer caption, and its wider label, on the start edge. - The Map draws the dashed abandon end for a group deeper in a document's tail, not only for a group that is the root's last step: a group that is the last step of an arm of the root's last step, or of the body of a group that is, finishes the document when one of its rules abandons it. In `StatifierBlocks.Map.graph/2` such a document gains the `abandon` end node, and an `abandon` edge into it from each group in that position whose rules abandon it, so one abandon end can have several edges into it; the `done` end and its edge are unchanged. `StatifierBlocks.Map.Info.elements/6` describes each new edge as it describes the root-level one. - `StatifierBlocks.Map.Info.idle/4` answers a "Finishes with" fact right after "What starts it": the document's ends in the words its end marks and the arrows into them carry, in order (each outcome, and "abandons" for an abandon end), for example `["done", "abandons"]`. A document whose map draws no end, such as one with no step yet, has no such fact. ### Fixed - The Map hook draws the first layout, its line bent at the group, when the second layout of a graph whose group body holds a container fails, instead of drawing the error pane. - `StatifierBlocks.Describe.render/2` reads a timer or interrupt edge whose event is blank as "its event", as it already did for an edge with no event, instead of leaving a gap in the line. ## [0.42.1] 2026-10-05 0.42.1 changes documentation only: no function's behaviour changes, and the package gains no Hex dependency. ### Changed - The hexdocs sidebar groups the guides by the kind of page: the guide to describing a document sits under How-to guides, and the README and the CHANGELOG stay ungrouped at the top. The module groups are unchanged. - Three guides read on GitHub take titles that say what they help you do: "How to build common flow patterns", "How to mount the editor for one audience" and "How to theme the editor". No file is renamed, so links to them still resolve. - `StatifierBlocks.Editor.Inspector`'s module documentation now places the Note section beside the Config tab's two sections and says why it alone appears only with a block selected. ## [0.42.0] 2026-09-30 0.42.0 changes three things a host of the editor or the Map can see, and fixes what raised or dropped out on documents and classes a host passes. The changes to existing answers are under Changed: `map_region/1` no longer stamps `data-info-region` on the map's element; the editor stores a browser's CRLF note line breaks as LF, while the note command a host issues keeps its bytes; and a host's `:phrase` words reword an event name only in event position. Under Fixed: a note-free block kept as a stored Erlang term no longer raises in the note command, the Map's descriptions or the editor's note field; `description_region/1` degrades instead of raising on a composite whose declaration cannot expand; and the host's `class` reaches the description region's hover layer. 0.42.0 is a minor, because what existing functions answer changes. The package gains no Hex dependency. ### Changed - `StatifierBlocks.Editor.MapRegions.map_region/1` no longer stamps `data-info-region` on the map's element, which the `StatifierBlocksMap` hook has not read since 0.40.0 (it finds its hover layer by `data-info-hover` and its store by `data-info-store`), so the hover is unchanged. A host that stamps the attribute on its own element has nothing to do; a host that read it off the element finds it gone and takes the region's id from the `description` it passes. - The editor's note field now stores each CRLF line break a browser posts as LF, so a note written in the editor holds the same bytes as the same note written by a host, and a change of line endings alone is no longer an undo entry; a lone CR is stored as posted, and the `{:update_note, id, note}` command a host issues itself still stores the note as written. - A host's `:phrase` words for its event names (`StatifierBlocks.Map.graph/2` and the Map's description region) now reword a name only in event position - after "Send" or a delayed send's "send", after "Wait for", or after a rule's "When" - and leave a known name anywhere else as written, such as a path a step sets, a name after a send or wait word glued to a dotted prefix, or the event a timer edge's line names before "reaches"; a host that relied on a name reading as words elsewhere now sees the name. ### Fixed - The `class` a host passes to `StatifierBlocks.Editor.MapRegions.description_region/1` now goes on the region's hover layer as well as on the region, so styling the host gives the region through it no longer drops out while a hover is shown. - A document whose blocks were built before blocks had a note, and that a host kept as a stored Erlang term rather than as JSON, now also goes through the note edit command `{:update_note, id, note}` (its inverse carrying the empty note), `StatifierBlocks.Map.Info`'s descriptions and the editor's note field as a note-free document, instead of raising `KeyError` or `CaseClauseError`. - `StatifierBlocks.Editor.MapRegions.description_region/1` no longer raises when a composite in the document has a declaration that cannot expand: the region renders with no description in it instead of raising out of the host's render, as the editor already survives such a document. ## [0.41.0] 2026-09-29 0.41.0 changes how the Map draws three things and how Describe names a container. The Map draws the happy path straight through a group whose body holds a container, the Map hook laying such a document out a second time; it draws the clock mark on a timed wait; and its how-to-read text names every mark it draws. The changes to existing answers are under Changed: `StatifierBlocks.Describe.render/2` names a container in its edge lines by a noun rather than by its sentence, and sets an embedded delayed send's sentence in double quotation marks, so a host that matched the old edge lines reads the new words; and the Map hook warns once in the browser console when its element has no `data-map-canvas` child. `StatifierBlocks.Describe.Node` gains the `noun` field. 0.41.0 is a minor, because what an existing function answers changes and a public struct gains a field. The package gains no Hex dependency. ### Added - `StatifierBlocks.Describe.Node` carries `noun`, the name an edge line gives the block when it is the edge's container: its title, else a short noun for its type, and `nil` for a block with no slots or one the palette cannot resolve. ### Changed - The Map draws the happy path straight through a group whose body holds a container, such as a branch: the Map hook lays that document out twice, the second time with the group's edges attached where its body's steps stand, instead of at the middle of the group. - The paragraph on how to read the map, in the idle description, names every mark the Map draws once each: the shaded slot boxes, the band and its fork mark, the captions, the rejoin's dot and heavier arrow, the selection outline and the "+" on a page that can edit, beside the marks it already named. It says a dotted timer arrow runs to the interrupt rule or the hourglass step that hears it. - `StatifierBlocks.Describe.render/2` names a container by a noun in its edge lines rather than by its sentence: its title where it has one, else a short noun for its type (`The steps start with Wait 14d`, `Send loan.overdue (done) ends the steps`, `abandons the group`); a host's container reads `the` and its palette label in lower case. Node lines, and a step named in an edge line, keep their sentence. A host that matched the old edge lines reads the new words or rewords them through `StatifierBlocks.Describe.Phrasing`. - `StatifierBlocks.Describe.render/2` sets a delayed `core.send`'s sentence in double quotation marks wherever an edge line embeds it, so its own comma no longer reads as the line's: `The steps start with "In 7 days, send loan.overdue"`, `After "In 7 days, send loan.overdue" (done), Wait 14d`. The send's node line, an undelayed send and every other step read as before. A host that matched the old edge lines reads the new words or rewords them through `StatifierBlocks.Describe.Phrasing`. - The Map draws the clock mark on a timed wait (`core.wait`), as it does on a delayed send: the clock says time passes, and the hourglass on an await says a step waits for an event. The mark is a mark only; a wait still takes no part in a timer edge. The paragraph on how to read the map, in the idle description, says so. - The Map hook warns once per mount in the browser console when its element has no `data-map-canvas` child. It still draws into the element itself, as before, but that is not supported: LiveView patches the element, so a patch can take the drawing away. `map_region/1` always renders the child; a host that attaches the hook to its own element gives it one. ## [0.40.0] 2026-09-29 0.40.0 lets an author write a block's note in the editor, and shows the selected block's description under the editor's canvas. The new edit command `{:update_note, id, note}` writes the note with the previous note as its inverse, so undo and redo move it, and the inspector's Note field issues it; `StatifierBlocks.Edit.t()` gains that member, so a host that matches every member of the union by hand has one more to handle. The editor draws the Map's description region, `StatifierBlocks.Editor.MapRegions.description_region/1`, under its canvas with no map beside it, and the region takes new `map` and `label` attrs whose defaults render what it rendered before. The changes to existing answers are under Changed: the region no longer announces a hover, which shows in a hover layer beside it that the Map hook finds by `data-info-hover`, and `map_region/1` and `description_region/1` refuse a `phrase` that is not a function of one argument with an `ArgumentError` naming the attr. Under Fixed, a block kept as a stored Erlang term from before blocks had a note encodes and validates, and the npm manifest names both licences. 0.40.0 is a minor, because it adds to the public surface, a member of the edit union included. The package gains no Hex dependency. ### Added - The editor draws a description region under its canvas: the selected block's description, its note first, or the document's name, description, what starts it and its counts when nothing is selected. It is the Map's `StatifierBlocks.Editor.MapRegions.description_region/1`, live and showing values only; the editor still draws no map. It is drawn in a read-only mount too, and no `profile` key hides it. - `description_region/1` takes a `map` attr, `true` by default, saying whether a map is mounted beside the region; `false` renders no hover layer, no store and no how-to-read paragraph in the idle description. A host that passes nothing gets the region it had. - The edit command `{:update_note, id, note}` writes a block's author note, with the previous note as its inverse, so undo and redo move it like any other edit; an empty note removes it. `StatifierBlocks.Edit.t()` gains this member, so a host that matches every member of the union by hand has one more to handle. - The editor's inspector opens its Config tab on a Note field for the selected block, which writes the note through that command; a read-only mount shows the note as text and does not edit it. - `StatifierBlocks.Editor.MapRegions.description_region/1` takes a `label` attr, the live region's accessible name, rendered as its `aria-label`; it defaults to `"Description"`, so a host that passes nothing gets the region it had. ### Changed - `StatifierBlocks.Editor.MapRegions.map_region/1` and `description_region/1` refuse a `phrase` that is neither `nil` nor a function of one argument with an `ArgumentError` naming the attr, where they raised a `FunctionClauseError` from a private function; `nil` and a one-argument function render as before. - The Map's description region no longer announces a hover: what `description_region/1`'s `aria-live="polite"` region holds changes only when the host renders a new selection, and a hover over the map shows its description in a new hover layer beside the region instead (`aria-hidden`, `hidden` until the `StatifierBlocksMap` hook fills it, left alone by LiveView), which the package stylesheet draws in the region's place. The region now sits with the layer inside a `.sb-map__description-frame` wrapper, and `map_region/1` also stamps the layer's id in `data-info-hover`; a host that set the `--sb-*` palette on `.sb-map__description` alone sets it on `.sb-map__description-frame` so the layer reads it too. - The `StatifierBlocksMap` hook now finds its hover layer by `data-info-hover` and no longer reads `data-info-region`, so a host that stamps the hook's ids on its own element and names only the region and the store gets no hover: stamp `data-info-hover` with the id of an `aria-hidden`, `hidden` element beside the region for the hook to fill, or mount `description_region/1` and `map_region/1`, which render and stamp it. ### Fixed - A document whose blocks were built before blocks had a note, and that a host kept as a stored Erlang term rather than as JSON, now encodes and validates as a note-free document instead of raising `KeyError`. - The npm package manifest names its licence as `(MIT AND EPL-2.0)`, since it ships the vendored elkjs file under EPL-2.0. ## [0.39.0] 2026-09-28 0.39.0 ships the Map, a second view of a block document drawn beside the host's own list. `StatifierBlocks.Map` is a pure reader of the view model, and nothing about the map is stored in the document. A draw-only hook, `StatifierBlocksMap`, lays that graph out and draws it from its own entry point, `statifier_blocks/map`, with elkjs 0.9.3 vendored (about 1.6 MB, loaded only by a host that imports that entry point; the default export is unchanged). `StatifierBlocks.Map.Info` answers the description region's data, and `StatifierBlocks.Editor.MapRegions` gives a host the map region and the description region to mount beside its list. The one change to an existing answer is under Changed: Decode admits an optional `note` string on a block, a key it refused before, and refuses a note that is not a string with the new reason `{:malformed_block, id, {:note, :not_a_string}}`. Under Fixed, a card whose control strip wraps now holds that wrapped height at rest. The vendored elkjs file is the package's one file under the Eclipse Public License 2.0, so the package metadata lists `EPL-2.0` beside `MIT`. 0.39.0 is a minor, because it adds to the public surface and changes no existing signature. The package gains no Hex dependency. ### Added - `StatifierBlocks.Map.Info` answers the description region's data: `elements/6` describes every element `StatifierBlocks.Map.graph/2` draws, keyed by the id the map draws it under - a block or a rule with its title, sentence, type's explanation, settings, place, outcomes, interrupt rules, timer edges and findings, a slot, an arm, an empty marker, the start and end marks, a connector, an interrupt edge and a timer edge - and `idle/4` describes the document for when nothing is selected. A block's author-written `note` is its description's `note`, shown above the built-in text; the host's `:phrase` reads event names as words, as the Map's does. - The `StatifierBlocksMap` hook swaps the description region, in the browser, to the description of the element under the pointer and puts the region back when the pointer leaves, reading the region and a hidden store of rendered descriptions by the ids the host stamps on the map's element (`data-info-region`, `data-info-store`). Hover pushes nothing and changes no selection; a host that stamps neither id gets no hover. - `StatifierBlocks.Map.graph/2` builds the graph a layout hook draws the block document from, as boxes in boxes read off the view model: the start dot, an end mark per way the document finishes, a branch's arms under one band, a group's rules in a side column, a marker per empty slot, every edge the outline describes including the dotted timer edge, the host's selection marked and the host's words for its event names read into the sentences; with `nodes/1`, `interrupts/1`, `timers/1`, `caption/1`, `empty_text/0` and `start_text/0` beside it. - `StatifierBlocksMap`, a draw-only LiveView hook at its own entry point `statifier_blocks/map` (`assets/js/statifier_blocks_map.js`), lays out the graph `StatifierBlocks.Map.graph/2` answers with elkjs and draws it as plain SVG: model order kept, the happy path straight through a group's fixed ports, an error pane in place of a map that could not be laid out, a moved selection re-marked without a second layout, and a click on a box, a gap or an empty slot's marker sent as the host list's own select or insert event, under the names the host stamps on the element (`data-select-event`, `data-insert-event`). It is not in the default export, so a host that never mounts the Map never bundles the layout library. - elkjs 0.9.3 ships vendored and unmodified as `assets/vendor/elk.bundled.js` (1,606,238 bytes, 466,990 gzipped at the highest level, loaded whole by any bundle that imports the Map hook), with its Eclipse Public License 2.0 text beside it as `assets/vendor/elkjs-LICENSE.md`. - `StatifierBlocks.Editor.MapRegions`, the two function components a host mounts to show the Map beside its own list. `map_region/1` renders the element the `StatifierBlocksMap` hook draws into, stamped with the graph `StatifierBlocks.Map.graph/2` answers for the host's view model and selection, the host list's own select and insert event names, whether the page can edit, and the description region's ids for hover; the region is `aria-hidden` and its scroll box `tabindex="-1"`, so the list stays the keyboard and screen-reader path. `description_region/1` renders the `aria-live="polite"` region the list's rows name with `aria-describedby`, with the selected block's `StatifierBlocks.Map.Info` description (its note first) or the document's idle one rendered on the server, and beside it the hidden store of every element's description the hook's hover reads. - The package stylesheet styles both regions under `sb-map__` classes and declares the nine `--sb-map-*` tokens the Map hook's drawing reads (`--sb-map-block-fill`, `--sb-map-block-stroke`, `--sb-map-slot-fill`, `--sb-map-slot-stroke`, `--sb-map-empty-fill`, `--sb-map-empty-stroke`, `--sb-map-edge`, `--sb-map-mark`, `--sb-map-band-fill`) on `.sb-map__region`, mapped onto the `--sb-*` palette. ### Changed - Decode admits an optional `note` string on a block, a key it refused before: `StatifierBlocks.Block` gains a `note` field (default `""`, the absent note) that `Block.new/2` takes as `:note`, canonical form omits an empty note, the shipped schema describes it, and a non-string note is refused as `{:malformed_block, id, {:note, :not_a_string}}`. A note changes the document hash, not the compiled chart. ### Fixed - A card whose text is shorter than its wrapped control strip no longer grows taller on hover, selection or keyboard focus: the strip wraps its controls at rest too, so the card holds that height in every state. ## [0.38.0] 2026-09-28 Upgrading a host: a block type's declared field types now bind, so a host config its declared field types refuse is now refused before `validate_config/1` runs, at compile, at the edit gate and in the view model. After taking this version and before deploying it, run `StatifierBlocks.Palette.preflight/1` over your palette, and `StatifierBlocks.Palette.preflight/2` over the documents you store, and correct each declaration or stored block it lists; an empty list means you are ready. That is the one change to an existing answer, under Changed. 0.38.0 is a minor, because it adds to the public surface and changes no existing signature: `StatifierBlocks.Schema.for_palette/1` answers a draft-07 schema for one palette, and `preflight/1` and `preflight/2` are new. The package gains no dependency. ### Added - `StatifierBlocks.Schema.for_palette/1` answers a draft-07 schema for a palette: the shipped root with every block also judged by its own type's definition, a `core.*` type's from `definitions/core` and a host type's generated from its declared `config_schema/1` and `slots/1`, each declared field typed from its declared field type. - `StatifierBlocks.Palette.preflight/1` lists every host type in a palette whose own defaults, or the block `Palette.new_block/2` builds from them, disagree with their declared field types, each finding naming the type, the field's key, its declared type and the value; `preflight/2` also lists every block of the given documents whose config its type's declared field types refuse, by block id. A type whose callbacks raise is a finding, never a raise. ### Changed - A block type's declared field types now bind: a config value whose declared field type in `config_schema/1` does not admit it (an integer in a `:string` field, a value outside a `{:select, choices}`) is refused before `validate_config/1` runs, at compile, at the edit gate and under the field in the view model, with a finding naming the field's key and its declared type; `validate_config/1` still runs and its findings follow. An absent key and a `null` are still the type's own to judge. After taking this version and before deploying it, run the palette pre-flight (`StatifierBlocks.Palette.preflight/1`, or `preflight/2` with your stored documents) over your host types and correct each declaration or stored block it lists, since a host type whose documents disagree with its declared field types will see new `:config` findings. ## [0.37.0] 2026-09-28 0.37.0 is a minor, because it adds to the public surface and changes no existing signature. A block type can now say what every block of it does: `StatifierBlocks.BlockType` gains an optional `explain/0` callback and the resolver `explain/1`, and every `core.*` type declares one. `StatifierBlocks.Describe` draws a new edge kind, `:timer`, from a delayed `core.send` to the rule or await that names its event, carrying the delay in `StatifierBlocks.Describe.Edge`'s new `delay` field, which a host rewords through the new optional `Phrasing.timer/2` callback. The one change to an existing answer is `core.send`'s card line for a delayed send, which now names the delay, under Changed. Upgrading a host: nothing needs migrating, the package gains no dependency, and a document with no delayed `core.send` reads and describes exactly as it did in 0.36.1. ### Added - `StatifierBlocks.BlockType` gains an optional `explain/0` callback, one short paragraph saying what every block of the type does, and the resolver `StatifierBlocks.BlockType.explain/1`, which answers that paragraph, else the palette entry's `description`, else `nil`, through the palette so a `{module, state}` type resolves the same way; every `core.*` type declares one. - `StatifierBlocks.Describe.outline/3` answers a new edge kind, `:timer`, from a delayed `core.send` to every `core.on_event` and `core.await` in the document that names its event, after every other edge and carrying the delay in `StatifierBlocks.Describe.Edge`'s new `delay` field; `render/2` writes it as `In 24 hours, registration.deadline reaches ...`, and a phrasing module rewords it through the new optional `StatifierBlocks.Describe.Phrasing.timer/2` callback. A document with no delayed send describes exactly as before. ### Changed - A `core.send` block with a delay names that delay on its card line: `sentence/1` answers `In 7 days, send loan.fines_notice` where it answered `Send loan.fines_notice`, the short duration form put in words and any other stored spelling shown as stored, and the `StatifierBlocks.Describe` lines built from that sentence change with it; a send with no delay reads exactly as before. ## [0.36.1] 2026-09-27 0.36.1 is a patch, because it changes no public function, option or callback and adds nothing to the public surface. It fixes `StatifierBlocks.Describe`: the outline now draws the interrupt edge for an abandon handler that names `finish_as`, which 0.36.0 left out. Upgrading a host: nothing needs migrating, and the package gains no dependency. ### Fixed - `StatifierBlocks.Describe.outline/3` draws the interrupt edge to the group's end for an abandon handler that names `finish_as`, keying the edge on the handler's `outcome` select rather than on the name it finishes with. ## [0.36.0] 2026-09-26 0.36.0 is a minor, because it adds to the public surface and changes no existing signature. A host gains two things. The block document's JSON Schema (draft-07) now ships in the package, and `StatifierBlocks.Schema` reads it, so a host can check a document with its own validator before it reaches the package. `StatifierBlocks.Describe` describes a document in words: a deterministic outline of its nodes and flow-graph edges, and one sentence per node and per edge, which a host rewords through a phrasing behaviour. The release also gives `core.sequence`, `core.group` and `core.await` card lines of their own in place of their labels. Upgrading a host: nothing needs migrating, the package gains no runtime dependency, and a host that calls neither new module sees no change from 0.35.1 other than those three card lines. ### Added - `StatifierBlocks.Describe` describes a block document in words: `outline/3` answers one node per block and the flow-graph edges between them, read from the document's structure without compiling it, and `render/2` writes one deterministic English line per node and per edge, which a host rewords through the `StatifierBlocks.Describe.Phrasing` behaviour. - The block document's JSON Schema (draft-07) ships in the package at `priv/schemas/block-document.schema.json`, with `StatifierBlocks.Schema.path/0` and `json/0` to read it: its root never refuses a document `StatifierBlocks.Document.from_json/1` accepts, and typed `config` and `slots` definitions for the `core.*` types sit under its `definitions/core`, which the root does not apply. ### Changed - `core.sequence` declares `sentence/1`: its card line, and its name in `StatifierBlocks.Describe`'s lines, is "Run its steps in order" where it was the label "Sequence". - `core.group` declares `sentence/1`: its card line, and its name in `StatifierBlocks.Describe`'s lines, is "Run interruptible steps" where it was the label "Group". - `core.await` declares `sentence/1`: its card line, and its name in `StatifierBlocks.Describe`'s lines, is "Wait for ", followed by ", giving up after " when a deadline is set, where it was the label "Wait for event". ## [0.35.1] 2026-09-25 0.35.1 is a patch, because it changes no public function, option or callback and adds nothing to the public surface. It fixes how a card lays out its title: a long title on a card that carries several controls no longer breaks mid-word. Upgrading a host: nothing needs migrating, the package gains no dependency, and the fix is in the shipped stylesheet only. ### Fixed - A card's title no longer breaks mid-word when the card carries several controls: the title column keeps a minimum of 6.5 times `--sb-text-md`, the hidden controls yield their width to it at rest, and on hover or selection they wrap inside the space left rather than squeezing the title. ## [0.35.0] 2026-09-24 0.35.0 is a minor, because it adds to the public surface and changes no existing signature. A host can now check a whole document against the palette it is about to mount before an author opens it: `StatifierBlocks.Plan.expressible/3` answers `:ok`, or `{:no, reasons}` with one reason per refusal, each naming the rule and the block, and `StatifierBlocks.Plan.expressible?/3` answers the same question as a boolean. The release also carries a host upgrade page for moving from 0.31 to 0.34 one minor at a time, and a guide for moving a document off the 0.27 vocabulary onto declared outcomes. Upgrading a host: nothing needs migrating, the package gains no dependency, and a host that calls neither new function sees no change from 0.34.0. ### Added - `StatifierBlocks.Plan.expressible/3` checks a whole document against a palette before it reaches the editor: `:ok` when every block's type resolves, every block sits in a slot the editor would let an author drop it into (declared, with room, admitting its kinds), and every empty required slot is one the palette can fill; otherwise `{:no, reasons}` with one reason per refusal naming the rule and the block. A read type mismatch is not a reason, since the editor flags it rather than refusing the drop. An optional third argument is the assignability context, defaulting to `%{}` as `Edit.Targets.admits_at?/5` defaults it. `StatifierBlocks.Plan.expressible?/3` asks the same question with the same arguments and answers a boolean, `true` exactly when `expressible/3` answers `:ok`. ## [0.34.0] 2026-09-23 0.34.0 is a minor, because it adds to the public surface and changes no existing signature. A host can now generate the migration plan between two compiled revisions of one document: `StatifierBlocks.Migration.plan/2` maps the old revision's states onto the new one's through their block ids and answers the mapping as plain data, reporting every state it could not map. The editor can show the host's publish line: a new `publish_status` assign carries the count of live executions on the previous revision and the class of the change, drawn beside the header. Upgrading a host: nothing needs migrating, the package gains no dependency, and an editor mounted without `publish_status` renders exactly what it rendered in 0.33.0. ### Added - `StatifierBlocks.Migration.plan/2` maps the states of one compiled revision of a document onto another's through their block ids, roles included, and answers plain string-keyed data in the migration plan's `states`, `history` and `invocations` fields. Every old state with no counterpart - each state of a deleted block, and each final of an outcome a block no longer declares - is listed under `unmapped` and mapped nowhere. Two artifacts of different documents are refused with `{:error, :different_documents}`. It moves no execution and reads no timer. - `StatifierBlocks.Editor` takes a `publish_status` assign, `nil` or `%{live: n, class: class}` with `class` one of the four classes `Statifier.Chart.diff/3` returns, and draws it as one line beside the `:header` slot, such as "3 live executions on the previous revision; this change is compatible". The host computes both values and the editor makes no query; `nil`, the default, renders exactly what the editor rendered before. ## [0.33.0] 2026-09-22 0.33.0 is a minor, because it adds to the public surface and changes no existing signature. A document can declare the external events it accepts, as a new `accepts` key on its envelope. Two new public modules serve a host's publish step: `StatifierBlocks.Publish.findings/3` returns every finding the host judges a document by before it compiles, and `StatifierBlocks.Graph` judges a parent's compiled artifact against the children it names, and a child's next revision against the parents that name it. Upgrading a host that stores documents: `accepts` defaults to `[]`, a stored document decodes unchanged and keeps its `content_hash/1`, and nothing needs migrating; a document saved with a non-empty `accepts` list cannot be read by 0.32.0 or earlier. Beside that, this release carries a minted-id collision finding at the Resolve stage, a Document-stage refusal where the compile raised, and clearer wording on the `:undeclared_slot` finding. ### Added - A document can declare the external events it accepts, as an `accepts` list of event names on the envelope beside `datamodel`. `Document.validate/1` refuses a value that is not a list, an entry that is not a string, an empty name and a repeated name, each as a `{:malformed_envelope, {:accepts, _}}` reason. An empty or absent list encodes to the same bytes as before, so no existing document's `content_hash/1` changes; a reader from an earlier release refuses a document that declares one. - `Compiler.compile/3` carries the document's `accepts` list, exactly as written, onto `%Compiled{}` and `%CompilationRecord{}` as a new `accepts` field. The compile reads nothing from it and the SCXML and chart identity do not change with it; whether each name is one the chart can take is for a host's publish step to check. - The edit command `{:set_accepts, names}` replaces a document's whole `accepts` list, with the previous list as its inverse, and the editor's Declarations tab gains an accepted-events row where an author adds, renames, reorders and removes them. - `StatifierBlocks.Declarations.add_accepted/1` appends a freshly named accepted event, `event_1` or the first `event_N` the list does not already hold, and `Declarations.put_accepted/3` writes the name at an index, or returns the list unchanged when no name sits there. `Declarations.refusal/1` phrases a refused `{:set_accepts, names}` as one sentence for the panel. - `StatifierBlocks.Editor.Findings.anchor_tag/1` tags a finding anchored on the document `document`, with no id. - `StatifierBlocks.Graph.check/2` and `StatifierBlocks.Graph.consumers_broken/2` return a `:warning` finding on a `core.map` block's `collect_type` field when that field names a type and the parent was compiled without `:datamodel`, saying the done-data keys read there are unchecked; each `interface` reference records the name in an `unresolved` field. Pass `:datamodel` to the compile, or write the `collect_type` inline, to have the keys checked. - `Compiler.structure_findings/3` returns the findings the compile's Document, Resolve, Config and Structure stages refuse a document for, without emitting anything: exactly the list `Compiler.compile/3` refuses with when it refuses at one of those stages, and `[]` otherwise. It takes `compile/3`'s own options and never raises. - `StatifierBlocks.Publish.findings/3` returns every finding a host's publish step judges a document by before it compiles, in the order the editor shows them: the structure findings above, then the editor's own findings for the same document and the same `:datamodel`, `:declare` and `:chart_outcomes`. A document the Document stage refuses comes back as that one finding. The host refuses the publish on an `:error`; an undeclared datamodel path stays an `:info` advisory. - `StatifierBlocks.Finding` gains the anchor `:document` for a finding about the document rather than a block. `Finding.from_compiler/2` adapts the compile's Document-stage finding to it instead of refusing it as `:unanchorable`, and the editor lists it first on both findings surfaces, under `Document`, with nothing to select. `Shell.findings_groups/3`'s groups gain a `document?` key, and the inspector stamps `data-document` on each group. - `Compiler.compile/3` records the document's parent/child interface on `%Compiled{}` as a new `interface` field: the outcomes and done-data keys its root block declares, and for each `core.subchart` or `core.map` block the document it names, the child outcomes it routes on and the child done-data keys it reads. The SCXML and chart identity do not change with it, and `%CompilationRecord{}` does not carry it. - `StatifierBlocks.Graph.check/2` judges a parent's compiled artifact against each child it names, through a resolver the host supplies, and `StatifierBlocks.Graph.consumers_broken/2` judges a child's next revision against the parents that name it, for a host's publish step to refuse on. A child that is not published, an outcome the parent routes on that the child does not declare, and a done-data key the parent reads that the child does not declare are each an `:error` finding on the parent's referencing block. The reverse direction pairs each finding with the parent's document id. - `StatifierBlocks.Finding` gains the source `:graph` for those findings. ### Changed - `StatifierBlocks.Shell.drawer_view/1` takes the document's accepted events under an optional `accepts` key, and the Declarations tab's count adds them to the datamodel roots it counted before. - A recipe's `insert/2` may return `{:set_accepts, names}` beside the blocks it inserts, as it already could `{:set_datamodel, entries}`: `Recipe.within_reach?/2` answers `true` for a list holding it, and `Edit.Targets.recipe_inserts/4` no longer refuses such a recipe as `{:recipe_out_of_reach, name}`. Every command that names a position is still held to the armed position and the block that encloses it. - A block placed in a composite's pass-through slot, or in a declaring composite's `on_` slot, whose id equals one the composite's expansion mints for its own members now draws a `:minted_id_collision` finding at the Resolve stage, against the composite block and naming the placed block; before, such a document was refused at the Chart stage with `:duplicate_id` findings when both blocks emitted a state, and a block in a pass-through slot could hide an `:outcome_not_raisable` finding. Give that block another id. ### Fixed - `Compiler.compile/3` returns its Document-stage refusal for a document whose `root` is not a block, or whose `slots` value is not a map of block lists, where it raised. - The `:undeclared_slot` finding message no longer calls a single stray block "they": at both the Structure and the Resolve stage it now says the slot's contents are dropped, and the Resolve message says to move them into a slot "this block type declares" instead of an ambiguous "it declares". ## [0.32.0] 2026-09-18 0.32.0 is a minor, because a public function's arity changes. A composite block type may now implement an optional `declared_outcomes/1` callback and have its outcomes read from each instance's own config, so one type can stand for blocks that finish in different ways. Breaking: `StatifierBlocks.Composite.unraisable_outcomes/4` is now `unraisable_outcomes/5`, and a caller passes the config of the block it expanded, between the type ref and the expansion members. Beside that, this release carries fixes to the compiler's slot findings and their wording, to a `capture` literal that is not valid UTF-8, to the refusals a handler that finishes with `done` while it resumes reports, and to an editor card that reflowed when it was selected. ### Added - `StatifierBlocks.BlockType.finishing_outcome_name/2` answers the outcome a block in a declared slot finishes with: the name it carries under `finish_as` when that name is well formed, and the outcome its config declares at the given key otherwise. - A composite block type may implement an optional `declared_outcomes/1` callback and have its outcomes read from each instance's own config, so one type can stand for blocks that finish in different ways. ### Changed - The editor view model reads a `core.on_event` handler that names the outcome it finishes with under `finish_as` as that name; a handler naming none still reads as its `outcome` select value. - Every reader of a composite's declared outcome list now reads the list of the block in hand. A composite declaring `outcomes:` statically, and one declaring nothing at all, behave exactly as before. - **Breaking:** `StatifierBlocks.Composite.unraisable_outcomes/4` is now `unraisable_outcomes/5`, taking the block's config as its third argument; a caller passes the config of the block it expanded, between the type ref and the expansion members. ### Fixed - A declared slot whose child count violates its declared arity now draws a `:slot_arity_violated` finding even when the composite carrying it declares no outcomes; it used to compile green with the declaration's refusal lost. - Selecting an editor card no longer reflows it: the control strip reserves the widest set of controls the card can show, so the "Save as a step" control arriving on selection no longer narrows the title column or re-wraps the title. - The compiler's slot findings no longer read "holds 1 blocks": the undeclared-slot and slot-arity messages now count in blocks or in one block, to agree with the number they report. - A child placed in a slot a composite's type does not declare now draws an `:undeclared_slot` finding even when that composite declares no outcomes; it used to compile green and be dropped with nothing to read. - `StatifierBlocks.Core.OnEvent.validate_config/1` answers `:ok` instead of raising `UnicodeConversionError` when a direct caller passes a `capture` literal that is not valid UTF-8; the encoding refusal stays with the compiler, which already refuses such a literal before the walk runs. - A `core.on_event` handler that names a finishing outcome of `done` while it resumes its group now reports both of the refusals that apply, instead of only the first. ## [0.31.0] 2026-09-14 0.31.0 is a minor, because a core block type takes a new public key and what a named handler compiles to changes. A `core.on_event` handler may now name the outcome it finishes its group with, so an enclosing composite can declare that outcome and route it through its derived `on_` slot (ADR-0002 C8). Beside that, a slot written on a declaring composite under the name the compiler reserves for that composite's expansion members is now reported instead of silently dropping the children. ### Added - `core.on_event` takes an optional `finish_as` key naming the outcome the handler finishes with when it abandons its group, so an enclosing composite can declare that outcome and route it through its derived `on_` slot. ### Changed - A slot written on a composite that declares outcomes, under the name the compiler keeps that composite's expansion members under, is reported as a compile finding instead of being replaced with its children silently dropped. ## [0.30.0] 2026-09-13 0.30.0 is a minor, because what a composite compiles to changes. A composite that declares `outcomes` now compiles to a state of its own with one `` per declared name, and the enclosing body routes its completion through a derived `on_` slot per declared outcome (ADR-0002 C6 and C7). Beside that, a `core.on_event` `capture` literal carrying a raw control character is now refused at compile. ### Changed - A `core.on_event` `capture` literal carrying a raw control character other than tab, line feed or carriage return is now refused at compile, on the `capture` key, because the value reaches an XML attribute raw and XML 1.0 admits no such character there. - A composite that declares `outcomes` now compiles to a state of its own with one `` per declared name, so an enclosing body can route its completion, and it derives one `on_` slot per declared outcome for the blocks that run when it finishes that way. - A composite declaration whose `slots:` names a pass-through slot after one of its own declared outcomes is now refused, because the two kinds of slot cannot share a name; rename one of them. ## [0.29.0] 2026-09-13 0.29.0 is a minor, and its one consumer-visible requirement comes first: **the `predicator` floor moves from `~> 9.0` to `~> 9.4.1`**. That is the version whose string lexer reads a literal back whole, and it is what the release's one behaviour change needs - a `core.on_event` capture pair's literal source now accepts a string carrying any character, so the interim restriction that kept a literal inside printable ASCII is lifted and a handler may capture a label such as `"Café inscrit"`. Beside that, this release is about an editor that tells the truth about what it will accept. A literal capture pair draws a read-only row rather than going missing from the form that cannot author it, and editing a `core.on_event` block no longer drops one. A read-only mount withholds the card controls it refuses and names the arm behind an empty slot. And two composite-facing reports are corrected: a member the palette cannot resolve no longer lends the composite a raisable outcome, and a summary chip that is both translated and over the cap still carries its declared event name. ### Added - A literal capture pair - `["const", value]` - draws a read-only row in the editor's capture section, so a pair the two controls cannot author is visible rather than absent. ### Changed - A `core.on_event` capture pair's literal source - `["const", value]` - now accepts a string carrying any character. The interim restriction that a literal string stay inside printable ASCII, tab, newline and carriage return is lifted: it was earned only while predicator 9.4.0's string lexer wrote a literal's codepoints back one byte at a time, and 9.4.1 fixed that lexer. A handler may now capture a label such as `"Café inscrit"` and the datamodel reads it back whole. - Dependency floor: `predicator` moves from `~> 9.0` to `~> 9.4.1`. That is the version whose string lexer reads a literal back whole, which is what the lifted restriction above needs; 9.4.0 and below are excluded. ### Fixed - A read-only editor mount no longer draws the card controls it refuses: "Replace with its steps" and Delete are withheld, the way the palette column and the gap "+" already were. - A composite member whose block type the palette cannot resolve no longer contributes the default `done` outcome to the composite's raisable set, so a declared outcome name is no longer accepted on the strength of a missing palette entry. - A summary chip that is both translated and over the presentation cap now carries its declared event name on the chip's `title`, rather than the clipped chip's own full translated text, so the generated event name is still on the card for a reader debugging against the compiled chart. - Editing a `core.on_event` block no longer drops its literal capture pairs: a pair the form could not draw was previously replaced away by the next change the form posted. - A read-only editor mount's empty slot now names the arm it draws the placeholder for, so a screen reader hears which arm is empty instead of hearing the slot header and nothing. ## [0.28.0] 2026-09-12 0.28.0 is a minor, and its two behaviour changes come first. **The compiled chart of a document with a failure-classed final moves**: the reserved `` param the compiler mints on such a final is now named `statifier_persistence:execution_status` rather than `statifier_persistence:run_status`, so a durable host that reads that key needs `statifier_persistence >= 0.12`, which is the floor for the new name. And **a `core.on_event` capture pair whose source is absent from the event payload no longer writes `:undefined`** - the destination is left unwritten, so a document that captures by a path compiles to a different chart and a stored compiled document has to be recompiled. A document with no failure-classed final, and a handler that captures nothing or captures only literals, compile byte for byte to what they compiled to before. Beside those, this release is about what a capture and a composite may say for themselves. A capture pair may take a literal source, written `["const", value]`, so a handler records a value the document states rather than one the event's payload has to carry. A composite may declare its own `outcomes`, checked at Resolve against what its expansion can raise. And the editor's `profile` assign takes a `run?` key that seats no run at all when it is false, rather than merely hiding the run pane. ### Added - A composite declaration may carry `outcomes`, a list of outcome names it declares for itself, on both the `use` form and the data form. Present, the list replaces the expansion root's derived outcomes - each name labelled by the member that raises it - and the compiler checks at Resolve that the expansion can raise every declared name, reporting an `:outcome_not_raisable` finding against the composite block when it cannot. Absent, nothing changes: a document that writes no `outcomes` key compiles to the same bytes as before. - The editor's `profile` assign takes a `run?` key: `run?: false` mounts an editor that seats no run at all, so there is no run pane, no run marks on the canvas and no **Held here** column, whatever the host passes in `run` and `run_session`. It defaults to `true`, and it does not touch the marks a host paints itself through `active_marks` and `invoke_mark`. - A `core.on_event` capture pair may take a literal source, written `["const", value]` in the block document, so a handler records a value the document states rather than one the firing event's payload has to carry; a string source is still the payload path it has always been, and the two are told apart by shape. ### Changed - The compiled chart of a document with a failure-classed final changes: the reserved `` param the compiler mints on such a final is now named `statifier_persistence:execution_status` instead of `statifier_persistence:run_status`. Upgrade a durable host to `statifier_persistence >= 0.12`, which is the floor for reading the new key; 0.12 reads both keys for one release and 0.13.0 reads only the new one. A document with no failure-classed final compiles byte for byte to what it compiled to before. Both names stay refused for a `donedata_type/1` declaration while the old one is still read. - A `core.on_event` capture pair whose source is absent from the event payload no longer writes `:undefined`; the destination is left unwritten, so "not answered" and "answered with nothing" are different values and a reader tests a captured path by asking whether it is there. A document that captures by a path compiles to a different chart - each such pair's `` is now wrapped in an `` that tests the path - so recompile stored documents; a handler that captures nothing, and a pair whose source is a literal, compile byte-identically. A reader that tested a captured path for `:undefined` should test it for presence instead. ## [0.27.0] 2026-09-08 0.27.0 is a minor, and its two breaking changes come first. **The compiled chart of every document holding an interruptible group moves**: a group's two interrupt transitions and the `` of the interrupt pair inside its rail now carry that group's own emitted state id, so a stored compiled chart or a pinned chart identity for such a document must be re-captured. The spelling an author configures and the pair a host block type raises do not change - the salt is applied at emit, and a raise outside any rail is emitted unchanged. And **`StatifierBlocks.Composite.expand/2` answers a tuple**, `{:ok, {blocks, param_map}} | {:error, reason}` instead of the bare `{blocks, param_map}` pair, and no longer raises; `expand!/2` is the raising spelling the compiler's Resolve and the editor call, and a caller that wants the old return and the old raise adds one character. Beside those, this release is about **admission** and **the card face**. Admission now resolves a composite's members through the palette it is asked about - `Assignability.kinds/3`, `slot_accepts/4` and `admits?/4` take the palette first - so a host-rooted composite is admitted on the kinds that host declares and a drop is refused exactly where a compile would refuse it. Beside the `Edit.Targets.accepted_types/4` sweep there is now a per-target fast path, `admits_at?/5` and `accepted_types_at/5`: one probe and one check at the slot's append gap, which is the call a "+" chooser at a gap should make. `Assignability.assignable?/5` takes a `strict: true` that refuses a pair either side of which resolves to `:unknown`. On the card, the summary-chip presentation cap is 32 characters rather than 24, and a chip past it is drawn clipped with an ellipsis and its full text on the chip's `title` instead of being dropped. A presentation-cap `:lint` finding is read in the drawer's Findings tab rather than on the card face, and a finding that does draw on a face is laid out inside the card's own box. The card's controls moved into a reserved strip beside the title, so a title that wrapped to two lines is never covered and nothing truncates; "Save as a step" and its marking tray are no longer drawn on a mount that registered no `on_collapse`. Two class contracts moved with those: `.sb-node__chrome > .sb-node__strip > ...` for the controls, and `.sb-node__chrome > .sb-finding` for a face finding. For a host drawing its own surface, `Editor.ConfigForm.config_form/1` takes an `event` attr defaulting to `"config-change"` and posts the block id as a hidden input, so one call replaces a hand-written field pair, and `Edit.Session.refusal/1` says what a refused gesture refused in one sentence - the same sentence the editor now draws under its own toolbar. ### Added - `StatifierBlocks.Composite.expand!/2` is the raising spelling of the expansion: it keeps the return and the broken-declaration raises `expand/2` had, and it is what the compiler's Resolve, the environment walk and this module's own derivations call. - A data composite draws the summary chips its `use`-composite twin draws: one chip per param the config gives a value to, minus those declared `hidden?: true`. - `StatifierBlocks.Edit.Session.refusal/1` says what is in a session's `last_error` as one sentence, so a host driving the same commit funnel draws the same words for the same refusal. - `StatifierBlocks.Edit.Targets.admits_at?/5` answers whether one block type would be accepted at one `{parent_id, slot}` target, with one probe and one `StatifierBlocks.Assignability.check/5` at the slot's append gap instead of the whole-document walk `accepted_types/4` runs per candidate - the call a "+" chooser at a gap should make. - `StatifierBlocks.Edit.Targets.accepted_types_at/5` asks that question over a candidate list, defaulting to the palette's own types, so a surface with a shortlist pays for the shortlist. `accepted_types/4` is unchanged and stays the sweep; the module's moduledoc says which of the three to call. - `StatifierBlocks.BlockType.summary_refusal_message?/1` says whether a message is one `summary_refusal_message/4` wrote, which is how a surface tells a presentation-cap diagnostic from every other `:lint` finding. - `StatifierBlocks.Assignability.assignable?/5` takes an options keyword whose `strict: true` refuses a pair either side of which resolves to `:unknown`, for the caller that must not admit a value nothing has typed. The host relation is not asked about an unknown side. - The option defaults to `strict: false`, so `assignable?/3` and `assignable?/4` decide exactly what they decided before. - `StatifierBlocks.Assignability.kinds/3`, `slot_accepts/4` and `admits?/4` take a palette as their first argument and resolve a composite's members through it, so a composite whose expansion is rooted at a host type is admitted on the kinds that host declares rather than on the `[:step]` fallback the core-only `kinds/2`, `slot_accepts/3` and `admits?/3` reach. The `c:StatifierBlocks.BlockType.io/1` callback is unchanged and gains no palette argument. - `StatifierBlocks.Editor.ConfigForm.config_form/1` takes an `event` attr, defaulting to `"config-change"`, which is written to both `phx-change` and `phx-submit`, so a host can draw one block's fields under its own `handle_event/3` instead of hand-writing the field pair. The block the params are about still arrives as the hidden `block-id` input the form already posted. ### Changed - The card's controls moved into a `.sb-node__strip` element inside `.sb-node__chrome`. A host stylesheet or test selecting `.sb-node__chrome > .sb-node__remove`, `> .sb-node__expand`, `> .sb-node__save-step`, `> .sb-node__fold` or `> .sb-node__offer` should select `.sb-node__chrome > .sb-node__strip > ...` instead. The classes, the `data-reveal` contract and the events are unchanged, and the strip is drawn on every card. Within it the controls are in left-to-right order, so a keyboard now reaches Save before Expand. - `StatifierBlocks.Editor.Canvas.canvas/1`, `.Slot.slot/1` and `.BlockNode.block_node/1` take a `collapsible` attr, threaded the way `expandable` is; it is `false` by default and the editor passes whether its `on_collapse` assign is a one-arity function. - **Breaking.** `StatifierBlocks.Composite.expand/2` now answers `{:ok, {blocks, param_map}} | {:error, reason}` instead of the bare `{blocks, param_map}` pair, and it no longer raises on a broken declaration. A caller that wants the old return and the old raise calls `expand!/2` and needs no other change; a caller that would rather be told than raised at matches on the tuple. - A read-check `:type_mismatch` whose disagreeing writer is a block a composite minted for its own expansion now names the composite the author placed, by that composite's sentence, instead of naming an id the author cannot see, select or edit. A writer the author did place - including a block dropped into a composite's pass-through slot - is still named by its own id. - The finding's reason tuple is unchanged: it still carries the minted id, so a fixture run and the Source tab still say which member of the expansion wrote the entry. - `StatifierBlocks.Composite.expand/2` blames a member carrying more than one param's value on the first param in declaration order, instead of answering `nil` for it; a finding re-anchored onto the composite now names a field to open. A member carrying no param value still answers `nil`. - The summary-chip presentation cap is 32 characters, up from 24. Every message that quotes the cap follows the number; `--sb-card-width` is unchanged, because the cap is a legibility number rather than a measurement of the card. - A summary chip past the cap is now drawn clipped, with an ellipsis in its last position and its full text on the chip's `title`, instead of being dropped. A blank, multiline or non-string chip is still refused. The `:lint` finding that reports the length stays, and its sentence now ends "so it is drawn clipped". - `StatifierBlocks.BlockType.badge/1` is unaffected: an over-long badge is still dropped rather than clipped. - A presentation-cap `:lint` finding no longer draws on the card face; it is read in the drawer's Findings tab, and still counts toward a card's findings rollup. Every other finding a card carries draws where it did. - A finding that does draw on a card face is laid out inside the card's own box. On a container it previously drew full-width between the card and the slot label below it, where it read as belonging to the slot. A host stylesheet targeting `.sb-node > .sb-finding` should target `.sb-node__chrome > .sb-finding` instead. - The compiled chart of every document holding an interruptible group changes: a group's two interrupt transitions, and the `` of the interrupt pair inside its rail, now carry that group's own emitted state id (`statifier_blocks.interrupt.resume.`), so a stored compiled chart or a pinned chart identity for such a document must be re-captured. The spelling an author configures and the pair a host block type raises do not change: the salt is applied at emit, and a raise outside any rail is emitted unchanged. A railed composite can now be nested inside a resumable group's body without the two rails contending for one event name. - `StatifierBlocks.ViewModel.overlay_findings/2` enforces the findings shape `validate_config/1` declares: a block type answering with anything but a list of `{key, message}` string pairs is refused with an error naming that type, rather than failing a clause head that named the view model. - Kind admission inside `check/5`, `valid_targets/4` and `validate/3`, and the editor's expansion check, now route through the palette-carrying arities, so a drop is refused exactly where a compile would be refused. A host-rooted composite that was wrongly admitted at a step slot, or wrongly refused at an interrupts slot, now gets the verdict the compiler gives it. - `config_form/1`'s `target` attr is optional and defaults to `nil`, which renders no `phx-target` anywhere - the case of a host whose form posts to the LiveView it is mounted in. Every present caller passes a target and is unchanged. ### Fixed - The assigns map an `:expression` field hands a host's `expression_component` carries a `debounce` key - the field's own `debounce` value, and `nil` when the caller named none - so an override can rate-limit the way every other control in the same form does instead of posting per keystroke. Overrides that ignore the key are unchanged. - An `:expression` field served through the `expression_component` seam is handed the values the host offered for that field ahead of the document's declared paths - one de-duplicated `candidates` list - instead of the declared paths alone. A host that named values for the field now sees them in its own control, the way the plain input this package renders itself has always shown them; a host that named none sees the declared paths exactly as before. - The "Save as a step" control and its marking tray are no longer drawn on a mount that registered no `on_collapse` callback, and the four events the gesture is made of are answered with the socket unchanged there. The gesture's only outcome is that callback, so a mount without one offered a marking step, a Save, and then silence. "Replace with its steps" is unaffected in both directions: it commits an edit the editor makes itself. - The card's controls no longer draw on top of a title that wrapped to two lines. They sit in a reserved control strip beside the title - a grid column of its own, held whether or not the controls are revealed - so a long name wraps beside them and nothing truncates. - The edit algebra's config gate refuses a `{:update_config, id, config}` whose value for a `{:type_expr, opts}` field is no arm that field admits, so the editor reports it where the edit is made rather than only at compile. - An empty slot on a read-only editor mount now draws a non-interactive placeholder. The mark that says "nothing is here yet" was styled on the gap's "+" button, which a read-only mount does not draw, so an empty arm rendered as a slot header and nothing else. - A read-only editor mount now refuses the Expand gesture. "Replace with its steps" reached the document and fired `on_change` on a mount whose profile said `read_only?: true`, which every other gesture that changes the document already refused. - A gesture the editor refuses now draws the refusal as one sentence in the canvas column, under the toolbar. Every refusal already recorded its reason and nothing read it, so a gesture the editor refused looked on screen exactly like a gesture that did nothing. - A composite's expansion is compiled at each member type's **current** version, so a config value a subtree writes reaches the chart as written rather than through that type's `migrate_config/2`. A subtree naming `core.send` or `core.wait` - the two core types past version 1 - used to have its `delay` or `duration` read as a stored value at version 1 and silently rewritten; such a value is now the author's to write in the accepted spelling, and one that is not is refused by name. A block the document stores is untouched: it still migrates. - `StatifierBlocks.Composite.Collapse.replacement/4` gives the composite it inserts the collapsed arrangement's own block id instead of a freshly minted one, so the state ids of the chart a host gets back after committing the swap are the ones the document implies rather than a new UXID each time. - `use StatifierBlocks.Composite` refuses an option it does not recognize, naming the key, instead of dropping it and compiling the composite with the default the declaration was trying to replace. ## [0.26.0] 2026-09-07 0.26.0 is about what a host does **around** a composite. `StatifierBlocks.Composite.Collapse` reads a selected arrangement back as the `Composite.Data` declaration that stands for it, and the editor's "Save as a step" control hands that declaration to a new `on_collapse` callback - the gesture edits no document and this package persists nothing, because which table a saved step lives in, and whether it is saved at all, is the host's. A composite may now declare **pass-through slots**, so an author puts children into one instead of only filling in params, and `expand/2` splices them into the mapped member's slot with their ids unchanged. A data declaration may carry a `"migrations"` chain, so a block saved against an older revision of a saved composite resolves instead of being refused. And all nine field types now have a JSON spelling, so a declaration held as data reaches the same field-type set a module composite declares. Beside that, this release publishes what a host drawing its own surface over a document was otherwise writing privately: `Composite.io/2` and `outcomes/2` resolved through a palette you supply, a derived `summary/1`, `Edit.Targets.accepted_recipes/4` and `recipe_inserts/4` beside the type half, `Environment.with_writes/4`, `ViewModel.transparent?/2`, `effective_parent/3`, `end_of_list_target/3` and `core_containers/0`, `ViewModel.overlay_findings/2` over the session's own `draft_findings`, `ViewModel.order_palette_groups/2`, a `variant: :inline` on `Editor.Field.field/1`, a `debounce` assign on the editor mount, and `use StatifierBlocks.InvokeStep, failure_outcomes: [...]`. It is a minor, and no compiled chart bytes move: a document holding a composite with a pass-through slot compiles to the bytes of the same document with that composite expanded in place, exactly as one with no slot does. Two things answer differently from 0.25.0 for a host that does nothing: `StatifierBlocks.Palette.new/2` now runs the duplicate-`order` refusal that `from_modules/2` already ran, so a palette built by merging onto `core_types/0` raises where it used to build; and a composite's `slots/1` answers its declared pass-through slots rather than always `[]`. ### Added - `StatifierBlocks.Environment.with_writes/5` is public: `env` with one block's own writes applied, member expansion included. The declarations argument carries a default, so `with_writes/4` is the spelling a caller writes. - `StatifierBlocks.Editor.Field.field/1` takes a `variant` attribute (`:block`, the default and byte-identical to what it rendered before, or `:inline`), so a host placing one field inside a sentence of its own gets the same control, the same posted params and a label that is off the screen but still announced, without the editor gaining a layout mode. - `core.on_event` answers `sentence/1` - "When card.authz_timed_out, abandon" - so a host list view draws the handler's own line instead of the palette label "On event". - `StatifierBlocks.Edit.Targets.accepted_recipes/4` answers which of a palette's recipe names would land at a target, the recipe half of `accepted_types/4`, so a host drawing its own insert picker offers recipes beside block types. - `StatifierBlocks.Edit.Targets.recipe_inserts/4` answers the command list that inserts a named recipe's arrangement at a target, or the refusal, without committing anything. - `ViewModel.transparent?/2`, `effective_parent/3` and `end_of_list_target/3` answer where a row sits and where an append lands once a host has flattened its transparent containers, taking the transparent type names as an argument. - `ViewModel.core_containers/0` names the three core containers a host most often flattens, as the documented default for those readers rather than a built-in policy. - `StatifierBlocks.Edit.Session` carries a `draft_findings` map: the per-field findings each refused `change_config/3` was handed, keyed by block id. - `StatifierBlocks.ViewModel.overlay_findings/2` routes those findings onto a node's form fields, with a finding naming no field landing in `form.unrouted` - the findings half of `overlay_draft/2`. - `StatifierBlocks.Composite.io/2` and `outcomes/2` answer a composite block's io and outcomes with every member resolved through a palette you supply, so a composite rooted at a host block type is exact wherever a palette is in hand. - A composite derives `summary/1`: one card chip per declared param that is not `hidden?: true`, drawn as `"