Mechanism

When to useCopy Anchor Link

• The user asks how a machine or mechanism works and seeing it move helps: "how does a jet engine work?", "how does a drip coffee maker work?", "how does a gearbox reduce speed?".
• The user wants a 3D figure of a physical object, device or building they'd recognise: "the Empire State Building in 3D", "a 3D model of an active speaker".
• An idea is easiest to grasp as a physical mechanism: a reduction, a pump, a flow from one part to another.

When not to useCopy Anchor Link

• What it's made of matters more than how it moves. Use a Part Diagram, an exploded view by system.
• The parts are abstract (services, teams, steps). Use the Relationship Explorer or a Timeline.
• A sentence answers it, or the user wants a photo.
• Its shape is organic (a person, an animal, a plant): the figure is built from machined solids.

How the agent should use itCopy Anchor Link

• Shape first. The object must be recognisable from its outline alone: its real proportions (the longest side about 200 to 260 units, about a pixel each) and its real orientation. An engine lies along x, a speaker stands with its cones facing +x, a tower stands up along z. x and y are the floor, z is up.
• Show how it works through its outside. When the user asks how something works or what's inside, keep the object closed and set ghost: true on the one casing, cabinet or housing that hides the workings; the parts inside show through it. Don't leave walls off. When the user just wants a 3D model of the thing, draw it solid. A ghost is for what is really enclosed (a drum in a cabinet, an impeller in a casing), not for a speaker's cones, a door or a dial.
• Rings are bored cylinders. A rim, hoop, tyre, fan cage, tube or flange is a cylinder with a bore (a hollow centre), never a solid disc, which would hide what's behind it.
• Turn the front toward +x, the default view: an engine's intake and fan, a speaker's cones, a machine's door and controls.
• Get the ratios right: scale the longest side to 200 to 260 units and derive every other size from the real ratios, so tall things stay tall (the Empire State Building is 3 times taller than its base is wide, the Eiffel Tower 2.6 times).
• Round bodies are cylinders or lathes on their real axis. A nacelle, nozzle, cone, dome, bell, horn or speaker cone is a lathe profile; collars, flanges and bands are steps in that profile, not extra parts; open makes a hollow you see into.
• Detail, not extra parts. Windows on buildings, vents or panels on cases, blades on fans and turbines, ribs for fins, rings for seams between sections, bolts on flanges and hubs.
• Start from the recipe for its kind: buildings as stacked boxes with windows and a spire; vehicles with a body along x and wheels, propellers or rotors as cylinders with blades; towers that taper as lathes with sides: 4, iron towers, pylons and cranes as lattice lathes; open rotors (windmill sails, propellers, wind turbines, helicopter rotors) as rotor parts; appliances as a box with panels, vents and small ribbed controls; fans as a motor, a rotor and a cage of bored rings; engines, pumps and washing machines as a ghost casing or cabinet with the rotor, impeller or drum inside it; instruments and tools as base, column, arm and head; bridges as boxes and pipes. Then add what makes this one recognisable.
• Use 8 to 40 parts, each resting on or joined to another (set z so parts sit on what's under them). No base plate unless the real thing stands on one. The component fits the whole object to the card and picks the card's height from its shape: a tower gets a tall card, an engine a wide one.
• Move only what moves in the real machine, at believable relative speeds. Rotors and fans spin about their own axis. Meshing gears turn opposite ways, their speeds in inverse ratio to their radii, and share a tooth size. Flow runs from a pipe's first point to its last; stream draws only the flow, for air or exhaust in open space. A building has no motion.
• Mark one or two parts as accent: the thing the figure is about.
• Give every part a short label and, for the parts that matter, a one-sentence description.
• Set askable only when you want questions. On explain, answer about that part in text.

InteractionCopy Anchor Link

While streaming, parts appear one at a time and the figure refits as they arrive. The helpers in mechanism-utils.ts (fitView, buildScene, latheGeometry, gearRing, extrude) are pure, so the server can reuse them.

AccessibilityCopy Anchor Link

The figure is hidden from assistive tech; a visually hidden list carries every part with its motion and description, and the arrow keys (and Home/End) move through it, showing each part on the figure. Every control is a labelled button with a tooltip, and view changes and pausing are announced. Motion stops off screen, can be paused at any time, and doesn't play under reduced motion.

CreditCopy Anchor Link

The isometric camera, the extruded solids and their shading are ported from Anatomy (MIT, © 2026 Ryan), and so are its drawing rules: round parts as lathe profiles on any axis, many small purposeful details, one lit accent. Anatomy is a Claude Code skill that writes a bespoke figure for each idea; Mechanism keeps the drawing but takes the object as data, so an agent can produce one at runtime within a fixed contract.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/mechanism.json

UsageCopy Anchor Link

import { tool } from "ai"
import { mechanismTool } from "@/components/genui/mechanism.schema"

const tools = {
  [mechanismTool.name]: tool({
    description: mechanismTool.description,
    inputSchema: mechanismTool.inputSchema,
  }),
}

Without askable the figure is the whole answer, so give the tool an execute that returns immediately. With askable, the agent receives:

{ action: "explain", partId: "hot-water" }

Reviewing a figureCopy Anchor Link

The schema accepts figures that still read wrong. reviewMechanism(parts) in mechanism-utils.ts checks a finished figure and returns notes:

• parts floating apart from the object;
• parts hidden entirely inside a solid;
• an object far from the 200 to 260 units the drawing is tuned for;
• no surface detail;
• fewer than 6 parts;
• more than two accents;
• a solid disc over a fan or rotor, hiding its blades;
• more than two ghosts.

The figure still renders. A host can send reviewMessage(notes) back as the tool's result once, and the model redraws if the notes are right:

import { reviewMechanism, reviewMessage } from "@/components/genui/mechanism-utils"

const tools = {
  [mechanismTool.name]: tool({
    description: mechanismTool.description,
    inputSchema: mechanismTool.inputSchema,
    // The notes, or a plain acknowledgement: the model may call show_mechanism again.
    execute: async (input) => reviewMessage(reviewMechanism(input.parts)) ?? "Shown.",
  }),
}

Showing the model its figureCopy Anchor Link

The agent writes coordinates without seeing the result. mechanismSvg(parts) in mechanism-svg.ts draws the figure as a standalone SVG string: the light theme, at rest, from the front and turned 90°, side by side. Rasterize it on the server (for example with @resvg/resvg-js) and return it with lookMessage(title, notes) as the tool's result. The model compares the figure with the real object and redraws it if it reads wrong. This costs one more model turn per figure, plus about 1,500 input tokens for the image.

import { Resvg } from "@resvg/resvg-js"
import { lookMessage, mechanismSvg } from "@/components/genui/mechanism-svg"
import { reviewMechanism } from "@/components/genui/mechanism-utils"

const svg = mechanismSvg(input.parts)
const png = svg && new Resvg(svg, { fitTo: { mode: "width", value: 1280 } }).render().asPng()
const content = png && [
  { type: "image", source: { type: "base64", media_type: "image/png", data: Buffer.from(png).toString("base64") } },
  { type: "text", text: lookMessage(input.title, reviewMechanism(input.parts)) },
]

Keep the image out of the transcript you store, since it would be resent on every later turn.

Restoring from historyCopy Anchor Link

Pass the stored tool output as result. The component restores the inspected part, locks the question, and never calls onResult again:

<Mechanism
  {...part.input}
  result={part.state === "output-available" ? part.output : undefined}
/>

SchemaCopy Anchor Link

A part's shape is one of:

• { type: "box", x, y, z?, w, d, h, r?, pattern? }: centred on (x, y); r rounds the floor corners; h: 0 is a flat plate. pattern is windows, vents or panels, drawn on the visible sides.
• { type: "cylinder", x, y, z?, r, h, axis?, bore?, ...detail }: (x, y, z) is the centre of the starting face; h is the length along axis (x, y or z, default z). bore is the radius of a hole through the centre: the ends become rings and you see into it.
• { type: "lathe", x, y, z?, axis?, profile: [s, r][], open?, ...detail }: a half-section turned around the axis from (x, y, z). 2 to 24 points of distance along the axis (0 to 800) and radius (0 to 400); two points at the same s make a shoulder, r: 0 closes an end to a point. open leaves the ends off so you see inside.
• { type: "rotor", x, y, z?, axis?, r, blades, chord? }: flat blades from a hub at (x, y, z), turning about axis, with open air between them; chord is the blade width as a fraction of r (default 0.15). Spin turns it; a rotor is drawn behind or in front of other parts by the side of its plane.
• { type: "gear", x, y, z?, r, h, teeth? }: a spur gear lying flat; r is to the tooth tips.
• { type: "pipe", points: [x, y, z][], r?, stream? }: 2 to 24 points along the centre line; r defaults to 3 (0.1 to 20, so a thin cable can be 0.2). stream draws only the flow, no tube.

Round parts take the same detail fields: ribs (3 to 64 lines along the body), rings (up to 12 seams at distances along the axis), blades (2 to 48 vanes on the far end face) and bolts (3 to 36 on that face). sides (3 to 12) makes the body faceted instead of round: a square tower, pyramid or hex nut. lattice draws it as an open truss you see through: legs at the corners, a ring at each profile point and X-bracing on every face.

A part can also be ghost: true, drawn as a see-through shell so the parts inside it show, and accent: true. Slender members that don't run along an axis (a connecting rod, strut, boom, brace, arm, cable) are pipe parts with no motion or flow, which draw as solid rods.

A part's motion is one of { type: "spin", speed } (turns a second, −3 to 3, positive counter-clockwise seen from above), { type: "flow", speed? } (pipes only) or { type: "slide", by: [dx, dy, dz], seconds? }.

Host props: status (streaming, ready, submitted), onResult, result and className.

SourceCopy Anchor Link