Add partner placement rotation

Author: tannerlinsley

docs/partner-placement.md

@@ -0,0 +1,70 @@
+# Partner Placement
+
+Partner placement is split into three separate decisions:
+
+- **Eligibility:** whether a partner can appear for a surface, category, library, feature, or user context.
+- **Tier:** the partner's commercial/display tier, which controls visual treatment and relative access to surfaces.
+- **Order:** the sequence used inside a surface once eligible partners are known.
+
+The order policy should be explicit per surface. Avoid treating the partner array order or legacy score as the policy itself.
+
+## Order Strategies
+
+### `static-curated`
+
+Use for surfaces where the order is editorially or commercially curated and should remain stable. These surfaces can preserve the existing order, use partner seniority, or use private commercial priority when seniority is unavailable.
+
+Do not expose private commercial criteria in client-facing field names, comments, or API responses. If a private priority is required, keep the public/client value generic, such as `placementPriority` or an already-resolved ordered list.
+
+### `tier-rotated`
+
+Use for visible partner surfaces where partners in the same tier should cycle over time. Tier order remains fixed, but partners inside the same tier are selected with weighted-random ordering for each page view and surface.
+
+The root loader creates the initial page-view seed, so SSR and hydration receive the same value through loader data. A React provider owns the seed after hydration and refreshes it on client-side page views. Each surface combines its stable surface id with the page-view seed; avoid runtime-generated component ids in the seed because they can diverge across server and client rendering. Partners default to equal probability within their tier; a future `placementWeight` can bias same-tier odds without changing the ordering API.
+
+### `contextual-recommendation`
+
+Use when a surface behaves like a product recommendation or builder suggestion. Product fit should be established before commercial weighting affects order. This strategy currently preserves the legacy tier/priority behavior while giving recommendation surfaces a separate policy label.
+
+### `machine-readable`
+
+Use for AI- or crawler-facing outputs such as `llms.txt` and JSON feeds. These should be deterministic and relevance-first. Do not rotate them merely for logo fairness unless the downstream behavior has been designed and disclosed as such.
+
+## Reserved Rules
+
+Reserved rules should be narrow. For example, Cloudflare is reserved as the first deployment/hosting partner in any list that contains Cloudflare and other deployment partners. That should not imply Cloudflare is globally first across every partner surface; non-deployment partners can still appear before Cloudflare when the surface is mixed-category.
+
+Deployment action buttons are a deployment-only surface. Cloudflare remains first when present. Tier order is still preserved, and providers within the same tier can rotate by page view.
+
+## Current Surfaces
+
+- Partner directory: `tier-rotated` for active partners, `static-curated` for previous partners.
+- Partner grids and embeds: `tier-rotated`.
+- Docs and blog rails: `tier-rotated`.
+- Mobile docs strip: `tier-rotated`.
+- Builder feature picker and starter partner suggestions: `contextual-recommendation`.
+- Deploy action buttons: `tier-rotated` with deployment provider tiers preserved.
+- `llms.txt` and `/api/data/partners`: `machine-readable`.
+
+## Analytics
+
+Partner impression and click events should include:
+
+- `partner_id`
+- `placement`
+- `slot_index`
+- `partner_tier`
+- `order_strategy`
+- `rotation_seed` when the strategy rotates
+
+This lets reporting distinguish partner performance from placement policy and makes under/over-exposure easier to debug.
+
+## Contract Language
+
+Suggested external framing:
+
+> Partner tiers determine eligibility, visual treatment, reporting, and relative access to surfaces. Placement within the same tier may rotate or be curated depending on the surface. Some placements may include explicitly reserved rules for product, infrastructure, legal, or strategic reasons.
+
+For AI-assisted selection:
+
+> AI-assisted partner selection prioritizes user need and capability fit first. Partner tier may influence selection only among qualified options.

src/components/ApplicationStarter.tsx

