Implement custom portrait generation: update API, UI, and localization to support user-defined prompts for portraits, replacing half-body option with custom variant.

src/HSchool.Server/Game/PortraitService.cs

@@ -9,6 +9,8 @@ internal sealed class PortraitService(
     GameCommandQueue commands,
     ILogger<PortraitService> logger)
 {
+    public const int MaxCustomPromptLength = 2000;
+
     private static readonly TimeSpan PersonLookupTimeout = TimeSpan.FromSeconds(5);
 
     /// <summary>English labels for Swarm prompts, independent of the UI locale.</summary>
@@ -16,13 +18,20 @@ internal sealed class PortraitService(
 
     public bool IsGenerationEnabled => swarm.IsConfigured;
 
-    public (bool HasAvatar, bool HasHalfBody, bool HasFullBody) Flags(int schoolId, string personId) =>
+    public (bool HasAvatar, bool HasCustom, bool HasFullBody) Flags(int schoolId, string personId) =>
         store.PortraitFlags(schoolId, personId);
 
     public PersonCardResponse WithPortraitFlags(int schoolId, PersonCardResponse card)
     {
-        var (hasAvatar, hasHalfBody, hasFullBody) = Flags(schoolId, card.Id);
-        return card with { HasAvatar = hasAvatar, HasHalfBody = hasHalfBody, HasFullBody = hasFullBody };
+        var (hasAvatar, hasCustom, hasFullBody) = Flags(schoolId, card.Id);
+        var customPrompt = hasCustom ? store.TryReadCustomPortraitPrompt(schoolId, card.Id) : null;
+        return card with
+        {
+            HasAvatar = hasAvatar,
+            HasCustom = hasCustom,
+            HasFullBody = hasFullBody,
+            CustomPortraitPrompt = customPrompt,
+        };
     }
 
     public async Task<PersonLookupError> EnsurePersonAsync(
@@ -45,6 +54,7 @@ internal sealed class PortraitService(
         int schoolId,
         string personId,
         PortraitKind kind,
+        string? promptExtra,
         CancellationToken cancellationToken)
     {
         if (!swarm.IsConfigured)
@@ -52,6 +62,20 @@ internal sealed class PortraitService(
             return PortraitGenerationResult.NotConfigured;
         }
 
+        if (kind == PortraitKind.Custom)
+        {
+            promptExtra = promptExtra?.Trim();
+            if (string.IsNullOrWhiteSpace(promptExtra))
+            {
+                return PortraitGenerationResult.InvalidPrompt;
+            }
+
+            if (promptExtra.Length > MaxCustomPromptLength)
+            {
+                return PortraitGenerationResult.InvalidPrompt;
+            }
+        }
+
         var command = new GameCommand.GetPerson(
             schoolId,
             personId,
@@ -70,14 +94,20 @@ internal sealed class PortraitService(
             return PortraitGenerationResult.UnknownSchool;
         }
 
-        var (positive, negative) = PortraitPromptBuilder.Build(outcome.Card, settings, kind);
+        var (positive, negative) = PortraitPromptBuilder.Build(outcome.Card, settings, kind, promptExtra);
 
         try
         {
             var bytes = await swarm.GenerateAsync(positive, negative, settings, kind, cancellationToken);
-            store.SavePortrait(schoolId, personId, kind, bytes);
+            store.SavePortrait(schoolId, personId, kind, bytes, kind == PortraitKind.Custom ? promptExtra : null);
             var flags = Flags(schoolId, personId);
-            return PortraitGenerationResult.Succeeded(kind, flags.HasAvatar, flags.HasHalfBody, flags.HasFullBody);
+            var savedPrompt = kind == PortraitKind.Custom ? promptExtra : store.TryReadCustomPortraitPrompt(schoolId, personId);
+            return PortraitGenerationResult.Succeeded(
+                kind,
+                flags.HasAvatar,
+                flags.HasCustom,
+                flags.HasFullBody,
+                savedPrompt);
         }
         catch (TaskCanceledException ex) when (!cancellationToken.IsCancellationRequested)
         {
@@ -106,6 +136,7 @@ internal enum PortraitGenerationOutcome
     UnknownSchool,
     UnknownPerson,
     NotConfigured,
+    InvalidPrompt,
     Unavailable,
     TimedOut,
 }
@@ -114,26 +145,42 @@ internal sealed record PortraitGenerationResult(
     PortraitGenerationOutcome Outcome,
     PortraitKind Kind,
     bool HasAvatar,
-    bool HasHalfBody,
-    bool HasFullBody)
+    bool HasCustom,
+    bool HasFullBody,
+    string? CustomPortraitPrompt)
 {
     public static PortraitGenerationResult UnknownSchool { get; } =
-        new(PortraitGenerationOutcome.UnknownSchool, default, false, false, false);
+        new(PortraitGenerationOutcome.UnknownSchool, default, false, false, false, null);
 
     public static PortraitGenerationResult UnknownPerson { get; } =
-        new(PortraitGenerationOutcome.UnknownPerson, default, false, false, false);
+        new(PortraitGenerationOutcome.UnknownPerson, default, false, false, false, null);
 
     public static PortraitGenerationResult NotConfigured { get; } =
-        new(PortraitGenerationOutcome.NotConfigured, default, false, false, false);
+        new(PortraitGenerationOutcome.NotConfigured, default, false, false, false, null);
+
+    public static PortraitGenerationResult InvalidPrompt { get; } =
+        new(PortraitGenerationOutcome.InvalidPrompt, default, false, false, false, null);
 
     public static PortraitGenerationResult Unavailable { get; } =
-        new(PortraitGenerationOutcome.Unavailable, default, false, false, false);
+        new(PortraitGenerationOutcome.Unavailable, default, false, false, false, null);
 
     public static PortraitGenerationResult TimedOut { get; } =
-        new(PortraitGenerationOutcome.TimedOut, default, false, false, false);
+        new(PortraitGenerationOutcome.TimedOut, default, false, false, false, null);
 
-    public static PortraitGenerationResult Succeeded(PortraitKind kind, bool hasAvatar, bool hasHalfBody, bool hasFullBody) =>
-        new(PortraitGenerationOutcome.Succeeded, kind, hasAvatar, hasHalfBody, hasFullBody);
+    public static PortraitGenerationResult Succeeded(
+        PortraitKind kind,
+        bool hasAvatar,
+        bool hasCustom,
+        bool hasFullBody,
+        string? customPortraitPrompt) =>
+        new(PortraitGenerationOutcome.Succeeded, kind, hasAvatar, hasCustom, hasFullBody, customPortraitPrompt);
 }
 
-internal sealed record PortraitResponse(string Kind, bool HasAvatar, bool HasHalfBody, bool HasFullBody);
+internal sealed record GeneratePortraitRequest(string? PromptExtra);
+
+internal sealed record PortraitResponse(
+    string Kind,
+    bool HasAvatar,
+    bool HasCustom,
+    bool HasFullBody,
+    string? CustomPortraitPrompt);