@react-x11/components 0.1.0 → 0.2.0

package/src/three/jsx.ts

@@ -0,0 +1,275 @@
+// The scene vocabulary, typed — r3f-shaped props with refs that hand out
+// the mutable objects.
+//
+// Two layers, because of where the names currently live:
+//
+// 1. `ThreeElements` here is the full catalogue and the durable contract.
+//    The optional `@react-x11/components/three/jsx-runtime` gives a file
+//    the whole vocabulary at these types (see that file for the pragma).
+// 2. The `declare module` at the bottom teaches the default JSX namespace
+//    the names react-x11 does **not** already declare. The shared names —
+//    `<mesh>`, the geometries, the lights — are still typed by core's own
+//    3D declarations until core drops them with its scene graph; an
+//    augmentation cannot replace an inherited member, only add new ones.
+//    When the core removal lands, the shared names move into this block and
+//    the pragma stops being necessary.
+import type { Key, ReactNode, Ref } from 'react';
+
+import type { Color, Euler, Vector3 } from './math.js';
+import type {
+  AmbientLight,
+  DirectionalLight,
+  Group,
+  InstancedMesh,
+  InstanceSpec,
+  Line,
+  LineLoop,
+  LineSegments,
+  Mesh,
+  Object3D,
+  OrthographicCamera,
+  PerspectiveCamera,
+  PointLight,
+  Points,
+  SpotLight,
+} from './objects.js';
+import type {
+  BoxGeometry,
+  BufferGeometry,
+  ConeGeometry,
+  CylinderGeometry,
+  PlaneGeometry,
+  SphereGeometry,
+  TorusGeometry,
+} from './geometries.js';
+import type {
+  LineBasicMaterial,
+  Material,
+  MaterialSide,
+  MeshBasicMaterial,
+  MeshLambertMaterial,
+  MeshPhongMaterial,
+  MeshStandardMaterial,
+  PointsMaterial,
+  RawShaderMaterial,
+  ShaderMaterial,
+  TextureImage,
+} from './materials.js';
+import type {
+  BloomPass,
+  EffectComposer,
+  FxaaPass,
+  ShaderPass,
+  VignettePass,
+} from './passes.js';
+import type { ThreeEvent } from './events.js';
+
+export type Vec3 = [number, number, number] | Vector3;
+export type EulerLike = [number, number, number] | Euler;
+export type ColorLike =
+  | string
+  | number
+  | Color
+  | [number, number, number]
+  | [number, number, number, number];
+
+export interface PointerEventProps {
+  onClick?: (event: ThreeEvent) => void;
+  onPointerDown?: (event: ThreeEvent) => void;
+  onPointerUp?: (event: ThreeEvent) => void;
+  onPointerMove?: (event: ThreeEvent) => void;
+  onPointerOver?: (event: ThreeEvent) => void;
+  onPointerOut?: (event: ThreeEvent) => void;
+}
+
+/** What every scene element takes on top of its own props. */
+export interface NodeProps<T> {
+  key?: Key;
+  ref?: Ref<T>;
+  children?: ReactNode;
+  /** Where in the parent this object is assigned instead of being a child —
+   * `"geometry"`, `"material"`, `"background"`, a dashed path. Geometries,
+   * materials and `<color>` infer theirs. */
+  attach?: string;
+}
+
+export interface Object3DProps<T = Object3D>
+  extends NodeProps<T>, PointerEventProps {
+  position?: Vec3;
+  /** XYZ euler angles, radians. */
+  rotation?: EulerLike;
+  /** A tuple, or one number for a uniform scale. */
+  scale?: Vec3 | number;
+  visible?: boolean;
+  name?: string;
+  userData?: Record<string, unknown>;
+  /** Shown while this object is hovered (needs a pointer handler). */
+  cursor?: string;
+  /** dashed paths — `position-x`, `material-color` — are applied but typed
+   * loosely; spell the object form when the checker matters. */
+  'position-x'?: number;
+  'position-y'?: number;
+  'position-z'?: number;
+  'rotation-x'?: number;
+  'rotation-y'?: number;
+  'rotation-z'?: number;
+  'scale-x'?: number;
+  'scale-y'?: number;
+  'scale-z'?: number;
+}
+
+export interface GeometryElementProps<T, A = number[]> extends NodeProps<T> {
+  /** Constructor arguments, exactly as in three.js. Changing them rebuilds
+   * the shape in place (refs stay valid). */
+  args?: A;
+}
+
+export interface MaterialElementProps<T = Material> extends NodeProps<T> {
+  color?: ColorLike;
+  opacity?: number;
+  transparent?: boolean;
+  wireframe?: boolean;
+  side?: MaterialSide;
+  map?: TextureImage;
+}
+
+export interface LightProps<T> extends Object3DProps<T> {
+  color?: ColorLike;
+  intensity?: number;
+}
+
+export interface ShaderMaterialProps<
+  T = ShaderMaterial,
+> extends MaterialElementProps<T> {
+  vertexShader?: string;
+  fragmentShader?: string;
+  /** three.js's `{ name: { value } }` shape; bare values are wrapped. */
+  uniforms?: Record<string, unknown>;
+}
+
+export interface PassProps<T> extends NodeProps<T> {
+  /** false skips this pass; the rest of the chain still runs. */
+  enabled?: boolean;
+}
+
+/** The full scene vocabulary at this package's types. */
+export interface ThreeElements {
+  group: Object3DProps<Group>;
+  mesh: Object3DProps<Mesh>;
+  instancedMesh: Object3DProps<InstancedMesh> & {
+    instances?: readonly InstanceSpec[];
+  };
+  points: Object3DProps<Points>;
+  line: Object3DProps<Line>;
+  lineSegments: Object3DProps<LineSegments>;
+  lineLoop: Object3DProps<LineLoop>;
+  /** Mounts an existing object: `<primitive object={mesh} />`. */
+  primitive: Omit<Object3DProps<Object3D>, 'args'> & { object: object };
+
+  perspectiveCamera: Object3DProps<PerspectiveCamera> & {
+    /** Replace the canvas's default camera with this one. */
+    makeDefault?: boolean;
+    fov?: number;
+    near?: number;
+    far?: number;
+    zoom?: number;
+    target?: Vec3;
+    up?: Vec3;
+  };
+  orthographicCamera: Object3DProps<OrthographicCamera> & {
+    makeDefault?: boolean;
+    near?: number;
+    far?: number;
+    zoom?: number;
+    target?: Vec3;
+    up?: Vec3;
+  };
+
+  ambientLight: LightProps<AmbientLight>;
+  directionalLight: LightProps<DirectionalLight>;
+  pointLight: LightProps<PointLight> & { distance?: number; decay?: number };
+  spotLight: LightProps<SpotLight> & {
+    distance?: number;
+    decay?: number;
+    /** Radians. */
+    angle?: number;
+    penumbra?: number;
+    target?: Vec3;
+  };
+
+  boxGeometry: GeometryElementProps<BoxGeometry>;
+  planeGeometry: GeometryElementProps<PlaneGeometry>;
+  sphereGeometry: GeometryElementProps<SphereGeometry>;
+  cylinderGeometry: GeometryElementProps<
+    CylinderGeometry,
+    (number | boolean)[]
+  >;
+  coneGeometry: GeometryElementProps<ConeGeometry, (number | boolean)[]>;
+  torusGeometry: GeometryElementProps<TorusGeometry>;
+  bufferGeometry: NodeProps<BufferGeometry> & {
+    position?: ArrayLike<number>;
+    /** Derived from the triangles when omitted. */
+    normal?: ArrayLike<number>;
+    uv?: ArrayLike<number>;
+    index?: ArrayLike<number>;
+  };
+
+  meshBasicMaterial: MaterialElementProps<MeshBasicMaterial>;
+  meshLambertMaterial: MaterialElementProps<MeshLambertMaterial> & {
+    emissive?: ColorLike;
+  };
+  meshPhongMaterial: MaterialElementProps<MeshPhongMaterial> & {
+    emissive?: ColorLike;
+    specular?: ColorLike;
+    shininess?: number;
+  };
+  /** `roughness`/`metalness`, approximated onto Blinn-Phong — identically
+   * on both backends. See the docs page for the honest edges. */
+  meshStandardMaterial: MaterialElementProps<MeshStandardMaterial> & {
+    emissive?: ColorLike;
+    roughness?: number;
+    metalness?: number;
+  };
+  pointsMaterial: MaterialElementProps<PointsMaterial> & { size?: number };
+  lineBasicMaterial: MaterialElementProps<LineBasicMaterial> & {
+    linewidth?: number;
+  };
+  shaderMaterial: ShaderMaterialProps;
+  rawShaderMaterial: ShaderMaterialProps<RawShaderMaterial>;
+
+  /** `<color attach="background" args={['#101418']} />` */
+  color: NodeProps<Color> & { args?: [ColorLike] };
+
+  effectComposer: NodeProps<EffectComposer> & { enabled?: boolean };
+  shaderPass: PassProps<ShaderPass> & {
+    fragmentShader?: string;
+    vertexShader?: string;
+    uniforms?: Record<string, unknown>;
+  };
+  bloomPass: PassProps<BloomPass> & {
+    threshold?: number;
+    strength?: number;
+    radius?: number;
+  };
+  vignettePass: PassProps<VignettePass> & {
+    offset?: number;
+    darkness?: number;
+  };
+  fxaaPass: PassProps<FxaaPass>;
+}
+
+// Teach the default JSX namespace the names core does not already declare.
+// The module-augmentation shape react-x11's docs prescribe for third-party
+// elements — `src/flow/index.ts` is the worked example.
+declare module 'react-x11/jsx-runtime' {
+  namespace JSX {
+    interface IntrinsicElements {
+      primitive: ThreeElements['primitive'];
+      perspectiveCamera: ThreeElements['perspectiveCamera'];
+      orthographicCamera: ThreeElements['orthographicCamera'];
+      coneGeometry: ThreeElements['coneGeometry'];
+      meshStandardMaterial: ThreeElements['meshStandardMaterial'];
+      color: ThreeElements['color'];
+    }
+  }
+}

