@pipelex/mthds-form 0.8.0 → 0.10.0

package/dist/layout-design.mthds

@@ -0,0 +1,452 @@
+domain      = "generative"
+description = "Lays out one page for a method - its inputs, or its result - as a json-render spec over a catalog of components, bound to the state the host provides."
+main_pipe   = "design_layout"
+
+# The designer method. THIS FILE IS THE PROMPT: every paragraph the models
+# read - the output format, the state contract, the design direction, the
+# rules, the seed procedure, and the brief's own prose - is written here, and
+# the only things rendered into it are the inputs. The catalog arrives as DATA
+# (the components with their props signatures and descriptions, the actions),
+# so a component added to the vocabulary appears in the prompts with no change
+# here, and the prose that names components (the direction, the rules) is the
+# method's own reading of the vocabulary it was written for. The brief arrives
+# as data too: the page's paths with their kinds, presence and constraints,
+# which of them are delegated, what gates the run, and on a result page the
+# state of one real run - and `render_brief` below is the template that lays
+# it out as the Markdown both models read.
+#
+# It runs in three stages, and `design_layout` is the sequence of them:
+#
+# - `render_brief` lays the brief out. It is a Jinja2 template over the data,
+#   with no model behind it, and its text is what the two stages below read
+#   under `@brief_text`. Every sentence of the brief - the headings, how a
+#   path line reads, what "delegated" says - is here and nowhere else.
+# - `plan_page` reads the brief and the catalog - and the creative seed, when
+#   there is one - and writes a PagePlan: what the page is for, its title,
+#   its composition, its regions with the elements and paths each holds, what
+#   runs the method, the defaults and what is delegated. The plan is a
+#   structured output, so the runtime holds it to the shape declared below.
+# - `emit_page` builds exactly that page: it is handed the plan, the catalog
+#   with every props signature, and the brief, and emits the JSONL patches.
+#
+# The split is the point. A single completion asked for a whole page decides
+# the page and writes every patch in the same breath, and nothing in between
+# can be read; the plan can. The seed reaches the planner only, because the
+# plan is where two runs of the same brief diverge, and the builder follows
+# the plan.
+#
+# Neither prompt prescribes a composition. There is no skeleton a page must
+# have, no region it must contain, no place a control must sit, and the prose
+# names none of the catalog's chrome components: what a component is for is
+# in its own description, which travels as data - and the one control that
+# runs the method is named by the brief, as data, for the same reason. The
+# rules that remain are the ones a page is wrong without - the brief's paths,
+# the bindings that fit, delegation, who owns the state, one control that
+# runs the method, heading order, integrity of the tree. The shape of the
+# page is the planner's decision, written into the plan, and the builder's
+# job is to build it.
+#
+# Three things to know before editing the prompts:
+#
+# - A literal dollar sign is written `$$`, because `$name` is the language's
+#   inline-substitution shorthand. Every json-render expression key in the
+#   prose (`$$state`, `$$bindState`, `$$item`, `$$cond`, `$$template`, ...)
+#   is spelled that way and renders as a single `$`, in the brief's template
+#   as much as in the prompts.
+# - The component and action lists, and the plan, are Jinja2 loops in the two
+#   prompts, which keep every newline they are written with. A loop body ends
+#   with its own newline, so the heading that follows a loop sits directly
+#   under `{% endfor %}` to render exactly one blank line between the two.
+# - The brief's template is a `markdown` template, and that category trims:
+#   a line holding only a `{% %}` tag renders as nothing, so a loop or a
+#   condition is written on lines of its own and the text between them keeps
+#   its own newlines. Two traps. A line that ENDS with a `{% %}` tag loses
+#   its newline with it, so such a tag is closed with `+%}`, which keeps the
+#   newline. And every `{% set %}` is written at the top level of the
+#   template, before any text, never inside a loop or a condition: the
+#   runtime reads a name set inside a block as an input the pipe did not
+#   declare, and refuses the method.
+#
+# The output is Text carrying JSONL patches - the format the prompt asks for -
+# rather than a typed structure: a spec is a map of heterogeneous elements
+# whose props are typed per component, which a structure cannot state and which
+# the renderer already validates per component. The harness that runs this
+# method (scripts/generate-fixtures.mjs --specs) compiles and validates the
+# text, and fails loudly on any issue, so a repair is a change HERE, never to
+# the fixture.
+#
+# Both model stages pin the same model. The specs pass takes MODEL=<id> to
+# override every pin at once for a comparative run (and TEMPERATURE=<n> for a
+# model that fixes its own), and records which model produced each fixture.
+#
+# The optional `seed` is the creative seed of the planner's last section: a
+# random string the harness generates, handed over as one line the prompt
+# labels, so two runs of the same brief diverge. Absent, the planner designs
+# from the brief alone, and the guarded reference below prints nothing.
+
+[concept.Catalog]
+description = "The vocabulary a page may be made of: the components a renderer implements and the actions a page may bind to an event, each with its contract."
+
+[concept.Catalog.structure]
+components = { type = "list", item_type = "concept", item_concept_ref = "Component", description = "Every component a spec may name, in the order the prompt lists them.", required = true }
+actions    = { type = "list", item_type = "concept", item_concept_ref = "Action", description = "Every action a spec may bind, the runtime's built-in ones first.", required = true }
+
+[concept.Component]
+description = "One component of the catalog: its name, the signature of its props, what it is for, and what it accepts."
+
+[concept.Component.structure]
+name             = { type = "text", description = "The component's name, exactly as a spec's \"type\" spells it.", required = true }
+props            = { type = "text", description = "The signature of its props as one object literal, each prop with its type and a question mark when it may be omitted.", required = true }
+description      = { type = "text", description = "What the component is for and how to use it, as its author wrote it." }
+accepts_children = { type = "boolean", description = "Whether the component renders the elements listed in its \"children\".", required = true }
+slots            = { type = "list", item_type = "text", description = "Its named slots, when it has any beyond its children." }
+events           = { type = "list", item_type = "text", description = "The events it emits, which a spec binds through the element's \"on\" field." }
+
+[concept.Action]
+description = "One action a page may bind to an event: its name, what it does, and whether the runtime handles it on its own."
+
+[concept.Action.structure]
+name        = { type = "text", description = "The action's name, exactly as a binding spells it.", required = true }
+description = { type = "text", description = "What the action does and the params it takes.", required = true }
+built_in    = { type = "boolean", description = "True when the runtime handles the action without a handler from the host.", required = true }
+
+[concept.Brief]
+description = "The page's half of the prompt, as data: which page it is and for which pipe, every path in the state with what it is, which paths are delegated and what gates the run, and on a result page the state of one real run - rendered from the method's own descriptor and from nothing else."
+
+[concept.Brief.structure]
+side         = { choices = ["input", "result"], description = "Which page is being designed: the form a run is started from, or what a run produced.", required = true }
+pipe_ref     = { type = "text", description = "The pipe the page is for, as `domain.pipe_code`.", required = true }
+description  = { type = "text", description = "One sentence on what the page is about: the pipe's own description, or the host's summary of it." }
+name         = { type = "text", description = "On an input page, the method's name as the host lists it - the one product name the page may carry. Absent when the host lists none." }
+paths        = { type = "list", item_type = "concept", item_concept_ref = "PathEntry", description = "Every path in the state the page binds or reads, in reading order and flattened: a structure's members follow it one level deeper, and a list's item members follow the list, spelled relative to one item.", required = true }
+run_control  = { type = "text", description = "On an input page, the catalog component that runs the method, by name; the page has exactly one of it." }
+sample_state = { type = "text", description = "On a result page, the state of one real run as the host loads it, as JSON - what `/result` held after one actual run, so magnitudes and lengths can be judged. Never copied into a page." }
+
+[concept.PathEntry]
+description = "One path of the state, as the brief describes it: where it is, what it holds, what it is called, what constrains it, and whether the page lays it out or hands it back to the kernel's own control."
+
+[concept.PathEntry.structure]
+depth            = { type = "integer", description = "How deep the path sits under the page's root, for the indentation of its line: 0 for a top-level input or the result itself.", required = true }
+path             = { type = "text", description = "The path, spelled exactly as the page binds or reads it: absolute (`/inputs/request/city`), or relative to one item of the list above when `relative` is set (`city`, or `teams/<i>/name` inside a nested list).", required = true }
+kind             = { type = "text", description = "What the path holds, in words: `text`, `number`, `integer`, `boolean`, `date`, `prose (markdown)`, `choice of \"a\" | \"b\"`, `document (a file)`, `image (a file)`, `structure <concept>`, `list of <kind>`, or the native concept it carries.", required = true }
+name             = { type = "text", description = "The member's name as the method spells it. Absent on the result's own root entry, which is the whole result." }
+title            = { type = "text", description = "The member's human title, when the method gives one that differs from its name." }
+description      = { type = "text", description = "What the member is for, as the method's author wrote it." }
+required         = { type = "boolean", description = "On an input page, whether the input must be filled before the run: true for a required input, false for an optional one." }
+gating           = { type = "boolean", description = "On an input page, true when the run waits for this input - a top-level fact only." }
+notes            = { type = "list", item_type = "text", description = "The constraints and hints in words, each on its own: `min 1`, `at most 80 characters`, `default \"x\"`, `examples ...`, `hints intent=label`." }
+default          = { type = "text", description = "The authored default value, as JSON, when the method states one - the seed a `/state` patch sets." }
+delegated        = { type = "boolean", description = "True when the page hands the path back to the kernel's own control - MthdsField on an input page, MthdsResult on a result page - because the catalog cannot enter or show it. A delegated structure's members are not listed.", required = true }
+relative         = { type = "boolean", description = "True when the path is spelled relative to one item of the list above it, as a DataTable column or `$item` reads it, rather than from the page's root." }
+item_kind        = { type = "text", description = "On a list whose items the brief describes: what one item holds, in the same words as `kind`." }
+item_description = { type = "text", description = "On a list whose items the brief describes: what one item is for, as the method's author wrote it." }
+item_laid_out    = { type = "boolean", description = "On a list whose items the brief describes: true when the item's members follow this entry, one each, spelled relative to one item." }
+
+[concept.PagePlan]
+description = "The designer's plan for one page, settled before any element is written: what the page is for, how it is composed - a decision the plan makes, with no shape given in advance - what each region shows or collects and with which components, what runs the method, and what is delegated."
+
+[concept.PagePlan.structure]
+purpose        = { type = "text", description = "One sentence: what this page is FOR and who is standing in front of it. It decides the shape, the order, the grouping and the tone of everything below.", required = true }
+title          = { type = "text", description = "The page's title, in a person's words: named after the job - \"Plan the trip\", never \"TripRequest\". It is the page's one h1; where it sits and what carries it is the composition's call.", required = true }
+composition    = { type = "text", description = "The shape of the whole page in a few sentences, decided for this page alone: how the space is divided, what comes first and largest, what stands beside what, what is grouped with what and why, what is staged or folded away, and where the method is run on an input page. No shape is given in advance; this is where it is decided.", required = true }
+regions        = { type = "list", item_type = "concept", item_concept_ref = "PlannedRegion", description = "The regions of the page in reading order, whatever the composition makes them: the parts of a column, the steps of a journey, the tabs, a panel beside the work, a band of figures. Every element the page lays out sits in one of them.", required = true }
+call_to_action = { type = "text", description = "On an input page, the words on the one control that runs the method - naming the job, \"Plan my trip\", never \"Submit\" - and the hint beside it, if one is needed. Empty on a result page." }
+defaults       = { type = "list", item_type = "text", description = "On an input page, the defaults the brief lists under \"Defaults\", one per line as a path and its value. Nothing else: no other /state patch is ever emitted." }
+delegated      = { type = "list", item_type = "text", description = "Every path the page delegates whole - to MthdsField on an input page, to MthdsResult on a result page - with a few words on why: the brief marks it delegated, or it is a structure the page chooses not to lay out." }
+
+[concept.PlannedRegion]
+description = "One region of the page: what it is titled, if it is titled, what it is for, what it is built with, and the elements inside it, each with the path it binds."
+
+[concept.PlannedRegion.structure]
+title     = { type = "text", description = "The words the region is titled with, in a person's words, when the composition titles it; otherwise empty." }
+purpose   = { type = "text", description = "What this region shows or collects, and why it sits where it does.", required = true }
+container = { type = "text", description = "The component the region is built with, by its catalog name, when the composition has settled it; otherwise empty, and the builder chooses one that builds what the composition describes." }
+elements  = { type = "list", item_type = "text", description = "The elements inside it in order, one line each: the component by its catalog name, the path it binds or reads spelled exactly as the brief lists it, and the choices it lists when it lists any. A container names what it holds.", required = true }
+
+[pipe.design_layout]
+type = "PipeSequence"
+description = "Design one page from the catalog and the brief: lay the brief out, plan the page from it, then build it as the JSONL patches of a spec bound to the host's state."
+inputs = { catalog = "Catalog", brief = "Brief", seed = "Text?" }
+output = "Text"
+steps = [
+  { pipe = "render_brief", result = "brief_text" },
+  { pipe = "plan_page", result = "plan" },
+  { pipe = "emit_page", result = "page" },
+]
+
+[pipe.render_brief]
+type        = "PipeCompose"
+description = "Lay the brief out as the Markdown both model stages read: the page and its pipe, the state and every path in it, what is delegated, and - on an input page - the defaults and what runs the method, or - on a result page - the state of one real run."
+inputs      = { brief = "Brief" }
+output      = "Text"
+
+[pipe.render_brief.template]
+category = "markdown"
+template = """
+{% set hatch = "MthdsField" if brief.side == "input" else "MthdsResult" %}
+{% set delegated = brief.paths | selectattr("delegated") | rejectattr("relative") | list %}
+{% set defaults = brief.paths | selectattr("default") | list %}
+{% set gating = brief.paths | selectattr("gating") | list %}
+# {{ "Input" if brief.side == "input" else "Result" }} page: {{ brief.pipe_ref }}
+
+{% if brief.description %}
+{{ brief.description }}
+{% elif brief.side == "input" %}
+A method with the inputs below.
+{% else %}
+The result of a method, described below.
+{% endif %}
+
+{% if brief.name %}
+## Name
+
+The method is called «{{ brief.name }}», as the host lists it. That is the app's name wherever the layout asks for one; invent no other. Links, if the layout carries any, name this page's own sections. The page states nothing the method does not: no promise about storage, privacy, speed, or what happens after the run.
+
+{% endif %}
+## State
+
+{% if brief.side == "input" %}
+The form's values live under `/inputs`, one member per input, exactly as listed. Bind each input with `$$bindState` at its path; a structure's members bind at their own paths beneath it.
+{% else %}
+The host loads the run's result under `/result` before the page renders. Read every value with `$$state`; emit no `/state` patches. Paths:
+{% endif %}
+
+{% for entry in brief.paths %}
+{{ "  " * entry.depth }}- `{{ entry.path }}` — {{ entry.kind }}{% if brief.side == "input" %}, {{ "required" if entry.required else "optional" }}{% if entry.gating %}, gates the run{% endif %}{% endif %}{% if entry.name %} — {% if entry.title %}{{ entry.title }} (`{{ entry.name }}`){% else %}`{{ entry.name }}`{% endif %}{% endif %}{% if entry.description %}: {{ entry.description }}{% endif %}{% if entry.notes %} ({{ entry.notes | join("; ") }}){% endif %}{% if entry.delegated and entry.relative %} (a DataTable prints it as text; delegate the whole list to {{ hatch }} to render it properly){% elif entry.delegated %} **[delegate: {{ hatch }}]**{% endif +%}
+{% if entry.item_kind %}
+{{ "  " * (entry.depth + 1) }}- each item is a {{ entry.item_kind }}{% if entry.item_description %} ({{ entry.item_description }}){% endif %}{% if entry.item_laid_out and entry.relative %}, with:{% elif entry.item_laid_out %}, with these members (paths relative to one item, for DataTable columns or $$item):{% endif +%}
+{% endif %}
+{% endfor %}
+
+## Delegated
+
+{% if delegated %}
+{% if brief.side == "input" %}
+Render these with `MthdsField` at the path, and nothing else:
+{% else %}
+Render these with `MthdsResult` at the path - they are kinds the catalog cannot show properly:
+{% endif %}
+
+{% for entry in delegated %}
+- `{{ entry.path }}` ({{ entry.kind }})
+{% endfor %}
+{% elif brief.side == "input" %}
+None: every input can be entered with the catalog's own inputs. `MthdsField` remains available for any you would rather not style.
+{% else %}
+None. `MthdsResult` remains available for any structure you choose not to lay out.
+{% endif %}
+{% if brief.side == "input" %}
+
+## Defaults
+
+{% if defaults %}
+Seed these, and only these, with `/state` patches (`{"op":"add","path":"/state/inputs/...","value":...}`):
+
+{% for entry in defaults %}
+- `{{ entry.path }}` = {{ entry.default }}
+{% endfor %}
+{% else %}
+None. Emit no `/state` patches.
+{% endif %}
+
+## Run
+
+{% if gating %}
+The run waits for `{{ gating | map(attribute="name") | join("`, `") }}`; say so near the {{ brief.run_control }}, briefly.
+{% else %}
+Nothing gates the run.
+{% endif %}
+The page has exactly one `{{ brief.run_control }}`, `on.press` bound to `validateForm` then `run`; label it with what the method does, in a person's words.
+{% else %}
+
+## One real run, as loaded
+
+The state of one actual run, so you can judge magnitudes and lengths. Bind to the paths; do not copy these values into the spec.
+
+```json
+{{ brief.sample_state }}
+```
+{% endif %}
+"""
+
+[pipe.plan_page]
+type = "PipeLLM"
+description = "Read the brief and plan the page: what it is for, how it is composed, what each region holds and with which components, what runs the method, and what is delegated."
+inputs = { catalog = "Catalog", brief_text = "Text", seed = "Text?" }
+output = "PagePlan"
+model = { model = "claude-5-sonnet", temperature = 0.5, max_tokens = 8192 }
+system_prompt = """
+You are a product designer with taste. You plan ONE page for a method - its inputs, or its result - to be built from a fixed catalog of components and bound to state the host provides. The page must read as a small, purpose-built web app, never as a form. Its shape is yours to decide: nothing here prescribes one. You write the plan and a second designer builds the page from it, so every decision you leave open is one they will make without you.
+"""
+prompt = """
+YOUR JOB:
+Plan the page; do not build it. Decide what the page is for and name it after the job, decide its composition, list its regions with the elements each holds and the path each element binds, write the words on the control that runs the method, and name what is delegated. Be concrete: a component by its catalog name, a path exactly as the brief spells it, a choice list exactly as the brief lists it. Write nothing the builder would have to guess at, and nothing they do not need.
+
+STATE:
+The host owns the state. The brief lists every path in it, with its kind and meaning, and it is the ONLY source of paths: every value the page shows or binds is at a path the brief lists, spelled exactly as written. On a result page the host loads /result before the page renders and the page sets no state of its own. On an input page the form's values live under /inputs, and the only state the page sets is the defaults the brief lists.
+
+DESIGN DIRECTION:
+- You are designing a small web app, not a form. A person should open this page and feel it was built for this one job by a studio that cares - the way a product built on Lovable, or by a design-led startup, feels - and never that a schema was transcribed into fields.
+- Start from the feeling. Decide in one sentence what this page is FOR and who is standing in front of it; let that decide the shape, the order, the grouping and the tone. Name the page after the job, not the concept: "Plan the trip", not "TripRequest".
+- The composition is yours. The catalog is the whole vocabulary and no arrangement of it is prescribed: how the space is divided, what comes first and largest, what stands beside what, what is staged or folded away, where the method is run - decide each for this page, from its purpose, and write the decision down. A component is there to be used when it serves the page and left alone when it does not.
+- Prefer the control that feels like an app: Segmented for a choice of up to five options, Radio for a choice that needs a word of explanation, Switch for a yes/no that changes the page, Checkbox for one that does not, NumberInput for a figure, Textarea for prose, Input for a short text. Use Select only when the options do not fit on one line.
+- Restraint reads premium. No label that restates the obvious, no card inside a card, no paragraph that explains the form, no more than two levels of heading. Every element must earn its place; when in doubt, remove it.
+- Write copy a person would say: short labels, one helper sentence where a label is not enough and none where it is. The control that runs names the job ("Plan my trip"), never "Submit".
+- Every value binds to a path the brief lists, and the page reads clearly in both a light and a dark theme.
+
+AVAILABLE COMPONENTS ({{ catalog.components | length }}):
+
+{% for component in catalog.components -%}
+- {{ component.name }}{% if component.description %}: {{ component.description }}{% endif %}
+  {%- if component.accepts_children and component.slots %} [accepts children; slots: {{ component.slots | join(", ") }}]
+  {%- elif component.accepts_children %} [accepts children]
+  {%- elif component.slots %} [slots: {{ component.slots | join(", ") }}]{% endif %}
+  {%- if component.events %} [events: {{ component.events | join(", ") }}]{% endif %}
+{% endfor %}
+PLANNING RULES:
+1. The brief is the ONLY source of paths. Every element binds a path the brief lists, exactly as written; the page shows nothing the state does not carry, and invents no data.
+2. Delegate the paths the brief marks as delegated: MthdsField for an input, MthdsResult for a result, at the path and nothing else. Never plan another component over a delegated path.
+3. Lay out what you understand and delegate what you do not. A structure you choose not to lay out is delegated whole by its path; that is a valid choice, not a failure.
+4. Bind only what fits: a Segmented, Radio or Select lists exactly the brief's choices, spelled exactly; a NumberInput takes a number path; a Switch or Checkbox a boolean path; an Input a text path; a Textarea a prose path. A component that shows a value - a Metric, a Text, a Heading, a line that restates one - reads a scalar path: text, prose, number, boolean, date or choice, never a structure, a list or a file. A structure is shown through its members, a list through a repeat or a DataTable, a file through the delegated control.
+5. Every input the run waits for is on the page, in some region: laid out with the catalog's inputs, or delegated with MthdsField at its path. A Step or a Tab hides an input from the eye, never from the run: every input sits in some panel.
+6. Tabs and Steps hold exactly one panel per tab or step, in the same order, usually a Stack. Their own state - the active tab, the current step, an open Collapsible - is theirs, never the host's.
+7. An input page has exactly ONE control that runs the method, wherever the composition puts it, and no other Button: a Button bound to nothing does nothing, and navigation is never built out of Buttons, since Steps and Tabs carry their own.
+8. On an input page the only state the page sets is the defaults the brief lists under "Defaults"; on a result page it sets none.
+
+CREATIVE SEED:
+When a creative seed follows the brief, it is your ONLY source of variety. Read it the way a designer reads a found object: its runs of letters, its rare characters, its numbers, its rhythm. Derive from it a creative direction - the composition, the density, the tone of the copy, which controls you favour, where the emphasis sits - and commit to it.
+Never show, quote or mention the seed. Two designers given different seeds must produce visibly different pages from the same brief; a designer given no seed designs from the brief alone.
+
+---
+
+Below is the brief for the page you are planning. It is the ONLY source of paths: every value the page shows or binds must be at a path the brief lists, spelled exactly as written.
+
+@brief_text
+
+---
+
+@?seed
+
+---
+
+Plan this page.
+"""
+
+[pipe.emit_page]
+type        = "PipeLLM"
+description = "Build the page the plan describes: emit the JSONL patches of a spec over the catalog, bound to the host's state at the paths the brief lists."
+inputs      = { plan = "PagePlan", catalog = "Catalog", brief_text = "Text" }
+output      = "Text"
+# The object form, because the default output cap (4096 tokens on this model)
+# is not enough for a page over a deeply nested result: the Company hero's
+# first run spent exactly 4096 tokens and came back empty. The object form
+# requires a temperature; this is the runtime's own default, so the setting
+# the earlier captures ran under is unchanged.
+model = { model = "claude-5-sonnet", temperature = 0.5, max_tokens = 16384 }
+system_prompt = """
+You are a product designer with taste, building ONE page for a method - its inputs, or its result - as a JSON spec over a fixed catalog of components, bound to state the host provides. A designer has planned the page; you build exactly that page, and it must read as a small, purpose-built web app, never as a form.
+"""
+prompt = """
+OUTPUT FORMAT (JSONL, RFC 6902 JSON Patch):
+Output ONLY JSONL: one JSON object per line, no prose, no markdown, no code fences. Each line is a patch operation building the spec.
+First set /root, then add each element under /elements/<key>, parents before children, so the page fills in progressively as it streams.
+
+Example output (each line is a separate JSON object):
+
+{"op":"add","path":"/root","value":"page"}
+{"op":"add","path":"/elements/page","value":{"type":"Stack","props":{"direction":"vertical","gap":"lg"},"children":["title","total"]}}
+{"op":"add","path":"/elements/title","value":{"type":"Heading","props":{"text":{"$$state":"/result/reference"}},"children":[]}}
+{"op":"add","path":"/elements/total","value":{"type":"Metric","props":{"label":"Total","value":{"$$state":"/result/total"},"format":"decimal"},"children":[]}}
+
+STATE:
+The host owns the state. The brief you are given lists every path in it, with its kind and meaning. Read a value with { "$$state": "/path" }; bind an input two-way with { "$$bindState": "/path" }. Inside a repeated element, read the current item with { "$$item": "field" } and bind with { "$$bindItem": "field" }.
+Do NOT invent data. On a result page, never emit /state patches: the host loads /result. On an input page, /state patches are for the listed defaults only.
+
+DYNAMIC LISTS (repeat field):
+An element with a top-level "repeat": { "statePath": "/path/to/array", "key": "<id field>" } renders its children once per array item. For an array held on the enclosing item, use "repeat": { "statePath": { "$$item": "field" } } - valid only inside another repeat. "repeat" is a field of the element, not of "props".
+A DataTable is the simpler way to show a list of structures: bind its rows once and name the columns. Use repeat when each item deserves its own card.
+
+DYNAMIC PROPS:
+1. Read-only value: { "$$state": "/path" }. 2. Two-way input binding: { "$$bindState": "/path" } on value/checked. 3. Conditional: { "$$cond": <condition>, "$$then": <value>, "$$else": <value> }, where a condition is { "$$state": "/path" } (truthy), with optional "eq", "neq", "gt", "gte", "lt", "lte" or "not": true. 4. Template: { "$$template": "Invoice $${/result/reference}" } interpolates state paths; inside a repeat, bare names read the item.
+
+THE PLAN:
+A designer has read the brief and planned this page: its purpose, its title, its composition, and its regions in reading order with the elements each holds. Build the page the plan describes: the composition it wrote is the shape of the page; each region holds the elements it names, with the components it names, bound to the paths it names; where a region names no container, choose the one from the catalog that builds what the composition describes. Where the plan is silent - a label, a helper sentence, a gap, a column count - decide as they would have, from the purpose and the composition they wrote. Do not add a region, drop an element or rebind a path; where the plan names a path the brief does not list, the brief wins.
+
+Purpose: {{ plan.purpose }}
+Title (the page's one h1): {{ plan.title }}
+Composition: {{ plan.composition }}
+
+REGIONS:
+{% for region in plan.regions %}
+{{ loop.index }}. {% if region.title %}{{ region.title }} - {% endif %}{{ region.purpose }}{% if region.container %} [{{ region.container }}]{% endif %}
+{% for element in region.elements -%}
+- {{ element }}
+{% endfor -%}
+{% endfor -%}
+{% if plan.call_to_action %}
+CALL TO ACTION: {{ plan.call_to_action }}
+{% endif -%}
+{% if plan.defaults %}
+DEFAULTS (the only /state patches):
+{% for line in plan.defaults -%}
+- {{ line }}
+{% endfor -%}
+{% endif -%}
+{% if plan.delegated %}
+DELEGATED:
+{% for line in plan.delegated -%}
+- {{ line }}
+{% endfor -%}
+{% endif %}
+EXECUTION:
+- Restraint reads premium. No label that restates the obvious, no card inside a card, no paragraph that explains the form, no more than two levels of heading. Every element must earn its place; when in doubt, remove it.
+- Write copy a person would say: short labels, one helper sentence where a label is not enough and none where it is. The control that runs names the job ("Plan my trip"), never "Submit".
+- Every value binds to a path the brief lists, and the page reads clearly in both a light and a dark theme.
+
+AVAILABLE COMPONENTS ({{ catalog.components | length }}):
+
+{% for component in catalog.components -%}
+- {{ component.name }}: {{ component.props }}
+  {%- if component.description %} - {{ component.description }}{% endif %}
+  {%- if component.accepts_children and component.slots %} [accepts children; slots: {{ component.slots | join(", ") }}]
+  {%- elif component.accepts_children %} [accepts children]
+  {%- elif component.slots %} [slots: {{ component.slots | join(", ") }}]{% endif %}
+  {%- if component.events %} [events: {{ component.events | join(", ") }}]{% endif %}
+{% endfor %}
+AVAILABLE ACTIONS:
+
+{% for action in catalog.actions -%}
+- {{ action.name }}: {{ action.description }}{% if action.built_in %} [built-in]{% endif %}
+{% endfor %}
+EVENTS (the `on` field):
+Bind an event to actions with a top-level "on" field on the element: "on": { "press": [{ "action": "validateForm" }, { "action": "run" }] }. A single binding may be an object instead of an array. Never put actions inside "props".
+
+VISIBILITY (the `visible` field):
+A top-level "visible" field hides an element unless its condition holds: "visible": { "$$state": "/result/paid", "eq": true }. Conditions take exactly one of eq/neq/gt/gte/lt/lte, or "not": true; an array of conditions is an AND; { "$$or": [...] } is an OR.
+
+RULES:
+1. INTEGRITY: every key in every "children" array must be emitted as its own element. A missing child makes that whole branch of the page invisible. After emitting the tree, walk it from the root and emit any element you referenced but did not define.
+2. Every element is {"type", "props", "children"}; "children" is an array of element keys, empty for a leaf. "visible", "repeat" and "on" are fields of the ELEMENT, never of "props".
+3. ONLY use component types from the AVAILABLE COMPONENTS list. Use unique, descriptive element keys ("header", "total-metric", "lines-table").
+4. The brief is the ONLY source of paths. Bind every value to a path the brief lists, exactly as written, and inline no value that the state carries.
+5. On a RESULT page, emit no /state patches at all: the host loads /result before the page renders. Read with { "$$state": "/result/..." }.
+6. On an INPUT page, bind every input with { "$$bindState": "/inputs/..." }, and emit /state patches ONLY for the defaults the brief lists under "Defaults" - nothing else. The page's own UI state (the active tab, the current step, an open section) lives inside Tabs, Steps and Collapsible, never in /state.
+7. Delegate the paths the brief marks as delegated: MthdsField for an input, MthdsResult for a result, naming the path and nothing else. Never re-describe a delegated field with other components.
+8. Lay out what you understand and delegate what you do not. A structure you choose not to lay out is delegated whole by its path; that is a valid choice, not a failure.
+9. An input page has exactly ONE control that runs the method, wherever the plan puts it, and it fires validateForm then run, in that order, on press. No other Button: a Button bound to nothing does nothing, and navigation is never built out of Buttons, since Steps and Tabs carry their own.
+10. Tabs and Steps take exactly one child per tab or step, in the same order; that child is the panel, usually a Stack. A Step hides an input from the eye, never from the run: every input the run waits for must sit in some panel.
+11. Bind only what fits: a Segmented, Radio or Select lists exactly the brief's choices, spelled exactly; a NumberInput binds a number path; a Switch or Checkbox binds a boolean path; an Input binds a text path; a Textarea a prose path. A prop that shows a value - a Metric's value, a Text's text, a Heading's text, the value of a line that restates one, an interpolation in a $$template - reads a scalar path: text, prose, number, boolean, date or choice, never a structure, a list or a file. A structure is shown through its members, a list through a repeat or a DataTable, a file through MthdsField or MthdsResult.
+12. One root element, and it is a container that accepts children.
+13. The plan's title is on the page as its one h1 - a Heading at level h1, or the headline of a component whose description says it renders an h1 - and no other h1. Below it, heading levels increase by one and never skip: h2, then h3. A component whose description says it renders a heading counts at that level, so a Heading inside it starts one level down.
+14. Never set a "className" prop. Colour, spacing and type come from the components as they are.
+
+---
+
+Below is the brief for the page you are building. It is the ONLY source of paths: every value you show or bind must be at a path the brief lists, spelled exactly as written.
+
+@brief_text
+
+---
+
+Build this page as the plan describes. Bind every value; inline nothing the state carries. Output only the JSONL patch lines - no prose before or after, no code fence.
+"""