@affordances/react 0.0.0-stage → 0.0.0

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @affordances/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Affordances for React. `<AffordancesProvider>` loads the current page's graph and registers each available action as a WebMCP tool for browser agents; the tools call the page's Affordances endpoint, so they pass the same checks as any agent. `<Affordance>` marks the controls a person would use for an action, for agents that read the DOM. `<AffordancesDevtools>` from `@affordances/react/dev` outlines them in development.
+
+```bash
+vlt install @affordances/react
+```
+
+```tsx
+'use client'
+
+import { usePathname, useRouter } from 'next/navigation'
+import { AffordancesProvider } from '@affordances/react'
+
+export const Agents = ({ children }: { children: React.ReactNode }) => {
+  const pathname = usePathname()
+  const router = useRouter()
+  return (
+    <AffordancesProvider path={pathname} onDelta={() => router.refresh()}>
+      {children}
+    </AffordancesProvider>
+  )
+}
+```
+
+Docs: [https://github.com/vltpkg/affordances/blob/main/apps/docs/content/react.mdx](https://github.com/vltpkg/affordances/blob/main/apps/docs/content/react.mdx)

package/dist/affordance.d.ts

@@ -0,0 +1,11 @@
+export type AffordanceProps = {
+  children: React.ReactNode;
+  input?: Record<string, unknown>;
+} & ({
+  action: (...args: never[]) => unknown;
+  name?: never;
+} | {
+  name: string;
+  action?: never;
+});
+export declare const Affordance: ({ action, name, input, children }: AffordanceProps) => import("react").JSX.Element;

package/dist/affordance.js

@@ -0,0 +1,14 @@
+import { jsx } from "react/jsx-runtime";
+// src/affordance.tsx
+const AFFORDANCES = Symbol.for("affordances.action");
+const Affordance = ({ action, name, input, children }) => {
+	const resolved = name ?? action?.[AFFORDANCES]?.name;
+	if (!resolved) throw new Error("<Affordance action> needs an action from defineAction, used in a server component. In a client component, pass name=\"…\" instead.");
+	return /* @__PURE__ */ jsx("span", {
+		"data-affordances-action": resolved,
+		"data-affordances-input": input && JSON.stringify(input),
+		style: { display: "contents" },
+		children
+	});
+};
+export { Affordance };

package/dist/dev.d.ts

@@ -0,0 +1,3 @@
+export declare const AffordancesDevtools: ({ shortcut }: {
+  shortcut?: string;
+}) => import("react").JSX.Element | null;

package/dist/dev.js

@@ -0,0 +1,140 @@
+"use client";
+import { useAffordances } from "./provider.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+// src/dev.tsx
+const mono = "var(--font-geist-mono, ui-monospace, SFMono-Regular, monospace)";
+const measure = (marker) => {
+	const rects = [...marker.children].flatMap((child) => [...child.getClientRects()]);
+	if (!rects.length) return;
+	const top = Math.min(...rects.map((r) => r.top));
+	const left = Math.min(...rects.map((r) => r.left));
+	return {
+		top,
+		left,
+		width: Math.max(...rects.map((r) => r.right)) - left,
+		height: Math.max(...rects.map((r) => r.bottom)) - top
+	};
+};
+const AffordancesDevtools = ({ shortcut = "KeyA" }) => {
+	const { graph, lastDelta } = useAffordances();
+	const [open, setOpen] = useState(false);
+	const [boxes, setBoxes] = useState([]);
+	useEffect(() => {
+		const onKey = (event) => {
+			if (event.altKey && event.code === shortcut) setOpen((value) => !value);
+		};
+		addEventListener("keydown", onKey);
+		return () => removeEventListener("keydown", onKey);
+	}, [shortcut]);
+	useEffect(() => {
+		if (!open) return;
+		let frame = 0;
+		const update = () => {
+			cancelAnimationFrame(frame);
+			frame = requestAnimationFrame(() => {
+				const actions = new Map(graph?.actions.map((a) => [a.name, a]));
+				setBoxes([...document.querySelectorAll("[data-affordances-action]")].flatMap((marker) => {
+					const rect = measure(marker);
+					const name = marker.getAttribute("data-affordances-action");
+					const action = actions.get(name);
+					return rect ? [{
+						name,
+						available: action?.available ?? false,
+						reason: action?.reason,
+						...rect
+					}] : [];
+				}));
+			});
+		};
+		update();
+		const observer = new MutationObserver(update);
+		observer.observe(document.body, {
+			subtree: true,
+			childList: true,
+			attributes: true
+		});
+		addEventListener("scroll", update, {
+			passive: true,
+			capture: true
+		});
+		addEventListener("resize", update);
+		return () => {
+			cancelAnimationFrame(frame);
+			observer.disconnect();
+			removeEventListener("scroll", update, { capture: true });
+			removeEventListener("resize", update);
+		};
+	}, [open, graph]);
+	if (!open) return null;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-affordances-devtools": "",
+		"aria-live": "polite",
+		style: {
+			position: "fixed",
+			inset: 0,
+			pointerEvents: "none",
+			zIndex: 2147483647,
+			fontFamily: mono,
+			fontSize: 11
+		},
+		children: [boxes.map((box, i) => /* @__PURE__ */ jsx("div", {
+			style: {
+				position: "fixed",
+				top: box.top - 3,
+				left: box.left - 3,
+				width: box.width + 6,
+				height: box.height + 6,
+				border: `1px ${box.available ? "solid" : "dashed"} currentColor`,
+				borderRadius: 6,
+				color: "var(--foreground, #111)"
+			},
+			children: /* @__PURE__ */ jsxs("span", {
+				style: {
+					position: "absolute",
+					bottom: "100%",
+					left: -1,
+					marginBottom: 2,
+					padding: "1px 5px",
+					borderRadius: 4,
+					background: "var(--foreground, #111)",
+					color: "var(--background, #fff)",
+					whiteSpace: "nowrap",
+					lineHeight: "16px"
+				},
+				children: [box.name, !box.available && ` · ${box.reason ?? "unavailable"}`]
+			})
+		}, i)), /* @__PURE__ */ jsxs("section", {
+			"aria-label": "Affordances devtools",
+			style: {
+				position: "fixed",
+				right: 16,
+				bottom: 16,
+				width: 320,
+				maxHeight: "40vh",
+				overflow: "auto",
+				pointerEvents: "auto",
+				padding: 12,
+				borderRadius: 8,
+				border: "1px solid var(--border, #e5e5e5)",
+				background: "var(--background, #fff)",
+				color: "var(--foreground, #111)"
+			},
+			children: [/* @__PURE__ */ jsx("p", {
+				style: {
+					margin: 0,
+					color: "var(--muted-foreground, #666)"
+				},
+				children: graph ? `${graph.route} · ${graph.actions.length} actions · ${boxes.length} on screen` : "No graph for this page"
+			}), /* @__PURE__ */ jsx("pre", {
+				style: {
+					margin: "8px 0 0",
+					whiteSpace: "pre-wrap",
+					wordBreak: "break-word"
+				},
+				children: lastDelta ? JSON.stringify(lastDelta, null, 2) : "Call an action to see its delta."
+			})]
+		})]
+	});
+};
+export { AffordancesDevtools };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { Affordance, AffordanceProps } from "./affordance.js";
+import { AffordancesContext, AffordancesProvider, AffordancesProviderProps, useAffordances } from "./provider.js";
+import { ModelContext, ModelContextTool, getModelContext } from "./model-context.js";
+export { Affordance, type AffordanceProps, type AffordancesContext, AffordancesProvider, type AffordancesProviderProps, type ModelContext, type ModelContextTool, getModelContext, useAffordances };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { Affordance } from "./affordance.js";
+import { getModelContext } from "./model-context.js";
+import { AffordancesProvider, useAffordances } from "./provider.js";
+export { Affordance, AffordancesProvider, getModelContext, useAffordances };

