@lynx-js/genui 0.0.1-rc.0

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/README.md

@@ -0,0 +1,170 @@
+# @lynx-js/genui
+
+Generative UI primitives for Lynx applications.
+
+`@lynx-js/genui` is the single npm package for the GenUI toolchain. It exposes
+A2UI rendering, OpenUI rendering, A2UI prompt/catalog utilities, and the CLI
+from one package while keeping implementation directories private to this
+monorepo.
+
+## Installation
+
+```bash
+pnpm add @lynx-js/genui @lynx-js/react
+```
+
+`@lynx-js/react` is a peer dependency. Some built-in A2UI catalog components
+also use `@lynx-js/lynx-ui`; install it when your app renders those components.
+
+## Entry Points
+
+```ts
+import {
+  A2UI,
+  createMessageStore,
+  createOpenUiLibrary,
+  createStreamingParser,
+  buildA2UISystemPrompt,
+  extractCatalogComponents,
+} from '@lynx-js/genui';
+```
+
+The root entry point exports the stable APIs most applications and tools need:
+
+- A2UI ReactLynx renderer and data-store helpers.
+- OpenUI parser, library, and renderer APIs.
+- A2UI prompt builders.
+- A2UI catalog extraction utilities.
+
+Focused subpaths are also available:
+
+```ts
+import { A2UI, Text, Button } from '@lynx-js/genui/a2ui';
+import { createMessageStore } from '@lynx-js/genui/a2ui/store';
+import { createOpenUiLibrary } from '@lynx-js/genui/openui';
+import { buildA2UISystemPrompt } from '@lynx-js/genui/a2ui-prompt';
+import { extractCatalogComponents } from '@lynx-js/genui/a2ui-catalog-extractor';
+```
+
+Catalog manifests are exported through a single public catalog entry:
+
+```ts
+import { Text, Button } from '@lynx-js/genui/a2ui/catalog';
+```
+
+## A2UI
+
+A2UI renders agent-generated UI messages that follow the A2UI v0.9 protocol.
+Create a message store, push protocol messages into it from your transport, and
+render the latest surface with `<A2UI>`.
+
+```tsx
+import { A2UI, Button, Text, createMessageStore } from '@lynx-js/genui/a2ui';
+
+const messageStore = createMessageStore();
+
+export function GenUIScreen() {
+  return (
+    <A2UI
+      messageStore={messageStore}
+      catalogs={[Text, Button]}
+      onAction={(action) => {
+        // Send the action back to your agent, then push response messages
+        // into the same messageStore.
+      }}
+    />
+  );
+}
+```
+
+Use the A2UI style entry when you want the packaged component styles:
+
+```ts
+import '@lynx-js/genui/a2ui/styles/theme.css';
+```
+
+See [`a2ui/README.md`](./a2ui/README.md) for catalog composition and custom
+component details.
+
+## OpenUI
+
+OpenUI renders parsed OpenUI DSL through a configurable component library.
+
+```tsx
+import {
+  OpenUiRenderer,
+  createOpenUiLibrary,
+  createStreamingParser,
+} from '@lynx-js/genui/openui';
+
+const library = createOpenUiLibrary();
+const parser = createStreamingParser(library.toJSONSchema());
+const result = parser.push('root = Stack([TextContent("Hello")])');
+
+export function OpenUIScreen() {
+  return <OpenUiRenderer result={result} library={library} />;
+}
+```
+
+Renderer styles are explicit:
+
+```ts
+import '@lynx-js/genui/openui/styles/renderer.css';
+```
+
+See [`openui/README.md`](./openui/README.md) for streaming and custom library
+examples.
+
+## CLI
+
+The package installs the GenUI CLI and the low-level catalog extractor binary:
+
+```bash
+genui --help
+genui-cli --help
+a2ui-catalog-extractor --help
+```
+
+`a2ui-cli` is also kept as a compatibility alias for existing A2UI scripts. New
+scripts should prefer the namespace-first `genui a2ui ...` form so OpenUI
+commands can be added under `genui openui ...` later.
+
+Generate catalog artifacts:
+
+```bash
+genui a2ui generate catalog \
+  --catalog-dir src/catalog \
+  --source src/functions \
+  --out-dir dist/catalog
+```
+
+Generate an A2UI system prompt:
+
+```bash
+genui a2ui generate prompt \
+  --catalog-dir dist/catalog \
+  --out dist/a2ui-system-prompt.txt
+```
+
+## Published Package Layout
+
+Only `@lynx-js/genui` is intended to be published. The package contains compiled
+JavaScript and declarations under `dist/` directories, plus CLI entry points,
+README files, styles, and extractor skills.
+
+The root `index.ts` is compiled during build. Do not hand-write
+`dist/index.js` or `dist/index.d.ts`; run:
+
+```bash
+pnpm -C packages/genui build
+```
+
+Before publishing, verify the package contents:
+
+```bash
+pnpm -C packages/genui pack --dry-run
+```
+
+## License
+
+Apache-2.0

