Wallive Plugin React

React TSX authoring helpers for Wallive Island plugins. This package uses a small React custom reconciler to map an allowed component tree into Wallive presentation JSON; it supports normal function components, hooks, and rerenders, but it does not render DOM, CSS, or arbitrary native views.

import React from "react";
import { createWallivePlugin } from "@wallive/plugin-sdk";
import {
  Action,
  ActionPanel,
  ActivityPlacement,
  Flex,
  List,
  NotificationPlacement,
  VisualMetric,
  VisualProgress,
  VisualSurface,
  WindowPlacement,
  createDisplayRoot,
  renderDisplay,
} from "@wallive/plugin-react";

const plugin = createWallivePlugin();
const root = createDisplayRoot(plugin);

function Todos() {
  const [title, setTitle] = React.useState("Todos");
  React.useEffect(() => setTitle("Todos ready"), []);
  return <List id="todos" title={title}>
    <List.Item
      id="one"
      title="Ship plugin support"
      actionPanel={
        <ActionPanel>
          <Action id="open" title="Open" autoFocus />
        </ActionPanel>
      }
    />
  </List>;
}

root.render(<Todos />);

plugin.ready();
plugin.start();

createDisplayRoot and renderDisplay(element, plugin) publish Display v2 display.upsert items through plugin.display(...). For compatibility with older Wallive hosts, createRoot, render(element, plugin), and toPresentation(element) still publish or return legacy presentation.upsert payloads. renderDisplay reuses a default Display v2 root per plugin.

Supported root presentation components are Notification, VisualProgress, VisualTask, VisualStatus, List, Detail, Form, Confirm, Toast, HUD, Log, VisualMetric, Grid, VisualTimeline, VisualStatusMenu, and VisualSurface. VisualSurface plus nested Flex provides controlled composite layout; semantic children serialize as same-plugin child presentations plus surface.layoutTree slot references. ActionPanel, Action, CompactPresence, PresencePlacement, ActivityPlacement, BodyPlacement, OverlayPlacement, NotificationPlacement, and WindowPlacement are helper components that serialize into root presentations.

The Visual* names are the React authoring API. They still serialize to Display v2 content types such as progress, status, timeline, and surface; older generic authoring names like Progress, Status, Timeline, Surface, and StatusMenu are not exported aliases.

Use View children for host-owned drill-in navigation targets. View supports only kind="detail", kind="list", kind="grid", and kind="form" so pushView actions cannot generate unsupported plugin-window routes:

renderDisplay(
  <List id="issues" title="Issues">
    <WindowPlacement windowID="main" title="Issues" size="wide" primary />
    <List.Item id="one" title="Fix release notes" />
    <View id="issue-detail" kind="detail" title="Issue detail" markdown="Ready to ship" />
    <ActionPanel>
      <Action id="inspect" title="Inspect" intent={{ kind: "pushView", viewID: "issue-detail" }} />
    </ActionPanel>
  </List>,
  plugin,
);

renderDisplay(
  <VisualSurface id="ops" title="Ops">
    <WindowPlacement windowID="main" title="Ops" size="wide" primary />
    <Flex direction="row" gap="sm" align="stretch">
      <VisualMetric id="health" title="Health" value="99.96%" grow={1} />
      <VisualProgress id="rollout" title="Rollout" progress={0.42} basis="wide" />
    </Flex>
  </VisualSurface>,
  plugin,
);

WindowPlacement must target the primary/default window contribution declared in the plugin manifest, for example windowContribution("main", { primary: true }). Current Wallive hosts reject arbitrary secondary window ids instead of creating implicit plugin windows.

Placement helpers are declaration-only and do not become layout nodes:

renderDisplay(
  <VisualProgress id="rollout" title="Rollout" progress={0.42}>
    <ActivityPlacement groupID="release" preferredSizeClass="foreground" />
    <NotificationPlacement threadID="release" ttlSeconds={30} />
  </VisualProgress>,
  plugin,
);

The React package publishes through @wallive/plugin-sdk, so invalid Content/Placement Matrix combinations fail during render. For example, List with ActivityPlacement throws locally because list content belongs in bounded body or plugin windows, not the Activity rail.