a2uink 0.1.0

package/.eslintignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+build
+.husky

package/.eslintrc.cjs

@@ -0,0 +1,21 @@
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2024,
+    sourceType: 'module'
+  },
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'prettier'
+  ],
+  env: {
+    node: true,
+    es2024: true
+  },
+  rules: {
+    // project-specific rules can be added here
+  }
+};

package/.gitattributes

@@ -0,0 +1,5 @@
+* text=auto eol=lf
+*.ts linguist-language=TypeScript
+*.js linguist-language=JavaScript
+package.json text
+*.md text

package/.github/copilot-instructions.md

@@ -0,0 +1,21 @@
+- [x] Verify that the copilot-instructions.md file in the .github directory is created.
+
+- [x] Clarify Project Requirements
+
+- [x] Scaffold the Project
+
+- [x] Customize the Project
+
+- [x] Install Required Extensions
+
+- [x] Compile the Project
+
+- [x] Create and Run Task
+
+- [x] Launch the Project
+
+- [x] Ensure Documentation is Complete
+
+- Work through each checklist item systematically.
+- Keep communication concise and focused.
+- Follow development best practices.

package/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  build:
+    runs-on: windows-latest
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build --if-present
+
+      - name: Test
+        run: npm test --if-present

package/.husky/pre-commit

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+. "$(dirname "$0")/_/husky.sh"
+
+# Run tests if present; adjust as needed (lint-staged can be added later)
+npx --no-install lint-staged || true
+npm test --if-present

package/.prettierignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+build
+.husky
+.git
+*.log

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "semi": true,
+  "singleQuote": true,
+  "printWidth": 100
+}

package/README.md

@@ -0,0 +1,44 @@
+A2UI v0.8 Ink wrapper MVP.
+
+This library renders a minimal subset of A2UI components using Ink and React. It supports beginRendering, surfaceUpdate, dataModelUpdate, adjacency-list rendering, and basic user actions for input, selection, and buttons.
+
+Use npm run demo to launch the sample surface renderer.
+
+## Supported Features
+- A2UI v0.8 render gate: beginRendering, surfaceUpdate, dataModelUpdate
+- Adjacency-list tree reconstruction with explicit children and template lists
+- Data binding via `BoundValue` (path + literal fallbacks)
+- Ink-backed components: Text, Box, Spacer, Input, Select, Button, Checkbox, RadioGroup, List, Tabs, Table, Slider, Modal, Divider, Image, Chart
+- Focus management with Tab / Shift+Tab navigation
+- Action dispatch: onPress, onChange, onSubmit, onSelect
+
+## Implementation Guide
+1. Create a renderer instance with `createA2uiInkRenderer`.
+2. Send A2UI server messages in this order:
+	- surfaceUpdate: component catalog and root ID
+	- dataModelUpdate: initial state
+	- beginRendering: unlock rendering
+3. Handle `userAction` callbacks to round-trip input back to your A2UI server.
+
+## Usage with A2UI
+Create the renderer, stream A2UI messages into `handleMessage`, and forward user actions back to your server.
+
+Example flow:
+1. `surfaceUpdate` provides the component graph.
+2. `dataModelUpdate` supplies initial data.
+3. `beginRendering` allows the client to render.
+
+Use the `onUserAction` callback to capture input and selection events.
+
+Recommended entry points:
+- Public API: [src/index.ts](src/index.ts)
+- Renderer core: [src/renderer.ts](src/renderer.ts)
+- Component registry: [src/catalog.ts](src/catalog.ts)
+- Binding and tree build: [src/binding.ts](src/binding.ts) and [src/tree.ts](src/tree.ts)
+
+## Future Plan
+- Add more standard catalog components (checkbox, radio, list view, tabs)
+- Styling parity improvements (alignment, borders, padding presets)
+- Better input controls (multi-line input, validation, masking)
+- Multi-surface support in a single process
+- Performance tuning for large dynamic lists

package/dist/binding.d.ts

@@ -0,0 +1,3 @@
+import type { BindingContext, BoundValue } from "./types.js";
+export declare function resolveBoundValue(boundValue: BoundValue | undefined, dataModel: Record<string, unknown>, context?: BindingContext): unknown;
+export declare function resolveProps(props: Record<string, unknown>, dataModel: Record<string, unknown>, context?: BindingContext): Record<string, unknown>;

package/dist/binding.js

