@wl-wo/compositor-roots

Small React primitives for writing a Wo compositor. The package supplies no visual theme. It mounts author-defined shell and window methods, injects refs and Wo window actions, and positions windows from Wo geometry. Window dragging uses the Wo window-management capability.

Consumers need React 18 or newer and @wl-wo/wo-types. The package uses standard TypeScript decorators, so parameter injection is declared on the method with @Inject(...) instead of parameter decorators. Ref arguments are React callback refs and can be attached directly to JSX elements.

import { Actions, createCompositor, Inject, Layer, Layers, Mount, Mounting, OnClick, OrganizeWindows, Root, WoCompositor } from "@wl-wo/compositor-roots";

@OrganizeWindows({ type: "floating", desktops: true })
export default class App extends WoCompositor {
  @Layer(Layers.Shell)
  @Inject("shell-ref")
  wallpaper(ref: React.RefCallback<HTMLImageElement>) {
    return <img ref={ref} src="/wallpaper.jpg" />;
  }

  @Layer(Layers.Window)
  @OnClick(Actions.RaiseToTop)
  @Inject("window-content-ref", "window-props", "window-actions", "drag-ref")
  window(ref: React.RefCallback<HTMLDivElement>, win: import("@wl-wo/wo-types").WoWindow, actions: import("@wl-wo/compositor-roots").WindowActions, drag: React.RefCallback<HTMLHeadingElement>) {
    return <section><header ref={drag} onDoubleClick={actions.max}>{win.title}</header><div ref={ref} /></section>;
  }

  @Mount(Mounting.Desktop)
  @Root()
  @Inject("shell-ref", "view-children", "mount-context")
  viewRoot(ref: React.RefCallback<HTMLElement>, children: React.ReactNode, context: import("@wl-wo/compositor-roots").DesktopMountContext) {
    return <main ref={ref} data-monitor={context.monitor.id}>{children}</main>;
  }
}

Mount it with createCompositor(App) inside the application's React root. Shell methods marked with @Layer receive a positioned wrapper. Window methods marked with @Layer(Layers.Window) render once per Wo window, inside a wrapper using its reported position and size. The injected content ref points at the author-rendered content host. Wo currently reports window metadata and control actions through this API, and does not expose native window pixels as React children.

@Mount(Mounting.Main) renders once in the application tree. @Mount(Mounting.Monitor) renders once per selected monitor in that tree. @Mount(Mounting.Desktop) mounts one Wo overlay surface for each selected physical output and requested desktop target. @Inject("mount-context") provides the monitor and desktop target to the component. Set monitors and workspaces in @OrganizeWindows to select targets. Wo physically positions each surface on its output and receives the desktop target in the mount call. Wo does not yet provide a virtual desktop manager, so a separate desktop ID cannot activate or validate an independent workspace by itself.

@WrapperStyles adds only author-specified wrapper styles. @Background and @Foreground annotate shell roles for inspection and future host integration. No default colors, typography, controls, or layout are supplied. Window frames drag from the outer wrapper unless a @WindowDragRef() handle is provided.

Wo's current window metadata has no workspace or desktop identifier. workspaces and desktops are preserved as organization metadata, but cannot filter windows until Wo exposes those identifiers.