package/a2ui/README.md

@@ -0,0 +1,140 @@
+# @lynx-js/genui/a2ui
+
+ReactLynx renderer for the A2UI v0.9 protocol. **Headless** — the package
+ships no styles or chrome; consumers wrap surfaces themselves.
+
+This package includes:
+
+- `<A2UI>`: all-in-one component that owns a `MessageProcessor`,
+  subscribes to a developer-supplied `MessageStore`, and renders the
+  most recent surface.
+- `MessageStore`: an append-only buffer of raw protocol messages the
+  developer pushes into from any IO transport (fetch, SSE, WebSocket,
+  in-process mock, …).
+- `defineCatalog` / `mergeCatalogs` / `serializeCatalog`: the pluggable
+  catalog API. No global registry — every consumer composes the set of
+  components they want available.
+- `catalog/<Name>`: built-in component renderers (`Text`, `Button`,
+  `Card`, `Column`, `Row`, `List`, `CheckBox`, `RadioGroup`, `Slider`,
+  `Image`, `Divider`, `Icon`, `Modal`, `Tabs`).
+- `catalog/<Name>/catalog.json`: per-component JSON-Schema manifests
+  for the agent handshake.
+
+## Exports
+
+- `@lynx-js/genui/a2ui`: `<A2UI>`, `createMessageStore`,
+  `defineCatalog`, the built-ins, plus protocol types.
+- `@lynx-js/genui/a2ui/catalog`: re-exports of the catalog API and
+  built-ins for tree-shake-friendly subpath access.
+- `@lynx-js/genui/a2ui/catalog/<Name>`: import a single built-in.
+- `@lynx-js/genui/a2ui/catalog/<Name>/catalog.json`: import the
+  per-component manifest.
+- `@lynx-js/genui/a2ui/store`: `MessageStore`, `MessageProcessor`,
+  `Resource`, payload normalizers — the pure data layer.
+- `@lynx-js/genui/a2ui/react`: lower-level renderer pieces for
+  consumers that want manual surface lifecycle control.
+
+## Installation
+
+Make sure your app provides the peer dependencies:
+
+- `@lynx-js/react`
+
+## Quick Start
+
+1. Create a `MessageStore`.
+2. Wire your IO module (mock / SSE / fetch / …) to push raw protocol
+   messages into the store.
+3. Render `<A2UI messageStore={store} catalogs={[...]}>`.
+
+```tsx
+import { A2UI, Button, Text, createMessageStore } from '@lynx-js/genui/a2ui';
+
+const store = createMessageStore();
+
+// Your IO module pushes raw v0.9 protocol messages into the store.
+// async function streamFromAgent(input: string) {
+//   for await (const msg of myAgent.stream(input)) store.push(msg);
+// }
+
+export function A2UIScreen(): import('@lynx-js/react').ReactNode {
+  return (
+    <A2UI
+      messageStore={store}
+      catalogs={[Text, Button]}
+      className='surface-container'
+      onAction={(action) => {
+        // Forward to your agent — push the response messages back into
+        // the same store. Fire-and-forget; the renderer never awaits.
+      }}
+      wrapSurface={(c) => <view className='luna-light'>{c}</view>}
+    />
+  );
+}
+```
+
+The `<A2UI>` component is intentionally minimal:
+
+- It owns its own `MessageProcessor` per mount; passing a different
+  `messageStore` instance does **not** reset internal state — use a
+  `key` prop derived from your turn/session id when you want a fresh
+  session.
+- `onAction` is fire-and-forget. The renderer doesn't wait for a
+  response — your agent pushes follow-up messages back into the same
+  `messageStore`.
+- `className` applies to the surface root view (`surface-${surfaceId}`).
+- `wrapSurface` applies an outer wrapper around the rendered surface.
+- Both can be used for multi-theme switching; choose the layer that
+  matches your styling strategy.
+
+## Catalogs
+
+The package intentionally **does not** ship an "all-in-one" aggregate.
+Composition is per-component so bundlers can tree-shake what isn't
+referenced.
+
+### Bare components (renderer-only)
+
+```ts
+import { defineCatalog, Text, Button } from '@lynx-js/genui/a2ui';
+
+const catalog = defineCatalog([Text, Button]);
+```
+
+The protocol name comes from `displayName ?? component.name`.
+
+> ⚠️ Production minifiers rewrite `function` names. For production
+> safety, set an explicit `displayName` on every custom component, or
+> pair it with its `catalog.json` manifest (the manifest key is
+> authoritative).
+
+### Paired with manifests (renderer + agent handshake)
+
+```ts
+import { Text, defineCatalog } from '@lynx-js/genui/a2ui';
+import textManifest from '@lynx-js/genui/a2ui/catalog/Text/catalog.json'
+  with { type: 'json' };
+
+const catalog = defineCatalog([[Text, textManifest]]);
+agentChannel.handshake({ catalog: serializeCatalog(catalog) });
+```
+
+See [`src/catalog/README.md`](src/catalog/README.md) for the full
+recipe (including the paste-able "every built-in" snippet).
+
+## Custom Components
+
+Any function returning a `ReactNode` works. The function's name (or
+`displayName`) is the protocol name the agent will use:
+
+```tsx
+function MyChart(props: { data: number[] }) { ... }
+MyChart.displayName = 'MyChart';
+
+<A2UI catalogs={[Text, Button, MyChart]} ... />;
+// Agent emits `{ component: 'MyChart', data: [...] }` → renders MyChart.
+```
+
+If you want schema introspection for a custom component, generate the
+manifest with `@lynx-js/genui/a2ui-catalog-extractor` against your interface
+and pair it with the component the same way as the built-ins.

