Create Instruction

Segment animator

The segment animator is a curried function: (instr) => (init, who) => Segment[].

import { type SegmentAnimator } from "./_segment";

export const fooSegments =
  (instr: FooInstruction): SegmentAnimator =>
  (init, who) => {
    // Optional: pre-compute partner lookups, assert formation validity
    return [
      {
        dur: instr.beats,
        position: ...,  // omit = stay put
        facing: ...,    // omit = keep current facing
        hands: ...,     // omit = leave hands unchanged
        labels: ...,    // omit = leave labels unchanged
      },
    ];
  };

Key imports by need

Position primitives

• arc(cid, { semiMinor, phi }) — Elliptical path from dancer to partner. phi: PI = swap positions. semiMinor sign controls curve direction (typically ±0.25).
• orbit(cid, { radians }) — Circular orbit around midpoint with partner.
• linearTo(targetFn) — Straight-line interpolation to target position.
• Custom: (id, frac, segInit) => Vector — full control over position.

Facing primitives

• lerpFacingTo(targetFn) — Shortest-arc interpolation to target facing.
• rotateFacingBy(radiansFn) — Rotate by fixed radians. radiansFn receives id, can vary by role.
• Omit — Facing stays at segment-initial value.

Hand primitives

• hold(hand, cid, theirHand) — Hold one hand pair throughout.
• holdByRole({ lark: [h, cid, th], robin: [h, cid, th] }) — Role-dependent hands.
• holdUntil(threshold, hand, cid, theirHand) — Hold until frac, then disconnect.
• disconnect() — Remove all hand connections.
• Custom: (frac) => Partial<Record<Hand, DancerHandPointer | undefined>> — return hand pointers directly (e.g. { left: { theirId: matchId, theirHand: "left" } }).

Pre-computing partners

When you need role-filtered or direction-based partner lookups (which can't use the arc/hold primitives that take a cid), resolve them in the plan function from the Dancer:

export function planFoo(dancer: Dancer): DancerSegment[] {
  const partner = dancer.findDancerInDirection(
    dancer.resolvePureDirection("on_right"),
    { roles: "different" },
  );
  if (!partner) throw new SnazzyError([{ dancerId: dancer.id }, " has no partner for foo"]);
  return [{
    dur: instr.beats,
    position: (frac) => lerpVectors(dancer.pos, partner.pos, frac),
    hands: () => ({ right: { theirId: partner.id, theirHand: "left" } }),
  }];
}

2. Register in src/instructions/_atomic.ts

Add three things:

// 1. Import
import { FooInstructionSchema, fooSegments } from "./foo";

// 2. Add to AtomicInstructionSchema discriminated union (alphabetical order)
export const AtomicInstructionSchema = z.discriminatedUnion("type", [
  // ...existing...
  FooInstructionSchema,
  // ...existing...
]);

// 3. Add case to makeAtomicInstructionSegments switch (alphabetical order)
export function makeAtomicInstructionSegments(...) {
  switch (instr.type) {
    // ...existing...
    case "foo":
      return fooSegments(instr, init, who);
    // ...existing...
  }
}

3. Field component: src/components/fields/FooFields.tsx

import type { AtomicInstruction } from "../../instructions/_atomic";
import { InstructionSchema } from "../../instructions/index";
import type { SubFormProps } from "../fieldUtils";

export function FooFields({
  instruction,
  onChange,
  onInvalid,
}: SubFormProps & {
  instruction: Extract<AtomicInstruction, { type: "foo" }>;
}) {
  const { id } = instruction;

  function tryCommit(overrides: Record<string, unknown>) {
    const raw = {
      id,
      type: "foo",
      beats: instruction.beats,
      // spread all instruction-specific fields as defaults
      ...overrides,
    };
    const result = InstructionSchema.safeParse(raw);
    if (result.success) onChange(result.data);
    else onInvalid?.();
  }

  return (
    <>
      {/* Use <InlineDropdown> and <InlineNumber> for editable fields */}
      {/* Use <CalledIdentifierDropdown> for cid fields */}
      {/* Use <CardinalDirectionDropdown> for endFacing fields */}
    </>
  );
}

Available UI components: InlineDropdown (from ../InlineDropdown), InlineNumber (from ../InlineNumber), CalledIdentifierDropdown (from ../CalledIdentifierDropdown), CardinalDirectionDropdown (from ../CardinalDirectionDropdown).

Common field option constants from ../fieldUtils: ROLE_OPTIONS, HAND_OPTIONS, TAKE_HAND_OPTIONS.

4. Wire into src/components/CommandPane.tsx

Four changes:

4a. Import the field component

import { FooFields } from "./fields/FooFields";

4b. Add to ACTION_OPTIONS array and ACTION_LABELS object

const ACTION_OPTIONS: ActionOptionType[] = [
  // ...existing...
  "foo",
  // ...
];
const ACTION_LABELS: Record<string, string> = {
  // ...existing...
  foo: "foo",
};

4c. Add to doesRequireBeatsInput switch

Return true if the user should be able to edit beats in the UI, false for zero-beat instructions like relabel or drop_hands.

4d. Add render case to the instruction fields switch

case "foo":
  return <FooFields {...common} instruction={instruction} />;

5. Wire into src/components/fieldUtils.ts

Add a case to makeDefaultInstruction:

case "foo":
  return {
    id,
    type: "foo",
    // provide sensible defaults for all fields
  };

Verification

After all changes:

1. npx tsc --noEmit — must pass with no errors
2. npm run test — must pass with no regressions
3. npm run format && npm run lint -- --fix && npm run typecheck