@octanejs/opentui 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+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/LICENSE.upstream

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 opentui
+
+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,120 @@
+# `@octanejs/opentui`
+
+An experimental Octane renderer for [OpenTUI](https://github.com/anomalyco/opentui),
+tracking the public binding surface of `@opentui/react@0.5.8` without embedding
+React Reconciler. Octane owns component execution, hooks, context, scheduling,
+errors, refs, and effects; `@opentui/core` continues to own terminal layout,
+input, rendering, and native resources.
+
+## Runtime requirements
+
+OpenTUI 0.5.8 requires either Bun 1.3 or newer, or Node.js 26.4 or newer with
+`--experimental-ffi`. This package does not add a JavaScript fallback for
+OpenTUI's native Zig renderer.
+
+```sh
+pnpm add @octanejs/opentui @opentui/core
+```
+
+## Compiler configuration
+
+OpenTUI components live in `*.opentui.tsrx` modules. Add the serializable
+renderer preset to the Octane Vite, Rsbuild, or Rspack compiler configuration:
+
+```ts
+import { defineConfig } from '@octanejs/vite-plugin';
+import { opentuiRenderers } from '@octanejs/opentui/config';
+
+export default defineConfig({
+	compiler: {
+		renderers: opentuiRenderers,
+	},
+});
+```
+
+The preset uses OpenTUI host text, supports retained visibility and same-renderer
+portals, and rejects server compilation. Terminal trees have no HTML SSR or
+hydration path.
+
+## Rendering an application
+
+```tsx
+// App.opentui.tsrx
+import { useKeyboard, useTerminalDimensions } from '@octanejs/opentui';
+import { useState } from 'octane';
+
+export function App() @{
+	const [count, setCount] = useState(0);
+	const size = useTerminalDimensions();
+
+	useKeyboard((event) => {
+		if (event.name === 'return') setCount((value) => value + 1);
+	});
+
+	<box style={{ flexDirection: 'column', padding: 1 }}>
+		<text>{'Count: ' + count}</text>
+		<text>{'Terminal: ' + size.width + 'x' + size.height}</text>
+	</box>
+}
+```
+
+```ts
+import { createCliRenderer } from '@opentui/core';
+import { createRoot } from '@octanejs/opentui';
+import { App } from './App.opentui.tsrx';
+
+const renderer = await createCliRenderer();
+const root = createRoot(renderer);
+root.render(App);
+```
+
+`createRoot(renderer).render(Component, props)` follows Octane's programmatic
+root convention. Destroying the `CliRenderer` unmounts the Octane root, and
+`root.unmount()` releases component state, effects, listeners, refs, portals,
+and owned renderables without destroying the caller-owned renderer.
+
+## Surface
+
+The built-in intrinsic catalogue matches OpenTUI React 0.5.8: `box`, `text`,
+`code`, `diff`, `markdown`, `input`, `select`, `textarea`, `scrollbox`,
+`ascii-font`, `tab-select`, `line-number`, `image`, `time-to-first-draw`, and
+the text modifiers `span`, `br`, `b`, `strong`, `i`, `em`, `u`, and `a`.
+Register application renderables with `extend()` and augment
+`OpenTUIComponents` for their intrinsic types.
+
+The binding exports `useRenderer`, `useKeyboard`, `usePaste`, `useFocus`,
+`useBlur`, `useSelectionHandler`, `useOnResize`, `useTerminalDimensions`, and
+`useTimeline`. OpenTUI callback names and argument lists are preserved: for
+example, select `onChange(index, option)` remains a two-argument OpenTUI event,
+not a DOM synthetic event.
+
+`createPortal(children, target)` accepts a borrowed `RootRenderable` created
+from the same `CliRenderer` context. Portal teardown removes only Octane-owned
+children; the target remains caller-owned.
+
+The OpenTUI slot system is available as `createOctaneSlotRegistry`, `Slot`, and
+`createSlot`; `createReactSlotRegistry` and the upstream `React*` type names are
+retained as migration aliases. Plugins return Octane universal renderables
+instead of React nodes, and plugin failures are reported to the core registry
+with source `"octane"`.
+
+For native integration tests, `@octanejs/opentui/test-utils` exports
+`testRender(Component, props, options)`. The package's focused test command runs
+Vitest with Bun so the OpenTUI FFI-backed test renderer is available.
+
+## Differences from `@opentui/react`
+
+- Components are authored in `.opentui.tsrx`; the package does not export
+  React's `createElement` or accept React elements.
+- Programmatic roots render an Octane component plus props rather than a React
+  node.
+- Refs are ordinary Octane props and can be composed with `ref={[a, b]}`; there
+  is no `forwardRef` layer.
+- Octane's compiler-assigned hook slots permit hooks behind conditions and
+  after early returns. The exported hooks forward manual slots internally.
+- React DevTools integration and OpenTUI's React runtime-plugin bundling
+  subpaths are not included. Compiler setup uses `opentuiRenderers` instead.
+- OpenTUI terminal rendering is client-only; SSR and hydration are unsupported.
+
+The compatibility baseline and verified scope are recorded in
+[`status.json`](./status.json).

package/UPSTREAM.md

@@ -0,0 +1,63 @@
+# OpenTUI React upstream contract
+
+## Pin and source boundary
+
+| Field | Value |
+|---|---|
+| Package | `@opentui/react` |
+| Version | `0.5.8` |
+| Canonical commit | `21b002174255ca2236ed3115e2bb2294642f2cf5` |
+| Supported upstream range | exactly `0.5.8` |
+| npm integrity | `sha512-l3N/Kbg5V+OABp60A5iCfEj3WK5pKVUDmUrVPf/xgct9R7Xy2Jbw/0MoSFpgr3odq3CuWprYajnoLCR9f81BRQ==` |
+| License | MIT |
+
+The complete `packages/react` subtree from the canonical commit is committed
+byte-for-byte under `upstream/`. Every file verifies offline against its Git
+blob hash in `audit/upstream.lock.json`. The repository-root license is retained
+byte-for-byte as `LICENSE.upstream`; the Octane-authored binding remains under
+the repository MIT license in `LICENSE`.
+
+The authored port lives in `src/`. It reuses `@opentui/core@0.5.8` unchanged and
+independently reimplements the React renderer, reconciliation, DevTools
+transport boundary, and WebSocket dependency through Octane's universal host
+driver and existing runtime instrumentation. No `react`, `react-reconciler`,
+`react-devtools-core`, or `ws` source is copied into the binding.
+
+## Export crosswalk
+
+| Upstream export group | Octane disposition | Evidence |
+|---|---|---|
+| `createRoot`, `Root`, `flushSync`, `createPortal` | Ported to Octane's universal renderer; roots take a component and props separately and portals target a same-renderer `RootRenderable` | `src/root.ts`, `src/scheduling.ts`, native integration tests |
+| `baseComponents`, `componentCatalogue`, `extend`, `getComponentCatalogue` | Ported with the complete OpenTUI 0.5.8 built-in catalogue and custom renderable extension | `src/components.ts`, config tests |
+| `AppContext`, `useAppContext` | Ported to Octane universal context | `src/context.ts`, native integration tests |
+| `useRenderer`, keyboard, paste, focus, blur, selection, resize, dimensions, and timeline hooks | Ported to Octane hooks with compiler-owned slots and native OpenTUI subscriptions | `src/hooks.ts`, native integration tests |
+| `createReactSlotRegistry`, `Slot`, `createSlot`, and `React*` slot types | Ported over OpenTUI core's slot registry; React-named APIs remain migration aliases for canonical `Octane*` APIs | `src/slot.ts`, native slot tests |
+| `TimeToFirstDraw`, `TimeToFirstDrawProps` | Ported as a universal renderer component | `src/time-to-first-draw.ts`, public source typecheck |
+| component prop types, `RenderableConstructor`, extension types, and `OpenTUIComponents` | Ported with `OctaneNode`, ordinary ref props, and renderer-specific intrinsic types | `src/types.ts`, published-source checks |
+| `testRender` | Adapted to accept an Octane component plus props and execute against `@opentui/core/testing` | `src/test-utils.ts`, native integration tests |
+| `./renderer` | Ported as the renderer/runtime surface plus the OpenTUI host driver | `src/renderer.ts` |
+| `./jsx-runtime`, `./jsx-dev-runtime` | Replaced by the compiler-facing `./intrinsics` and `./intrinsics/jsx-runtime` entries | `src/intrinsics.ts`, config tests |
+| `createElement` | Intentional divergence: Octane component trees are authored in `.opentui.tsrx`; nested runtime element construction is not supported | `README.md`, `docs/differences-from-react.md` |
+| React runtime-plugin support entries | Inapplicable: applications configure the Octane compiler with `opentuiRenderers`; no runtime JSX rewrite is needed | `src/config.ts`, config tests |
+| React Reconciler and React DevTools internals | Reimplemented by Octane's universal host driver and runtime instrumentation; these are not binding public exports | `src/driver.ts`, native lifecycle and identity tests |
+
+## Upstream test-suite disposition
+
+The pinned upstream suite contains 56 runtime registrations across seven test
+files. It remains fully visible under `upstream/tests`; fixtures beside those
+suites are preserved but are not registrations.
+
+| Upstream area | Disposition |
+|---|---|
+| root teardown and renderer-destroy races | Covered by the native coordinated-cleanup test |
+| image loading, rerender retention, prop reset, cancellation, and abandoned renders | Public image props and host lifecycle are ported; focused image parity remains an explicit follow-up rather than a claimed passing lane |
+| text, layout, prop reset, keyed reconciliation, focus, and intrinsic catalogue behavior | Covered at the binding boundary by native frame, state/prop update, identity, callback, and config tests; the core layout engine itself is reused unchanged |
+| link behavior | Intrinsic and prop surface ported; terminal escape rendering remains owned by unchanged `@opentui/core` |
+| runtime-plugin configuration | Inapplicable because Octane compiles `.opentui.tsrx` ahead of time and exports a serializable renderer preset |
+| slot modes, ordering, failures, context, identity, and teardown | Representative append/fallback, registration, error, identity, and teardown behavior covered by native slot tests |
+| timeline identity | Hook implementation preserves one `Timeline` per component instance; direct adapted case remains an explicit follow-up |
+
+The parity manifest is deliberately `recorded-unverified`: the pin and current
+Octane-specific behavioral lanes are machine-checked, but this change does not
+claim that all 56 React-owned upstream registrations have been adapted one for
+one.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@octanejs/opentui",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "OpenTUI bindings for Octane — terminal components, hooks, and a universal renderer over @opentui/core.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/opentui"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "LICENSE",
+    "LICENSE.upstream",
+    "README.md",
+    "UPSTREAM.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./config": "./src/config.ts",
+    "./renderer": "./src/renderer.ts",
+    "./intrinsics": "./src/intrinsics.ts",
+    "./intrinsics/jsx-runtime": "./src/intrinsics.ts",
+    "./test-utils": "./src/test-utils.ts"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.5.8 <0.6.0",
+    "octane": "0.1.46"
+  },
+  "devDependencies": {
+    "@opentui/core": "0.5.8",
+    "vitest": "^4.1.10",
+    "octane": "0.1.46"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.. --project opentui && pnpm test:native",
+    "test:native": "NODE_OPTIONS= REACT_PORT_TEST_REPORT_DIR= bun ../../node_modules/vitest/vitest.mjs run --config vitest.native.config.ts",
+    "typecheck": "tsrx-tsc --noEmit"
+  }
+}