package/src/three/materials.ts

@@ -0,0 +1,270 @@
+// Materials: what a surface looks like, spelled with three.js's names.
+//
+// Mutable objects for the same reason the scene objects are — three-fiber
+// code animates a material by writing to it (`material.opacity = t`,
+// `material.uniforms.uTime.value = t`) — but the renderers read the *values*
+// every frame rather than watching for writes, so there is no version
+// counter here: the indirect renderer's material key is built from the
+// current values and the direct renderer sets uniforms per draw either way.
+//
+// The one three.js material family deliberately reshaped is
+// `MeshStandardMaterial`. PBR needs an environment and shading neither
+// backend has, so `roughness`/`metalness` are *mapped* onto the Blinn-Phong
+// terms both backends can draw — through one shared function, so the
+// approximation is identical over indirect GLX and over DRI3. Honest edge:
+// it will not look like three.js's PBR; it will look like the same material
+// on both react-x11 backends.
+import { Color } from './math.js';
+import type { ColorLike } from './math.js';
+
+/** An ntk `Image`, or anything with `{ width, height, data }` RGBA bytes. */
+export interface TextureImage {
+  width: number;
+  height: number;
+  data: ArrayLike<number>;
+}
+
+export type MaterialSide = 'front' | 'back' | 'double';
+
+/** three.js's `{ value }` wrapper; a bare value is accepted and wrapped. */
+export interface UniformEntry {
+  value: unknown;
+}
+export type Uniforms = Record<string, UniformEntry>;
+
+export class Material {
+  readonly isMaterial: boolean = true;
+  /** The renderer switch key — matches the JSX element name. */
+  readonly kind: string = 'meshBasicMaterial';
+
+  readonly color = new Color([1, 1, 1]);
+  opacity = 1;
+  transparent = false;
+  wireframe = false;
+  side: MaterialSide = 'front';
+  map: TextureImage | null = null;
+
+  /** @internal notified on any change so a demand-mode surface redraws */
+  __dirty: (() => void) | null = null;
+
+  constructor(parameters?: Record<string, unknown>) {
+    this.color._onChange = () => this.__dirty?.();
+    if (parameters) this.setValues(parameters);
+  }
+
+  /** three.js's constructor-parameter contract: `{ color: 'hotpink' }`. */
+  setValues(parameters: Record<string, unknown>): void {
+    for (const [key, value] of Object.entries(parameters)) {
+      if (value === undefined) continue;
+      const current = (this as Record<string, unknown>)[key];
+      if (current instanceof Color) current.set(value as ColorLike);
+      else (this as Record<string, unknown>)[key] = value;
+    }
+    this.__dirty?.();
+  }
+}
+
+/** Unlit: colour, `opacity`, `map`. */
+export class MeshBasicMaterial extends Material {
+  override readonly kind: string = 'meshBasicMaterial';
+}
+
+/** Diffuse shading. */
+export class MeshLambertMaterial extends Material {
+  override readonly kind: string = 'meshLambertMaterial';
+  readonly emissive = new Color([0, 0, 0]);
+
+  constructor(parameters?: Record<string, unknown>) {
+    super();
+    this.emissive._onChange = () => this.__dirty?.();
+    if (parameters) this.setValues(parameters);
+  }
+}
+
+/** + Blinn-Phong specular. */
+export class MeshPhongMaterial extends MeshLambertMaterial {
+  override readonly kind: string = 'meshPhongMaterial';
+  readonly specular = new Color([1, 1, 1]);
+  shininess = 30;
+
+  constructor(parameters?: Record<string, unknown>) {
+    super();
+    this.specular._onChange = () => this.__dirty?.();
+    if (parameters) this.setValues(parameters);
+  }
+}
+
+/**
+ * `roughness`/`metalness`, approximated. Both renderers draw this through
+ * `standardToPhong` below, so a scene written against three.js's most common
+ * material renders — the same way on both backends, and not the way a PBR
+ * pipeline would. The mapping is the documented contract, not an accident.
+ */
+export class MeshStandardMaterial extends MeshLambertMaterial {
+  override readonly kind: string = 'meshStandardMaterial';
+  roughness = 1;
+  metalness = 0;
+
+  constructor(parameters?: Record<string, unknown>) {
+    super();
+    if (parameters) this.setValues(parameters);
+  }
+}
+
+/**
+ * The Blinn-Phong terms a standard material shades with:
+ *
+ * - shininess falls out of roughness as `(1 - roughness)^4 * 128` — rough 1
+ *   is matte (no highlight), rough 0.5 a broad sheen, rough 0 a tight one;
+ * - the specular colour runs from a neutral 4% grey (dielectric) toward the
+ *   base colour (metal), scaled so a rough surface's highlight also dims;
+ * - metals reflect rather than scatter, so the diffuse term shrinks with
+ *   metalness.
+ */
+export function standardToPhong(material: MeshStandardMaterial): {
+  shininess: number;
+  specular: [number, number, number];
+  diffuseScale: number;
+} {
+  const rough = Math.min(1, Math.max(0, material.roughness));
+  const metal = Math.min(1, Math.max(0, material.metalness));
+  const gloss = (1 - rough) ** 4;
+  const { r, g, b } = material.color;
+  const strength = 0.04 + 0.96 * metal;
+  return {
+    shininess: Math.max(1, gloss * 128),
+    specular: [
+      (0.04 + (r - 0.04) * metal) * strength * (1 - rough * 0.8) * 4,
+      (0.04 + (g - 0.04) * metal) * strength * (1 - rough * 0.8) * 4,
+      (0.04 + (b - 0.04) * metal) * strength * (1 - rough * 0.8) * 4,
+    ].map((v) => Math.min(1, v)) as [number, number, number],
+    diffuseScale: 1 - metal * 0.75,
+  };
+}
+
+/** Unlit dots; `size` in pixels. */
+export class PointsMaterial extends Material {
+  override readonly kind: string = 'pointsMaterial';
+  size = 1;
+
+  // Subclass fields initialize after super() returns, so parameters must be
+  // applied here, not passed up — `super(parameters)` would set `size` and
+  // then the field initializer above would put the default back.
+  constructor(parameters?: Record<string, unknown>) {
+    super();
+    if (parameters) this.setValues(parameters);
+  }
+}
+
+/** Unlit lines; `linewidth` is three.js's spelling, and most drivers only
+ * honour 1 — a GL limitation, not a react-x11 one. */
+export class LineBasicMaterial extends Material {
+  override readonly kind: string = 'lineBasicMaterial';
+  linewidth = 1;
+
+  constructor(parameters?: Record<string, unknown>) {
+    super();
+    if (parameters) this.setValues(parameters);
+  }
+}
+
+/**
+ * Your own GLSL — the **direct** backend only, because the GLX protocol
+ * encodes no shader objects. three.js's prelude is injected: attributes
+ * `position`/`normal`/`uv`, the matrix uniforms and `cameraPosition`, so a
+ * shader copied from an r3f tutorial compiles unchanged.
+ *
+ * `uniforms` entries are normalized to `{ value }` wrappers on assignment,
+ * so `material.uniforms.uTime.value = t` — the r3f animation idiom — works
+ * whether the component wrote `{ uTime: 0 }` or `{ uTime: { value: 0 } }`.
+ */
+export class ShaderMaterial extends Material {
+  override readonly kind: string = 'shaderMaterial';
+  vertexShader = '';
+  fragmentShader = '';
+
+  private _uniforms: Uniforms = {};
+
+  constructor(parameters?: Record<string, unknown>) {
+    super();
+    if (parameters) this.setValues(parameters);
+  }
+
+  get uniforms(): Uniforms {
+    return this._uniforms;
+  }
+
+  set uniforms(value: Record<string, unknown>) {
+    const wrapped: Uniforms = {};
+    for (const [name, entry] of Object.entries(value ?? {})) {
+      wrapped[name] =
+        entry && typeof entry === 'object' && 'value' in entry
+          ? (entry as UniformEntry)
+          : { value: entry };
+    }
+    this._uniforms = wrapped;
+    this.__dirty?.();
+  }
+}
+
+/** The same, with nothing declared for you — as in three.js. */
+export class RawShaderMaterial extends ShaderMaterial {
+  override readonly kind: string = 'rawShaderMaterial';
+}
+
+/** Materials with no surface to shade, which lighting never applies to. */
+export const UNLIT_MATERIALS = new Set([
+  'meshBasicMaterial',
+  'pointsMaterial',
+  'lineBasicMaterial',
+]);
+
+/**
+ * The colour reading both renderers share, so a material means the same
+ * thing whichever pipeline draws it: `[r, g, b]`, the effective alpha
+ * (CSS-spelled alpha times `opacity`), emissive and specular.
+ */
+export function materialColors(material: Material | null): {
+  color: [number, number, number];
+  alpha: number;
+  emissive: [number, number, number];
+  specular: [number, number, number];
+  shininess: number;
+  diffuseScale: number;
+} {
+  if (!material) {
+    return {
+      color: [1, 1, 1],
+      alpha: 1,
+      emissive: [0, 0, 0],
+      specular: [1, 1, 1],
+      shininess: 30,
+      diffuseScale: 1,
+    };
+  }
+  const { r, g, b, _alpha } = material.color;
+  const emissive =
+    material instanceof MeshLambertMaterial
+      ? material.emissive.toArray()
+      : ([0, 0, 0] as [number, number, number]);
+  let specular: [number, number, number] = [1, 1, 1];
+  let shininess = 30;
+  let diffuseScale = 1;
+  if (material instanceof MeshStandardMaterial) {
+    const phong = standardToPhong(material);
+    specular = phong.specular;
+    shininess = phong.shininess;
+    diffuseScale = phong.diffuseScale;
+  } else if (material instanceof MeshPhongMaterial) {
+    specular = material.specular.toArray();
+    shininess = material.shininess;
+  }
+  return {
+    color: [r, g, b],
+    alpha: _alpha * material.opacity,
+    emissive,
+    specular,
+    shininess,
+    diffuseScale,
+  };
+}