@surfaice/react 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 surfaiceai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @surfaice/react
+
+React annotation components for Surfaice — describe your UI once, agents navigate it, CI verifies it.
+
+## Install
+
+```bash
+npm install @surfaice/react @surfaice/format
+```
+
+## Usage
+
+```tsx
+import { SurfaiceProvider, ui } from '@surfaice/react'
+
+// Wrap your app
+<SurfaiceProvider enabled={process.env.SURFAICE_ENABLED === 'true'}>
+  <App />
+</SurfaiceProvider>
+
+// Annotate your pages
+<ui.page route="/settings" name="Settings Page" states={['auth-required']}>
+  <ui.section name="Profile">
+    <ui.element id="name" type="textbox" label="Display Name"
+      value={user.name}
+      current="{user.name}"
+      action="PUT /api/profile">
+      <input value={user.name} onChange={handleChange} />
+    </ui.element>
+    <ui.element id="save" type="button" label="Save Changes"
+      action="PUT /api/profile"
+      result="toast 'Saved!'">
+      <button onClick={handleSave}>Save</button>
+    </ui.element>
+  </ui.section>
+</ui.page>
+```
+
+## API
+
+### `<SurfaiceProvider enabled? />`
+Context provider. Set `enabled={true}` to collect annotations. Zero overhead when disabled.
+
+### `ui.page` / `ui.section` / `ui.element`
+Annotation components — always render children as-is, optionally register metadata.
+
+### `useSurfaicePage(): SurfaicePage | null`
+Hook to access the collected page AST. Use in middleware or dev tools.
+
+## Zero Overhead When Disabled
+
+All annotation components are pure passthroughs when `enabled={false}` (the default). Ship to production without worry.

package/dist/components.d.ts

@@ -0,0 +1,40 @@
+import React from 'react';
+import type { ElementType, Capability } from '@surfaice/format';
+export interface UIPageProps {
+    route: string;
+    name?: string;
+    states?: string[];
+    capabilities?: Capability[];
+    children: React.ReactNode;
+}
+declare function UIPage({ route, name, states, capabilities, children }: UIPageProps): import("react/jsx-runtime").JSX.Element;
+export interface UISectionProps {
+    name: string;
+    children: React.ReactNode;
+}
+declare function UISection({ name, children }: UISectionProps): import("react/jsx-runtime").JSX.Element;
+export interface UIElementProps {
+    id: string;
+    type: ElementType;
+    label: string;
+    attributes?: string[];
+    action?: string;
+    result?: string;
+    navigates?: string;
+    /** Live runtime value — injected into agent-facing markdown */
+    value?: string | number | boolean;
+    /** Template binding for static export, e.g. "{user.name}" */
+    current?: string;
+    accepts?: string;
+    options?: string[];
+    /** Value displayed by display elements at runtime */
+    shows?: string | number;
+    children: React.ReactNode;
+}
+declare function UIElement({ children, value, shows, ...props }: UIElementProps): import("react/jsx-runtime").JSX.Element;
+export declare const ui: {
+    page: typeof UIPage;
+    section: typeof UISection;
+    element: typeof UIElement;
+};
+export {};

package/dist/components.js

