@decky.fx/raven-tsx 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,12 @@
+raven-tsx
+Copyright 2026 Decky Fx
+
+This package contains the Bun binding of Raven (src/vendor/raven.ts), written by
+tools/bindgen in Raven, unchanged. Its native packages contain Raven's library.
+
+Raven: https://github.com/oscar-soirey/Raven
+Raven
+Copyright 2026 Oscar Soirey
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+It includes third-party components under their own licenses; see THIRD_PARTY.md.

package/RAVEN_VERSION

@@ -0,0 +1 @@
+899a268cb0bf11c771c18076d9375243dee47e43

package/README.md

@@ -1,3 +1,395 @@
-# Temporary Holding Version
+# raven-tsx
 
-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.
+Native desktop interfaces in TSX, for [Bun](https://bun.com), on the real widgets of [Raven](https://github.com/oscar-soirey/Raven). A core knows only Raven, and an adapter for a framework is built on it; React is the one there is today. No XML and no build step, as Bun compiles TSX itself.
+
+```tsx
+import { useState } from "react";
+import { Button, Label, runApp, VBox } from "@decky.fx/raven-tsx/react";
+
+function App() {
+	const [count, setCount] = useState(0);
+	return (
+		<VBox Spacing={12} Slot={{ Padding: 24 }}>
+			<Label>Clicked {count} times</Label>
+			<Button Style="Primary" OnClicked={() => setCount(count + 1)}>Click me</Button>
+		</VBox>
+	);
+}
+
+await runApp(<App />, { Title: "Hello", Width: 480, Height: 240 });
+```
+
+![The studio example: a node graph and a timeline, in the Blueprint look](../../docs/screenshots/studio.png)
+
+Every C example of Raven has a TSX port in [examples](../../examples), with screenshots in the [README of the repository](../../README.md).
+
+## Install
+
+    bun add @decky.fx/raven-tsx react react-reconciler
+
+`react` and `react-reconciler` are optional peer dependencies: `@decky.fx/raven-tsx/react` needs both, and an application that uses only the core installs neither.
+
+| Import | What it is |
+|---|---|
+| `@decky.fx/raven-tsx/react` | The components, `runApp`, the hooks and `registerTag`, for React, and everything of the core |
+| `@decky.fx/raven-tsx` | The core, for code that is not a component: `defineTheme`, `loadTheme`, `raven`, and `onAction`, `onShortcut`, `onFrame`, which each return what stops them |
+
+```json
+{ "compilerOptions": { "jsx": "react-jsx", "types": ["bun", "react"] } }
+```
+
+The package is TypeScript, so your compiler checks it with your settings (`skipLibCheck` skips only `.d.ts` files). It compiles with `strict`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes` (optional props take `undefined`, as React's do), `noPropertyAccessFromIndexSignature`, `noUnusedLocals`, `noUnusedParameters`, `noImplicitOverride`, `noImplicitReturns`, `noFallthroughCasesInSwitch`, `isolatedModules` and `verbatimModuleSyntax`. Not yet with `erasableSyntaxOnly`: Raven's own binding has `enum`s.
+
+Raven's native library comes with it: there is a package per platform, and the package manager installs the one that fits. No install script runs, and nothing is compiled on your machine.
+
+| Platform | Package |
+|---|---|
+| Linux x64, arm64 | `@decky.fx/raven-tsx-linux-x64`, `-linux-arm64` |
+| macOS Apple Silicon, Intel | `@decky.fx/raven-tsx-darwin-arm64`, `-darwin-x64` |
+| Windows x64 | `@decky.fx/raven-tsx-win32-x64` |
+
+What the system must have: a Vulkan driver, and on Linux libX11. On macOS, version 14 or newer, Vulkan comes from MoltenVK: `brew install molten-vk`.
+
+`RAVEN_LIBRARY` set to the path of a library has priority, to try a build of your own.
+
+## One executable
+
+`bun build --compile` holds Bun, your code and the native library in one file:
+
+    bun build --compile src/index.tsx --outfile app
+
+For another platform, install its package first:
+
+    bun install --os=win32 --cpu=x64
+    bun build --compile --target=bun-windows-x64 src/index.tsx --outfile app.exe
+
+## How props work
+
+The components, with their props, are generated from Raven's own schema.
+
+| XML | TSX |
+|---|---|
+| `Text="Hi"` | `Text="Hi"`, or `<Label>Hi</Label>` |
+| `Width="120"` | `Width={120}` |
+| `Slot.Padding="24"` | `Slot={{ Padding: 24 }}`, since JSX has no dots in names |
+| `Items="a\|b"` | `Items={["a", "b"]}` |
+| `OnClicked="name"` | `OnClicked={() => ...}` |
+
+## Events
+
+Events with a value give it to the function, at each change. A `TextInput` gives its text in `OnChanged` and again in `OnCommitted` on Enter.
+
+| Component | Event | Value |
+|---|---|---|
+| `TextInput` | `OnChanged`, `OnCommitted` | `string` |
+| `Checkbox`, `Expander` | `OnChanged` | `boolean` |
+| `Slider`, `SpinBox` | `OnChanged` | `number` |
+| `ComboBox`, `TabView` | `OnChanged` | index |
+| `ListView`, `TileView` | `OnChanged`, `OnActivated` | index |
+| `TreeView` | `OnChanged`, `OnActivated` | handle of the item |
+| `Table` | `OnChanged`, `OnActivated` | row |
+| `Table` | `OnSort` | column, and whether it is descending |
+| `DatePicker` | `OnChanged` | `"YYYY-MM-DD"` |
+| `TimePicker` | `OnChanged` | `"HH:MM:SS"` |
+| `Rating` | `OnChanged` | `number` |
+| `Pagination` | `OnChanged` | page, from 0 |
+| `Breadcrumb` | `OnClicked` | index |
+| `TextEditor` | `OnChanged`, `OnCompletion` | its text, the start of the word |
+| `TextEditor` | `OnZoom` | `number` |
+| `ColorPicker` | `OnChanged` | `"#RRGGBB"`, or `"#RRGGBBAA"` when it is not opaque |
+| `Label` | `OnLink` | the address of the link |
+| `MenuItem` | `OnClicked` | whether it is checked now |
+| `Island` | `OnChanged` | `boolean` |
+| `Viewport`, `<Window>` | `OnResize` | width, height |
+| `FileBrowser` | `OnChanged`, `OnAccepted` | path |
+| `DockArea` | `OnChanged` | its layout, for `Layout` or `Rdock_area_load_layout` |
+| `TreeView`, `TileView`, `NodeGraph`, `BlockEditor` | `OnContext` | what was right clicked, x, y |
+| `Timeline` | `OnTime` | seconds |
+| `Timeline` | `OnItemChanged`, `OnSelection`, `OnActivated`, `OnRemoved` | item |
+| `NodeGraph` | `OnLinked`, `OnUnlinked`, `OnMoved`, `OnSelection`, `OnRemoved`, `OnActivated` | link or node |
+| `BlockEditor` | `OnChanged`, `OnClicked` | block |
+| any widget, `<Window>` | `OnDrop` | an `RDropEvent` |
+| any widget | `OnEvent` | an `REvent`, before the widget sees it: the pointer over a `Custom`, for one |
+
+Some events ask: `OnClose` of a `TabView` (index, page) and of a `DockArea` (panel), `OnConnect` of a `NodeGraph` (two pins), and `OnEvent` and `OnDrop`, where true means taken. Return true to let the thing happen. A tab or a panel that stays can then go by taking its element out, which is the way to do it: when Raven closes a panel by itself, it deletes a widget React still has, which does no harm but leaves the element with a `.widget` that is no longer valid. `Documents` on a `TabView` gives its tabs a close button.
+
+Other events give nothing, and share the one action a widget has in Raven: give a widget one of them. `Timeline` and `NodeGraph` have an `OnChanged` of this kind, once per gesture.
+
+Inputs are controlled, as in React DOM. With `Text={value}`, what the state says stays on screen if a handler refuses a change. An update made in an event is committed before the next event, as a click in React DOM. `ListView` and `ComboBox` keep their `Selected` when their `Items` change. A `|` in an item would split it, as `Items` is written that way in XML: for such items use `ItemText`. `FileBrowser`'s `Directory` and `Timeline`'s `Playing` are not held this way: the user changes them with no event that says so.
+
+## Windows
+
+`<Window>` is an element like any other, anywhere in the tree: it opens with its element and closes with it. Without options, `runApp` lets the tree say what windows there are, and ends when the last one closes.
+
+```tsx
+function App() {
+	const [help, setHelp] = useState(false);
+	return (
+		<>
+			<Window Title="Main" Width={640} Height={480}>
+				<Button OnClicked={() => setHelp(true)}>Help</Button>
+			</Window>
+			{help && <Window Title="Help" OnClose={() => setHelp(false)}><Label>...</Label></Window>}
+		</>
+	);
+}
+
+await runApp(<App />);
+```
+
+A tree that never opens a window never ends: Raven runs until a window has existed, so that one can open later. An application that renders nothing at all waits for ever, and wakes about 60 times a second.
+
+A splash screen is a window like the others, with `IsSplashScreen`: no frame, centered, above the other windows and out of the taskbar. Render the main window beside it and take the splash out when the main window is ready.
+
+```tsx
+{loading && <Window IsSplashScreen Width={480} Height={280}><Label>Starting...</Label></Window>}
+<Window Title="Main" Width={1024} Height={720}>...</Window>
+```
+
+With `OnClose`, closing is a request: the window stays until the element is taken out. Without it, the user can close the window at any time. `Title`, `Theme`, `Width`, `Height`, `Backdrop`, `Opacity` and `ContinuousRedraw` can change on an open window. Other attributes only count when it is made.
+
+What a `<Window>` holds directly fills it and follows its `Slot`, as the content of a window in C. Several such children lie on top of each other: put them in a `<VBox>` to stack them.
+
+On macOS a `MenuBar` goes to the menu bar of the system; `Native={false}` keeps it in the window. An `<Island>` directly in a `<Window>` floats above the content at the top, as in XML. A `<Menu>` that no `MenuBar` or `Menu` holds is not shown until it is asked: its ref has `open(x, y)`, in the coordinates `OnContext` gives. A `<Separator>` in a `<Menu>` is a line of the menu.
+
+## Themes
+
+A theme is a typed object, not a theme file: `defineTheme` checks it, and `loadTheme` gives it to Raven, which keeps it under its name. The colors and metrics take the names of Raven's schema, so a typo does not compile.
+
+```tsx
+import { defineTheme, loadTheme, raven } from "@decky.fx/raven-tsx/react";
+
+export const ocean = defineTheme({
+	Name: "Ocean",
+	Base: "Dark",
+	Accent: "#22D3EE",
+	Colors: { Window: "#0B1220", Panel: "#111A2C", Text: "#DCE7F5" },
+	Metrics: { ControlHeight: 32, Spacing: 8 },
+	Syntax: { Keyword: "#7DD3FC", String: "#86EFAC" },
+	Styles: [
+		{ Widget: "Button", CornerRadius: 16 },
+		{ Class: "danger", Accent: "#FB7185" },
+		{ Widget: "Slider", Part: "Knob", State: "Hovered", Size: 16 },
+	],
+});
+
+await runApp(<App />, options, { setup: () => raven.Rtheme_use(loadTheme(ocean)) });
+```
+
+`Theme={ocean.Name}` gives it to a part of the window only. Everything a theme file has is there: `Look` or `Base`, `Motion`, `Material`, `Font`, `Wallpaper`, `Colors`, `Metrics`, `Glass`, `Syntax`, and `Styles` for a type, a class, a part and its states. A mistake Raven finds (a `Base` that names no theme) is reported by Raven, and the rest is used, as in a file. `themeXml(theme)` gives the text of the theme file, to save one.
+
+## Tags of your own
+
+A component can be a tag Raven knows, built by Raven from XML as `<Button>` is: in a document made by code, in `Markup`, in a file of someone else. There is no XML declaration of it: the component is the only one.
+
+```tsx
+await runApp(<App />, options, {
+	// (once Raven started: Raven refuses a tag before)
+	setup: () => {
+		registerTag("Card", Card, {
+			attributes: { Title: "string", Wide: "boolean", Count: "number" },
+			slots: ["footer"],
+		});
+		registerTag("Stat", Stat, { attributes: { Label: "string", Value: "string" } });
+	},
+});
+```
+
+```xml
+<Card Title="Sales" Wide="true">
+	<Stat Label="This week" Value="1 284"/>
+	<Into Name="footer"><Button Text="Details"/></Into>
+</Card>
+```
+
+`attributes` lists the attributes it takes, with the kind of their prop, checked against the component's props; the others stay with the widget (`Name`, `Width`, `Slot`...), and a value of the wrong kind is reported by Raven. The widgets of the children go where the component renders `children`, and those of `<Into Name="...">` where it renders the prop of that name, one of `slots`, with no box around them. Those it does not render are not shown, and stay alive until the element is destroyed. `Rwidget_set_attribute` renders it again, and destroying the widget unmounts it. Each element is a root of its own, so context does not reach it from around it. `registerTag` returns what unregisters the tag.
+
+## Going beyond props
+
+`useShortcut(window, "Ctrl+S", save)` adds a shortcut to a window, given the ref of its `<Window>`. `useAction("scene.play", play)` names a function, for whatever fires actions by name; it receives the widget that fired it. An `On...` prop also takes such a name, or a built-in action: `OnClicked="app.quit"`.
+
+`useFrame((seconds) => ...)` runs a function once per frame, before the layout, in any number of components. It also runs when nothing is happening, about 60 times a second: `runApp` wakes that often so that Bun's timers run beside Raven. `raven.Rset_frame_callback` goes in the same slot as one more function, so neither takes the place of the other, and the last one it was given is the only one kept alive.
+
+`runApp(<App />, options, { appName, setup, allocator })`: `setup` runs after Raven starts and before the first render, for a look or a theme. `allocator` is what `Rset_allocator` takes, functions of C only.
+
+`Theme` takes the name of a theme loaded with `loadTheme` (or `Rtheme_load`), and `Language` a language that was registered, beside those the types propose. A color or a metric goes back to the theme with `null`, without making the widget again: `Color={{ Text: null }}`. `FontStyle` on a `Label` takes a style of the font of the theme, and does not go with `Font`.
+
+A function given directly to the C API runs outside what props get. `inEventScope(fn)` makes it the same: an exception stays on this side, and what it changes in React is committed before the next event.
+
+`createPortal(children, widget)`, as in ReactDOM, renders into a widget given to Raven by hand, the content of a graph node for one, and context goes on through it. `tag<Props>("Name")` makes a component for a tag given to `Rxml_register_tag`.
+
+Children added with `Rwidget_add_child` to a parent React also fills stay in their place, through inserts and when the parent is made again. They are yours to delete.
+
+Web pages need `registerWebView` once, as the `setup` of `runApp`, which runs before the first render. They are apart from the binding, as a library can be built without them, and `webFunctions()` gives the functions of `raven_web.h`.
+
+A `WebView` drives a browser of the Chromium family installed on the machine (Chrome, Chromium, Edge...), hidden, and shows its picture: there is none in the package. So show something else when there is no browser (`Rweb_is_available()` is 0), and when the library has no web pages: built with `-DRAVEN_BUILD_WEB=OFF`, `registerWebView` and `webFunctions()` throw a `RavenError`.
+
+```tsx
+/** Whether web pages can be shown, known once `setup` ran. */
+let pages = false;
+
+function App(): ReactNode {
+	return pages ? <WebView Url="https://example.com" Slot={{ Fill: 1 }} /> : <Label>No browser to show the page in</Label>;
+}
+
+await runApp(<App />, { Width: 800, Height: 600 }, {
+	setup: () => {
+		try {
+			registerWebView();
+			pages = webFunctions().Rweb_is_available() !== 0;
+		} catch {
+			// (a library without web pages)
+		}
+	},
+});
+```
+
+The data of a few widgets is given as props. Rows of a `TreeView` have new handles each time `Items` changes. `Markup` holds the elements XML takes inside a widget, and a change to it makes the widget again:
+
+```tsx
+<TreeView Items={[{ Text: "World", Expanded: true, Children: [{ Text: "Sky" }] }]} />
+<Timeline Markup={`<Track Name="Camera"><Clip Start="0" Length="3"/></Track>`} />
+<Image Texture={raven.Rtexture_create_from_pixels(pixels, width, height)} />
+```
+
+A `Plot` takes its curves in `Series` and the lines the user drags in `DragLines`. The numbers are lists or `Float64Array`s, handed to Raven as they are: a new render sends only what changed, and a new array is what says that values changed. Streaming a million points with `Rplot_add_point` works too: leave `Y` out of that series.
+
+```tsx
+<Plot
+	Title="Signal" XLabel="t (s)" Legend="TopLeft" YScale="SymLog"
+	Series={[{ Name: "wave", X: times, Y: values, Marker: "Circle" }, { Name: "mean", Y: means, Color: "#E5484D", Line: "Dashed" }]}
+	DragLines={[{ Axis: "Y", Value: limit, Label: "limit" }]}
+	OnChanged={(_line, value) => setLimit(value)}
+	OnViewChanged={(view) => console.log(view.X)}
+/>
+```
+
+A `ref` gives a `WidgetInstance`, and `raven` is all of Raven's C API. Read `.widget` when you need it: the handle changes if the widget is made again.
+
+```tsx
+const input = useRef<WidgetInstance>(null);
+useEffect(() => input.current?.focus(), []);
+<TextInput ref={input} />
+
+// a TreeView is filled this way
+raven.Rtree_view_add_item(tree.current.widget, raven.R_INVALID_ID, "World");
+```
+
+A `Custom` draws with the `Rdraw_` functions. `OnPaint` runs while a frame is drawn, so it must not change state.
+
+```tsx
+<Custom
+	OnMeasure={() => ({ Width: 400, Height: 200 })}
+	OnPaint={(painter, width, height) => raven.Rdraw_rect(painter, 0, 0, width, height, 8, 0.2, 0.3, 0.4, 1)}
+/>
+```
+
+Long lists ask for their rows as they are shown, and a million rows cost nothing:
+
+```tsx
+<ListView ItemCount={1_000_000} ItemText={(index) => `Row ${index}`} />
+<TileView ItemCount={200} ItemFill={(index, item) => { item.text = names[index]; }} />
+<Table Columns={["Name", "Age"]} RowCount={people.length} CellText={(row, column) => cell(people[row], column)} />
+```
+
+A `NodeGraph` and a `Timeline` take one of Raven's looks, `Preset` "Auto" (the theme), "Modern", "Blueprint", "Blender" or "Neon", and their parts can be changed one by one: `LinkShape`, `PinShape`, `HeaderStyle`, `ClipStyle`, `KeyShape`, `PlayheadColor`... One type of pin, one node or one track takes its own with `Rnode_graph_set_type_style`, `Rnode_graph_set_node_style` and `Rtimeline_set_track_style`.
+
+```tsx
+<NodeGraph Preset="Blueprint" LinkShape="Step" />
+<Timeline Preset={look} ClipStyle="Outline" />
+```
+
+Some things are done through a `ref`, as they are actions and not state. A `Toast` shows one message at a time; with `Queue="Sequence"` the next one waits its turn, with `Queue="Stack"` up to `MaxVisible` show at once.
+
+```tsx
+raven.Rtoast_show(toast.current.widget, "Saved", 3);
+raven.Rnotification_show("Backup", "It is finished", raven.R_NOTIFICATION_NORMAL);
+```
+
+What belongs to the system and not to a window has no component: an icon in the tray (`Rtray_create`, `Rtray_set_menu`, `Rtray_set_clicked_callback`), the badge, progress and menu of the taskbar or the Dock (`Rtaskbar_set_badge`, `Rwindow_set_taskbar_progress`), picture in picture (`Rwindow_set_picture_in_picture`), and the inspector of a window, which lists its widgets and picks one with a click (`Rwindow_set_inspector`). Call them from an effect, and undo them in its cleanup.
+
+An application with a tray icon lives on when its last window closes, as a tray application should: `runApp` returns only after `raven.Rquit(0)`, or the action `app.quit`. Give the icon a way to end it, a "Quit" item of its menu for one; the cleanup that destroys the icon still runs then. Make it only where the system shows it, `Rtray_is_supported()`: on Linux an icon is made even when no panel runs to show it, and the application would live on with nothing to click. Without one, closing the last window ends it, as usual.
+
+```tsx
+useEffect(() => {
+	// (on Linux, a panel that shows tray icons must be running)
+	const tray = raven.Rtray_is_supported() ? raven.Rtray_create() : raven.R_INVALID_ID;
+	if (tray === raven.R_INVALID_ID) {
+		return; // (no tray: the application ends with its last window)
+	}
+	// Its picture, as RGBA pixels: without one, some panels show nothing to click.
+	// An orange square here; in practice, the icon of the application.
+	const pixels = new Uint8Array(32 * 32 * 4);
+	for (let index = 0; index < pixels.length; index += 4) {
+		pixels.set([0xe8, 0x59, 0x0c, 0xff], index);
+	}
+	raven.Rtray_set_icon(tray, pixels, 32, 32);
+	raven.Rtray_set_tooltip(tray, "Backup");
+	raven.Rtray_set_clicked_callback(tray, () => raven.Rquit(0));
+	return () => raven.Rtray_destroy(tray);
+}, []);
+```
+
+An `Image` shows an SVG file like any other: `<Image Source="logo.svg" />`.
+
+## What to expect
+
+- Removing a prop makes the widget again, in its place, with the same children: Raven has no way to give an attribute its default back. What the widget held by itself (focus, typed text, scrolling) is lost. To avoid that, keep the prop and change its value.
+- The designer of Raven does not edit TSX.
+- Style parts and states (`Part`, `State`) only exist in themes: `Styles` of `defineTheme`, not props.
+
+## Working on this package
+
+The repository is a Bun workspace, with this package in `packages/raven-tsx` and the examples in `examples`: `helloworld` tries everything, the others are the examples of Raven in TSX. It expects a Raven checkout two folders up, at `../../raven` from the root:
+
+    raven/                 github.com/oscar-soirey/Raven
+    bun/raven-tsx/         this repository
+
+Check out the commit of Raven this package is pinned to, build it, then make the native package of your platform from it (`native:local` refuses a library built from any other commit):
+
+    git -C raven checkout "$(cat bun/raven-tsx/packages/raven-tsx/RAVEN_VERSION)"
+    cmake -S raven -B raven/build-shared -DCMAKE_BUILD_TYPE=Release -DRAVEN_BUILD_SHARED=ON
+    cmake --build raven/build-shared --parallel
+    cd bun/raven-tsx/packages/raven-tsx
+    bun run native:local
+    bun install
+    bun test
+
+Then, in `examples/helloworld`: `bun run dev`, or `bun run build`. Every other example runs with `bun run dev` in its folder.
+
+| Task | Command |
+|---|---|
+| Regenerate `src/core/props.generated.ts` and `src/react/components.generated.ts` | `bun run generate` |
+| Cross-build `raven.dll` on Linux with MinGW-w64, then `bun install` | `bun run native:windows` |
+| Compile a Windows `.exe` of the example, after that | `bun run build:windows` in `examples/helloworld` |
+| Where things stand, and what changed in Raven's API | `bun run raven:status [ref]` |
+| Check that everything agrees with the pin | `bun run raven:check` |
+| Move to another Raven, or to the latest | `bun run raven:update [ref]` |
+
+`RAVEN_VERSION` says which Raven this is, a full commit or a tag, and nothing else does. `raven:update` is the way to change it: it moves the checkout, builds the libraries, packages one, and only then takes the binding, writes the pin and generates the components, since a newer library works with an older binding and the opposite stops every application at startup. It stops at the first step that fails, and can be run again.
+
+Nothing in a library says which commit it is: `Rget_version` is the same for every commit between two releases. So `native:local` asks CMake which checkout the build folder belongs to, refuses it unless that checkout is at the pin with no changes, brings the build up to date, and writes `raven.json` beside the library. `--allow-mismatch` packages a library to try a change, and `raven:check` then says so. An application started with a library that lacks what the binding needs says so too, rather than naming one symbol.
+
+`src/test/core/coverage.test.ts` fails when Raven adds a tag, an attribute or a callback nobody has decided about: wire it, or say there why not.
+
+### Drift
+
+`drift.txt` records the git blob of each Raven file that raven-tsx copies or mirrors: the examples, `src/widgets`, `src/widget` and `src/xml`. It catches what an API diff cannot, such as a widget that behaves differently or an example that gained a feature.
+
+| Task | Command |
+|---|---|
+| What differs from `drift.txt` at the pin | `bun run raven:drift` |
+| Preview another commit before moving to it | `bun run raven:drift upstream/main` |
+| The same, failing if anything differs | `bun run raven:drift --check` |
+| Record a file or folder as checked, at the pin | `bun run raven:drift --accept examples/music` |
+| Record everything as checked, at the pin | `bun run raven:drift --accept-all` |
+
+`raven:status` and `raven:check` include it. A changed file is listed as `old..new`, and `git diff old new` in the Raven checkout shows the change. Accept a file only after you have looked at it: the diff of `drift.txt` in a commit is the record of what was reviewed.
+
+Every push builds Raven at `RAVEN_VERSION` on each platform, and runs `raven:check` and the tests there.
+
+Publishing is off until the repository variable `NPM_PUBLISH` is `true`; until then the workflow rehearses it with `npm pack --dry-run`. A new version is: set `version` in `package.json`, and push the tag `v<version>`. The packages of the platforms are published first, then this one.
+
+npm can only trust a workflow for a package that exists, so the first version needs the secret `NPM_TOKEN`: a granular token that can write to the scope, with bypass 2FA on, as nobody is there to answer a prompt. Delete the secret after that release.
+
+Later versions publish through OIDC, with provenance. Just before pushing the next tag, give each of the 6 packages a trusted publisher on npm (repository `deckyfx/raven-tsx`, workflow `release.yml`, environment `npm`, with `npm publish` allowed: by default it may only stage). Limit the GitHub environment `npm` to `v*` tags, so that a run of a branch cannot publish. A new publisher expires unless it publishes within 2 days; if that happens, delete it and make another.