@@ -12,8 +12,13 @@ import {
 import { twMerge } from 'tailwind-merge'
 import anthropicDarkLogo from '~/images/anthropic-dark.svg'
 import anthropicLightLogo from '~/images/anthropic-light.svg'
+import cloudflareBlackLogo from '~/images/cloudflare-black.svg'
+import cloudflareWhiteLogo from '~/images/cloudflare-white.svg'
+import netlifyDarkLogo from '~/images/netlify-dark.svg'
+import netlifyLightLogo from '~/images/netlify-light.svg'
 import openaiDarkLogo from '~/images/openai-dark.svg'
 import openaiLightLogo from '~/images/openai-light.svg'
+import railwayBlackLogo from '~/images/railway-black.svg'
 import type {
   ApplicationStarterContext,
   ApplicationStarterResult,
@@ -37,6 +42,11 @@ import {
   type StarterTone,
 } from '~/components/application-builder/shared'
 import { useApplicationBuilder } from '~/components/application-builder/useApplicationBuilder'
+import {
+  deploymentProviderIds,
+  type DeploymentProviderId,
+  useDeploymentProviderPlacement,
+} from '~/utils/useDeploymentProviderPlacement'
 import { Button, GitHub } from '~/ui'
 
 export interface ApplicationStarterProps {
@@ -165,6 +175,10 @@ export function ApplicationStarter({
     onResolvedResult,
     suggestionContext,
   })
+  const orderedDeploymentProviders = useDeploymentProviderPlacement({
+    availableProviders: deploymentProviderIds,
+    surface: `application_starter_deploy_actions:${context}`,
+  })
 
   const palette = toneClasses[tone]
   const compact = mode === 'compact'
@@ -201,6 +215,110 @@ export function ApplicationStarter({
     hasInput &&
     !hasMigrationRepositoryUrlError &&
     !isGenerating
+  const renderDeploymentProviderButton = (provider: DeploymentProviderId) => {
+    switch (provider) {
+      case 'cloudflare':
+        return (
+          <Button
+            key={provider}
+            size="md"
+            type="button"
+            onClick={() => {
+              void openDeployDialog('cloudflare')
+            }}
+            disabled={!canUseFinalActions}
+            aria-label="Cloudflare"
+            className="h-[60px] min-w-[196px] border-[#F48120]/50 bg-white px-5 text-gray-950 shadow-sm hover:bg-[#fff7ef] disabled:opacity-80 disabled:saturate-75 dark:border-[#F48120]/70 dark:bg-gray-950 dark:text-white dark:hover:bg-[#2a1808]"
+          >
+            <span className="relative h-7 w-[164px] shrink-0">
+              <img
+                src={cloudflareBlackLogo}
+                alt=""
+                aria-hidden="true"
+                className="h-full w-full object-contain dark:hidden"
+              />
+              <img
+                src={cloudflareWhiteLogo}
+                alt=""
+                aria-hidden="true"
+                className="hidden h-full w-full object-contain dark:block"
+              />
+            </span>
+          </Button>
+        )
+      case 'netlify':
+        return (
+          <Button
+            key={provider}
+            size="md"
+            type="button"
+            onClick={() => void openNetlifyStart()}
+            disabled={!canUseFinalActions}
+            aria-label="Netlify"
+            className="h-11 min-w-[136px] border-gray-200 bg-white px-4 text-gray-700 shadow-sm hover:bg-gray-50 disabled:opacity-65 dark:border-gray-700 dark:bg-gray-900 dark:text-gray-300 dark:hover:bg-gray-800"
+          >
+            {isGeneratingNetlify ? (
+              <Loader2 className="h-5 w-5 animate-spin" />
+            ) : (
+              <span className="relative h-8 w-[78px] shrink-0">
+                <img
+                  src={netlifyLightLogo}
+                  alt=""
+                  aria-hidden="true"
+                  className="h-full w-full object-contain dark:hidden"
+                />
+                <img
+                  src={netlifyDarkLogo}
+                  alt=""
+                  aria-hidden="true"
+                  className="hidden h-full w-full object-contain dark:block"
+                />
+              </span>
+            )}
+          </Button>
+        )
+      case 'railway':
+        return (
+          <Button
+            key={provider}
+            size="md"
+            type="button"
+            onClick={() => {
+              void openDeployDialog('railway')
+            }}
+            disabled={!canUseFinalActions}
+            aria-label="Railway"
+            className="h-[60px] min-w-[174px] border-gray-200 bg-white px-5 text-gray-950 shadow-sm hover:bg-gray-50 disabled:opacity-80 disabled:saturate-75 dark:border-gray-700 dark:bg-white dark:text-gray-950 dark:hover:bg-gray-100"
+          >
+            <span className="relative h-7 w-[132px] shrink-0">
+              <img
+                src={railwayBlackLogo}
+                alt=""
+                aria-hidden="true"
+                className="h-full w-full object-contain"
+              />
+            </span>
+          </Button>
+        )
+    }
+  }
+  const renderGeneratePromptButton = () => (
+    <Button
+      color={buttonColor}
+      variant={hasGeneratedPrompt ? 'secondary' : 'primary'}
+      size="sm"
+      type="button"
+      onClick={() => void generatePrompt()}
+      disabled={!canUseFinalActions}
+    >
+      {isGeneratingPrompt ? (
+        <Loader2 className="h-4 w-4 animate-spin" />
+      ) : (
+        <Wand2 className="h-4 w-4" />
+      )}
+      {isGeneratingPrompt ? loadingPhrase : primaryActionLabel}
+    </Button>
+  )
   const showPostAnalysisSection =
     alwaysShowPostAnalysisSection || hasFreshAnalysis || hasGeneratedPrompt
   const showActionSection =
@@ -769,81 +887,33 @@ export function ApplicationStarter({
                         )}
                       >
                         <div className="flex flex-wrap items-center gap-3">
-                          <Button
-                            color={buttonColor}
-                            variant={
-                              hasGeneratedPrompt ? 'secondary' : 'primary'
-                            }
-                            size="sm"
-                            type="button"
-                            onClick={() => void generatePrompt()}
-                            disabled={!canUseFinalActions}
-                          >
-                            {isGeneratingPrompt ? (
-                              <Loader2 className="h-4 w-4 animate-spin" />
-                            ) : (
-                              <Wand2 className="h-4 w-4" />
-                            )}
-                            {isGeneratingPrompt
-                              ? loadingPhrase
-                              : primaryActionLabel}
-                          </Button>
-
                           {showCliExportActions ? (
-                            <>
-                              <Button
-                                size="sm"
-                                type="button"
-                                onClick={() => {
-                                  void openDeployDialog('cloudflare')
-                                }}
-                                disabled={!canUseFinalActions}
-                                className="border-[#F48120] bg-[#F48120] text-white hover:bg-[#E67210]"
-                              >
-                                <Rocket className="h-4 w-4" />
-                                Deploy to Cloudflare
-                              </Button>
-
-                              <Button
-                                size="sm"
-                                type="button"
-                                onClick={() => void openNetlifyStart()}
-                                disabled={!canUseFinalActions}
-                                className="border-[#00AD9F] bg-[#00AD9F] text-white hover:bg-[#009a8e]"
+                            <div className="flex flex-col gap-1.5">
+                              <div className="px-1 text-[10px] font-medium uppercase tracking-[0.16em] text-gray-400 dark:text-gray-500">
+                                Deploy to
+                              </div>
+                              <div
+                                aria-label="Deploy to"
+                                className="flex flex-wrap items-center gap-2"
+                                role="group"
                               >
-                                {isGeneratingNetlify ? (
-                                  <Loader2 className="h-4 w-4 animate-spin" />
-                                ) : (
-                                  <Rocket className="h-4 w-4" />
+                                {orderedDeploymentProviders.map((provider) =>
+                                  renderDeploymentProviderButton(provider),
                                 )}
-                                {secondaryActionLabel}
-                              </Button>
-
-                              <Button
-                                size="sm"
-                                type="button"
-                                onClick={() => {
-                                  void openDeployDialog('railway')
-                                }}
-                                disabled={!canUseFinalActions}
-                                className="border-[#7C66FF] bg-[#7C66FF] text-white hover:bg-[#6A54F0]"
-                              >
-                                <Rocket className="h-4 w-4" />
-                                Deploy to Railway
-                              </Button>
+                              </div>
 
                               {!showMoreActions ? (
                                 <Button
-                                  variant="secondary"
-                                  size="sm"
+                                  variant="ghost"
+                                  size="xs"
                                   type="button"
                                   onClick={() => setShowMoreActions(true)}
+                                  className="h-auto self-start border-transparent bg-transparent px-1 py-0 text-[11px] font-medium text-gray-500 hover:bg-transparent hover:text-gray-700 dark:text-gray-500 dark:hover:bg-transparent dark:hover:text-gray-300"
                                 >
-                                  <ChevronDown className="h-4 w-4" />
                                   Show More
                                 </Button>
                               ) : null}
-                            </>
+                            </div>
                           ) : (
                             <>
                               <Button
@@ -992,6 +1062,10 @@ export function ApplicationStarter({
                             </Button>
                           </div>
                         ) : null}
+
+                        <div className="flex flex-wrap items-center gap-3">
+                          {renderGeneratePromptButton()}
+                        </div>
                       </div>
                     </div>
                   </CollapsibleContent>