package/src/components.ts

@@ -0,0 +1,63 @@
+import {
+	ASCIIFontRenderable,
+	BoxRenderable,
+	CodeRenderable,
+	DiffRenderable,
+	ImageRenderable,
+	InputRenderable,
+	LineNumberRenderable,
+	MarkdownRenderable,
+	ScrollBoxRenderable,
+	SelectRenderable,
+	TabSelectRenderable,
+	TextareaRenderable,
+	TextRenderable,
+	TimeToFirstDrawRenderable,
+} from '@opentui/core';
+import type { RenderableConstructor } from './types.js';
+import {
+	BoldSpanRenderable,
+	ItalicSpanRenderable,
+	LineBreakRenderable,
+	LinkRenderable,
+	SpanRenderable,
+	UnderlineSpanRenderable,
+} from './text.js';
+
+export const baseComponents = {
+	box: BoxRenderable,
+	text: TextRenderable,
+	code: CodeRenderable,
+	diff: DiffRenderable,
+	markdown: MarkdownRenderable,
+	input: InputRenderable,
+	select: SelectRenderable,
+	textarea: TextareaRenderable,
+	scrollbox: ScrollBoxRenderable,
+	'ascii-font': ASCIIFontRenderable,
+	'tab-select': TabSelectRenderable,
+	'line-number': LineNumberRenderable,
+	image: ImageRenderable,
+	'time-to-first-draw': TimeToFirstDrawRenderable,
+	span: SpanRenderable,
+	br: LineBreakRenderable,
+	b: BoldSpanRenderable,
+	strong: BoldSpanRenderable,
+	i: ItalicSpanRenderable,
+	em: ItalicSpanRenderable,
+	u: UnderlineSpanRenderable,
+	a: LinkRenderable,
+} as const;
+
+export type ComponentCatalogue = Record<string, RenderableConstructor>;
+
+export const componentCatalogue: ComponentCatalogue = { ...baseComponents };
+
+/** Add application-specific OpenTUI renderables to the intrinsic catalogue. */
+export function extend<T extends ComponentCatalogue>(objects: T): void {
+	Object.assign(componentCatalogue, objects);
+}
+
+export function getComponentCatalogue(): ComponentCatalogue {
+	return componentCatalogue;
+}

