Add computePotAim query and shot-simulation operations

Schema: computePotAim(simulationInput, targetBallId, pocket) ->
PotAimGQL, the spin/throw-compensated aim solver (regenerated from
backend strawberry definitions; reuses the existing PocketIdentifier
enum). Operations: GetTableState, SimulateShot, and ComputePotAim
documents so both clients get generated hooks.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/index.tsx

@@ -88,6 +88,12 @@ export type AppleIapSubscriptionOptionsGql = {
   productIds: Array<Scalars["String"]["output"]>;
 };
 
+export type BallTrajectoryGql = {
+  __typename?: "BallTrajectoryGQL";
+  ballId: Scalars["Int"]["output"];
+  points: Array<TrajectoryPointGql>;
+};
+
 export type BankFeaturesGql = {
   __typename?: "BankFeaturesGQL";
   bankAngle: Scalars["Float"]["output"];
@@ -268,6 +274,14 @@ export type CueObjectFeaturesGql = {
   spinType?: Maybe<SpinTypeEnum>;
 };
 
+export type CueStrikeInputGql = {
+  a?: Scalars["Float"]["input"];
+  b?: Scalars["Float"]["input"];
+  phi: Scalars["Float"]["input"];
+  theta?: Scalars["Float"]["input"];
+  v0: Scalars["Float"]["input"];
+};
+
 export type DateRangeFilter = {
   greaterThan?: InputMaybe<Scalars["Date"]["input"]>;
   greaterThanEqualTo?: InputMaybe<Scalars["Date"]["input"]>;
@@ -2830,6 +2844,18 @@ export type PocketingIntentionInfoGql = {
   pocketId: PocketIdentifier;
 };
 
+export type PotAimGql = {
+  __typename?: "PotAimGQL";
+  converged: Scalars["Boolean"]["output"];
+  cutAngle: Scalars["Float"]["output"];
+  feasible: Scalars["Boolean"]["output"];
+  geometricPhi: Scalars["Float"]["output"];
+  occludingBallIds: Array<Scalars["Int"]["output"]>;
+  phi: Scalars["Float"]["output"];
+  potted: Scalars["Boolean"]["output"];
+  requiredPrecision: Scalars["Float"]["output"];
+};
+
 export type ProcessingFailedErr = {
   __typename?: "ProcessingFailedErr";
   processing: VideoProcessingGql;
@@ -2851,6 +2877,7 @@ export type Query = {
   challenge?: Maybe<Challenge>;
   challengeLeaderboard: Array<ChallengeEntry>;
   challenges: Array<Challenge>;
+  computePotAim: PotAimGql;
   doesUsernameExist: Scalars["Boolean"]["output"];
   getAggregatedShotMetrics: Array<AggregateResultGql>;
   getAppleAppAccountToken: Scalars["String"]["output"];
@@ -2893,6 +2920,7 @@ export type Query = {
   myVideoExports: Array<VideoExportJobGql>;
   notifications: NotificationConnection;
   ruleSets: Array<RuleSet>;
+  simulateShot: ShotProjectionGql;
   unreadNotificationCount: Scalars["Int"]["output"];
   videoExportJob?: Maybe<VideoExportJobGql>;
   videoPlayerClusters: Array<PlayerClusterGql>;
@@ -2912,6 +2940,12 @@ export type QueryChallengesArgs = {
   includeDismissed?: Scalars["Boolean"]["input"];
 };
 
+export type QueryComputePotAimArgs = {
+  pocket: PocketIdentifier;
+  simulationInput: SimulateShotInputGql;
+  targetBallId: Scalars["Int"]["input"];
+};
+
 export type QueryDoesUsernameExistArgs = {
   candidateUsername: Scalars["String"]["input"];
 };
@@ -3082,6 +3116,10 @@ export type QueryNotificationsArgs = {
   offset?: Scalars["Int"]["input"];
 };
 
+export type QuerySimulateShotArgs = {
+  simulationInput: SimulateShotInputGql;
+};
+
 export type QueryVideoExportJobArgs = {
   jobId: Scalars["Int"]["input"];
 };
@@ -3345,6 +3383,14 @@ export type ShotMoveInput = {
   shotId: Scalars["Int"]["input"];
 };
 
+export type ShotProjectionGql = {
+  __typename?: "ShotProjectionGQL";
+  events: Array<SimulationEventGql>;
+  finalState: Array<SimulationBallStateGql>;
+  pottedBallIds: Array<Scalars["Int"]["output"]>;
+  trajectories: Array<BallTrajectoryGql>;
+};
+
 export type ShotsOrderingComponent =
   | {
       difficulty: FloatOrdering;
@@ -3395,6 +3441,42 @@ export type ShotsOrderingComponent =
       videoId: IntOrdering;
     };
 
+export type SimulateShotInputGql = {
+  b64Image?: InputMaybe<Scalars["String"]["input"]>;
+  balls?: InputMaybe<Array<SimulationBallStateInputGql>>;
+  cueBallId: Scalars["Int"]["input"];
+  strike: CueStrikeInputGql;
+  tableSize?: InputMaybe<Scalars["Float"]["input"]>;
+  useHomography?: InputMaybe<HomographyInputGql>;
+};
+
+export type SimulationBallStateGql = {
+  __typename?: "SimulationBallStateGQL";
+  ballId: Scalars["Int"]["output"];
+  position: Array<Scalars["Float"]["output"]>;
+};
+
+export type SimulationBallStateInputGql = {
+  ballId: Scalars["Int"]["input"];
+  position: Array<Scalars["Float"]["input"]>;
+};
+
+export type SimulationEventGql = {
+  __typename?: "SimulationEventGQL";
+  ballIds: Array<Scalars["Int"]["output"]>;
+  eventType: SimulationEventType;
+  position?: Maybe<Array<Scalars["Float"]["output"]>>;
+  time: Scalars["Float"]["output"];
+};
+
+export enum SimulationEventType {
+  BallBall = "BALL_BALL",
+  BallCushion = "BALL_CUSHION",
+  BallPocket = "BALL_POCKET",
+  BallStop = "BALL_STOP",
+  StickBall = "STICK_BALL",
+}
+
 export type SpinTypeBreakdownGql = {
   __typename?: "SpinTypeBreakdownGQL";
   center: Scalars["Int"]["output"];
@@ -3571,6 +3653,12 @@ export type TooManyProfileImageUploadsErr = {
   linksRequested: Scalars["Int"]["output"];
 };
 
+export type TrajectoryPointGql = {
+  __typename?: "TrajectoryPointGQL";
+  position: Array<Scalars["Float"]["output"]>;
+  time: Scalars["Float"]["output"];
+};
+
 export type UpdateAnnotationInputGql = {
   name: Scalars["String"]["input"];
   notes?: InputMaybe<Scalars["String"]["input"]>;
@@ -5472,6 +5560,74 @@ export type FinalizePlayerAssignmentsMutation = {
   }>;
 };
 
+export type GetTableStateQueryVariables = Exact<{
+  b64Image: Scalars["String"]["input"];
+  tableSize?: InputMaybe<Scalars["Float"]["input"]>;
+  useHomography?: InputMaybe<HomographyInputGql>;
+}>;
+
+export type GetTableStateQuery = {
+  __typename?: "Query";
+  getTableState: {
+    __typename?: "TableStateGQL";
+    identifierToPosition: Array<Array<number>>;
+  };
+};
+
+export type SimulateShotQueryVariables = Exact<{
+  simulationInput: SimulateShotInputGql;
+}>;
+
+export type SimulateShotQuery = {
+  __typename?: "Query";
+  simulateShot: {
+    __typename?: "ShotProjectionGQL";
+    pottedBallIds: Array<number>;
+    trajectories: Array<{
+      __typename?: "BallTrajectoryGQL";
+      ballId: number;
+      points: Array<{
+        __typename?: "TrajectoryPointGQL";
+        time: number;
+        position: Array<number>;
+      }>;
+    }>;
+    events: Array<{
+      __typename?: "SimulationEventGQL";
+      eventType: SimulationEventType;
+      time: number;
+      ballIds: Array<number>;
+      position?: Array<number> | null;
+    }>;
+    finalState: Array<{
+      __typename?: "SimulationBallStateGQL";
+      ballId: number;
+      position: Array<number>;
+    }>;
+  };
+};
+
+export type ComputePotAimQueryVariables = Exact<{
+  simulationInput: SimulateShotInputGql;
+  targetBallId: Scalars["Int"]["input"];
+  pocket: PocketIdentifier;
+}>;
+
+export type ComputePotAimQuery = {
+  __typename?: "Query";
+  computePotAim: {
+    __typename?: "PotAimGQL";
+    phi: number;
+    geometricPhi: number;
+    cutAngle: number;
+    requiredPrecision: number;
+    feasible: boolean;
+    potted: boolean;
+    converged: boolean;
+    occludingBallIds: Array<number>;
+  };
+};
+
 export type GetSerializedShotPathsQueryVariables = Exact<{
   filterInput: FilterInput;
 }>;
@@ -11731,6 +11887,269 @@ export type FinalizePlayerAssignmentsMutationOptions =
     FinalizePlayerAssignmentsMutation,
     FinalizePlayerAssignmentsMutationVariables
   >;
+export const GetTableStateDocument = gql`
+  query GetTableState(
+    $b64Image: String!
+    $tableSize: Float
+    $useHomography: HomographyInputGQL
+  ) {
+    getTableState(
+      b64Image: $b64Image
+      tableSize: $tableSize
+      useHomography: $useHomography
+    ) {
+      identifierToPosition
+    }
+  }
+`;
+
+/**
+ * __useGetTableStateQuery__
+ *
+ * To run a query within a React component, call `useGetTableStateQuery` and pass it any options that fit your needs.
+ * When your component renders, `useGetTableStateQuery` returns an object from Apollo Client that contains loading, error, and data properties
+ * you can use to render your UI.
+ *
+ * @param baseOptions options that will be passed into the query, supported options are listed on: https://www.apollographql.com/docs/react/api/react-hooks/#options;
+ *
+ * @example
+ * const { data, loading, error } = useGetTableStateQuery({
+ *   variables: {
+ *      b64Image: // value for 'b64Image'
+ *      tableSize: // value for 'tableSize'
+ *      useHomography: // value for 'useHomography'
+ *   },
+ * });
+ */
+export function useGetTableStateQuery(
+  baseOptions: Apollo.QueryHookOptions<
+    GetTableStateQuery,
+    GetTableStateQueryVariables
+  >,
+) {
+  const options = { ...defaultOptions, ...baseOptions };
+  return Apollo.useQuery<GetTableStateQuery, GetTableStateQueryVariables>(
+    GetTableStateDocument,
+    options,
+  );
+}
+export function useGetTableStateLazyQuery(
+  baseOptions?: Apollo.LazyQueryHookOptions<
+    GetTableStateQuery,
+    GetTableStateQueryVariables
+  >,
+) {
+  const options = { ...defaultOptions, ...baseOptions };
+  return Apollo.useLazyQuery<GetTableStateQuery, GetTableStateQueryVariables>(
+    GetTableStateDocument,
+    options,
+  );
+}
+export function useGetTableStateSuspenseQuery(
+  baseOptions?: Apollo.SuspenseQueryHookOptions<
+    GetTableStateQuery,
+    GetTableStateQueryVariables
+  >,
+) {
+  const options = { ...defaultOptions, ...baseOptions };
+  return Apollo.useSuspenseQuery<
+    GetTableStateQuery,
+    GetTableStateQueryVariables
+  >(GetTableStateDocument, options);
+}
+export type GetTableStateQueryHookResult = ReturnType<
+  typeof useGetTableStateQuery
+>;
+export type GetTableStateLazyQueryHookResult = ReturnType<
+  typeof useGetTableStateLazyQuery
+>;
+export type GetTableStateSuspenseQueryHookResult = ReturnType<
+  typeof useGetTableStateSuspenseQuery
+>;
+export type GetTableStateQueryResult = Apollo.QueryResult<
+  GetTableStateQuery,
+  GetTableStateQueryVariables
+>;
+export const SimulateShotDocument = gql`
+  query SimulateShot($simulationInput: SimulateShotInputGQL!) {
+    simulateShot(simulationInput: $simulationInput) {
+      trajectories {
+        ballId
+        points {
+          time
+          position
+        }
+      }
+      events {
+        eventType
+        time
+        ballIds
+        position
+      }
+      finalState {
+        ballId
+        position
+      }
+      pottedBallIds
+    }
+  }
+`;
+
+/**
+ * __useSimulateShotQuery__
+ *
+ * To run a query within a React component, call `useSimulateShotQuery` and pass it any options that fit your needs.
+ * When your component renders, `useSimulateShotQuery` returns an object from Apollo Client that contains loading, error, and data properties
+ * you can use to render your UI.
+ *
+ * @param baseOptions options that will be passed into the query, supported options are listed on: https://www.apollographql.com/docs/react/api/react-hooks/#options;
+ *
+ * @example
+ * const { data, loading, error } = useSimulateShotQuery({
+ *   variables: {
+ *      simulationInput: // value for 'simulationInput'
+ *   },
+ * });
+ */
+export function useSimulateShotQuery(
+  baseOptions: Apollo.QueryHookOptions<
+    SimulateShotQuery,
+    SimulateShotQueryVariables
+  >,
+) {
+  const options = { ...defaultOptions, ...baseOptions };
+  return Apollo.useQuery<SimulateShotQuery, SimulateShotQueryVariables>(
+    SimulateShotDocument,
+    options,
+  );
+}
+export function useSimulateShotLazyQuery(
+  baseOptions?: Apollo.LazyQueryHookOptions<
+    SimulateShotQuery,
+    SimulateShotQueryVariables
+  >,
+) {
+  const options = { ...defaultOptions, ...baseOptions };
+  return Apollo.useLazyQuery<SimulateShotQuery, SimulateShotQueryVariables>(
+    SimulateShotDocument,
+    options,
+  );
+}
+export function useSimulateShotSuspenseQuery(
+  baseOptions?: Apollo.SuspenseQueryHookOptions<
+    SimulateShotQuery,
+    SimulateShotQueryVariables
+  >,
+) {
+  const options = { ...defaultOptions, ...baseOptions };
+  return Apollo.useSuspenseQuery<SimulateShotQuery, SimulateShotQueryVariables>(
+    SimulateShotDocument,
+    options,
+  );
+}
+export type SimulateShotQueryHookResult = ReturnType<
+  typeof useSimulateShotQuery
+>;
+export type SimulateShotLazyQueryHookResult = ReturnType<
+  typeof useSimulateShotLazyQuery
+>;
+export type SimulateShotSuspenseQueryHookResult = ReturnType<
+  typeof useSimulateShotSuspenseQuery
+>;
+export type SimulateShotQueryResult = Apollo.QueryResult<
+  SimulateShotQuery,
+  SimulateShotQueryVariables
+>;
+export const ComputePotAimDocument = gql`
+  query ComputePotAim(
+    $simulationInput: SimulateShotInputGQL!
+    $targetBallId: Int!
+    $pocket: PocketIdentifier!
+  ) {
+    computePotAim(
+      simulationInput: $simulationInput
+      targetBallId: $targetBallId
+      pocket: $pocket
+    ) {
+      phi
+      geometricPhi
+      cutAngle
+      requiredPrecision
+      feasible
+      potted
+      converged
+      occludingBallIds
+    }
+  }
+`;
+
+/**
+ * __useComputePotAimQuery__
+ *
+ * To run a query within a React component, call `useComputePotAimQuery` and pass it any options that fit your needs.
+ * When your component renders, `useComputePotAimQuery` returns an object from Apollo Client that contains loading, error, and data properties
+ * you can use to render your UI.
+ *
+ * @param baseOptions options that will be passed into the query, supported options are listed on: https://www.apollographql.com/docs/react/api/react-hooks/#options;
+ *
+ * @example
+ * const { data, loading, error } = useComputePotAimQuery({
+ *   variables: {
+ *      simulationInput: // value for 'simulationInput'
+ *      targetBallId: // value for 'targetBallId'
+ *      pocket: // value for 'pocket'
+ *   },
+ * });
+ */
+export function useComputePotAimQuery(
+  baseOptions: Apollo.QueryHookOptions<
+    ComputePotAimQuery,
+    ComputePotAimQueryVariables
+  >,
+) {
+  const options = { ...defaultOptions, ...baseOptions };
+  return Apollo.useQuery<ComputePotAimQuery, ComputePotAimQueryVariables>(
+    ComputePotAimDocument,
+    options,
+  );
+}
+export function useComputePotAimLazyQuery(
+  baseOptions?: Apollo.LazyQueryHookOptions<
+    ComputePotAimQuery,
+    ComputePotAimQueryVariables
+  >,
+) {
+  const options = { ...defaultOptions, ...baseOptions };
+  return Apollo.useLazyQuery<ComputePotAimQuery, ComputePotAimQueryVariables>(
+    ComputePotAimDocument,
+    options,
+  );
+}
+export function useComputePotAimSuspenseQuery(
+  baseOptions?: Apollo.SuspenseQueryHookOptions<
+    ComputePotAimQuery,
+    ComputePotAimQueryVariables
+  >,
+) {
+  const options = { ...defaultOptions, ...baseOptions };
+  return Apollo.useSuspenseQuery<
+    ComputePotAimQuery,
+    ComputePotAimQueryVariables
+  >(ComputePotAimDocument, options);
+}
+export type ComputePotAimQueryHookResult = ReturnType<
+  typeof useComputePotAimQuery
+>;
+export type ComputePotAimLazyQueryHookResult = ReturnType<
+  typeof useComputePotAimLazyQuery
+>;
+export type ComputePotAimSuspenseQueryHookResult = ReturnType<
+  typeof useComputePotAimSuspenseQuery
+>;
+export type ComputePotAimQueryResult = Apollo.QueryResult<
+  ComputePotAimQuery,
+  ComputePotAimQueryVariables
+>;
 export const GetSerializedShotPathsDocument = gql`
   query GetSerializedShotPaths($filterInput: FilterInput!) {
     getShots(filterInput: $filterInput) {

src/operations/shot_simulation.gql

@@ -0,0 +1,57 @@
+query GetTableState(
+  $b64Image: String!
+  $tableSize: Float
+  $useHomography: HomographyInputGQL
+) {
+  getTableState(
+    b64Image: $b64Image
+    tableSize: $tableSize
+    useHomography: $useHomography
+  ) {
+    identifierToPosition
+  }
+}
+
+query SimulateShot($simulationInput: SimulateShotInputGQL!) {
+  simulateShot(simulationInput: $simulationInput) {
+    trajectories {
+      ballId
+      points {
+        time
+        position
+      }
+    }
+    events {
+      eventType
+      time
+      ballIds
+      position
+    }
+    finalState {
+      ballId
+      position
+    }
+    pottedBallIds
+  }
+}
+
+query ComputePotAim(
+  $simulationInput: SimulateShotInputGQL!
+  $targetBallId: Int!
+  $pocket: PocketIdentifier!
+) {
+  computePotAim(
+    simulationInput: $simulationInput
+    targetBallId: $targetBallId
+    pocket: $pocket
+  ) {
+    phi
+    geometricPhi
+    cutAngle
+    requiredPrecision
+    feasible
+    potted
+    converged
+    occludingBallIds
+  }
+}

src/schema.gql

@@ -66,6 +66,12 @@ type Query {
     tableSize: Float = 100
     useHomography: HomographyInputGQL = null
   ): TableStateGQL!
+  simulateShot(simulationInput: SimulateShotInputGQL!): ShotProjectionGQL!
+  computePotAim(
+    simulationInput: SimulateShotInputGQL!
+    targetBallId: Int!
+    pocket: PocketIdentifier!
+  ): PotAimGQL!
   getOrderedShots(
     filterInput: FilterInput!
     ids: [Int!] = null
@@ -970,6 +976,76 @@ input IntPoint2DInput {
   y: Int!
 }
 
+type ShotProjectionGQL {
+  trajectories: [BallTrajectoryGQL!]!
+  events: [SimulationEventGQL!]!
+  finalState: [SimulationBallStateGQL!]!
+  pottedBallIds: [Int!]!
+}
+
+type BallTrajectoryGQL {
+  ballId: Int!
+  points: [TrajectoryPointGQL!]!
+}
+
+type TrajectoryPointGQL {
+  time: Float!
+  position: [Float!]!
+}
+
+type SimulationEventGQL {
+  eventType: SimulationEventType!
+  time: Float!
+  ballIds: [Int!]!
+  position: [Float!]
+}
+
+enum SimulationEventType {
+  STICK_BALL
+  BALL_BALL
+  BALL_CUSHION
+  BALL_POCKET
+  BALL_STOP
+}
+
+type SimulationBallStateGQL {
+  ballId: Int!
+  position: [Float!]!
+}
+
+input SimulateShotInputGQL {
+  cueBallId: Int!
+  strike: CueStrikeInputGQL!
+  balls: [SimulationBallStateInputGQL!] = null
+  b64Image: String = null
+  useHomography: HomographyInputGQL = null
+  tableSize: Float = null
+}
+
+input CueStrikeInputGQL {
+  v0: Float!
+  phi: Float!
+  theta: Float! = 0
+  a: Float! = 0
+  b: Float! = 0
+}
+
+input SimulationBallStateInputGQL {
+  ballId: Int!
+  position: [Float!]!
+}
+
+type PotAimGQL {
+  phi: Float!
+  geometricPhi: Float!
+  cutAngle: Float!
+  requiredPrecision: Float!
+  feasible: Boolean!
+  potted: Boolean!
+  converged: Boolean!
+  occludingBallIds: [Int!]!
+}
+
 type GetShotsResult {
   shots: [ShotGQL!]!
   count: Int