@opsydyn/effect-three 0.2.0 → 0.4.0

package/src/kernel/history.ts

@@ -0,0 +1,118 @@
+/**
+ * Undo and branching history from an immutable Model (roadmap, "Beyond parity" 4). A
+ * Model's values are never changed in place, so keeping every one costs only the
+ * references: a history is a tree of them. Recording after an undo starts a new branch
+ * and keeps the old future as another, so nothing done is ever lost; redo follows the
+ * branch last taken, and `chooseBranch` or `jumpTo` take another.
+ *
+ * Entries are numbered in the order they were recorded, from 0 (the first value), and
+ * each names the entry it followed. Pure data with a schema (`SceneSchema.History`),
+ * so a history can be saved, sent or inspected like the rest of the Model. Use it as a
+ * namespace: `History.make(value)`, `History.record(history, next, 'Moved crate')`.
+ *
+ * @module
+ */
+
+/** A value in the history: the entry it followed, and the one redo goes to from it. */
+export type HistoryEntry<A> = {
+  readonly id: number;
+  /** The entry this one followed, `null` for the first. */
+  readonly parent: number | null;
+  /** A few words for the change that made it, for a list of steps. */
+  readonly label: string;
+  readonly value: A;
+  /** The entry redo goes to from here: the branch last taken, `null` with none. */
+  readonly next: number | null;
+};
+
+export type History<A> = {
+  /** Every value recorded, by id. */
+  readonly entries: ReadonlyArray<HistoryEntry<A>>;
+  /** The present value's id. */
+  readonly current: number;
+};
+
+/** A history holding `value` alone. */
+export const make = <A>(value: A, label = 'Start'): History<A> => ({
+  entries: [{ id: 0, parent: null, label, value, next: null }],
+  current: 0,
+});
+
+const entryOf = <A>(state: History<A>, id: number): HistoryEntry<A> => {
+  const entry = state.entries[id];
+  // Ids are indices, made only here: one out of range is a broken history.
+  if (entry === undefined) throw new RangeError(`No history entry ${id}`);
+  return entry;
+};
+
+/** The present entry. */
+export const presentEntry = <A>(state: History<A>): HistoryEntry<A> =>
+  entryOf(state, state.current);
+
+/** The present value. */
+export const present = <A>(state: History<A>): A => presentEntry(state).value;
+
+const withNext = <A>(state: History<A>, id: number, next: number): History<A> => ({
+  ...state,
+  entries: state.entries.map((entry) => (entry.id === id ? { ...entry, next } : entry)),
+});
+
+/** `value` after the present, labelled: the new present, its own branch after an undo. */
+export const record = <A>(state: History<A>, value: A, label: string): History<A> => {
+  const id = state.entries.length;
+  const grown: History<A> = {
+    entries: [...state.entries, { id, parent: state.current, label, value, next: null }],
+    current: id,
+  };
+  return withNext(grown, state.current, id);
+};
+
+/** Whether there is a value before the present. */
+export const canUndo = <A>(state: History<A>): boolean => presentEntry(state).parent !== null;
+
+/** Whether there is a value after the present on the branch last taken. */
+export const canRedo = <A>(state: History<A>): boolean => presentEntry(state).next !== null;
+
+/** Back one value; at the first, as it was. */
+export const undo = <A>(state: History<A>): History<A> => {
+  const parent = presentEntry(state).parent;
+  return parent === null ? state : { ...state, current: parent };
+};
+
+/** Forward one value along the branch last taken; at its end, as it was. */
+export const redo = <A>(state: History<A>): History<A> => {
+  const next = presentEntry(state).next;
+  return next === null ? state : { ...state, current: next };
+};
+
+/** The entries that followed the present: one per branch, in the order recorded. */
+export const branches = <A>(state: History<A>): ReadonlyArray<HistoryEntry<A>> =>
+  state.entries.filter((entry) => entry.parent === state.current);
+
+/** Redo from the present goes to `id`, when it is one of the present's branches. */
+export const chooseBranch = <A>(state: History<A>, id: number): History<A> =>
+  branches(state).some((entry) => entry.id === id) ? withNext(state, state.current, id) : state;
+
+/** The entries from the first to `id`, in order. */
+export const pathTo = <A>(state: History<A>, id: number): ReadonlyArray<HistoryEntry<A>> => {
+  const path: Array<HistoryEntry<A>> = [];
+  for (let at: number | null = id; at !== null; at = entryOf(state, at).parent) {
+    path.unshift(entryOf(state, at));
+  }
+  return path;
+};
+
+/**
+ * Straight to entry `id`, wherever it is in the tree, with each step to it the branch
+ * redo takes, so undoing and redoing comes back to it.
+ */
+export const jumpTo = <A>(state: History<A>, id: number): History<A> => {
+  const path = pathTo(state, id);
+  const chosen = path
+    .slice(1)
+    .reduce((at, entry) => withNext(at, entry.parent ?? 0, entry.id), state);
+  return { ...chosen, current: id };
+};
+
+/** How many steps the present is from the first value. */
+export const depth = <A>(state: History<A>): number => pathTo(state, state.current).length - 1;