@@ -0,0 +1,43 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useEffect, createContext } from 'react';
+import { SurfaiceContext } from './context.js';
+// Inner context to pass section name down to ui.element
+const SectionNameContext = createContext(null);
+function UIPage({ route, name, states, capabilities, children }) {
+    const ctx = useContext(SurfaiceContext);
+    useEffect(() => {
+        if (ctx.enabled) {
+            ctx.registerPage({ version: 'v1', route, name, states, capabilities });
+        }
+    }, [ctx.enabled, route, name]);
+    return _jsx(_Fragment, { children: children });
+}
+function UISection({ name, children }) {
+    const ctx = useContext(SurfaiceContext);
+    useEffect(() => {
+        if (ctx.enabled) {
+            ctx.registerSection({ name });
+        }
+    }, [ctx.enabled, name]);
+    return (_jsx(SectionNameContext.Provider, { value: name, children: children }));
+}
+function UIElement({ children, value, shows, ...props }) {
+    const ctx = useContext(SurfaiceContext);
+    const sectionName = useContext(SectionNameContext);
+    useEffect(() => {
+        if (ctx.enabled) {
+            ctx.registerElement({
+                ...props,
+                value: value !== undefined ? String(value) : props.current,
+                shows: shows !== undefined ? String(shows) : undefined,
+            }, sectionName ?? undefined);
+        }
+    }, [ctx.enabled, value, shows, props.id, sectionName]);
+    return _jsx(_Fragment, { children: children });
+}
+// ── ui namespace export ───────────────────────────────────────────────────────
+export const ui = {
+    page: UIPage,
+    section: UISection,
+    element: UIElement,
+};

package/dist/context.d.ts

@@ -0,0 +1,9 @@
+import type { SurfaicePage, Section, Element } from '@surfaice/format';
+export interface SurfaiceContextValue {
+    enabled: boolean;
+    page: SurfaicePage | null;
+    registerPage: (page: Partial<SurfaicePage>) => void;
+    registerSection: (section: Partial<Section>) => void;
+    registerElement: (element: Partial<Element>, sectionName?: string) => void;
+}
+export declare const SurfaiceContext: import("react").Context<SurfaiceContextValue>;

package/dist/context.js

@@ -0,0 +1,8 @@
+import { createContext } from 'react';
+export const SurfaiceContext = createContext({
+    enabled: false,
+    page: null,
+    registerPage: () => { },
+    registerSection: () => { },
+    registerElement: () => { },
+});

package/dist/hooks.d.ts

@@ -0,0 +1,7 @@
+import type { SurfaicePage } from '@surfaice/format';
+/**
+ * Hook to access the current collected SurfaicePage AST.
+ * Reactive — re-renders when annotations change.
+ * Returns null when provider is disabled or no page has been registered.
+ */
+export declare function useSurfaicePage(): SurfaicePage | null;

package/dist/hooks.js

