@opsydyn/effect-three 0.3.0 → 0.4.0

package/src/kernel/build.ts

@@ -3,8 +3,15 @@
  *
  * @module
  */
+import { CatmullRomCurve3, Color, CubicBezierCurve3, QuadraticBezierCurve3, Vector3 } from 'three';
+
 import type {
   AmbientLightNode,
+  LineNode,
+  PointLook,
+  PointsNode,
+  Edges,
+  Trail,
   Animation,
   CameraShake,
   Detail,
@@ -18,6 +25,8 @@ import type {
   ContactShadows,
   Environment,
   Gestures,
+  Hud,
+  HudAlignment,
   GridNode,
   Sky,
   Xr,
@@ -344,6 +353,7 @@ export const basic = (options: Partial<Omit<BasicMaterial, '_tag'>> = {}): Basic
   transparent: options.transparent ?? false,
   side: options.side ?? 'front',
   wireframe: options.wireframe ?? false,
+  depthTest: options.depthTest ?? true,
 });
 
 /**
@@ -539,6 +549,7 @@ export const group = (
     readonly body?: Body | null;
     readonly follow?: XrSpace | null;
     readonly detail?: Detail | null;
+    readonly trail?: Trail | null;
   },
 ): GroupNode => ({
   _tag: 'Group',
@@ -553,6 +564,7 @@ export const group = (
   body: options.body ?? null,
   follow: options.follow ?? null,
   detail: options.detail ?? null,
+  trail: options.trail ?? null,
 });
 
 /**
@@ -566,6 +578,272 @@ export const detailed = (options: {
   readonly hysteresis?: number;
 }): Detail => ({ distances: options.distances, hysteresis: options.hysteresis ?? 0 });
 
+/**
+ * A line through `points`, as Drei's `Line` (`bf6f4ad`, `src/core/Line.tsx`), with its
+ * defaults: white, 1 pixel wide, solid, opaque. three's `LineMaterial` defaults the dashes:
+ * size 1, gap 1, scale 1, offset 0. `segments: true` is Drei's `Segments`: pairs of points.
+ */
+export const line = (
+  options: TransformOptions & {
+    readonly points: ReadonlyArray<Vec3>;
+    readonly segments?: boolean;
+    readonly color?: Rgb;
+    readonly vertexColors?: ReadonlyArray<Rgb> | null;
+    readonly width?: number;
+    readonly worldUnits?: boolean;
+    readonly dashed?: boolean;
+    readonly dashSize?: number;
+    readonly gapSize?: number;
+    readonly dashScale?: number;
+    readonly dashOffset?: number;
+    readonly opacity?: number;
+    readonly transparent?: boolean;
+    readonly interactive?: boolean;
+  },
+): LineNode => ({
+  _tag: 'Line',
+  key: options.key,
+  position: options.position ?? origin,
+  rotation: options.rotation ?? noRotation,
+  scale: options.scale ?? unitScale,
+  transition: options.transition ?? instantTransition,
+  behaviour: options.behaviour ?? null,
+  interactive: options.interactive ?? false,
+  points: options.points,
+  segments: options.segments ?? false,
+  color: options.color ?? 0xffffff,
+  vertexColors: options.vertexColors ?? null,
+  width: options.width ?? 1,
+  worldUnits: options.worldUnits ?? false,
+  dashed: options.dashed ?? false,
+  dashSize: options.dashSize ?? 1,
+  gapSize: options.gapSize ?? 1,
+  dashScale: options.dashScale ?? 1,
+  dashOffset: options.dashOffset ?? 0,
+  opacity: options.opacity ?? 1,
+  transparent: options.transparent ?? false,
+});
+
+const asVector = (point: Vec3): Vector3 => new Vector3(point[0], point[1], point[2]);
+const asVec3 = (point: Vector3): Vec3 => [point.x, point.y, point.z];
+
+/** Where a points node sits, as the other placed nodes. */
+type Placing = Pick<
+  TransformOptions,
+  'key' | 'position' | 'rotation' | 'scale' | 'transition' | 'behaviour'
+>;
+
+const placed = (options: Placing, look: PointLook): PointsNode => ({
+  _tag: 'Points',
+  key: options.key,
+  position: options.position ?? origin,
+  rotation: options.rotation ?? noRotation,
+  scale: options.scale ?? unitScale,
+  transition: options.transition ?? instantTransition,
+  behaviour: options.behaviour ?? null,
+  look,
+});
+
+/**
+ * Dots at `positions`, as Drei's `Points` (`bf6f4ad`, `src/core/Points.tsx`) with its
+ * `PointMaterial`: round, white, 1 pixel (three's `PointsMaterial` size), smaller with
+ * distance. `colors` gives each its own colour, `sizes` a factor on `size`.
+ */
+export const points = (
+  options: Placing & {
+    readonly positions: ReadonlyArray<Vec3>;
+    readonly colors?: ReadonlyArray<Rgb> | null;
+    readonly sizes?: ReadonlyArray<number> | null;
+    readonly color?: Rgb;
+    readonly size?: number;
+    readonly sizeAttenuation?: boolean;
+    readonly round?: boolean;
+    readonly opacity?: number;
+    readonly transparent?: boolean;
+  },
+): PointsNode =>
+  placed(options, {
+    _tag: 'Dots',
+    positions: options.positions,
+    colors: options.colors ?? null,
+    sizes: options.sizes ?? null,
+    color: options.color ?? 0xffffff,
+    size: options.size ?? 1,
+    sizeAttenuation: options.sizeAttenuation ?? true,
+    round: options.round ?? true,
+    opacity: options.opacity ?? 1,
+    transparent: options.transparent ?? false,
+  });
+
+/**
+ * Glowing motes drifting in a box, as Drei's `Sparkles` (`src/core/Sparkles.tsx`), with
+ * its defaults: 100 of them, speed 1, opaque, a unit box (`spread`, Drei's `scale`),
+ * random sizes up to 1, white, noise 1. Drei scatters them with `Math.random`; `seed`
+ * scatters them the same way every time.
+ */
+export const sparkles = (
+  options: Placing & {
+    readonly count?: number;
+    readonly speed?: number;
+    readonly opacity?: number;
+    readonly size?: number | null;
+    readonly color?: Rgb;
+    readonly spread?: number | Vec3;
+    readonly noise?: number | Vec3;
+    readonly seed?: number;
+  },
+): PointsNode => {
+  const spread = options.spread ?? 1;
+  const noise = options.noise ?? 1;
+  return placed(options, {
+    _tag: 'Sparkles',
+    count: options.count ?? 100,
+    speed: options.speed ?? 1,
+    opacity: options.opacity ?? 1,
+    scale: typeof spread === 'number' ? [spread, spread, spread] : spread,
+    size: options.size ?? null,
+    color: options.color ?? 0xffffff,
+    noise: typeof noise === 'number' ? [noise, noise, noise] : noise,
+    seed: options.seed ?? 1,
+  });
+};
+
+/**
+ * A starfield, as Drei's `Stars` (`src/core/Stars.tsx`), with its defaults: 5000 stars
+ * from radius 100 to 150, size factor 4, white (saturation 0), hard-edged, twinkling at
+ * speed 1. `seed` places them the same way every time.
+ */
+export const stars = (
+  options: Placing & {
+    readonly radius?: number;
+    readonly depth?: number;
+    readonly count?: number;
+    readonly factor?: number;
+    readonly saturation?: number;
+    readonly fade?: boolean;
+    readonly speed?: number;
+    readonly seed?: number;
+  },
+): PointsNode =>
+  placed(options, {
+    _tag: 'Stars',
+    radius: options.radius ?? 100,
+    depth: options.depth ?? 50,
+    count: options.count ?? 5000,
+    factor: options.factor ?? 4,
+    saturation: options.saturation ?? 0,
+    fade: options.fade ?? false,
+    speed: options.speed ?? 1,
+    seed: options.seed ?? 1,
+  });
+
+/**
+ * Points along a Catmull-Rom curve through `points`, as Drei's `CatmullRomLine`, with its
+ * defaults: open, centripetal, tension 0.5, 20 segments (so 21 points).
+ */
+export const catmullRomPoints = (
+  points: ReadonlyArray<Vec3>,
+  options: {
+    readonly closed?: boolean;
+    readonly curveType?: 'centripetal' | 'chordal' | 'catmullrom';
+    readonly tension?: number;
+    readonly segments?: number;
+  } = {},
+): ReadonlyArray<Vec3> =>
+  new CatmullRomCurve3(
+    points.map(asVector),
+    options.closed ?? false,
+    options.curveType ?? 'centripetal',
+    options.tension ?? 0.5,
+  )
+    .getPoints(options.segments ?? 20)
+    .map(asVec3);
+
+/**
+ * The point `t` of the way along a Catmull-Rom curve through `points` (0 its start, 1 its
+ * end; three's `getPoint`, by parameter rather than arc length), with
+ * `catmullRomPoints`'s defaults: for something that rides the curve, a behaviour say.
+ */
+export const catmullRomPointAt = (
+  points: ReadonlyArray<Vec3>,
+  t: number,
+  options: {
+    readonly closed?: boolean;
+    readonly curveType?: 'centripetal' | 'chordal' | 'catmullrom';
+    readonly tension?: number;
+  } = {},
+): Vec3 =>
+  asVec3(
+    new CatmullRomCurve3(
+      points.map(asVector),
+      options.closed ?? false,
+      options.curveType ?? 'centripetal',
+      options.tension ?? 0.5,
+    ).getPoint(Math.min(1, Math.max(0, t))),
+  );
+
+/**
+ * Colours for a Catmull-Rom line's points from a few along it, as Drei's
+ * `CatmullRomLine` spreads `vertexColors` over its segments (blended in linear colour).
+ */
+export const catmullRomColors = (
+  colors: ReadonlyArray<Rgb>,
+  options: { readonly segments?: number; readonly closed?: boolean } = {},
+): ReadonlyArray<Rgb> => {
+  const segments = options.segments ?? 20;
+  if (colors.length < 2 || colors.length === segments + 1) return colors;
+  const stops = colors.map((color) => new Color(color));
+  const first = stops[0];
+  if (options.closed === true && first !== undefined) stops.push(first.clone());
+  const divisions = segments / (stops.length - 1);
+  // The colour at point `index`: between the two stops either side of it.
+  const at = (index: number): Rgb =>
+    (stops[Math.floor(index / divisions)] ?? new Color())
+      .clone()
+      .lerp(
+        stops[Math.floor(index / divisions) + 1] ?? new Color(),
+        (index % divisions) / divisions,
+      )
+      .getHex();
+  const blended = Array.from({ length: segments - 1 }, (_, step) => at(step + 1));
+  return [colors[0] ?? 0, ...blended, stops.at(-1)?.getHex() ?? 0];
+};
+
+/** Points along a cubic Bézier curve, as Drei's `CubicBezierLine` (20 segments). */
+export const cubicBezierPoints = (options: {
+  readonly start: Vec3;
+  readonly midA: Vec3;
+  readonly midB: Vec3;
+  readonly end: Vec3;
+  readonly segments?: number;
+}): ReadonlyArray<Vec3> =>
+  new CubicBezierCurve3(
+    asVector(options.start),
+    asVector(options.midA),
+    asVector(options.midB),
+    asVector(options.end),
+  )
+    .getPoints(options.segments ?? 20)
+    .map(asVec3);
+
+/**
+ * Points along a quadratic Bézier curve, as Drei's `QuadraticBezierLine` (20 segments).
+ * Without `mid`, Drei's default: level with `start`, above or below `end`.
+ */
+export const quadraticBezierPoints = (options: {
+  readonly start: Vec3;
+  readonly end: Vec3;
+  readonly mid?: Vec3;
+  readonly segments?: number;
+}): ReadonlyArray<Vec3> => {
+  const [, startY] = options.start;
+  const [endX, , endZ] = options.end;
+  const mid = options.mid ?? [endX, startY, endZ];
+  return new QuadraticBezierCurve3(asVector(options.start), asVector(mid), asVector(options.end))
+    .getPoints(options.segments ?? 20)
+    .map(asVec3);
+};
+
 /** The head (the viewer), for content that stays in view. */
 export const headSpace = (): XrSpace => ({ _tag: 'Head' });
 
