DocFlow (Mibo)

DocFlow Module

Namespace: Mibo.Markup
Assembly: Mibo.Markup.dll

 The Flow backend for the document surface: parses, resolves, and
 lays a document out through the Flow authoring API
 (`Mibo.Layout.Flow`) — one `Flow.run` per layer; `build` paints
 through the no-registry path and reports no structure.

   Stack pack  -> `Flow.overlay` of stack children: an `x= y=` child
                  becomes `Flow.at`, alignment becomes `Dock` flags
   Flow pack   -> `Flow.grid`: named areas pass through, `col=`/`row=`
                  and flow children place as explicit slots, `auto`
                  tracks size from the children's footprints
   Scatter     -> `Flow.scatter`: the framework's seeded rule places
                  the sized children
   Layers      -> `Flow.runLayers`: one stamp per layer, one grid per
                  layer, bottom first

 Build-time only, like every Flow consumer: the Item tree emits to
 stamps that compose at paint time, so measurement sees the assigned
 rectangle exactly as the document model describes it.

Types

Type	Description
BuiltLayer<'T>	One built layer of a document: its name, its grid, the landmarks that grid reported, and the occupancy that answers which instance owns each cell.

Functions and values

Function or value	Description
`build (surface, src)` Full Usage: `build (surface, src)` Parameters: surface : `Surface<'T>` src : `string` Returns: `Result<CellGrid2D<'T>, string>` Type parameters: 'T	Parses (KDL or XML — the same document in either syntax builds the same grid, pinned by test), resolves, and lays the document out through the Flow API. Parse and resolution failures carry their document positions when the front-end tracks them; emitter-stage failures — a gap mismatch, a bad slot, an unknown area, a mixed pack channel — name the container, and the child when one is at fault. Error builds nothing. The build returns the painted grid and records no landmarks: the emit runs with the tag channel off, and the paint goes through the no-registry path, so a build allocates no landmark memory. A caller that needs the structure — a hover that names the region under the cursor, a walkability walk over a tagged area — runs the same four steps itself and keeps what `Flow.run` hands back: `parse src \|> Result.bind (Doc.resolve surface src) \|> Result.bind (fun items -> Doc.findMapNode roots ...) \|> Result.map (fun dims -> grid \|> Flow.run (emit root))` Every element of the document reports its resolved rectangle under its own name through `Landmarks.Tagged`, plus a per-cell grid for `Flow.isTag`. That registry allocates one grid per name, so a very large document with very many elements pays for each one: build-time memory, released with the build — memory `build` never spends. surface : `Surface<'T>` src : `string` Returns: `Result<CellGrid2D<'T>, string>`
`buildLayers (surface, src)` Full Usage: `buildLayers (surface, src)` Parameters: surface : `Surface<'T>` src : `string` Returns: `Result<BuiltLayer<'T>[], string>` Type parameters: 'T	Parses, resolves, emits, and paints every layer of the document: one grid per layer, in layer order, each built the way `build` builds today (one cell per tile). A document without `layer` containers returns one layer named `main`. The syntax selects the parser, so this is the KDL entry point; `buildLayersXml` takes the same document in XML. surface : `Surface<'T>` src : `string` Returns: `Result<BuiltLayer<'T>[], string>`
`buildLayersXml (surface, src)` Full Usage: `buildLayersXml (surface, src)` Parameters: surface : `Surface<'T>` src : `string` Returns: `Result<BuiltLayer<'T>[], string>` Type parameters: 'T	`buildLayers` with the XML front-end. surface : `Surface<'T>` src : `string` Returns: `Result<BuiltLayer<'T>[], string>`
`buildXml (surface, src)` Full Usage: `buildXml (surface, src)` Parameters: surface : `Surface<'T>` src : `string` Returns: `Result<CellGrid2D<'T>, string>` Type parameters: 'T	`build` with the XML front-end: attributes carry the scalars, so the document reads the way XML means it. surface : `Surface<'T>` src : `string` Returns: `Result<CellGrid2D<'T>, string>`
`emit item` Full Usage: `emit item` Parameters: item : `Item<'T>` Returns: `Stamp<'T>` Modifiers: inline Type parameters: 'T	Emits one item as a Flow stamp: its own body paints its box, then its children paint by the container's pack (stack children, a grid, or seeded scatter). The composite is built inside the stamp's paint, so an emitted document painted onto a second grid lays out again. Every element reports its resolved rectangle under its own name through the tag channel, so a document painted with a landmarks registry reports its structure. item : `Item<'T>` Returns: `Stamp<'T>`
`emitLayers root` Full Usage: `emitLayers root` Parameters: root : `Item<'T>` Returns: `(string * Stamp<'T>)[]` Type parameters: 'T	The map's layers, bottom first: `main` — the map's own body and its non-layer children — when it has any content, then each stated layer in document order: `layer ground { ... }` in KDL, `` in XML. A layer's stamp is `Flow.stretch` over the layer's container, so it spans the whole grid whatever its statements cover; a plain stack child would dock at the layer's measured footprint instead. A document without layer nodes yields exactly one entry, `("main", the emitted root)`, which is the single grid `build` has always returned. `main` needs the map to paint something of its own: a bare statement in the map body, or a non-layer child. A map that holds only layer containers has no `main`. root : `Item<'T>` Returns: `(string * Stamp<'T>)[]`
`emitTags reportTags item` Full Usage: `emitTags reportTags item` Parameters: reportTags : `bool` item : `Item<'T>` Returns: `Stamp<'T>` Type parameters: 'T	Emits one resolved item as a Flow `Stamp`, recording element names and tags when `reportTags` is true. This is the recursive walk behind `emit` and `emitLayers`; call those instead. reportTags : `bool` item : `Item<'T>` Returns: `Stamp<'T>`