@@ -0,0 +1,73 @@
+const literalKeys = [
+    "literalString",
+    "literalNumber",
+    "literalBoolean",
+    "literalObject",
+    "literalArray"
+];
+export function resolveBoundValue(boundValue, dataModel, context) {
+    if (!boundValue) {
+        return undefined;
+    }
+    if (boundValue.path) {
+        const resolved = getPathValue(boundValue.path, dataModel, context);
+        if (resolved !== undefined) {
+            return resolved;
+        }
+    }
+    for (const key of literalKeys) {
+        if (key in boundValue) {
+            return boundValue[key];
+        }
+    }
+    return undefined;
+}
+export function resolveProps(props, dataModel, context) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(props)) {
+        if (isBoundValue(value)) {
+            resolved[key] = resolveBoundValue(value, dataModel, context);
+        }
+        else {
+            resolved[key] = value;
+        }
+    }
+    return resolved;
+}
+function isBoundValue(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    if ("path" in value) {
+        return true;
+    }
+    return literalKeys.some((key) => key in value);
+}
+function getPathValue(path, dataModel, context) {
+    const normalized = path.replace(/^\$\.?/, "");
+    if (normalized === "") {
+        return dataModel;
+    }
+    const parts = normalized.split(".");
+    const root = resolveContextRoot(parts[0], context, dataModel);
+    const startIndex = root === dataModel ? 0 : 1;
+    let current = root;
+    for (let i = startIndex; i < parts.length; i += 1) {
+        if (current && typeof current === "object" && parts[i] in current) {
+            current = current[parts[i]];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return current;
+}
+function resolveContextRoot(firstPart, context, dataModel) {
+    if (firstPart === "item" && (context === null || context === void 0 ? void 0 : context.item) !== undefined) {
+        return context.item;
+    }
+    if (firstPart === "index" && (context === null || context === void 0 ? void 0 : context.index) !== undefined) {
+        return context.index;
+    }
+    return dataModel;
+}

package/dist/catalog.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+import type { ActionDef, ResolvedNode } from "./types.js";
+export interface CatalogRenderOptions {
+    dispatchAction: (action: ActionDef, node: ResolvedNode, value?: unknown) => void;
+}
+export declare function renderNode(node: ResolvedNode, options: CatalogRenderOptions): React.ReactElement;

package/dist/catalog.js

@@ -0,0 +1,165 @@
+import React, { useEffect, useMemo, useState } from "react";
+import { Box, Spacer, Text } from "ink";
+import { useFocusRegistry } from "./focus.js";
+export function renderNode(node, options) {
+    const { type } = node;
+    switch (type) {
+        case "Text":
+            return React.createElement(A2uiText, { key: node.instanceKey, node });
+        case "Box":
+            return React.createElement(A2uiBox, { key: node.instanceKey, node, options });
+        case "Spacer":
+            return React.createElement(Spacer, { key: node.instanceKey });
+        case "Input":
+            return React.createElement(A2uiInput, { key: node.instanceKey, node, options });
+        case "Button":
+            return React.createElement(A2uiButton, { key: node.instanceKey, node, options });
+        case "Select":
+            return React.createElement(A2uiSelect, { key: node.instanceKey, node, options });
+        default:
+            return React.createElement(Text, { key: node.instanceKey }, `Unsupported: ${type}`);
+    }
+}
+const A2uiText = ({ node }) => {
+    var _a, _b;
+    const props = node.props;
+    const text = ((_b = (_a = props.text) !== null && _a !== void 0 ? _a : props.value) !== null && _b !== void 0 ? _b : "");
+    return React.createElement(Text, {
+        color: props.color,
+        backgroundColor: props.backgroundColor,
+        bold: props.bold,
+        dimColor: props.dim,
+        italic: props.italic,
+        underline: props.underline
+    }, text);
+};
+const A2uiBox = ({ node, options }) => {
+    var _a;
+    const props = node.props;
+    return React.createElement(Box, {
+        flexDirection: (_a = props.direction) !== null && _a !== void 0 ? _a : "column",
+        padding: props.padding,
+        paddingX: props.paddingX,
+        paddingY: props.paddingY,
+        margin: props.margin,
+        marginX: props.marginX,
+        marginY: props.marginY,
+        borderStyle: props.borderStyle,
+        borderColor: props.borderColor,
+        width: props.width,
+        height: props.height,
+        flexGrow: props.flexGrow,
+        flexShrink: props.flexShrink,
+        justifyContent: props.justifyContent,
+        alignItems: props.alignItems
+    }, node.children.map((child) => renderNode(child, options)));
+};
+const A2uiButton = ({ node, options }) => {
+    var _a, _b;
+    const focus = useFocusRegistry();
+    const label = ((_b = (_a = node.props.label) !== null && _a !== void 0 ? _a : node.props.text) !== null && _b !== void 0 ? _b : "Button");
+    const action = node.props.onPress;
+    const isFocused = focus.isFocused(node.instanceKey);
+    useEffect(() => {
+        const handler = (input, key) => {
+            if (!action) {
+                return;
+            }
+            if (key.return || input === " ") {
+                options.dispatchAction(action, node);
+            }
+        };
+        focus.register(node.instanceKey, handler);
+        return () => focus.unregister(node.instanceKey);
+    }, [action, focus, node, options]);
+    return React.createElement(Box, { borderStyle: "round", borderColor: isFocused ? "cyan" : undefined, paddingX: 1 }, React.createElement(Text, { inverse: isFocused }, label));
+};
+const A2uiInput = ({ node, options }) => {
+    var _a;
+    const focus = useFocusRegistry();
+    const action = node.props.onChange;
+    const submitAction = node.props.onSubmit;
+    const initial = ((_a = node.props.value) !== null && _a !== void 0 ? _a : "");
+    const [value, setValue] = useState(initial);
+    useEffect(() => {
+        setValue(initial);
+    }, [initial]);
+    useEffect(() => {
+        const handler = (input, key) => {
+            if (key.return) {
+                if (submitAction) {
+                    options.dispatchAction(submitAction, node, value);
+                }
+                return;
+            }
+            if (key.backspace || key.delete) {
+                setValue((current) => current.slice(0, -1));
+                if (action) {
+                    options.dispatchAction(action, node, value.slice(0, -1));
+                }
+                return;
+            }
+            if (input) {
+                const next = `${value}${input}`;
+                setValue(next);
+                if (action) {
+                    options.dispatchAction(action, node, next);
+                }
+            }
+        };
+        focus.register(node.instanceKey, handler);
+        return () => focus.unregister(node.instanceKey);
+    }, [action, focus, node, options, submitAction, value]);
+    const isFocused = focus.isFocused(node.instanceKey);
+    return React.createElement(Box, null, React.createElement(Text, { color: isFocused ? "cyan" : undefined }, value || " "));
+};
+const A2uiSelect = ({ node, options }) => {
+    var _a, _b;
+    const focus = useFocusRegistry();
+    const items = ((_a = node.props.items) !== null && _a !== void 0 ? _a : []);
+    const action = node.props.onSelect;
+    const initialIndex = ((_b = node.props.selectedIndex) !== null && _b !== void 0 ? _b : 0);
+    const [index, setIndex] = useState(initialIndex);
+    useEffect(() => {
+        setIndex(initialIndex);
+    }, [initialIndex]);
+    useEffect(() => {
+        const handler = (input, key) => {
+            if (key.upArrow) {
+                setIndex((current) => (current <= 0 ? items.length - 1 : current - 1));
+                return;
+            }
+            if (key.downArrow) {
+                setIndex((current) => (current + 1) % items.length);
+                return;
+            }
+            if (key.return && action) {
+                const value = items[index];
+                options.dispatchAction(action, node, value);
+            }
+            if (input === " " && action) {
+                const value = items[index];
+                options.dispatchAction(action, node, value);
+            }
+        };
+        focus.register(node.instanceKey, handler);
+        return () => focus.unregister(node.instanceKey);
+    }, [action, focus, index, items, node, options]);
+    const isFocused = focus.isFocused(node.instanceKey);
+    const labels = useMemo(() => items.map(getItemLabel), [items]);
+    return React.createElement(Box, { flexDirection: "column" }, labels.map((label, itemIndex) => React.createElement(Text, { key: `${node.instanceKey}_${itemIndex}`, inverse: isFocused && itemIndex === index }, label)));
+};
+function getItemLabel(item) {
+    var _a, _b;
+    if (typeof item === "string" || typeof item === "number" || typeof item === "boolean") {
+        return String(item);
+    }
+    if (item && typeof item === "object") {
+        const record = item;
+        const label = (_b = (_a = record.label) !== null && _a !== void 0 ? _a : record.text) !== null && _b !== void 0 ? _b : record.name;
+        if (label) {
+            return String(label);
+        }
+    }
+    return JSON.stringify(item);
+}

package/dist/examples/demo.d.ts

@@ -0,0 +1 @@
+export {};