package/dist/model-context.d.ts

@@ -0,0 +1,18 @@
+export type ModelContextTool = {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  annotations?: {
+    readOnlyHint?: boolean;
+    consequentialHint?: boolean;
+  };
+  execute: (input: unknown, options: {
+    signal?: AbortSignal;
+  }) => Promise<unknown>;
+};
+export type ModelContext = {
+  registerTool: (tool: ModelContextTool, options?: {
+    signal?: AbortSignal;
+  }) => unknown;
+};
+export declare const getModelContext: () => ModelContext | undefined;

package/dist/model-context.js

@@ -0,0 +1,6 @@
+// src/model-context.ts
+const getModelContext = () => {
+	if (typeof document === "undefined") return;
+	return document.modelContext ?? navigator.modelContext;
+};
+export { getModelContext };

package/dist/provider.d.ts

@@ -0,0 +1,15 @@
+import { Delta, Graph } from "@affordances/protocol";
+export type AffordancesContext = {
+  graph: Graph | null;
+  call: (action: string, input?: unknown) => Promise<Delta>;
+  lastDelta: Delta | null;
+  refresh: () => Promise<void>;
+};
+export type AffordancesProviderProps = {
+  children: React.ReactNode;
+  path: string;
+  onDelta?: (delta: Delta) => void;
+  confirm?: (message: string) => boolean | Promise<boolean>;
+};
+export declare const AffordancesProvider: ({ children, path, onDelta, confirm }: AffordancesProviderProps) => import("react").JSX.Element;
+export declare const useAffordances: () => AffordancesContext;

