graftjs 0.1.0

package/README.md

@@ -0,0 +1,576 @@
+```
+                                 ▄▄▄▄            
+                                 ██▀▀▀     ██     
+  ▄███▄██   ██▄████   ▄█████▄  ███████   ███████  
+ ██▀  ▀██   ██▀       ▀ ▄▄▄██    ██        ██     
+ ██    ██   ██       ▄██▀▀▀██    ██        ██     
+ ▀██▄▄███   ██       ██▄▄▄███    ██        ██▄▄▄  
+  ▄▀▀▀ ██   ▀▀        ▀▀▀▀ ▀▀    ▀▀         ▀▀▀▀  
+  ▀████▀▀ 
+```
+
+*The smallest API imaginable.*
+
+# graft
+
+Compose React components by wiring named parameters together.
+
+`compose({ into, from, key })` feeds `from`'s output into `into`'s input named `key`. The remaining unsatisfied inputs bubble up as the composed component's props. The result is always a standard React component.
+
+No prop drilling. No Context. No useState. No useEffect. No manual subscriptions.
+
+```
+npm install graft
+```
+
+## Why
+
+React components are functions with named parameters (props). When you build a UI, you're really building a graph of data dependencies between those functions. But React forces you to wire that graph imperatively — passing props down, lifting state up, wrapping in Context providers, sprinkling hooks everywhere.
+
+Graft lets you describe the wiring directly. You say *what* feeds into *what*, and the library builds the component for you. The unsatisfied inputs become the new component's props. This is [graph programming](https://uriva.github.io/blog/graph-programming.html) applied to React.
+
+Graft drastically reduces the tokens needed to construct something, and drastically reduces the number of possible bugs.
+
+## Core concepts
+
+There are only two things: **components** and **compose**.
+
+A **component** is a typed function from inputs to an output. If the output is a `ReactElement`, it renders UI. If the output is a `number`, `string`, `object`, etc., it's a data source. There is no separate "provider" concept — everything is a component.
+
+A **source** is a component with no inputs that pushes values over time — a WebSocket, a timer, a browser API. It's one way to introduce reactivity. Everything downstream re-runs automatically when a source emits.
+
+**`state`** is a global mutable cell. It returns a `[Component, setter]` tuple. The component behaves like a source (no inputs, emits values), and the setter can be called from anywhere — event handlers, outside the graph, wherever. New subscribers receive the current value immediately.
+
+**`instantiate`** creates an isolated copy of a subgraph. It takes a template — a function that builds and returns a component — and returns a new component. Each subscription gets its own fresh instance, so any `state()` or `source()` calls inside the template produce independent cells. This is how you get local state.
+
+**`compose({ into, from, key })`** wires `from`'s output into `into`'s input named `key`. Returns a new component whose inputs are `into`'s remaining inputs plus `from`'s inputs.
+
+When you're done composing, **`toReact`** converts the result into a regular `React.FC` (requires the output to be `ReactElement`).
+
+### "The" vs "a"
+
+In React, everything is **"a"** by default. Each render creates *a* counter, *a* form, *a* piece of state. Multiple instances are the norm — you get isolation for free via hooks.
+
+Graft defaults to **"the"**. `state()` creates *the* cell. `source()` creates *the* stream. There is exactly one, and every subscriber sees the same value. Definiteness is the default.
+
+`instantiate()` is how you say **"a"** — it's the explicit opt-in to indefinite instances. Each subscription gets its own independent copy of the subgraph, with its own state cells and source subscriptions.
+
+## Quick example
+
+A live crypto price card. The price streams over Binance's public WebSocket, the coin name is fetched async from CoinGecko, and a header embeds as a child View inside the card layout. All real, no API keys.
+
+```mermaid
+graph BT
+    App["<App coinId="bitcoin" />"] -- coinId --> CoinName
+    CoinName -- name --> Header
+    Header -- header --> PriceCard
+    PriceFeed -- price --> FormatPrice
+    FormatPrice -- displayPrice --> PriceCard
+    PriceCard -- View --> Output((" "))
+
+    style Output fill:none,stroke:none
+```
+
+```tsx
+import { z } from "zod/v4";
+import { component, compose, source, toReact, View } from "graft";
+
+// A live price feed — pushes new values over a public WebSocket.
+// source() is the only way to introduce reactivity into a graft graph.
+// Everything downstream re-runs automatically when it emits.
+const PriceFeed = source({
+  output: z.number(),
+  run: (emit) => {
+    const ws = new WebSocket("wss://stream.binance.com:9443/ws/btcusdt@trade");
+    ws.onmessage = (e) => emit(Number(JSON.parse(e.data).p));
+    return () => ws.close();
+  },
+});
+
+// An async data component — fetches the coin name from CoinGecko.
+// The run function is async. compose handles this automatically.
+const CoinName = component({
+  input: z.object({ coinId: z.string() }),
+  output: z.string(),
+  run: async ({ coinId }) => {
+    const res = await fetch(
+      `https://api.coingecko.com/api/v3/coins/${coinId}?localization=false&tickers=false&market_data=false&community_data=false&developer_data=false`,
+    );
+    return (await res.json()).name;
+  },
+});
+
+// A pure data component — formats a number into a display string.
+const FormatPrice = component({
+  input: z.object({ price: z.number() }),
+  output: z.string(),
+  run: ({ price }) =>
+    new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(price),
+});
+
+// A header component — returns a View.
+const Header = component({
+  input: z.object({ name: z.string() }),
+  output: View,
+  run: ({ name }) => <h1>{name}</h1>,
+});
+
+// The page layout — accepts a View for the header slot and a string for the price.
+// It doesn't know where any of its inputs come from.
+const PriceCard = component({
+  input: z.object({ header: View, displayPrice: z.string() }),
+  output: View,
+  run: ({ header, displayPrice }) => (
+    <div>
+      {header}
+      <span>{displayPrice}</span>
+    </div>
+  ),
+});
+
+// --- Wiring ---
+
+// PriceFeed → FormatPrice → PriceCard.displayPrice
+const LivePrice = compose({ into: FormatPrice, from: PriceFeed, key: "price" });
+const WithPrice = compose({ into: PriceCard, from: LivePrice, key: "displayPrice" });
+
+// CoinName (async) → Header → PriceCard.header
+const NamedHeader = compose({ into: Header, from: CoinName, key: "name" });
+const App = toReact(
+  compose({ into: WithPrice, from: NamedHeader, key: "header" }),
+);
+
+// One prop left — everything else is wired internally.
+// Renders nothing while CoinGecko loads, then shows the card.
+// When Binance pushes a new trade, only the price path re-runs.
+<App coinId="bitcoin" />
+```
+
+<p align="center">
+  <img src="demo.gif" alt="Live crypto price card demo" width="600" />
+</p>
+
+## API
+
+### `component({ input, output, run })`
+
+Define a component from a zod input schema, a zod output schema, and a function.
+
+```tsx
+import { z } from "zod/v4";
+import { component, View } from "graft";
+
+// A visual component (output is ReactElement)
+const UserCard = component({
+  input: z.object({
+    name: z.string(),
+    email: z.string(),
+    age: z.number(),
+  }),
+  output: View,
+  run: ({ name, email, age }) => (
+    <div>
+      <h2>{name}</h2>
+      <p>{email}</p>
+      <p>{age} years old</p>
+    </div>
+  ),
+});
+
+// A data component (output is a number)
+const FetchAge = component({
+  input: z.object({ userId: z.string() }),
+  output: z.number(),
+  run: ({ userId }) => lookupAge(userId),
+});
+```
+
+The input schema is the source of truth for both TypeScript types and runtime validation. The output schema declares the type of value the component produces. Use `View` for components that return JSX.
+
+### `compose({ into, from, key })`
+
+Wire `from`'s output into `into`'s input named `key`. Returns a new component.
+
+```tsx
+import { compose } from "graft";
+
+// UserCard needs { name, email, age }
+// FetchAge needs { userId } and produces a number
+// After composing on "age":
+//   → new component needs { name, email, userId }
+const UserCardWithAge = compose({ into: UserCard, from: FetchAge, key: "age" });
+```
+
+The key insight: `"age"` disappears from the inputs because it's now satisfied internally. `"userId"` appears because FetchAge needs it and nobody provides it yet.
+
+### `toReact(graftComponent)`
+
+Convert a graft component into a standard `React.FC`. This is the boundary between graft and React. The component must produce a `ReactElement`. Props are validated at runtime — a `ZodError` is thrown if anything is missing or has the wrong type.
+
+```tsx
+import { toReact } from "graft";
+
+const UserCardReact = toReact(UserCardWithAge);
+
+// TypeScript knows the props are { name: string, email: string, userId: string }
+<UserCardReact name="Alice" email="alice@example.com" userId="u123" />
+```
+
+### `source({ output, run })`
+
+Create a push-based data source with no inputs. This is the only way to introduce reactivity into a graft graph. The `run` function receives an `emit` callback and returns a cleanup function.
+
+```tsx
+import { z } from "zod/v4";
+import { source } from "graft";
+
+const GeoLocation = source({
+  output: z.object({ lat: z.number(), lng: z.number() }),
+  run: (emit) => {
+    const id = navigator.geolocation.watchPosition((pos) =>
+      emit({ lat: pos.coords.latitude, lng: pos.coords.longitude }),
+    );
+    return () => navigator.geolocation.clearWatch(id);
+  },
+});
+```
+
+When a source emits a new value, every downstream component that depends on it re-runs automatically. Cleanup is called when the React component unmounts.
+
+### `state({ schema, initial })`
+
+Create a global mutable state cell. Returns a `[Component, setter]` tuple.
+
+```tsx
+import { z } from "zod/v4";
+import { state, component, compose, toReact, View } from "graft";
+
+const [CurrentUser, setCurrentUser] = state({
+  schema: z.string(),
+  initial: "anonymous",
+});
+
+const Greeting = component({
+  input: z.object({ name: z.string() }),
+  output: View,
+  run: ({ name }) => <h1>Hello, {name}</h1>,
+});
+
+const App = toReact(
+  compose({ into: Greeting, from: CurrentUser, key: "name" }),
+);
+
+// Renders: <h1>Hello, anonymous</h1>
+// Then call from anywhere:
+setCurrentUser("Alice");
+// Re-renders: <h1>Hello, Alice</h1>
+```
+
+The component behaves like a source — no inputs, emits values, works with `compose`. The setter is a plain function you can call from event handlers, callbacks, or anywhere else. New subscribers immediately receive the current value, so they never start empty.
+
+Note: `state` is global — all usages share the same cell. If you need local state (e.g., two independent form fields from the same template), use `instantiate`.
+
+### `instantiate(template)`
+
+Create an isolated instance of a subgraph. The template is a function that builds and returns a component. Each call to `instantiate` creates independent `state()` cells and `source()` subscriptions.
+
+**When to use `instantiate` vs a plain `component`:**
+
+A `component` is a pure function — same inputs, same output. It has no internal state. If you only need to transform data or render props into JSX, use `component`. That's most of the time.
+
+Use `instantiate` when a piece of your graph needs **its own mutable state** — state that is local to that usage, not shared globally. The typical case is reusable UI elements: form fields, toggles, expandable sections, anything where each usage needs independent internal state.
+
+```tsx
+import { z } from "zod/v4";
+import { component, compose, instantiate, state, toReact, View } from "graft";
+
+// A template: a function that builds a subgraph.
+// Each call creates fresh state() cells.
+const TextField = () => {
+  const [Value, setValue] = state({ schema: z.string(), initial: "" });
+
+  const Input = component({
+    input: z.object({ label: z.string(), text: z.string() }),
+    output: View,
+    run: ({ label, text }) => (
+      <label>
+        {label}
+        <input value={text} onChange={(e) => setValue(e.target.value)} />
+      </label>
+    ),
+  });
+
+  return compose({ into: Input, from: Value, key: "text" });
+};
+
+// Two independent instances — each has its own Value state cell.
+const NameField = instantiate(TextField);
+const EmailField = instantiate(TextField);
+
+const Form = component({
+  input: z.object({ name: View, email: View }),
+  output: View,
+  run: ({ name, email }) => (
+    <form>
+      {name}
+      {email}
+    </form>
+  ),
+});
+
+const WithName = compose({ into: Form, from: NameField, key: "name" });
+const App = toReact(
+  compose({ into: WithName, from: EmailField, key: "email" }),
+);
+
+// Each field maintains its own text value independently.
+<App label="Name" />
+```
+
+Without `instantiate`, both fields would share the same `state()` cell — typing in one would update both. `instantiate` ensures each usage gets its own isolated copy of the entire subgraph.
+
+### `View`
+
+A pre-built zod schema for `ReactElement` output. Use it as the `output` for any component that returns JSX.
+
+```tsx
+import { View } from "graft";
+
+const MyComponent = component({
+  input: z.object({ text: z.string() }),
+  output: View,
+  run: ({ text }) => <p>{text}</p>,
+});
+```
+
+### `GraftLoading`
+
+A unique symbol sentinel. Emitted by `subscribe()` when an async component or lazy source hasn't produced a value yet. See [Loading and error states](#loading-and-error-states).
+
+### `isGraftError(value)`
+
+Type guard that checks if a value is a `GraftError` sentinel. Returns `true` for error objects produced by async component rejections. See [Loading and error states](#loading-and-error-states).
+
+## Chaining compositions
+
+`compose` returns a graft component, so you can compose again. Each step satisfies one more input, and the unsatisfied inputs keep bubbling up.
+
+```tsx
+const Display = component({
+  input: z.object({ msg: z.string() }),
+  output: View,
+  run: ({ msg }) => <p>{msg}</p>,
+});
+
+const Format = component({
+  input: z.object({ greeting: z.string(), name: z.string() }),
+  output: z.string(),
+  run: ({ greeting, name }) => `${greeting}, ${name}!`,
+});
+
+const MakeGreeting = component({
+  input: z.object({ prefix: z.string() }),
+  output: z.string(),
+  run: ({ prefix }) => `${prefix} says`,
+});
+
+// Step 1: Format feeds into Display's "msg"
+// Remaining inputs: { greeting, name }
+const Step1 = compose({ into: Display, from: Format, key: "msg" });
+
+// Step 2: MakeGreeting feeds into Step1's "greeting"
+// Remaining inputs: { prefix, name }
+const Step2 = compose({ into: Step1, from: MakeGreeting, key: "greeting" });
+
+const App = toReact(Step2);
+
+<App prefix="Alice" name="Bob" />
+// Renders: <p>Alice says, Bob!</p>
+```
+
+Each `compose` call is like drawing one edge in a dependency graph. The final component is the whole graph, with only the unconnected inputs exposed as props.
+
+## A more realistic example
+
+Consider a user profile page that needs data from multiple sources:
+
+```tsx
+// --- Visual component ---
+
+const ProfilePage = component({
+  input: z.object({
+    name: z.string(),
+    email: z.string(),
+    postCount: z.number(),
+    avatarUrl: z.string(),
+  }),
+  output: View,
+  run: ({ name, email, postCount, avatarUrl }) => (
+    <div>
+      <img src={avatarUrl} alt={name} />
+      <h1>{name}</h1>
+      <p>{email}</p>
+      <p>{postCount} posts</p>
+    </div>
+  ),
+});
+
+// --- Data components ---
+
+const UserInfo = component({
+  input: z.object({ userId: z.string() }),
+  output: z.object({ name: z.string(), email: z.string() }),
+  run: ({ userId }) => db.getUser(userId),
+});
+
+const PostCount = component({
+  input: z.object({ userId: z.string() }),
+  output: z.number(),
+  run: ({ userId }) => db.countPosts(userId),
+});
+
+const Avatar = component({
+  input: z.object({ email: z.string() }),
+  output: z.string(),
+  run: ({ email }) => `https://gravatar.com/avatar/${hash(email)}`,
+});
+
+const ExtractName = component({
+  input: z.object({ userInfo: z.object({ name: z.string(), email: z.string() }) }),
+  output: z.string(),
+  run: ({ userInfo }) => userInfo.name,
+});
+
+const ExtractEmail = component({
+  input: z.object({ userInfo: z.object({ name: z.string(), email: z.string() }) }),
+  output: z.string(),
+  run: ({ userInfo }) => userInfo.email,
+});
+
+// --- Wiring ---
+
+const WithPostCount = compose({ into: ProfilePage, from: PostCount, key: "postCount" });
+// Inputs: { name, email, avatarUrl, userId }
+
+const WithAvatar = compose({ into: WithPostCount, from: Avatar, key: "avatarUrl" });
+// Inputs: { name, userId, email }
+
+const WithName = compose({ into: WithAvatar, from: ExtractName, key: "name" });
+// Inputs: { userId, email, userInfo }
+
+const WithEmail = compose({ into: WithName, from: ExtractEmail, key: "email" });
+// Inputs: { userId, userInfo }
+
+const WithUserInfo = compose({ into: WithEmail, from: UserInfo, key: "userInfo" });
+// Inputs: { userId }
+
+const ProfilePageReact = toReact(WithUserInfo);
+
+// The only input left is userId — everything else is wired internally
+<ProfilePageReact userId="u123" />
+```
+
+## Runtime validation
+
+Every input is validated at runtime using the zod schemas you defined. If an input is missing or has the wrong type, you get a clear `ZodError` at render time — not a silent `undefined` propagating through your component tree.
+
+```tsx
+const App = toReact(
+  component({
+    input: z.object({ count: z.number() }),
+    output: View,
+    run: ({ count }) => <span>{count}</span>,
+  }),
+);
+
+// This throws a ZodError at runtime:
+<App count="not a number" />
+// ZodError: Invalid input: expected number, received string
+```
+
+## Loading and error states
+
+When a component in a graph is async, the graph needs to handle the time before the value arrives and the case where it fails. Graft does this with two sentinel values that flow through the graph like regular data.
+
+### `GraftLoading`
+
+A unique symbol emitted by `subscribe()` when a value is not yet available:
+
+- **Async components** emit `GraftLoading` immediately, then the resolved value.
+- **Sources** that don't call `emit` synchronously in their `run` function emit `GraftLoading` until the first `emit`.
+- **Sync components** and **state** never emit `GraftLoading` — they always have a value immediately.
+
+When `compose` sees `GraftLoading` from `from`, it short-circuits — `into`'s `run` is **not** called, and `GraftLoading` is passed through to the outer subscriber. This means loading propagates through the entire chain automatically.
+
+`toReact` renders `null` for `GraftLoading`.
+
+### `GraftError`
+
+A branded object `{ _tag: Symbol("GraftError"), error: unknown }` that carries a caught error through the graph:
+
+- **Async components** that reject produce a `GraftError` containing the rejection reason.
+- Like `GraftLoading`, errors short-circuit through `compose` without calling downstream `run` functions.
+- `toReact` renders `null` for `GraftError`.
+
+```tsx
+import { GraftLoading, isGraftError } from "graft";
+
+const AsyncData = component({
+  input: z.object({ id: z.string() }),
+  output: z.number(),
+  run: async ({ id }) => {
+    const res = await fetch(`/api/data/${id}`);
+    if (!res.ok) throw new Error("fetch failed");
+    return (await res.json()).value;
+  },
+});
+
+// subscribe() lets you observe the full lifecycle:
+AsyncData.subscribe({ id: "123" }, (value) => {
+  if (value === GraftLoading) {
+    // Still loading...
+  } else if (isGraftError(value)) {
+    console.error("Error:", value.error);
+  } else {
+    console.log("Got value:", value);
+  }
+});
+```
+
+The `run()` function is unaffected — it returns the raw `Promise` that rejects normally. The sentinel system only applies to `subscribe()` and `toReact()`.
+
+**Note:** `state()` never produces sentinels. It always has a value (the initial value), and the setter updates it synchronously. This is by design — state is always "ready".
+
+## Deduplication
+
+`compose` deduplicates emissions from `from` using reference equality (`===`). When `from` emits the same value it emitted last time, the re-subscription to `into` is skipped entirely — `into`'s `run` is never called, and no value propagates downstream.
+
+This means:
+- A source spamming the same primitive (e.g., a timer re-emitting `0`) doesn't cause unnecessary work.
+- Calling a state setter with the current value is a no-op for downstream subscribers.
+- Consecutive `GraftLoading` sentinels are collapsed into one.
+
+Reference equality is intentional. Two different objects with identical content (`{ x: 1 } !== { x: 1 }`) are *not* deduped — this matches React's behavior and avoids the cost and surprises of deep comparison.
+
+## How it works
+
+Graft is a runtime library, not a compiler plugin. `compose()` is a regular function call that:
+
+1. Takes `into`'s input schema and removes the key being wired
+2. Merges the remaining shape with `from`'s input schema
+3. Returns a new graft component with the merged schema
+4. At render time, splits the incoming props, runs `from`, and passes the result to `into`
+
+The type-level generics ensure TypeScript knows exactly what inputs the composed component needs. The runtime zod validation ensures the types are enforced even in JavaScript or at module boundaries.
+
+## Install
+
+```
+npm install graft
+```
+
+Requires React 18+ as a peer dependency. Uses [zod v4](https://zod.dev) (`zod/v4` import) for schemas.
+
+## License
+
+MIT

package/dist/component.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod/v4";
+import { type GraftComponent, type MaybePromise } from "./types.js";
+/**
+ * Define a graft component from an input schema, output schema, and a function.
+ *
+ * If the function returns JSX, this is a visual component.
+ * If it returns data, this is a data source.
+ * The run function may be sync or async — compose handles both.
+ */
+export declare function component<S extends z.ZodObject<z.ZodRawShape>, O>({ input, output, run }: {
+    input: S;
+    output: z.ZodType<O>;
+    run: (props: z.infer<S>) => MaybePromise<O>;
+}): GraftComponent<S, O>;

package/dist/component.js

@@ -0,0 +1,30 @@
+import { GraftLoading, graftError } from "./types.js";
+function isPromise(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        typeof value.then === "function");
+}
+/**
+ * Define a graft component from an input schema, output schema, and a function.
+ *
+ * If the function returns JSX, this is a visual component.
+ * If it returns data, this is a data source.
+ * The run function may be sync or async — compose handles both.
+ */
+export function component({ input, output, run }) {
+    const subscribe = (props, cb) => {
+        let cancelled = false;
+        const result = run(props);
+        if (isPromise(result)) {
+            cb(GraftLoading);
+            result.then((v) => { if (!cancelled)
+                cb(v); }, (err) => { if (!cancelled)
+                cb(graftError(err)); });
+        }
+        else {
+            cb(result);
+        }
+        return () => { cancelled = true; };
+    };
+    return { _tag: "graft-component", schema: input, outputSchema: output, run, subscribe };
+}

package/dist/compose.d.ts

@@ -0,0 +1,37 @@
+import React, { type ReactElement } from "react";
+import { z } from "zod/v4";
+import { type GraftComponent } from "./types.js";
+/**
+ * compose({ into, from, key }):
+ *   - into: a component with inputs SA that produces OA
+ *   - from: a component with inputs SB that produces OB
+ *   - key: an input name of `into` whose type matches OB
+ *   - Result: a component whose inputs are SA minus key, plus SB,
+ *     and whose output is OA
+ *
+ * If either `from` or `into` is async, the composed run is async.
+ * `from`'s output feeds into `into[key]`, remaining params bubble up.
+ *
+ * subscribe() propagates reactivity: subscribes to `from`, and whenever
+ * `from` emits, re-subscribes to `into` with the new value, forwarding
+ * `into`'s emissions to the outer callback.
+ *
+ * If `from` emits GraftLoading or GraftError, compose short-circuits —
+ * it passes the sentinel directly to the outer callback without calling
+ * `into`'s run/subscribe.
+ */
+export declare function compose<SA extends z.ZodObject<z.ZodRawShape>, SB extends z.ZodObject<z.ZodRawShape>, K extends string & keyof z.infer<SA>, OA, OB>({ into, from, key }: {
+    into: GraftComponent<SA, OA>;
+    from: GraftComponent<SB, OB>;
+    key: K;
+}): GraftComponent<z.ZodObject<Omit<SA["shape"], K> & SB["shape"]>, OA>;
+/**
+ * Convert a GraftComponent that returns ReactElement into a real React.FC.
+ * This is the boundary between graft and React.
+ *
+ * Uses subscribe() internally so that reactive sources automatically
+ * cause re-renders. For non-reactive graphs this fires once.
+ *
+ * GraftLoading and GraftError values are rendered as null.
+ */
+export declare function toReact<S extends z.ZodObject<z.ZodRawShape>>(gc: GraftComponent<S, ReactElement>): React.FC<z.infer<S>>;

package/dist/compose.js

@@ -0,0 +1,148 @@
+import { useState, useEffect } from "react";
+import { z } from "zod/v4";
+import { isSentinel } from "./types.js";
+/** Sentinel for "no previous value" in deduplication logic. */
+const UNSET = Symbol("UNSET");
+function isPromise(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        typeof value.then === "function");
+}
+/**
+ * Helper: split combined props into from's inputs and into's remaining inputs.
+ */
+function splitProps(parsed, into, from, key) {
+    const fromInput = {};
+    for (const fromKey of Object.keys(from.schema.shape)) {
+        fromInput[fromKey] = parsed[fromKey];
+    }
+    const buildIntoInput = (fromOutput) => {
+        const intoInput = { [key]: fromOutput };
+        for (const intoKey of Object.keys(into.schema.shape)) {
+            if (intoKey === key)
+                continue;
+            if (intoKey in parsed)
+                intoInput[intoKey] = parsed[intoKey];
+        }
+        return intoInput;
+    };
+    return { fromInput, buildIntoInput };
+}
+/**
+ * compose({ into, from, key }):
+ *   - into: a component with inputs SA that produces OA
+ *   - from: a component with inputs SB that produces OB
+ *   - key: an input name of `into` whose type matches OB
+ *   - Result: a component whose inputs are SA minus key, plus SB,
+ *     and whose output is OA
+ *
+ * If either `from` or `into` is async, the composed run is async.
+ * `from`'s output feeds into `into[key]`, remaining params bubble up.
+ *
+ * subscribe() propagates reactivity: subscribes to `from`, and whenever
+ * `from` emits, re-subscribes to `into` with the new value, forwarding
+ * `into`'s emissions to the outer callback.
+ *
+ * If `from` emits GraftLoading or GraftError, compose short-circuits —
+ * it passes the sentinel directly to the outer callback without calling
+ * `into`'s run/subscribe.
+ */
+export function compose({ into, from, key }) {
+    // Build the new schema: into's shape minus key, plus from's shape
+    const intoShape = { ...into.schema.shape };
+    delete intoShape[key];
+    const newShape = { ...intoShape, ...from.schema.shape };
+    const newSchema = z.object(newShape);
+    const run = (props) => {
+        const parsed = newSchema.parse(props);
+        const { fromInput, buildIntoInput } = splitProps(parsed, into, from, key);
+        const fromOutput = from.run(fromInput);
+        const runInto = (resolvedFromOutput) => {
+            return into.run(buildIntoInput(resolvedFromOutput));
+        };
+        if (isPromise(fromOutput)) {
+            return fromOutput.then((v) => runInto(v));
+        }
+        return runInto(fromOutput);
+    };
+    const subscribe = (props, cb) => {
+        const parsed = newSchema.parse(props);
+        const { fromInput, buildIntoInput } = splitProps(parsed, into, from, key);
+        // Track the current inner (into) subscription so we can tear it down
+        // when from emits a new value.
+        let intoCleanup = null;
+        let disposed = false;
+        // Deduplication: skip re-subscription when from emits the same value.
+        let lastFromValue = UNSET;
+        const fromCleanup = from.subscribe(fromInput, (fromValue) => {
+            if (disposed)
+                return;
+            // Reference equality dedup — skip if same value as last time.
+            if (fromValue === lastFromValue)
+                return;
+            lastFromValue = fromValue;
+            // Tear down previous into subscription
+            if (intoCleanup)
+                intoCleanup();
+            intoCleanup = null;
+            // Short-circuit on sentinels — don't call into's run/subscribe
+            if (isSentinel(fromValue)) {
+                cb(fromValue);
+                return;
+            }
+            // Subscribe to into with the new from value
+            intoCleanup = into.subscribe(buildIntoInput(fromValue), (intoValue) => {
+                if (!disposed)
+                    cb(intoValue);
+            });
+        });
+        return () => {
+            disposed = true;
+            fromCleanup();
+            if (intoCleanup)
+                intoCleanup();
+        };
+    };
+    return {
+        _tag: "graft-component",
+        schema: newSchema,
+        outputSchema: into.outputSchema,
+        run,
+        subscribe,
+    };
+}
+/**
+ * Convert a GraftComponent that returns ReactElement into a real React.FC.
+ * This is the boundary between graft and React.
+ *
+ * Uses subscribe() internally so that reactive sources automatically
+ * cause re-renders. For non-reactive graphs this fires once.
+ *
+ * GraftLoading and GraftError values are rendered as null.
+ */
+export function toReact(gc) {
+    const ReactComponent = (props) => {
+        const [element, setElement] = useState(null);
+        useEffect(() => {
+            let cancelled = false;
+            const cleanup = gc.subscribe(gc.schema.parse(props), (value) => {
+                if (cancelled)
+                    return;
+                if (isSentinel(value)) {
+                    setElement(null);
+                }
+                else {
+                    setElement(value);
+                }
+            });
+            return () => {
+                cancelled = true;
+                cleanup();
+            };
+            // eslint-disable-next-line react-hooks/exhaustive-deps
+        }, [gc, ...Object.values(props)]);
+        return element;
+    };
+    ReactComponent.displayName = "GraftComponent";
+    return ReactComponent;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { component } from "./component.js";
+export { compose, toReact } from "./compose.js";
+export { instantiate } from "./instantiate.js";
+export { source } from "./source.js";
+export { state } from "./state.js";
+export { GraftLoading, isGraftError, View } from "./types.js";
+export type { GraftComponent, GraftError, MaybePromise, Cleanup } from "./types.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { component } from "./component.js";
+export { compose, toReact } from "./compose.js";
+export { instantiate } from "./instantiate.js";
+export { source } from "./source.js";
+export { state } from "./state.js";
+export { GraftLoading, isGraftError, View } from "./types.js";

package/dist/instantiate.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod/v4";
+import { type GraftComponent } from "./types.js";
+/**
+ * Create an isolated instance of a subgraph template.
+ *
+ * The template is a function that builds and returns a GraftComponent.
+ * Each call to subscribe() invokes the template fresh, so any state()
+ * or source() calls inside produce independent cells/subscriptions.
+ *
+ * This is the mechanism for local state. Without instantiate(), all
+ * usages of a component that contains state() would share the same
+ * global cells. With instantiate(), each usage gets its own.
+ *
+ * The template is lazy — it is not called until subscribe() is called.
+ *
+ * To get the schema, the template is called once eagerly (at instantiate
+ * time) to inspect the returned component's schema. This "probe" instance
+ * is not used for subscriptions — each subscribe() creates a fresh one.
+ *
+ * Example:
+ *   const TextInput = () => {
+ *     const [Value, setValue] = state({ schema: z.string(), initial: "" });
+ *     // ... wire into a View
+ *     return InputView;
+ *   };
+ *
+ *   const Name = instantiate(TextInput);   // isolated state
+ *   const Email = instantiate(TextInput);  // isolated state
+ */
+export declare function instantiate<S extends z.ZodObject<z.ZodRawShape>, O>(template: () => GraftComponent<S, O>): GraftComponent<S, O>;

package/dist/instantiate.js

@@ -0,0 +1,51 @@
+function isPromise(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        typeof value.then === "function");
+}
+/**
+ * Create an isolated instance of a subgraph template.
+ *
+ * The template is a function that builds and returns a GraftComponent.
+ * Each call to subscribe() invokes the template fresh, so any state()
+ * or source() calls inside produce independent cells/subscriptions.
+ *
+ * This is the mechanism for local state. Without instantiate(), all
+ * usages of a component that contains state() would share the same
+ * global cells. With instantiate(), each usage gets its own.
+ *
+ * The template is lazy — it is not called until subscribe() is called.
+ *
+ * To get the schema, the template is called once eagerly (at instantiate
+ * time) to inspect the returned component's schema. This "probe" instance
+ * is not used for subscriptions — each subscribe() creates a fresh one.
+ *
+ * Example:
+ *   const TextInput = () => {
+ *     const [Value, setValue] = state({ schema: z.string(), initial: "" });
+ *     // ... wire into a View
+ *     return InputView;
+ *   };
+ *
+ *   const Name = instantiate(TextInput);   // isolated state
+ *   const Email = instantiate(TextInput);  // isolated state
+ */
+export function instantiate(template) {
+    // Probe the template once to get schema and outputSchema.
+    const probe = template();
+    const run = (props) => {
+        const instance = template();
+        return instance.run(props);
+    };
+    const subscribe = (props, cb) => {
+        const instance = template();
+        return instance.subscribe(props, cb);
+    };
+    return {
+        _tag: "graft-component",
+        schema: probe.schema,
+        outputSchema: probe.outputSchema,
+        run,
+        subscribe,
+    };
+}

package/dist/source.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod/v4";
+import { type Cleanup, type GraftComponent } from "./types.js";
+/**
+ * Create a push-based data source with no inputs that emits values over time.
+ *
+ * This is the only way to introduce reactivity into a graft graph.
+ * The `run` function receives an `emit` callback; call it whenever
+ * you have a new value. Return a cleanup function to tear down
+ * subscriptions / intervals / etc.
+ *
+ * Before the first emit(), subscribers receive GraftLoading.
+ *
+ * Example:
+ *   const Clock = source({
+ *     output: z.number(),
+ *     run: (emit) => {
+ *       const id = setInterval(() => emit(Date.now()), 1000);
+ *       return () => clearInterval(id);
+ *     },
+ *   });
+ */
+export declare function source<O>({ output, run }: {
+    output: z.ZodType<O>;
+    run: (emit: (value: O) => void) => Cleanup;
+}): GraftComponent<z.ZodObject<{}>, O>;

package/dist/source.js

@@ -0,0 +1,50 @@
+import { z } from "zod/v4";
+import { GraftLoading } from "./types.js";
+/**
+ * Create a push-based data source with no inputs that emits values over time.
+ *
+ * This is the only way to introduce reactivity into a graft graph.
+ * The `run` function receives an `emit` callback; call it whenever
+ * you have a new value. Return a cleanup function to tear down
+ * subscriptions / intervals / etc.
+ *
+ * Before the first emit(), subscribers receive GraftLoading.
+ *
+ * Example:
+ *   const Clock = source({
+ *     output: z.number(),
+ *     run: (emit) => {
+ *       const id = setInterval(() => emit(Date.now()), 1000);
+ *       return () => clearInterval(id);
+ *     },
+ *   });
+ */
+export function source({ output, run }) {
+    const emptySchema = z.object({});
+    const subscribe = (_props, cb) => {
+        let emitted = false;
+        const cleanup = run((value) => {
+            emitted = true;
+            cb(value);
+        });
+        if (!emitted)
+            cb(GraftLoading);
+        return cleanup;
+    };
+    return {
+        _tag: "graft-component",
+        schema: emptySchema,
+        outputSchema: output,
+        // run() returns the first emitted value (useful for non-reactive contexts).
+        // For true reactivity, use subscribe().
+        run: (_props) => {
+            return new Promise((resolve) => {
+                const cleanup = run((value) => {
+                    cleanup();
+                    resolve(value);
+                });
+            });
+        },
+        subscribe,
+    };
+}

package/dist/state.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod/v4";
+import { type GraftComponent } from "./types.js";
+/**
+ * Create a global mutable state cell.
+ *
+ * Returns a tuple: [Component, setter].
+ * - Component is a source-like GraftComponent (no inputs) that emits
+ *   the current value whenever the setter is called.
+ * - setter is a plain function you can call from anywhere.
+ *
+ * Example:
+ *   const [CurrentUser, setCurrentUser] = state({
+ *     schema: z.string(),
+ *     initial: "anonymous",
+ *   });
+ *
+ *   setCurrentUser("alice"); // every subscriber re-runs
+ */
+export declare function state<O>({ schema, initial }: {
+    schema: z.ZodType<O>;
+    initial: O;
+}): [GraftComponent<z.ZodObject<{}>, O>, (value: O) => void];

package/dist/state.js

@@ -0,0 +1,44 @@
+import { z } from "zod/v4";
+/**
+ * Create a global mutable state cell.
+ *
+ * Returns a tuple: [Component, setter].
+ * - Component is a source-like GraftComponent (no inputs) that emits
+ *   the current value whenever the setter is called.
+ * - setter is a plain function you can call from anywhere.
+ *
+ * Example:
+ *   const [CurrentUser, setCurrentUser] = state({
+ *     schema: z.string(),
+ *     initial: "anonymous",
+ *   });
+ *
+ *   setCurrentUser("alice"); // every subscriber re-runs
+ */
+export function state({ schema, initial }) {
+    let current = initial;
+    const listeners = new Set();
+    const setter = (value) => {
+        current = value;
+        for (const cb of listeners) {
+            cb(current);
+        }
+    };
+    const emptySchema = z.object({});
+    const subscribe = (_props, cb) => {
+        listeners.add(cb);
+        // Immediately emit the current value so subscribers don't start empty.
+        cb(current);
+        return () => {
+            listeners.delete(cb);
+        };
+    };
+    const gc = {
+        _tag: "graft-component",
+        schema: emptySchema,
+        outputSchema: schema,
+        run: () => current,
+        subscribe,
+    };
+    return [gc, setter];
+}

package/dist/types.d.ts

@@ -0,0 +1,46 @@
+import { type ReactElement } from "react";
+import { z } from "zod/v4";
+/** A value that may or may not be a Promise. */
+export type MaybePromise<T> = T | Promise<T>;
+/** Cleanup function returned by subscribe. */
+export type Cleanup = () => void;
+/** Sentinel value indicating a value is not yet available. */
+export declare const GraftLoading: unique symbol;
+/** Sentinel tag for error values propagating through the graph. */
+declare const GraftErrorTag: unique symbol;
+/** An error value that propagates through the graph instead of throwing. */
+export type GraftError = {
+    readonly _tag: typeof GraftErrorTag;
+    readonly error: unknown;
+};
+/** Create a GraftError from a caught error. */
+export declare const graftError: (error: unknown) => GraftError;
+/** Check if a value is a GraftError. */
+export declare const isGraftError: (value: unknown) => value is GraftError;
+/** Check if a value is a sentinel (GraftLoading or GraftError) that should short-circuit. */
+export declare const isSentinel: (value: unknown) => value is typeof GraftLoading | GraftError;
+/**
+ * A graft component: a typed function from inputs (schema S) to output O.
+ *
+ * When O is ReactElement, this is a visual component.
+ * When O is something else (number, string, object...), this is a data source.
+ * compose() doesn't care — it just wires outputs into inputs.
+ * toReact() requires O to be ReactElement.
+ *
+ * The run function may return O or Promise<O>. When any component in a
+ * composed graph is async, the entire graph becomes async.
+ *
+ * subscribe() is the reactive primitive: it calls the callback whenever
+ * the output changes. For regular components this fires once. For graphs
+ * containing sources, it fires whenever a source emits.
+ */
+export interface GraftComponent<S extends z.ZodObject<z.ZodRawShape>, O> {
+    readonly _tag: "graft-component";
+    readonly schema: S;
+    readonly outputSchema: z.ZodType<O>;
+    readonly run: (props: z.infer<S>) => MaybePromise<O>;
+    readonly subscribe: (props: z.infer<S>, cb: (value: O | typeof GraftLoading | GraftError) => void) => Cleanup;
+}
+/** Output schema for components that return JSX. */
+export declare const View: z.ZodType<ReactElement>;
+export {};

package/dist/types.js

@@ -0,0 +1,13 @@
+import { z } from "zod/v4";
+/** Sentinel value indicating a value is not yet available. */
+export const GraftLoading = Symbol("GraftLoading");
+/** Sentinel tag for error values propagating through the graph. */
+const GraftErrorTag = Symbol("GraftError");
+/** Create a GraftError from a caught error. */
+export const graftError = (error) => ({ _tag: GraftErrorTag, error });
+/** Check if a value is a GraftError. */
+export const isGraftError = (value) => value !== null && typeof value === "object" && "_tag" in value && value._tag === GraftErrorTag;
+/** Check if a value is a sentinel (GraftLoading or GraftError) that should short-circuit. */
+export const isSentinel = (value) => value === GraftLoading || isGraftError(value);
+/** Output schema for components that return JSX. */
+export const View = z.custom(() => true);

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "graftjs",
+  "version": "0.1.0",
+  "description": "Compose React components by wiring named parameters — type-safe, no prop drilling, no hooks",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npx tsx --test tests/*.test.tsx",
+    "prepublishOnly": "tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uriva/graft.git"
+  },
+  "homepage": "https://github.com/uriva/graft",
+  "keywords": [
+    "react",
+    "compose",
+    "component",
+    "graph",
+    "wiring",
+    "zod",
+    "typed",
+    "reactive"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^14.0.0",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^5.1.4",
+    "global-jsdom": "^28.0.0",
+    "jsdom": "^28.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0",
+    "vite": "^7.3.1"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.25.76"
+  }
+}