package/src/kernel/index.ts

@@ -96,15 +96,32 @@ export {
   pointLight,
   renderSettings,
   ring,
+  roundedBox,
+  backdrop,
   scene,
   sharedGeometry,
   lentGeometry,
   sharedMaterial,
   sphere,
   spin,
+  points,
+  sparkles,
+  stars,
+  trail,
+  edges,
+  line,
+  catmullRomPoints,
+  catmullRomPointAt,
+  catmullRomColors,
+  cubicBezierPoints,
+  quadraticBezierPoints,
+  cameraShake,
+  detailed,
+  billboard,
   spotLight,
   standard,
   overlay,
+  hud,
   renderTexture,
   torus,
   type TransformOptions,
@@ -194,6 +211,8 @@ export {
 export type { BodyCollision, BodyContactForce } from './bodies.ts';
 export type {
   ContactShadowPasses,
+  HostedLine,
+  HostedPoints,
   HostedShaderGrid,
   HostedSky,
   RenderKit,
@@ -272,3 +291,86 @@ export {
   type ParentKey,
   type SceneIndex,
 } from './sceneIndex.ts';
+export {
+  dragGizmo,
+  gizmo,
+  type Gizmo,
+  type GizmoGrab,
+  type GizmoHandle,
+  gizmoHandleOf,
+  type GizmoMode,
+  gizmoNodes,
+  type GizmoSpace,
+  hoverGizmo,
+  movedAlike,
+  type Placement,
+  pressGizmo,
+  releaseGizmo,
+} from './gizmo.ts';
+export { type BoxCorner, boxSelect, type CanvasSize, type Selectable } from './boxSelect.ts';
+export * as History from './history.ts';
+export * as Lockstep from './lockstep.ts';
+export {
+  describeScene,
+  formatSummary,
+  type LightSummary,
+  type SceneSummary,
+  type ThingSummary,
+  thingsBounds,
+} from './describeScene.ts';
+export {
+  type Mood,
+  moodStaging,
+  moods,
+  shotAngles,
+  type ShotAngle,
+  shotCamera,
+  type Staging,
+} from './shots.ts';
+export {
+  type FieldPath,
+  type FieldValue,
+  type InspectableAst,
+  type InspectedField,
+  type InspectHints,
+  inspectFields,
+  setAt,
+} from './inspect.ts';
+export {
+  type ChangePlace,
+  formatChanges,
+  type SceneChange,
+  type SceneChanges,
+  sceneChanges,
+  type SceneSetting,
+} from './sceneChanges.ts';
+export {
+  clearTape,
+  placeTapeEnd,
+  pointTape,
+  type Tape,
+  tape,
+  tapeLength,
+  type TapeLook,
+  tapeMiddle,
+  tapeNodes,
+} from './tape.ts';
+export {
+  dragPivot,
+  hoverPivot,
+  type Pivot,
+  pivot,
+  type PivotGrab,
+  type PivotHandle,
+  pivotHandleOf,
+  pivotNodes,
+  pressPivot,
+  releasePivot,
+} from './pivot.ts';
+export {
+  cameraAlong,
+  type ViewAxis,
+  viewportAxisOf,
+  viewportGizmoNodes,
+  type ViewportGizmoOptions,
+} from './viewportGizmo.ts';

package/src/kernel/inspect.ts

@@ -0,0 +1,214 @@
+/**
+ * The fields of a value, read from its schema (roadmap, "Beyond parity" 4: an inspector
+ * generated from the scene schemas). The runtime's `Inspector` passes a schema's AST in;
+ * this walks it beside the value and lists what an inspector shows: numbers, text,
+ * switches, choices of literals, colours, vectors, and the rest read-only (a node's
+ * kind, an absent part, a list of children). A tagged union shows the member the value
+ * is; nested structs show their fields under their name.
+ *
+ * The AST is read through the few shapes used here, so the kernel needs no schema
+ * library; colours and vectors are recognised by being the very AST nodes the caller
+ * names, not by field names.
+ *
+ * @module
+ */
+import type { Vec3 } from './description.ts';
+
+/** Where a field is in the value: property names and list indices from the top. */
+export type FieldPath = ReadonlyArray<string | number>;
+
+/** What an inspector's controls produce: a number, text, or a switch's state. */
+export type FieldValue = number | string | boolean;
+
+type Base = { readonly path: FieldPath; readonly label: string };
+
+/** A field as an inspector shows it. */
+export type InspectedField = Base &
+  (
+    | { readonly _tag: 'Number'; readonly value: number }
+    | { readonly _tag: 'Text'; readonly value: string }
+    | { readonly _tag: 'Toggle'; readonly value: boolean }
+    | { readonly _tag: 'Choice'; readonly value: string; readonly options: ReadonlyArray<string> }
+    | { readonly _tag: 'Colour'; readonly value: number }
+    | { readonly _tag: 'Vector'; readonly value: Vec3 }
+    /** Shown, not edited: a kind, an absent part, a list, or what this cannot edit. */
+    | { readonly _tag: 'Fixed'; readonly text: string }
+  );
+
+/** The parts of a schema AST read here (Effect's `SchemaAST`, structurally). */
+export type InspectableAst =
+  | { readonly _tag: 'Suspend'; readonly thunk: () => InspectableAst }
+  | {
+      readonly _tag: 'Objects';
+      readonly propertySignatures: ReadonlyArray<{
+        readonly name: PropertyKey;
+        readonly type: InspectableAst;
+      }>;
+    }
+  | {
+      readonly _tag: 'Arrays';
+      readonly elements: ReadonlyArray<InspectableAst>;
+      readonly rest: ReadonlyArray<InspectableAst>;
+    }
+  | { readonly _tag: 'Union'; readonly types: ReadonlyArray<InspectableAst> }
+  | { readonly _tag: 'Literal'; readonly literal: unknown }
+  | { readonly _tag: 'Number' | 'String' | 'Boolean' | 'Null' }
+  | { readonly _tag: string };
+
+/** AST nodes shown as a colour picker or as three numbers, by identity. */
+export type InspectHints = {
+  readonly colours: ReadonlyArray<unknown>;
+  readonly vectors: ReadonlyArray<unknown>;
+};
+
+const resolve = (ast: InspectableAst): InspectableAst =>
+  ast._tag === 'Suspend' && 'thunk' in ast ? resolve(ast.thunk()) : ast;
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const labelOf = (path: FieldPath): string => String(path.at(-1) ?? 'value');
+
+const literalOf = (ast: InspectableAst): unknown => ('literal' in ast ? ast.literal : undefined);
+
+/** The literal of an object member's `_tag`, if it has one. */
+const tagOf = (ast: InspectableAst): unknown => {
+  const member = resolve(ast);
+  if (!('propertySignatures' in member)) return undefined;
+  const tag = member.propertySignatures.find((property) => property.name === '_tag');
+  return tag === undefined ? undefined : literalOf(resolve(tag.type));
+};
+
+/** The union member `value` is: by its `_tag`, else the non-null one, else the first. */
+const memberFor = (
+  types: ReadonlyArray<InspectableAst>,
+  value: unknown,
+): InspectableAst | undefined => {
+  if (isRecord(value) && '_tag' in value) {
+    const tagged = types.find((member) => tagOf(member) === value['_tag']);
+    if (tagged !== undefined) return tagged;
+  }
+  if (value === null) return types.find((member) => resolve(member)._tag === 'Null');
+  return types.find((member) => resolve(member)._tag !== 'Null') ?? types[0];
+};
+
+const fixed = (path: FieldPath, text: string): InspectedField => ({
+  _tag: 'Fixed',
+  path,
+  label: labelOf(path),
+  text,
+});
+
+const isVector = (value: unknown): value is Vec3 =>
+  Array.isArray(value) && value.length === 3 && value.every((n) => typeof n === 'number');
+
+const walk = (
+  given: InspectableAst,
+  value: unknown,
+  path: FieldPath,
+  hints: InspectHints,
+): ReadonlyArray<InspectedField> => {
+  const ast = resolve(given);
+  const label = labelOf(path);
+  if (hints.colours.includes(ast) && typeof value === 'number') {
+    return [{ _tag: 'Colour', path, label, value }];
+  }
+  if (hints.vectors.includes(ast) && isVector(value)) {
+    return [{ _tag: 'Vector', path, label, value }];
+  }
+  switch (ast._tag) {
+    case 'Number':
+      return typeof value === 'number' ? [{ _tag: 'Number', path, label, value }] : [];
+    case 'String':
+      return typeof value === 'string' ? [{ _tag: 'Text', path, label, value }] : [];
+    case 'Boolean':
+      return typeof value === 'boolean' ? [{ _tag: 'Toggle', path, label, value }] : [];
+    case 'Literal':
+    case 'Null':
+      return [fixed(path, String(value))];
+    case 'Union':
+      return 'types' in ast ? unionFields(ast.types, value, path, hints) : [];
+    case 'Objects':
+      return 'propertySignatures' in ast ? objectFields(ast, value, path, hints) : [];
+    case 'Arrays':
+      return 'elements' in ast ? arrayFields(ast, value, path, hints) : [];
+    default:
+      return [fixed(path, String(value))];
+  }
+};
+
+/** A union of string literals is a choice; any other shows the member the value is. */
+const unionFields = (
+  types: ReadonlyArray<InspectableAst>,
+  value: unknown,
+  path: FieldPath,
+  hints: InspectHints,
+): ReadonlyArray<InspectedField> => {
+  const literals = types.map((member) => literalOf(resolve(member)));
+  if (typeof value === 'string' && literals.every((literal) => typeof literal === 'string')) {
+    return [{ _tag: 'Choice', path, label: labelOf(path), value, options: literals.map(String) }];
+  }
+  const member = memberFor(types, value);
+  return member === undefined ? [fixed(path, String(value))] : walk(member, value, path, hints);
+};
+
+const objectFields = (
+  ast: Extract<InspectableAst, { readonly propertySignatures: unknown }>,
+  value: unknown,
+  path: FieldPath,
+  hints: InspectHints,
+): ReadonlyArray<InspectedField> => {
+  if (!isRecord(value)) return [fixed(path, String(value))];
+  return ast.propertySignatures.flatMap((property) =>
+    propertyFields(String(property.name), property.type, value, path, hints),
+  );
+};
+
+/** One property's fields: none when absent; a tag shows what kind it is, never edited. */
+function propertyFields(
+  name: string,
+  type: InspectableAst,
+  value: Readonly<Record<string, unknown>>,
+  path: FieldPath,
+  hints: InspectHints,
+): ReadonlyArray<InspectedField> {
+  if (!(name in value)) return [];
+  if (name === '_tag') return [fixed([...path, name], String(value[name]))];
+  return walk(type, value[name], [...path, name], hints);
+}
+
+/** A fixed tuple shows each element; a list of any length shows how many it holds. */
+const arrayFields = (
+  ast: Extract<InspectableAst, { readonly elements: unknown }>,
+  value: unknown,
+  path: FieldPath,
+  hints: InspectHints,
+): ReadonlyArray<InspectedField> => {
+  if (!Array.isArray(value)) return [fixed(path, String(value))];
+  if (ast.rest.length > 0) {
+    return [fixed(path, `${value.length} ${value.length === 1 ? 'item' : 'items'}`)];
+  }
+  return ast.elements.flatMap((element, index) =>
+    walk(element, value[index], [...path, index], hints),
+  );
+};
+
+/** The fields of `value` as its schema's AST describes them, in the schema's order. */
+export const inspectFields = (
+  ast: InspectableAst,
+  value: unknown,
+  hints: InspectHints = { colours: [], vectors: [] },
+): ReadonlyArray<InspectedField> => walk(ast, value, [], hints);
+
+/** `value` with `next` at `path`, every object and list on the way copied, not changed. */
+export const setAt = (value: unknown, path: FieldPath, next: unknown): unknown => {
+  const [head, ...rest] = path;
+  if (head === undefined) return next;
+  if (Array.isArray(value) && typeof head === 'number') {
+    return value.map((item, index) => (index === head ? setAt(item, rest, next) : item));
+  }
+  if (isRecord(value) && typeof head === 'string') {
+    return { ...value, [head]: setAt(value[head], rest, next) };
+  }
+  return value;
+};

package/src/kernel/lineGeometry.ts

@@ -0,0 +1,75 @@
+/**
+ * A line's geometry, as Drei's `Line` builds it: three's `LineGeometry` through the points
+ * (or `LineSegmentsGeometry`, a segment for each pair), with a colour per point when it
+ * has them. Shared by the render kits, whose materials differ; the geometry does not.
+ *
+ * @module
+ */
+import { type BufferGeometry, Color, EdgesGeometry } from 'three';
+import type { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js';
+
+import type { Edges, LineNode, Vec3 } from './description.ts';
+
+/** Whether there is anything to draw: two points for a line, a pair for segments. */
+export const drawable = (line: LineNode): boolean => line.points.length >= 2;
+
+/**
+ * Fills a line's geometry: a `LineGeometry` through the points, or a
+ * `LineSegmentsGeometry` for segments. Too few points give one empty segment (hidden).
+ */
+export const fillLineGeometry = <G extends LineSegmentsGeometry>(
+  geometry: G,
+  line: LineNode,
+): G => {
+  const points = drawable(line) ? line.points : [[0, 0, 0] as const, [0, 0, 0] as const];
+  // Segments come in pairs: an odd last point has nothing to join.
+  const used = line.segments ? points.slice(0, points.length - (points.length % 2)) : points;
+  geometry.setPositions(used.flat());
+  const colors = line.vertexColors;
+  if (colors !== null) {
+    // A colour for every point: the last given carries on, as a line can't skip one.
+    const per = used.map((_, index) => colors[Math.min(index, colors.length - 1)] ?? line.color);
+    geometry.setColors(per.flatMap((color) => new Color(color).toArray()));
+  }
+  return geometry;
+};
+
+/**
+ * The line segments along a geometry's edges where faces meet at more than `threshold`
+ * degrees, as Drei's `Edges` takes them from three's `EdgesGeometry`.
+ */
+export const edgePoints = (geometry: BufferGeometry, threshold: number): ReadonlyArray<Vec3> => {
+  const found = new EdgesGeometry(geometry, threshold);
+  const position = found.getAttribute('position');
+  const points = Array.from(
+    { length: position.count },
+    (_, index): Vec3 => [position.getX(index), position.getY(index), position.getZ(index)],
+  );
+  found.dispose();
+  return points;
+};
+
+/** The line a mesh's edges are drawn as: segments in the mesh's own space. */
+export const edgeLine = (key: string, look: Edges, points: ReadonlyArray<Vec3>): LineNode => ({
+  _tag: 'Line',
+  key: `${key}:edges`,
+  position: [0, 0, 0],
+  rotation: { _tag: 'Fixed', euler: [0, 0, 0] },
+  scale: [1, 1, 1],
+  transition: { _tag: 'Instant' },
+  behaviour: null,
+  interactive: false,
+  points,
+  segments: true,
+  color: look.color,
+  vertexColors: null,
+  width: look.width,
+  worldUnits: look.worldUnits,
+  dashed: look.dashed,
+  dashSize: look.dashSize,
+  gapSize: look.gapSize,
+  dashScale: 1,
+  dashOffset: 0,
+  opacity: look.opacity,
+  transparent: look.transparent,
+});