package/a2ui/dist/catalog/Button/catalog.json

@@ -0,0 +1,156 @@
+{
+  "Button": {
+    "properties": {
+      "child": {
+        "type": "string"
+      },
+      "variant": {
+        "type": "string",
+        "enum": [
+          "primary",
+          "borderless"
+        ]
+      },
+      "isValid": {
+        "type": "boolean"
+      },
+      "action": {
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "event": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  },
+                  "context": {
+                    "type": "object",
+                    "additionalProperties": true,
+                    "description": "Context is a JSON object map in v0.9."
+                  }
+                },
+                "required": [
+                  "name"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "required": [
+              "event"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "functionCall": {
+                "type": "object",
+                "properties": {
+                  "call": {
+                    "type": "string"
+                  },
+                  "args": {
+                    "type": "object",
+                    "additionalProperties": true
+                  },
+                  "returnType": {
+                    "type": "string",
+                    "enum": [
+                      "string",
+                      "number",
+                      "boolean",
+                      "object",
+                      "array",
+                      "any",
+                      "void"
+                    ]
+                  }
+                },
+                "required": [
+                  "call",
+                  "args"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "required": [
+              "functionCall"
+            ],
+            "additionalProperties": false
+          }
+        ],
+        "description": "v0.9 actions should use the `event` wrapper for server-dispatched clicks."
+      },
+      "checks": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "condition": {
+              "oneOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "path": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "path"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "call": {
+                      "type": "string"
+                    },
+                    "args": {
+                      "type": "object",
+                      "additionalProperties": true
+                    },
+                    "returnType": {
+                      "type": "string",
+                      "enum": [
+                        "string",
+                        "number",
+                        "boolean",
+                        "object",
+                        "array",
+                        "any",
+                        "void"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "call",
+                    "args"
+                  ],
+                  "additionalProperties": false
+                }
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "condition",
+            "message"
+          ],
+          "additionalProperties": false
+        }
+      }
+    },
+    "required": [
+      "child",
+      "action"
+    ]
+  }
+}