package/src/config.ts

@@ -0,0 +1,32 @@
+/** Serializable compiler metadata for OpenTUI-rendered TSRX modules. */
+export const OPENTUI_RENDERER_ID = 'opentui';
+
+export const opentuiRenderer = {
+	module: '@octanejs/opentui/renderer',
+	target: 'universal',
+	server: 'unsupported',
+	intrinsics: '@octanejs/opentui/intrinsics',
+	text: 'host',
+	capabilities: ['portal', 'visibility'],
+} as const;
+
+export const opentuiRendererRegistry = {
+	[OPENTUI_RENDERER_ID]: opentuiRenderer,
+} as const;
+
+export const opentuiRendererRules = [
+	{
+		include: '**/*.opentui.tsrx',
+		renderer: OPENTUI_RENDERER_ID,
+	},
+] as const;
+
+export const opentuiRenderers = {
+	registry: opentuiRendererRegistry,
+	rules: opentuiRendererRules,
+} as const;
+
+/** Short compatibility name for application config files. */
+export const renderers = opentuiRenderers;
+
+export default opentuiRenderers;

package/src/context.ts

@@ -0,0 +1,16 @@
+import type { CliRenderer, KeyHandler } from '@opentui/core';
+import { createContext, useContext } from 'octane/universal';
+
+export interface AppContextValue {
+	keyHandler: KeyHandler | null;
+	renderer: CliRenderer | null;
+}
+
+export const AppContext = createContext<AppContextValue>({
+	keyHandler: null,
+	renderer: null,
+});
+
+export function useAppContext(): AppContextValue {
+	return useContext(AppContext);
+}