@@ -620,6 +898,8 @@ export const mesh = (
     readonly castShadow?: boolean;
     readonly receiveShadow?: boolean;
     readonly body?: Body | null;
+    readonly edges?: Edges | null;
+    readonly trail?: Trail | null;
   },
 ): MeshNode => ({
   _tag: 'Mesh',
@@ -635,6 +915,42 @@ export const mesh = (
   castShadow: options.castShadow ?? false,
   receiveShadow: options.receiveShadow ?? false,
   body: options.body ?? null,
+  edges: options.edges ?? null,
+  trail: options.trail ?? null,
+});
+
+/**
+ * A trail behind a moving node, as Drei's `Trail` (`bf6f4ad`, `src/core/Trail.tsx`), with
+ * its defaults: width 0.2, length 1, decay 1, world positions, no stride, every step, hot
+ * pink; no taper or fade (Drei's `attenuation` and `meshline` options).
+ */
+export const trail = (options: Partial<Trail> = {}): Trail => ({
+  width: options.width ?? 0.2,
+  length: options.length ?? 1,
+  decay: options.decay ?? 1,
+  local: options.local ?? false,
+  stride: options.stride ?? 0,
+  interval: options.interval ?? 1,
+  color: options.color ?? 0xff69b4,
+  taper: options.taper ?? 'none',
+  fade: options.fade ?? false,
+});
+
+/**
+ * Lines along a mesh's hard edges, as Drei's `Edges` (`bf6f4ad`, `src/core/Edges.tsx`),
+ * with its defaults: faces meeting at more than 15 degrees, a white line 1 pixel wide
+ * (Drei's `Line` defaults). `mesh({ edges: edges({ color: 0x000000 }) })`.
+ */
+export const edges = (options: Partial<Edges> = {}): Edges => ({
+  threshold: options.threshold ?? 15,
+  color: options.color ?? 0xffffff,
+  width: options.width ?? 1,
+  worldUnits: options.worldUnits ?? false,
+  dashed: options.dashed ?? false,
+  dashSize: options.dashSize ?? 1,
+  gapSize: options.gapSize ?? 1,
+  opacity: options.opacity ?? 1,
+  transparent: options.transparent ?? false,
 });
 
 /**
@@ -1386,11 +1702,26 @@ export const overlay = (options: {
   view: options.view ?? null,
 });
 
+/**
+ * Nodes drawn over the scene (Drei's `Hud`), with Drei's `GizmoHelper` defaults: the
+ * origin 80 CSS pixels in from the bottom right.
+ */
+export const hud = (options: {
+  readonly alignment?: HudAlignment;
+  readonly margin?: readonly [number, number];
+  readonly children?: ReadonlyArray<SceneNode>;
+}): Hud => ({
+  alignment: options.alignment ?? 'bottom-right',
+  margin: options.margin ?? [80, 80],
+  children: options.children ?? [],
+});
+
 export const scene = (options: {
   readonly camera?: Camera;
   readonly gestures?: Gestures;
   readonly views?: ReadonlyArray<View>;
   readonly renderTextures?: ReadonlyArray<RenderTexture>;
+  readonly hud?: Hud | null;
   readonly overlays?: ReadonlyArray<Overlay>;
   /** Optional staging: leave out or pass `null` for none, so a Model can switch it off. */
   readonly environment?: Environment | null;
@@ -1407,6 +1738,7 @@ export const scene = (options: {
   gestures: options.gestures ?? 'page',
   views: options.views ?? noViews,
   renderTextures: options.renderTextures ?? noRenderTextures,
+  hud: options.hud ?? null,
   overlays: options.overlays ?? noOverlays,
   environment: options.environment ?? null,
   sky: options.sky ?? null,

package/src/kernel/cameraShake.ts

@@ -15,20 +15,10 @@ import { SimplexNoise } from 'three/addons/math/SimplexNoise.js';
 
 import type { CameraShake } from './description.ts';
 import { cameraShakeEquals } from './equality.ts';
+import { seededRandom } from './seeded.ts';
 
-/** A small seeded generator (mulberry32), so the noise is the same on every page load. */
-const seeded = (seed: number): { readonly random: () => number } => {
-  let state = seed >>> 0;
-  return {
-    random: () => {
-      state = (state + 0x6d2b79f5) >>> 0;
-      let t = state;
-      t = Math.imul(t ^ (t >>> 15), t | 1);
-      t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-      return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-    },
-  };
-};
+/** Each axis's noise, seeded so the shake is the same on every page load. */
+const seeded = (seed: number) => ({ random: seededRandom(seed) });
 
 const yawNoise = new SimplexNoise(seeded(1));
 const pitchNoise = new SimplexNoise(seeded(2));

package/src/kernel/describeScene.ts

@@ -0,0 +1,224 @@
+/**
+ * What a scene contains, for an assistant (roadmap, "Beyond parity" 3): its camera, its
+ * things with their kind, size, colour and place, its lights, the box they fill and its
+ * staging, as data (`describeScene`) and as a few lines of text (`formatSummary`) an
+ * agent reads before it acts. An agent that reads the Model can describe a scene
+ * without three.js, so sizes come from the geometry's parameters and the node's scale:
+ * close enough to place things beside one another and to frame a shot.
+ *
+ * @module
+ */
+import type {
+  GeometryRef,
+  Rgb,
+  SceneDescription,
+  SceneNode,
+  ShapeGeometry,
+  Vec3,
+} from './description.ts';
+import type { Box } from './orbit.ts';
+
+export type ThingSummary = {
+  readonly key: string;
+  /** The node's kind, with its geometry's for a mesh: `Mesh (Box)`. */
+  readonly kind: string;
+  /** In its parent's space; for things at the top, the world's. */
+  readonly position: Vec3;
+  /** Width, height and depth, from the geometry and scale; `null` when not known. */
+  readonly size: Vec3 | null;
+  readonly colour: Rgb | null;
+  /** The group it is in, `null` at the top. */
+  readonly parent: string | null;
+};
+
+export type LightSummary = {
+  readonly key: string;
+  readonly kind: string;
+  readonly colour: Rgb;
+  readonly intensity: number;
+  readonly position: Vec3 | null;
+};
+
+export type SceneSummary = {
+  readonly camera: {
+    readonly kind: 'Perspective' | 'Orthographic';
+    readonly position: Vec3;
+    readonly lookAt: Vec3;
+  };
+  readonly things: ReadonlyArray<ThingSummary>;
+  readonly lights: ReadonlyArray<LightSummary>;
+  /** The box the top-level things of known size fill, `null` with none. */
+  readonly bounds: Box | null;
+  readonly staging: ReadonlyArray<string>;
+};
+
+/** Width, height and depth of a shape, unscaled; `undefined` for text and shapes. */
+const extentOf = (geometry: ShapeGeometry): Vec3 | undefined => {
+  switch (geometry._tag) {
+    case 'Box':
+    case 'RoundedBox':
+      return [geometry.width, geometry.height, geometry.depth];
+    case 'Sphere':
+      return [geometry.radius * 2, geometry.radius * 2, geometry.radius * 2];
+    case 'Cone':
+      return [geometry.radius * 2, geometry.height, geometry.radius * 2];
+    case 'Cylinder': {
+      const across = Math.max(geometry.radiusTop, geometry.radiusBottom) * 2;
+      return [across, geometry.height, across];
+    }
+    case 'Capsule':
+      return [geometry.radius * 2, geometry.height + geometry.radius * 2, geometry.radius * 2];
+    case 'Torus': {
+      const across = (geometry.radius + geometry.tube) * 2;
+      return [across, across, geometry.tube * 2];
+    }
+    case 'Plane':
+      return [geometry.width, geometry.height, 0];
+    case 'Circle':
+      return [geometry.radius * 2, geometry.radius * 2, 0];
+    case 'Ring':
+      return [geometry.outerRadius * 2, geometry.outerRadius * 2, 0];
+    default:
+      return undefined;
+  }
+};
+
+const scaled = (extent: Vec3, scale: Vec3): Vec3 => [
+  extent[0] * Math.abs(scale[0]),
+  extent[1] * Math.abs(scale[1]),
+  extent[2] * Math.abs(scale[2]),
+];
+
+/** The shape a geometry reference draws: its own, a shared one's, or none (lent). */
+const shapeOf = (
+  geometry: GeometryRef,
+  description: SceneDescription,
+): ShapeGeometry | undefined => {
+  if (geometry._tag === 'LentGeometry') return undefined;
+  if (geometry._tag !== 'SharedGeometry') return geometry;
+  return description.resources.geometries.find((entry) => entry.id === geometry.id)?.geometry;
+};
+
+const sizeOf = (node: SceneNode, description: SceneDescription): Vec3 | null => {
+  if (node._tag !== 'Mesh') return null;
+  const shape = shapeOf(node.geometry, description);
+  const extent = shape === undefined ? undefined : extentOf(shape);
+  return extent === undefined ? null : scaled(extent, node.scale);
+};
+
+const colourOf = (node: SceneNode): Rgb | null =>
+  node._tag === 'Mesh' && 'color' in node.material ? node.material.color : null;
+
+const kindOf = (node: SceneNode): string =>
+  node._tag === 'Mesh' ? `Mesh (${node.geometry._tag})` : node._tag;
+
+const isLight = (node: SceneNode): boolean => node._tag.endsWith('Light');
+
+const lightOf = (node: SceneNode): ReadonlyArray<LightSummary> => {
+  if (!isLight(node) || !('color' in node) || !('intensity' in node)) return [];
+  return [
+    {
+      key: node.key,
+      kind: node._tag,
+      colour: node.color,
+      intensity: node.intensity,
+      position: 'position' in node ? node.position : null,
+    },
+  ];
+};
+
+const thingsIn = (
+  nodes: ReadonlyArray<SceneNode>,
+  parent: string | null,
+  description: SceneDescription,
+): ReadonlyArray<ThingSummary> =>
+  nodes.flatMap((node) => [
+    ...(isLight(node)
+      ? []
+      : [
+          {
+            key: node.key,
+            kind: kindOf(node),
+            position: 'position' in node ? node.position : ([0, 0, 0] as const),
+            size: sizeOf(node, description),
+            colour: colourOf(node),
+            parent,
+          },
+        ]),
+    ...(node._tag === 'Group' ? thingsIn(node.children, node.key, description) : []),
+  ]);
+
+const lightsIn = (nodes: ReadonlyArray<SceneNode>): ReadonlyArray<LightSummary> =>
+  nodes.flatMap((node) => [
+    ...lightOf(node),
+    ...(node._tag === 'Group' ? lightsIn(node.children) : []),
+  ]);
+
+/** The box top-level things of known size fill, each taken as a box round its place. */
+export const thingsBounds = (things: ReadonlyArray<ThingSummary>): Box | null => {
+  const sized = things.filter((thing) => thing.parent === null && thing.size !== null);
+  if (sized.length === 0) return null;
+  const edge = (axis: 0 | 1 | 2, sign: 1 | -1): ReadonlyArray<number> =>
+    sized.map((thing) => thing.position[axis] + sign * ((thing.size?.[axis] ?? 0) / 2));
+  const low = (axis: 0 | 1 | 2) => Math.min(...edge(axis, -1));
+  const high = (axis: 0 | 1 | 2) => Math.max(...edge(axis, 1));
+  return { min: [low(0), low(1), low(2)], max: [high(0), high(1), high(2)] };
+};
+
+const stagingOf = (description: SceneDescription): ReadonlyArray<string> => [
+  ...(description.environment === null ? [] : ['environment lighting']),
+  ...(description.sky === null ? [] : ['sky']),
+  ...(description.render.shadows === 'off' ? [] : [`${description.render.shadows} shadows`]),
+  ...(description.contactShadows === null ? [] : ['contact shadows']),
+  ...description.render.effects.map((effect) => effect._tag.toLowerCase()),
+  ...(description.physics === null ? [] : ['physics']),
+];
+
+/** What `description` contains, for an assistant to read. */
+export const describeScene = (description: SceneDescription): SceneSummary => {
+  const things = thingsIn(description.children, null, description);
+  return {
+    camera: {
+      kind: description.camera._tag,
+      position: description.camera.position,
+      lookAt: description.camera.lookAt,
+    },
+    things,
+    lights: lightsIn(description.children),
+    bounds: thingsBounds(things),
+    staging: stagingOf(description),
+  };
+};
+
+const number = (value: number): string => String(Math.round(value * 100) / 100);
+const point = (at: Vec3): string => `(${at.map(number).join(', ')})`;
+const hex = (colour: Rgb): string => `#${colour.toString(16).padStart(6, '0')}`;
+
+const thingLine = (thing: ThingSummary): string =>
+  [
+    `- ${thing.key}: ${thing.kind}`,
+    thing.size === null ? '' : `, ${thing.size.map(number).join(' × ')}`,
+    thing.colour === null ? '' : `, ${hex(thing.colour)}`,
+    `, at ${point(thing.position)}`,
+    thing.parent === null ? '' : ` in ${thing.parent}`,
+  ].join('');
+
+const lightLine = (light: LightSummary): string =>
+  `- ${light.key}: ${light.kind}, ${hex(light.colour)} × ${number(light.intensity)}${
+    light.position === null ? '' : ` at ${point(light.position)}`
+  }`;
+
+/** The summary as a few lines of text, for a prompt or a tool's answer. */
+export const formatSummary = (summary: SceneSummary): string =>
+  [
+    `Camera: ${summary.camera.kind.toLowerCase()} at ${point(summary.camera.position)}, looking at ${point(summary.camera.lookAt)}`,
+    `Things (${summary.things.length})${
+      summary.bounds === null
+        ? ''
+        : `, within ${point(summary.bounds.min)} to ${point(summary.bounds.max)}`
+    }:`,
+    ...summary.things.map(thingLine),
+    `Lights (${summary.lights.length}):`,
+    ...summary.lights.map(lightLine),
+    `Staging: ${summary.staging.length === 0 ? 'none' : summary.staging.join(', ')}`,
+  ].join('\n');