@@ -0,0 +1,11 @@
+import { useContext } from 'react';
+import { SurfaiceContext } from './context.js';
+/**
+ * Hook to access the current collected SurfaicePage AST.
+ * Reactive — re-renders when annotations change.
+ * Returns null when provider is disabled or no page has been registered.
+ */
+export function useSurfaicePage() {
+    const ctx = useContext(SurfaiceContext);
+    return ctx.page;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { SurfaiceProvider } from './provider.js';
+export { ui } from './components.js';
+export { useSurfaicePage } from './hooks.js';
+export type { SurfaiceProviderProps } from './provider.js';
+export type { UIPageProps, UISectionProps, UIElementProps } from './components.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+// @surfaice/react
+export { SurfaiceProvider } from './provider.js';
+export { ui } from './components.js';
+export { useSurfaicePage } from './hooks.js';

package/dist/provider.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+export interface SurfaiceProviderProps {
+    /** Enable Surfaice annotation collection. Default: false (zero overhead in production) */
+    enabled?: boolean;
+    children: React.ReactNode;
+}
+export declare function SurfaiceProvider({ enabled, children }: SurfaiceProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/provider.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRef, useState, useCallback } from 'react';
+import { SurfaiceContext } from './context.js';
+import { SurfaiceRegistry } from './registry.js';
+export function SurfaiceProvider({ enabled = false, children }) {
+    const registryRef = useRef(new SurfaiceRegistry());
+    const [page, setPage] = useState(null);
+    const syncPage = useCallback(() => {
+        setPage(registryRef.current.toSurfaicePage());
+    }, []);
+    const registerPage = useCallback((p) => {
+        registryRef.current.setPage(p);
+        syncPage();
+    }, [syncPage]);
+    const registerSection = useCallback((s) => {
+        registryRef.current.addSection(s);
+        syncPage();
+    }, [syncPage]);
+    const registerElement = useCallback((e, sectionName) => {
+        registryRef.current.addElement(e, sectionName);
+        syncPage();
+    }, [syncPage]);
+    return (_jsx(SurfaiceContext.Provider, { value: {
+            enabled,
+            page: enabled ? page : null,
+            registerPage,
+            registerSection,
+            registerElement,
+        }, children: children }));
+}

package/dist/registry.d.ts

@@ -0,0 +1,21 @@
+import type { SurfaicePage, Section, Element } from '@surfaice/format';
+/**
+ * SurfaiceRegistry collects UI annotations at render time.
+ *
+ * React fires useEffect bottom-up (children before parents), so registration
+ * order is: elements → sections → page. We buffer elements with their target
+ * section name and reconcile when producing the final AST.
+ */
+export declare class SurfaiceRegistry {
+    private _meta;
+    private _sectionNames;
+    private _pendingElements;
+    private _currentSectionName;
+    setPage(page: Partial<SurfaicePage>): void;
+    addSection(section: Partial<Section>): void;
+    /** Register an element, tagged to the current section name */
+    addElement(element: Partial<Element>, sectionName?: string): void;
+    toSurfaicePage(): SurfaicePage | null;
+    get page(): SurfaicePage | null;
+    reset(): void;
+}

package/dist/registry.js

@@ -0,0 +1,66 @@
+/**
+ * SurfaiceRegistry collects UI annotations at render time.
+ *
+ * React fires useEffect bottom-up (children before parents), so registration
+ * order is: elements → sections → page. We buffer elements with their target
+ * section name and reconcile when producing the final AST.
+ */
+export class SurfaiceRegistry {
+    _meta = null;
+    _sectionNames = [];
+    _pendingElements = [];
+    // Track which section name the most recently registered section belongs to,
+    // so elements registered before their section still land correctly.
+    _currentSectionName = null;
+    setPage(page) {
+        this._meta = { ...page };
+    }
+    addSection(section) {
+        const name = section.name ?? 'Unnamed Section';
+        if (!this._sectionNames.includes(name)) {
+            this._sectionNames.push(name);
+        }
+        this._currentSectionName = name;
+    }
+    /** Register an element, tagged to the current section name */
+    addElement(element, sectionName) {
+        const target = sectionName ?? this._currentSectionName;
+        if (!target)
+            return;
+        const el = {
+            id: element.id ?? '',
+            type: element.type ?? 'text',
+            label: element.label ?? '',
+            ...element,
+        };
+        this._pendingElements.push({ sectionName: target, element: el });
+    }
+    toSurfaicePage() {
+        if (!this._meta)
+            return null;
+        // Build sections, attaching elements
+        const sections = this._sectionNames.map(name => ({
+            name,
+            elements: this._pendingElements
+                .filter(p => p.sectionName === name)
+                .map(p => p.element),
+        }));
+        return {
+            version: this._meta.version ?? 'v1',
+            route: this._meta.route ?? '/',
+            ...(this._meta.name !== undefined && { name: this._meta.name }),
+            ...(this._meta.states !== undefined && { states: this._meta.states }),
+            ...(this._meta.capabilities !== undefined && { capabilities: this._meta.capabilities }),
+            sections,
+        };
+    }
+    get page() {
+        return this.toSurfaicePage();
+    }
+    reset() {
+        this._meta = null;
+        this._sectionNames = [];
+        this._pendingElements = [];
+        this._currentSectionName = null;
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@surfaice/react",
+  "version": "0.0.1",
+  "description": "React annotations for Surfaice — describe your UI once, agents navigate it",
+  "main": "./dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/surfaiceai/surfaice",
+    "directory": "packages/react"
+  },
+  "dependencies": {
+    "@surfaice/format": "0.0.1"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "vitest": "^2.0.0",
+    "typescript": "^5.5.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "jsdom": "^25.0.0",
+    "@testing-library/jest-dom": "^6.0.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev": "tsc --watch"
+  }
+}