package/dist/provider.js

@@ -0,0 +1,94 @@
+"use client";
+import { getModelContext } from "./model-context.js";
+import { jsx } from "react/jsx-runtime";
+import { createContext, use, useCallback, useEffect, useRef, useState } from "react";
+import { MEDIA_TYPE } from "@affordances/protocol";
+// src/provider.tsx
+const Context = createContext(null);
+const post = (path, body) => fetch(path, {
+	method: "POST",
+	headers: {
+		"content-type": MEDIA_TYPE,
+		accept: MEDIA_TYPE
+	},
+	body: JSON.stringify(body)
+}).then((response) => response.json());
+const AffordancesProvider = ({ children, path, onDelta, confirm = (message) => window.confirm(message) }) => {
+	const [graph, setGraph] = useState(null);
+	const [lastDelta, setLastDelta] = useState(null);
+	const handlers = useRef({
+		onDelta,
+		confirm
+	});
+	useEffect(() => {
+		handlers.current = {
+			onDelta,
+			confirm
+		};
+	});
+	const load = useCallback(async (signal) => {
+		const response = await fetch(path, {
+			headers: { accept: MEDIA_TYPE },
+			signal
+		});
+		const isGraph = response.ok && response.headers.get("content-type")?.includes(MEDIA_TYPE);
+		setGraph(isGraph ? await response.json() : null);
+	}, [path]);
+	useEffect(() => {
+		const controller = new AbortController();
+		load(controller.signal).catch(() => {});
+		return () => controller.abort();
+	}, [load]);
+	const call = useCallback(async (action, input) => {
+		let delta = await post(path, {
+			action,
+			input
+		});
+		if (delta.error?.code === "confirm_required" && await handlers.current.confirm(delta.error.message)) delta = await post(path, {
+			action,
+			input,
+			confirm: true
+		});
+		setLastDelta(delta);
+		handlers.current.onDelta?.(delta);
+		await load().catch(() => {});
+		return delta;
+	}, [path, load]);
+	useEffect(() => {
+		const modelContext = getModelContext();
+		if (!modelContext || !graph) return;
+		const controller = new AbortController();
+		for (const action of graph.actions) {
+			if (!action.available) continue;
+			try {
+				Promise.resolve(modelContext.registerTool({
+					name: action.name,
+					description: action.description,
+					inputSchema: action.input,
+					annotations: {
+						readOnlyHint: action.readOnly ?? false,
+						consequentialHint: action.expose === "confirm"
+					},
+					execute: async (input) => JSON.stringify(await call(action.name, input))
+				}, { signal: controller.signal })).catch(() => {});
+			} catch {}
+		}
+		return () => controller.abort();
+	}, [graph, call]);
+	const refresh = useCallback(() => load(), [load]);
+	return /* @__PURE__ */ jsx(Context, {
+		value: {
+			graph,
+			call,
+			lastDelta,
+			refresh
+		},
+		children
+	});
+};
+const useAffordances = () => {
+	const context = use(Context);
+	if (!context) throw new Error("useAffordances needs an <AffordancesProvider> above it");
+	return context;
+};
+export { AffordancesProvider, useAffordances };

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@affordances/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "Affordances for React: WebMCP tools from the page graph, and <Affordance> markers",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vltpkg/affordances.git",
+    "directory": "packages/react"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./dev": {
+      "types": "./dist/dev.d.ts",
+      "default": "./dist/dev.js"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@affordances/protocol": "0.0.0"
+  },
+  "devDependencies": {
+    "@affordances/core": "0.0.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "happy-dom": "^21.0.4",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "zod": "^4.6.7"
+  },
+  "peerDependencies": {
+    "react": ">=19"
+  }
+}