@ringozz/react-godot 1.0.0-4 → 1.0.0-6

package/README.md

@@ -2,8 +2,6 @@
 
 Declarative, component-driven **Godot 4** scene graph management in React. Built for high-performance applications using `@ringozz/godot`.
 
----
-
 ## Overview
 
 `@ringozz/react-godot` brings a **React Three Fiber (R3F)**-like developer experience to Godot. It provides a custom React reconciler that renders React components directly into Godot's live engine scene tree (`SceneTree`).
@@ -13,8 +11,6 @@ If you are familiar with React Three Fiber, the core paradigms will feel instant
 - **Resource Attachment**: Use the `attach` prop to assign nested Godot resources (materials, shapes, meshes, environments) directly to parent properties.
 - **Reactive Engine Loop**: Use hooks like `useSignal` to hook into Godot signals (`processFrame`, `windowInput`) without triggering React state re-renders.
 
----
-
 ## Installation & Setup
 
 ### 1. Dependencies
@@ -40,8 +36,6 @@ To enable custom JSX element resolution for Godot nodes, configure `jsxImportSou
 }
 ```
 
----
-
 ## Application Entry & Portal Rendering
 
 ### 1. Mounting with `createRoot(parent: Node)`
@@ -80,13 +74,11 @@ function Overlay({ overlayNode }: { overlayNode: Node }) {
 - **Container Constraint**: The target `container` must be a Godot `Node` (it cannot target `Resource` instances).
 - **Cleanup**: Unmounting the portal safely disposes of and frees its child Godot nodes.
 
----
-
 ## Core Concepts & Patterns
 
 ### 1. Existing Objects with `object` Prop
 
-If you already have a pre-existing Godot `Node` or `Resource` instance (e.g. instantiated from C++ or loaded from disk), pass it via the `object` prop to adopt it into the React component tree instead of letting the reconciler instantiate a new object:
+If you already have a pre-existing Godot `Node`, `Resource`, or `PackedScene` instance (e.g. instantiated from C++ or loaded from disk), pass it via the `object` prop to adopt it into the React component tree instead of letting the reconciler instantiate a new object:
 
 ```tsx
 <Node object={myExistingGodotNode}>
@@ -94,6 +86,10 @@ If you already have a pre-existing Godot `Node` or `Resource` instance (e.g. ins
 </Node>
 ```
 
+- **`object` is immutable on a mounted instance.** It selects the host instance once, at creation. A re-render that changes `object` on an existing element throws (`Cannot change the \`object\` of a mounted instance`) because React cannot swap a fiber's Godot node — remount with a new `key` instead.
+- **A `PackedScene` `object` is instantiated once per host mount** — each element gets a fresh node tree; the result is a plain `Node` (not `.reference()`'d) freed on unmount. The same `PackedScene` can feed multiple elements; give same-type siblings stable `key`s.
+- **Dynamic same-type sibling lists need stable `key`s.** Godot host nodes are identity, not content: React reconciles keyless siblings by position, so deleting the *first* of two same-type siblings reuses its Godot node for the survivor (a plain state re-render does this too; the web dev server's React Fast Refresh makes it especially likely). Add `key="..."` to each dynamically toggled same-type sibling to keep nodes pinned to the right elements.
+
 ### 2. Resource Nesting with `attach`
 
 In Godot, nodes often hold references to `Resource` objects (such as shapes, meshes, materials, or environments). Use the `attach` prop to automatically assign a child resource to a specific property on its parent:
@@ -154,15 +150,9 @@ useSignal(root.windowInput, (event) => {
   if (event instanceof InputEventMouseMotion) {
     // Handle mouse motion
   }
-  // IMPORTANT: Always free transient input event objects
-  event.free();
 });
 ```
 
-> **Memory Tip**: Godot input events should be explicitly freed by calling `event.free()` inside your signal handler.
-
----
-
 ## Full Example
 
 Below is a complete interactive 3D physics scene with custom camera controls and physics bodies:
@@ -267,8 +257,6 @@ export function App() {
 }
 ```
 
----
-
 ## API Summary
 
 | Export | Type | Description |

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@ringozz/react-godot",
   "author": "Vladimir Davidovich",
-  "version": "1.0.0-4",
+  "version": "1.0.0-6",
   "description": "A React renderer for Godot Engine via @ringozz/godot",
+  "keywords": [
+    "react",
+    "godot"
+  ],
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -16,7 +20,7 @@
     "*.md"
   ],
   "dependencies": {
-    "@ringozz/godot": "^4.7.1-7",
+    "@ringozz/godot": "^4.7.1-9",
     "@types/react-reconciler": "^0.33.0",
     "react-reconciler": "^0.33.0"
   },

package/src/index.ts

@@ -13,7 +13,7 @@ const reconciler = Reconciler(FiberConfig);
 reconciler.injectIntoDevTools(undefined as never);
 
 export function createRoot(parent: Node) {
-  const isStrictMode = !!import.meta.env?.DEV;
+  const isStrictMode = process.env.NODE_ENV === 'development';
   const concurrentUpdatesByDefaultOverride = false;
   const identifierPrefix = '';
   /* eslint-disable @typescript-eslint/no-explicit-any */

package/src/react-fiber.ts

@@ -5,6 +5,7 @@
 import { ClassDB } from '@ringozz/godot/ClassDB';
 import type { Node } from '@ringozz/godot/Node';
 import { Object as Instance } from '@ringozz/godot/Object';
+import { PackedScene } from '@ringozz/godot/PackedScene';
 import { RefCounted } from '@ringozz/godot/RefCounted';
 import type Reconciler from 'react-reconciler';
 import Constants from 'react-reconciler/constants.js';
@@ -32,8 +33,10 @@ const EMPTY = Object.freeze({});
 const attachments = new WeakMap<Instance, string>();
 
 export function createInstance<T extends Instance>(type: Type, props: Props, root: Container, hostContext: HostContext, internalHandle: Reconciler.OpaqueHandle): T {
-  const { attach, object, ...rest } = props;
-  if (object instanceof RefCounted)
+  let { attach, object, ...rest } = props;
+  if (object instanceof PackedScene)
+    object = object.instantiate();
+  else if (object instanceof RefCounted)
     object.reference();
 
   const instance = (object ?? ClassDB.instantiate(type)) as T;
@@ -265,10 +268,12 @@ function isEqual(a: unknown, b: unknown) {
 }
 
 export function commitUpdate(instance: Instance, type: Type, prevProps: Props, nextProps: Props, internalHandle: Reconciler.OpaqueHandle): void {
-  const { attach: attachOld, ref: refOld, children: childrenOld, ...restOld } = prevProps;
-  const { attach: attachNew, ref: refNew, children: childrenNew, ...restNew } = nextProps;
+  const { attach: attachOld, object: objectOld, ref: refOld, children: childrenOld, ...restOld } = prevProps;
+  const { attach: attachNew, object: objectNew, ref: refNew, children: childrenNew, ...restNew } = nextProps;
   if (attachOld !== attachNew)
     throw new Error(`Cannot change attachment ${attachOld} to ${attachNew}`);
+  if (objectOld !== objectNew)
+    throw new Error(`Cannot change the \`object\` of a mounted instance (${objectOld} -> ${objectNew}); remount with a new key`);
 
   const toText = (c: unknown) => Array.isArray(c) ? c.join('') : c as string;
   if (shouldSetTextContent(type, prevProps)) restOld['text'] = toText(childrenOld);

package/src/react-hooks.ts

@@ -18,5 +18,8 @@ export function useSignal<T extends (...args: any[]) => any>(signal: Signal<T>,
     const fn = ((...args: any[]) => ref.current(...args)) as T;
     signal.connect(fn);
     return () => signal.disconnect(fn);
+  // do not specify 'signal' dependency, because it changes often.
+  // specify invariant contents instead.
+  /* oxlint-disable-next-line react-hooks/exhaustive-deps */
   }, [signal.getObjectId(), signal.getName()]);
 }

package/src/react-jsx.ts

@@ -5,7 +5,7 @@
 import { jsxDEV as reactJsxDEV } from 'react/jsx-dev-runtime';
 import type * as ReactJSX from 'react/jsx-runtime';
 import { Fragment, jsx as reactJsx, jsxs as reactJsxs } from 'react/jsx-runtime';
-import type { ComponentProps, Instance } from './react-types.ts';
+import type { ComponentProps, GodotConstructor } from './react-types.ts';
 import { GodotVar } from '@ringozz/godot/runtime';
 
 export function jsx(type: any, props?: any, key?: any) {
@@ -22,13 +22,16 @@ export function jsxDEV(type: any, props?: any, key?: any, isStatic?: any, source
 
 export { Fragment };
 
+// JSX namespace augmentation: these types are the public JSX contract for the
+// `@ringozz/react-godot/jsx-runtime` import source, consumed by TypeScript in
+// consumer files. They are intentionally not referenced within this module.
+/* oxlint-disable no-unused-vars */
 declare module '@ringozz/react-godot/jsx-runtime' {
   export namespace JSX {
+    interface IntrinsicAttributes extends ReactJSX.JSX.IntrinsicAttributes { }
     interface IntrinsicElements extends ReactJSX.JSX.IntrinsicElements { }
     interface Element extends ReactJSX.JSX.Element { }
 
-    type GodotConstructor = { new(...args: any[]): Instance } & Function;
-
     type ElementType =
       | ReactJSX.JSX.ElementType
       | GodotConstructor;
@@ -39,3 +42,4 @@ declare module '@ringozz/react-godot/jsx-runtime' {
       : ReactJSX.JSX.LibraryManagedAttributes<C, P>;
   }
 }
+/* oxlint-enable no-unused-vars */

package/src/react-types.ts

@@ -5,6 +5,7 @@
 import type React from 'react';
 import type { Object } from '@ringozz/godot/Object';
 import type { ValueTypes } from '@ringozz/godot';
+import type { PackedScene } from '@ringozz/godot/PackedScene';
 
 type FunctionKeys<T> = { [K in keyof T]: T[K] extends Function ? K : never }[keyof T];
 type Properties<T> = Omit<T, FunctionKeys<T>>;
@@ -14,9 +15,11 @@ type ConstructorRepresentation<T = any> = new (...args: any[]) => T;
 
 export type Instance = Object;
 
+export type GodotConstructor<T extends Instance = Instance> = ConstructorRepresentation<T> & Function;
+
 export type InstanceProps<T extends Instance = Instance> = {
   /** An existing instance to render instead of creating a new one. */
-  object?: T;
+  object?: T | PackedScene;
   /** Attaches the element to a named property of the parent instead of adding it as a child. */
   attach?: string;
 };
@@ -27,10 +30,10 @@ type WidenVT<T> = {
   [K in keyof T]: T[K] extends ValueTypes ? T[K] | number[] : T[K];
 };
 
-type ElementProps<T extends ConstructorRepresentation, P = InstanceType<T>> = Partial<
+type ElementProps<T extends GodotConstructor, P = InstanceType<T>> = Partial<
   Overwrite<WidenVT<P>, ReactProps<P>>
 >;
 
-export type ComponentProps<T extends ConstructorRepresentation> = Mutable<
-  Overwrite<ElementProps<T>, Omit<InstanceProps<InstanceType<T>>, 'object'>>
+export type ComponentProps<T extends GodotConstructor> = Mutable<
+  Overwrite<ElementProps<T>, InstanceProps<InstanceType<T>>>
 >;