@lynx-js/skill-lynx-openui-canary 0.0.0-rc.0 → 0.0.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: lynx-openui
+description: Generate valid OpenUI Lang v0.5 functional-notation programs for the Lynx OpenUI renderer. Use when Codex must turn a natural-language UI request into raw OpenUI DSL for OpenUiRenderer, including static mobile UI, $state, Query/Mutation tool flows, Action plans, streaming-friendly output, or catalog-constrained revisions. Do not use for JSX, HTML, CSS, A2UI JSON, or implementing new ReactLynx components.
+---
+
+# Generate Lynx OpenUI Programs
+
+Generate valid OpenUI Lang v0.5 consumed by
+`<OpenUiRenderer response={...}>`. Produce declarative DSL, not application
+code.
+
+## Read The References
+
+- Always read [components.md](references/components.md) before generating a
+  program. Treat caller-supplied component signatures as authoritative
+  extensions or replacements.
+- Read [runtime.md](references/runtime.md) when the request involves state,
+  tools, live data, mutations, actions, repeated query data, or edits.
+- Read [examples.md](references/examples.md) for a non-trivial layout or tool
+  workflow. Adapt patterns; do not copy irrelevant content.
+
+## Workflow
+
+1. Identify the requested UI, supplied component catalog, available tool
+   schemas, media URLs, and whether the host supports full programs or
+   `mergeStatements` patches.
+2. Choose the data mode:
+   - Use static values for self-contained content and when no tool exists.
+   - Use `Query` only for an actual read tool supplied by the caller or host.
+   - Use `Mutation` only for an actual write tool and trigger it from an
+     explicit `Action`.
+3. Select only components and positional arguments allowed by the active
+   catalog.
+4. Write a streaming-friendly graph. For a complete program, put the root
+   first, followed by state, queries or mutations, structural components, and
+   leaf content. For an edit-mode patch, return only changed statements.
+5. Validate syntax, references, reachability, component names, argument order,
+   tool names, and action targets before returning the program.
+
+## Output Contract
+
+- Return only OpenUI Lang. Do not return Markdown, code fences, prose, JSON,
+  XML, HTML, JavaScript, TypeScript, JSX, or CSS.
+- Put one assignment statement on each line.
+- For a complete program, make the first non-empty line `root = Stack(...)`.
+- Return a complete program by default. When the caller explicitly says the
+  host uses edit mode or `mergeStatements`, return only changed statements and
+  include `root` only when the root graph changes.
+- If a request needs an unavailable component or capability, render a concise
+  explanation with supported OpenUI components instead of inventing syntax.
+
+## Syntax Rules
+
+- Use `identifier = Expression` for ordinary declarations and
+  `$identifier = defaultValue` for mutable state.
+- Pass component arguments positionally. Never use named arguments such as
+  `gap: "m"`.
+- Omit optional arguments only from the end. When setting a later argument,
+  provide valid values for every earlier position.
+- Use double-quoted strings and escape embedded quotes and backslashes.
+- Use references or inline components. Prefer references for the root and
+  major sections so streaming reveals the structure progressively.
+- Ensure every referenced identifier is defined. Ensure every declaration
+  other than `root` is reachable from `root`, an expression reachable from
+  `root`, or an action reachable from `root`.
+- Use only documented operators, built-ins, components, and action steps.
+
+Correct positional layout:
+
+```text
+root = Stack([header, content], "column", false, "l", "stretch", "start")
+```
+
+Incorrect positional layout:
+
+```text
+root = Stack([header, content], "column", "l", "stretch")
+```
+
+The incorrect form passes a string into `wrap` and shifts every later prop.
+
+## Data And Interaction Rules
+
+- Do not invent tool names. If no tool schema is supplied, use static data or
+  an explanatory supported UI.
+- Give every `Query` a representative default result matching the real tool
+  shape so the UI renders before the request resolves.
+- Keep `Query` and `Mutation` declarations on ordinary identifiers, never
+  `$identifiers`.
+- Use `@Each` for query-backed repeated UI. Keep its loop-dependent component
+  inline inside `@Each`.
+- Put write operations on a submit or confirmation `Button`. Do not attach a
+  mutation to an input's change action.
+- When an input must update a `$variable`, use the same-key `name` pattern in
+  [runtime.md](references/runtime.md). Do not invent an event-value variable.
+- Execute multi-step actions in deliberate order. Remember that a failed
+  mutation stops the remaining steps.
+- Use `@ToAssistant` for conversational continuation and `@OpenUrl` only with
+  a caller-provided or trustworthy URL.
+- Use caller-provided media URLs. Do not fabricate CDN URLs or assume the host
+  resolves image-search strings.
+
+## Lynx UI Rules
+
+- Prefer compact, mobile-first layouts with a shallow component tree.
+- Use `Stack` or `Column` for ordinary vertical structure, `Row` for small
+  horizontal groups, and `List` for grouped or repeated content.
+- Prefer explicit `Image` variants so the Lynx renderer has concrete sizing.
+- Keep readable text in `Text` or `TextContent`; do not emit raw Lynx elements.
+- Use `Tabs` for alternate views and `Modal` for tap-to-open details. Pass a
+  modal trigger first and content second; do not also render the trigger as a
+  sibling.
+
+## Final Verification
+
+Before returning, verify all of the following:
+
+- A complete program starts with `root = Stack(...)`. An edit-mode patch omits
+  `root` unless the root graph changes. The response contains only OpenUI Lang.
+- Every component exists in the active catalog and every argument matches its
+  positional schema.
+- No `Form`, `Input`, `Select`, `SelectItem`, `FormControl`, table, or chart is
+  used unless the caller supplied that custom component.
+- Every reference resolves and no declaration is orphaned.
+- Every `Query` or `Mutation` uses a real supplied tool and is referenced by
+  visible UI or a visible action.
+- Every `$variable` participates in visible UI, a query argument, or an action.
+- Every `@Each` loop variable stays inside its inline template expression.
+- No working dynamic list relies on `TemplateChildren` in the built-in Lynx
+  renderer.
+- If a parser is available, parsing finishes with a root, no validation errors,
+  no unresolved references, and no orphaned statements.

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Lynx OpenUI"
+  short_description: "Create valid OpenUI Lang v0.5 for Lynx"
+  default_prompt: "Use $lynx-openui to turn this UI request into valid OpenUI Lang v0.5 code for Lynx."

package/package.json

@@ -1,13 +1,23 @@
 {
   "name": "@lynx-js/skill-lynx-openui-canary",
-  "version": "0.0.0-rc.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "0.0.1",
+  "description": "Generate Lynx OpenUI v0.5 programs for @lynx-js/genui.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lynx-family/lynx-stack.git",
+    "directory": "packages/genui/lynx-openui"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "packageManager": "pnpm@10.33.2"
-}
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "SKILL.md",
+    "agents",
+    "references"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/components.md

@@ -0,0 +1,111 @@
+# Lynx OpenUI Component Catalog
+
+## Contents
+
+- [Shared Types](#shared-types)
+- [Layout](#layout)
+- [Content](#content)
+- [Buttons](#buttons)
+- [Data Display](#data-display)
+- [Media](#media)
+- [Inputs](#inputs)
+- [Unsupported Components](#unsupported-unless-extended-by-the-host)
+
+Use the built-in component signatures exactly. Arguments are positional and
+`?` marks a schema-optional argument. Omit an optional argument only when every
+later argument is also omitted. If an optional argument precedes a required
+one, supply it so later positions do not shift. The signatures include exact
+argument types and allowed enum values.
+
+## Shared Types
+
+- `StringLike`: string, number, boolean, or a v0.5 expression that resolves to
+  one of those primitive values. Although the compatibility schema accepts
+  legacy object bindings, generated programs must not use them because the
+  built-in Lynx renderer does not resolve them.
+- `BooleanLike`: boolean or a v0.5 expression that resolves to boolean. Do not
+  generate legacy path objects.
+- `ActionExpression`: `Action([@step, ...])` or a host-supplied legacy action
+  object. Prefer `Action` plans.
+
+## Layout
+
+- `Stack(children: any[], direction?: "row" | "column", wrap?: boolean, gap?: "none" | "xs" | "s" | "m" | "l" | "xl", align?: "start" | "center" | "end" | "stretch", justify?: "start" | "center" | "end" | "between")`
+- `Row(children: any[], justify?: "start" | "center" | "end" | "between" | "around" | "evenly" | "spaceBetween" | "spaceAround" | "spaceEvenly" | "stretch", align?: "start" | "center" | "end" | "stretch", gap?: "none" | "xs" | "s" | "m" | "l" | "xl", wrap?: boolean)`
+- `Column(children: any[], justify?: "start" | "center" | "end" | "between" | "around" | "evenly" | "spaceBetween" | "spaceAround" | "spaceEvenly" | "stretch", align?: "start" | "center" | "end" | "stretch", gap?: "none" | "xs" | "s" | "m" | "l" | "xl")`
+- `List(children?: any[] | TemplateChildren, items?: any[] | TemplateChildren, direction?: "vertical" | "horizontal", align?: "start" | "center" | "end" | "stretch", gap?: "none" | "xs" | "s" | "m" | "l" | "xl", divider?: boolean)`
+- `Separator()`
+- `Divider(axis?: "horizontal" | "vertical")`
+- `Modal(trigger: any, content: any, title?: StringLike, closeOnAction?: boolean)`
+- `Tabs(tabs: {value: string, title: StringLike, child: any}[], value?: string)`
+
+For the built-in `List`, pass children as the first argument and normally omit
+the remaining arguments. The second position is the `items` alias, not
+`direction`. Use `@Each` for live repeated data. Built-in `TemplateChildren`
+currently renders a diagnostic hint rather than expanding content.
+
+## Content
+
+- `Card(children: any[], variant?: "card" | "sunk" | "clear", direction?: "row" | "column", wrap?: boolean, gap?: "none" | "xs" | "s" | "m" | "l" | "xl", align?: "start" | "center" | "end" | "stretch", justify?: "start" | "center" | "end" | "between")`
+- `CardHeader(title: string, subtitle?: string)`
+- `Text(text: StringLike, variant?: "h1" | "h2" | "h3" | "h4" | "h5" | "caption" | "body")`
+- `TextContent(text: string | number | boolean, size?: "small" | "default" | "large" | "small-heavy" | "large-heavy")`
+
+`Text.text` uses `StringLike`. `TextContent.text` accepts only a string, number,
+boolean, or an expression that resolves to one of those primitives. Never pass
+an object binding to `TextContent`.
+
+## Buttons
+
+- `Button(label: string, action?: ActionExpression, variant?: "primary" | "secondary" | "tertiary", type?: "normal" | "destructive", size?: "extra-small" | "small" | "medium" | "large")`
+- `Buttons(buttons: Button[])`
+
+A button without an action sends its label to the assistant. Use `Buttons`
+for a button group.
+
+## Data Display
+
+- `Tag(text: string)`
+- `Icon(name: "account_circle" | "add" | "arrow_back" | "arrow_forward" | "camera" | "check" | "close" | "delete" | "edit" | "error" | "favorite" | "help" | "home" | "info" | "location_on" | "lock" | "mail" | "menu" | "more_vert" | "pause" | "person" | "play_arrow" | "refresh" | "search" | "send" | "settings" | "share" | "star" | "warning", size?: "sm" | "md" | "lg", color?: "primary" | "muted" | "inherit")`
+- `Loading(variant?: "inline" | "block")`
+
+## Media
+
+- `Image(url: StringLike, fit?: "contain" | "cover" | "fill" | "none" | "scale-down", variant?: "icon" | "avatar" | "smallFeature" | "mediumFeature" | "largeFeature" | "header")`
+- `AudioPlayer(url: StringLike, description?: StringLike)`
+- `Video(url: StringLike, title?: StringLike)`
+
+Use a supplied URL. Prefer an explicit image variant; the Lynx implementation
+maps variants to concrete dimensions.
+
+## Inputs
+
+- `CheckBox(label: string, value?: boolean, action?: ActionExpression, name?: string)`
+- `RadioGroup(items: string[], value?: string, usageHint?: "default" | "card" | "row", action?: ActionExpression, name?: string)`
+- `ChoicePicker(label?: StringLike, options: (StringLike)[] | StringLike, value?: StringLike, variant?: "default" | "card", displayStyle?: "list" | "chips" | "dropdown", filterable?: BooleanLike)`
+- `Slider(label?: string, min?: number, max?: number, value?: number, step?: number, action?: ActionExpression, name?: string)`
+- `DateTimeInput(value: StringLike, enableDate?: BooleanLike, enableTime?: BooleanLike, min?: StringLike, max?: StringLike, label?: StringLike)`
+- `TextField(label: string, value?: string, variant?: "longText" | "number" | "shortText" | "obscured", validationRegexp?: string, action?: ActionExpression, name?: string)`
+
+`ChoicePicker.label` is schema-optional but precedes required `options`. Since
+OpenUI Lang calls are positional, always pass a label so `options` remains the
+second argument.
+
+Current Lynx runtime boundaries:
+
+- `CheckBox`, `RadioGroup`, `Slider`, and `TextField` persist host form state
+  when given `name`; their action fires on value change.
+- To bind one of those inputs to `$state`, pass the exact state key including
+  `$` as its literal `name`, for example `"$city"`. See
+  [runtime.md](runtime.md#state).
+- `ChoicePicker` keeps selection only inside the component and has no `name` or
+  action prop. Do not use it as a live `Query` filter.
+- `DateTimeInput` currently displays a date/time value; do not promise editable
+  date picking.
+- Put mutations on explicit submit or confirmation buttons, not change actions.
+
+## Unsupported Unless Extended By The Host
+
+Do not emit `Form`, `Input`, `Select`, `SelectItem`, `FormControl`, tables,
+charts, or any other name absent from the signatures above unless the caller
+provides its exact custom schema.

package/references/examples.md

@@ -0,0 +1,64 @@
+# Lynx OpenUI Examples
+
+Treat each block as a complete OpenUI program. Adapt component choices and
+content to the request.
+
+## Static Card And Conversational Action
+
+```openui
+root = Stack([hero, actions], "column", false, "m", "stretch", "start")
+hero = Card([CardHeader("Weekly Summary", "Updated just now"), TextContent("Revenue is up 18%.", "large-heavy"), TextContent("Three accounts need follow-up.", "small")], "card", "column", false, "s", "start", "start")
+actions = Buttons([Button("Show details", Action([@ToAssistant("Show the account details")]), "primary")])
+```
+
+## Local View State
+
+```openui
+root = Stack([switcher, content], "column", false, "m", "stretch", "start")
+$view = "summary"
+switcher = Buttons([Button("Summary", Action([@Set($view, "summary")]), "primary"), Button("Details", Action([@Set($view, "details")]), "secondary")])
+content = $view == "summary" ? summary : details
+summary = Card([CardHeader("Summary"), TextContent("Three tasks are on track.")], "card", "column", false, "s")
+details = Card([CardHeader("Details"), List([Text("Design review", "body"), Text("Release checklist", "body")])], "card", "column", false, "s")
+```
+
+## Query And Repeated Data
+
+Assume the host supplies a `list_tasks` read tool returning `{ rows: [...] }`.
+
+```openui
+root = Stack([header, taskList, refresh], "column", false, "m", "stretch", "start")
+tasks = Query("list_tasks", {}, { rows: [{ title: "Design review", status: "open" }, { title: "Release checklist", status: "done" }] })
+header = CardHeader("Tasks", @Count(tasks.rows) + " total")
+taskList = List(@Each(tasks.rows, "task", Card([Text(task.title, "h4"), Tag(task.status)], "card", "column", false, "s")))
+refresh = Buttons([Button("Refresh", Action([@Run(tasks)]), "secondary")])
+```
+
+## Query Driven By Text Input
+
+Assume the host supplies a `get_weather` read tool returning weather data for
+the requested city. This live pattern runs the query on each input change, so
+use it only when the tool can accept that request frequency.
+
+```openui
+root = Stack([cityInput, weatherCard, refresh], "column", false, "m", "stretch", "start")
+$city = "Seattle"
+weather = Query("get_weather", { city: $city }, { city: "Seattle", temp: 62, condition: "Cloudy" })
+cityInput = TextField("City", $city, "shortText", ".+", null, "$city")
+weatherCard = Card([CardHeader(weather.city, "Current weather"), TextContent(weather.temp + " degrees", "large-heavy"), TextContent(weather.condition)], "card", "column", false, "s")
+refresh = Button("Refresh", Action([@Run(weather)]), "secondary")
+```
+
+## Mutation With Ordered Feedback
+
+Assume the host supplies a `save_preference` write tool.
+
+```openui
+root = Stack([summary, choices, submit, status], "column", false, "m", "stretch", "start")
+$priority = "normal"
+save = Mutation("save_preference", { priority: $priority })
+summary = Card([CardHeader("Notification Priority"), TextContent("Selected: " + $priority)], "card", "column", false, "s")
+choices = Buttons([Button("High", Action([@Set($priority, "high")]), "secondary"), Button("Normal", Action([@Set($priority, "normal")]), "secondary"), Button("Low", Action([@Set($priority, "low")]), "secondary")])
+submit = Button("Save preference", Action([@Run(save)]), "primary")
+status = save.status == "loading" ? Loading("inline") : save.status == "success" ? TextContent("Preference saved.", "small-heavy") : TextContent("Choose a priority, then save.", "small")
+```

package/references/runtime.md

@@ -0,0 +1,145 @@
+# OpenUI Lang v0.5 Runtime
+
+Consult this reference for state, tool-backed data, actions, expressions, repeated
+data, or incremental edits.
+
+## Contents
+
+- [Program And Expressions](#program-and-expressions)
+- [State](#state)
+- [Query](#query)
+- [Mutation](#mutation)
+- [Actions](#actions)
+- [Data Built-ins](#data-built-ins)
+- [Streaming And Edits](#streaming-and-edits)
+
+## Program And Expressions
+
+- Write one `identifier = Expression` statement per line.
+- In a complete program, define `root = Stack(...)` first. Forward references
+  are allowed. An edit-mode patch may omit `root`.
+- Use double-quoted strings, numbers, booleans, `null`, arrays, objects,
+  component calls, and ordinary references.
+- Access fields and indices with `data.rows`, `rows[0]`, and
+  `data.rows.title` (array pluck).
+- Use arithmetic `+ - * / %`, comparisons `== != > < >= <=`, logic `&& || !`,
+  ternaries `condition ? yes : no`, and parentheses.
+- Keep every ordinary declaration reachable from `root`. Unreachable
+  declarations are orphaned and do not render.
+
+## State
+
+Declare mutable state with a `$` prefix:
+
+```openui
+$city = "Seattle"
+```
+
+Use simple string, number, or boolean defaults. Undeclared `$variables` may be
+auto-created as `null`, but explicit defaults make rendering and reset behavior
+predictable. Use `$variables` in expressions, tool arguments, `@Set`, and
+`@Reset`.
+
+Built-in Lynx inputs write their `name` into the runtime state store. To bind an
+input directly to a `$variable`, pass the variable as its value and pass the
+exact variable name, including `$`, as the literal `name` argument:
+
+```openui
+$city = "Seattle"
+weather = Query("get_weather", { city: $city }, { city: "Seattle", temp: 62 })
+cityInput = TextField("City", $city, "shortText", ".+", null, "$city")
+```
+
+Here `null` fills the unused action position so `"$city"` reaches `name`.
+Typing writes back to `$city`, so expressions update and dependent queries run
+again. Do not use `"city"` and then try to copy its value with `@Set`: input
+actions do not expose an event-value variable. Use explicit `@Set` buttons for
+fixed choices instead.
+
+This same-key binding requires the v0.5 `response` runtime and no enclosing
+custom `Form`; a form writes the value into nested form state instead. Each
+input event updates the state immediately, without debounce or validation
+gating, so use a text-driven `Query` only when live requests on each change are
+acceptable.
+
+## Query
+
+Use an actual read tool supplied by the caller or host:
+
+```openui
+weather = Query("get_weather", { city: $city }, { city: "Seattle", temp: 62, alerts: [] }, 30)
+```
+
+Arguments are tool name, arguments object, immediate default result, and an
+optional refresh interval in seconds. Use an ordinary identifier such as
+`weather`, not `$weather`.
+
+- Match defaults to the real result shape and keep them compact.
+- Read results with field access, index access, array pluck, or built-ins.
+- Changing a referenced `$variable` re-runs the query.
+- Use `@Run(weather)` for manual refresh.
+- Do not turn tool results into manually copied static component statements.
+
+## Mutation
+
+Declare a write tool without executing it:
+
+```openui
+save = Mutation("save_preference", { priority: $priority })
+```
+
+Execute it only from `@Run(save)` in a visible action. Use `save.status`,
+`save.data`, and `save.error` for feedback. Status is `"idle"`, `"loading"`,
+`"success"`, or `"error"`.
+
+## Actions
+
+Use `Action([@step, ...])`. Steps run in order:
+
+- `@Run(queryOrMutation)` executes a mutation or refreshes a query.
+- `@ToAssistant("message")` continues the conversation.
+- `@OpenUrl("https://...")` asks the host to navigate.
+- `@Set($variable, value)` updates state.
+- `@Reset($var1, $var2, ...)` restores declared defaults.
+
+If a mutation fails, later steps do not run. Put a mutation before dependent
+refresh/reset steps only when that halt behavior is intended.
+
+## Data Built-ins
+
+Use only these built-ins:
+
+- `@Count(array)`, `@First(array)`, `@Last(array)`
+- `@Sum(numbers)`, `@Avg(numbers)`, `@Min(numbers)`, `@Max(numbers)`
+- `@Sort(array, field, direction?)`
+- `@Filter(array, field, operator, value)` where operator is `"=="`, `"!="`,
+  `">"`, `"<"`, `">="`, `"<="`, or `"contains"`
+- `@Round(number, decimals?)`, `@Abs(number)`, `@Floor(number)`, `@Ceil(number)`
+- `@Each(array, variableName, inlineTemplate)`
+
+Keep the `@Each` loop variable inside the inline template:
+
+```openui
+taskList = List(@Each(tasks.rows, "task", Card([Text(task.title, "h4")])))
+```
+
+Do not extract `Card([Text(task.title)])` into another statement because
+`task` exists only inside the `@Each` template.
+
+## Streaming And Edits
+
+For complete programs, use this order:
+
+1. `root = Stack(...)`
+2. `$state` declarations
+3. `Query` and `Mutation` declarations
+4. structural component declarations
+5. leaf content
+
+The parser resolves forward references as statements stream in. Keep the root
+first so the shell appears immediately.
+
+Return a complete program unless the caller explicitly says the host enables
+edit mode or merges patches with `mergeStatements`. In edit mode, output only
+assignments that must be added or replaced, and include `root` only when the
+root graph changes.