pixelkiln 0.40.0 → 0.41.0

package/dist/index.d.cts

@@ -346,6 +346,21 @@ interface Provider {
     listCharacters?(): AsyncGenerator<RemoteCharacter>;
     /** One character with its rotations and animations. */
     getCharacter?(id: string): Promise<RemoteCharacterDetail>;
+    /**
+     * The object's source URLs as the service hands them out now, for
+     * `fetch --refresh` when recorded URLs go stale (PixelLab stamps a
+     * character's rotation URLs with its last edit time, and a cache may keep
+     * serving an old stamp's bytes). Resolve `null` when the object is gone
+     * upstream and `undefined` for objects whose recorded URLs stay good.
+     */
+    refreshSources?(objectId: string, context: RefreshContext): Promise<OutputSource[] | null | undefined>;
+}
+interface RefreshContext {
+    generator: Generator;
+    /** What the adapter recorded for this entry, under its own namespace. */
+    metadata?: ProviderMetadata;
+    /** The URLs the lockfile holds, in output order. */
+    sources: OutputSource[];
 }
 declare class UnsupportedCapabilityError extends PixelKilnError {
     constructor(providerId: string, capability: string);
@@ -6744,6 +6759,12 @@ declare class PixelLabProvider implements Provider {
     delete(assetId: string): Promise<void>;
     listCharacters(): AsyncGenerator<RemoteCharacter>;
     getCharacter(id: string): Promise<RemoteCharacterDetail>;
+    /**
+     * A character's rotation and frame URLs carry its last edit time as a
+     * cache-buster, so the record's URLs can name bytes a cache still holds
+     * after an edit in PixelLab's editor. Objects keep stable URLs.
+     */
+    refreshSources(objectId: string, context: RefreshContext): Promise<OutputSource[] | null | undefined>;
 }
 
 interface RetroDiffusionOptions {
@@ -7057,6 +7078,8 @@ declare class FakeProvider implements Provider {
     private listImpl;
     listCharacters(): AsyncGenerator<RemoteCharacter>;
     getCharacter(id: string): Promise<RemoteCharacterDetail>;
+    /** Characters answer with whatever the store holds now; other objects keep their URLs. */
+    refreshSources(objectId: string, context: RefreshContext): Promise<OutputSource[] | null | undefined>;
     delete(assetId: string): Promise<void>;
     /** Seed a pre-existing remote asset, for adopt / salvage tests. */
     seed(asset: Partial<RemoteAsset> & {
@@ -10258,6 +10281,8 @@ interface GalleryItem {
     revision: LockEntry["revision"];
     /** Parent lock key for a revision, so the page can link lineage. */
     revisionParentKey: string | null;
+    /** A character family member: what it is, whose it is, and what PixelLab holds for it. */
+    character: GalleryCharacter | null;
     outputs: GalleryOutput[];
     quality: GalleryQuality | null;
     providerMetadata: Record<string, unknown>;
@@ -10297,6 +10322,17 @@ interface GalleryItem {
     tags: string[];
     category: string | null;
 }
+interface GalleryCharacter {
+    kind: "base" | "state" | "animation";
+    /** Lock key of the base or state this is drawn from; null for a base. */
+    parentKey: string | null;
+    mode: string;
+    directions: number;
+    /** Animations only. */
+    direction: string | null;
+    /** Provider-side character id (an animation's is its character's). */
+    characterId: string | null;
+}
 interface GalleryStyle {
     id: string;
     /** Workspace project id, or null for a single-project gallery. */
@@ -10315,6 +10351,12 @@ interface GalleryStyle {
     /** Strip the generated background (sent for pixflux and non-PixelLab providers). */
     noBackground: boolean;
     quality: boolean;
+    /** Family counts for a `character` style; null otherwise. */
+    characters: {
+        bases: number;
+        states: number;
+        animations: number;
+    } | null;
     tags: string[];
     /** Parent style id when this style `extends` one. */
     extends: string | null;
@@ -11738,4 +11780,4 @@ interface WorkspaceStatusReport {
  */
 declare function workspaceStatus(ws: Workspace, dir: string): Promise<WorkspaceStatusReport>;
 
-export { type AdoptResult, type ApproveQualityOptions, type ApprovedQualityReview, type ArtifactBundleManifest, type ArtifactBundleOptions, type ArtifactBundleResult, type ArtifactFile, type ArtifactProvenance, type ArtifactSource, type ArtifactVerification, type Asset, type AssetAudit, AssetSchema, type AtlasSet, type AuditEvaluation, type AuditThresholds, type AuditViolation, type Balance, type BalanceChange, type BalanceInfo, BudgetError, type BuildGalleryOptions, type BuildWorkspaceGalleryOptions, CHARACTER_DIRECTIONS_4, CHARACTER_DIRECTIONS_8, type CacheHealthOptions, type CacheHealthReport, type CandidateSelection, type CharacterAnimation, type CharacterAnimationMode, CharacterAnimationModeSchema, CharacterAnimationSchema$1 as CharacterAnimationSchema, type CharacterDirection, CharacterDirectionSchema, type CharacterMode, CharacterModeSchema, type CharacterState, CharacterStateSchema, type ComfyUIBinding, type ComfyUIBindings, type ComfyUIFramesOptions, type ComfyUIImageInput, type ComfyUIOptions, ComfyUIProvider, type ContentCacheHealth, type ContentCacheIssue, type CostEstimate, type CostUnit, DEFAULT_HISTORY_LIMIT, DEFAULT_QUALITY_TOLERANCES, DEFAULT_RATE_LIMIT, DEFAULT_TIMEOUT_MS, type DoctorCheck, type DoctorLevel, type DoctorOptions, type DoctorReport, EDITOR_PIN, EDITOR_RELEASE_BASE, EXIT_CODES, EditorInstallError, type EditorInstallOptions, type EditorInstallProgress, type EditorInstallResult, type EditorInstallStatus, type EditorPin, type ErrorCode, FAKE_PNG, type FakeOptions, FakeProvider, type FetchResult, type GalleryBuild, type GalleryEditHandlerOptions, type GalleryEditMeta, type GalleryEditorHandlers, type GalleryEditorOptions, type GalleryEditorStatus, type GalleryGenerateHandlers, type GalleryGeneration, type GalleryItem, type GalleryMedia, type GalleryOutput, type GalleryProject, type GalleryProjectContext, type GalleryQuality, type GalleryServer, type GalleryServerOptions, type GallerySnapshot, type GalleryState, type GalleryStyle, type GenerateHandlerOptions, type GenerateJob, type GeneratePhase, GenerateRequestError, GenerateRequestSchema, type GenerateStatus, type Generator, GeneratorSchema, type GenericTileset, type GridConfidence, GridConfidenceSchema, HAND_EDIT_DIR, HISTORY_ENV, type HandEditCompanion, HandEditCompanionSchema, type HandEditMember, type HandEditSave, type HandEditSaveInput, type HandEditStart, type HandEditStatus, type HistoryPick, type ImageQualityMetrics, ImageQualityMetricsSchema, InheritedStyleSchema, type InstallRecipeOptions, type InstallRecipeResult, type JobState, type LoadedManifest, type LoadedRecipe, type Lock, type LockEntry, LockEntrySchema, type LockHistoryEntry, LockHistoryEntrySchema, type LockOutput, LockSchema, MAX_DOWNLOAD_BYTES, MAX_HAND_EDIT_BYTES, MAX_RETRIES, type ManagedArtifactBundleOptions, type Manifest, ManifestDriftError, type ManifestEdit, ManifestEditError, type ManifestEditResult, ManifestEditSchema, ManifestInputSchema, ManifestSchema, type MapObject, MediaType, type MountPlacement, type MountedSheet, type NormalizedTileRules, type OpenProjectOptions, type Orphan, type OrphanGroups, type OutputSelection, type OutputSource, OverwriteRefusedError, PIXEL_ART_FIXER_REVISION, PIXEL_ART_FIXER_URL, type PackedFrame, type PackedSheet, type PackedSource, type PendingQualityReview, type PickResult, type PixelArtFixerDetection, PixelKilnError, type PixelKilnErrorOptions, type PixelLabCharacter, type PixelLabCharacterAnimation, PixelLabClient, PixelLabError, type PixelLabObject, PixelLabProvider, type PixelLabUsage, type Plan, type PlanItem, type PlanState, type PollContext, type PollOptions, type PollResult, type Postprocess, PostprocessSchema, type PrepareReviewOptions, type Project, ProjectError, type Provider, ProviderError, type ProviderFactory, type ProviderInputContext, type ProviderInputScalar, type ProviderInputValue, type ProviderMetadata, type ProviderMode, type ProviderOptionContext, type ProviderSubmission, type QualityBaseline, QualityBaselineSchema, type QualityCheck, type QualityProfile, type QualityProfileInspection, QualityProfileSchema, type QualityProfileState, type QualityRegressionCaseResult, type QualityRegressionReport, type QualitySnapshotResult, QualityToleranceSchema, type QualityTolerances, type RateLimit, type Recipe, type RecipeFileVerification, type RecipeModelVerification, RecipeSchema, type RecipeVerification, type RefineAudit, type RefineFrameSetOptions, type RefineFrameSetResult, type RefineOptions, type RefineQualityProfilesOptions, type RefineQualityProfilesResult, type RefineRecordOptions, type RefineResult, type RemoteAsset, type RemoteCharacter, type RemoteCharacterDetail, type RemoteHashCacheHealth, type RenderGalleryOptions, type RenderSheetOptions, type ResolvedCharacter, type ResolvedOutput, type ResolvedProviderInputs, type ResolvedProviderOptions, type ResolvedQualityInput, type ResolvedQualityProfile, type ResolvedRevision, type ResolvedSpec, type ResolvedStyleImage, type ResumeAction, type ResumeCommand, type RetroDiffusionOptions, RetroDiffusionProvider, type RetryInit, type RetryOptions, type RetryingFetch, type RevertOptions, type RevertResult, type ReviewReadyInfo, type ReviewSession, type Revision, type RevisionMode, RevisionModeSchema, type RevisionReadiness, RevisionSchema, SHEET_FORMATS, type SalvageAction, type SalvageResult, type ScannedAsset, type ScenarioOptions, ScenarioProvider, type SessionBudget, type SheetAtlas, type SheetFormat, type SheetFormatOptions, type SheetGroup, type SiblingManifest, type SpriteInput, type Style, type StyleAudit, type StyleInput, StyleInputSchema, StyleSchema, type SubmissionCheckpoint, type SubmitContext, type SubmitOptions, type SubmitResult, type TilesPro, type TilesetExport, type TilesetExportOptions, type TilesetFormat, UnsupportedCapabilityError, UsageError, type Workspace, type WorkspaceClaims, type WorkspaceDiagnostic, type WorkspaceProject, WorkspaceProjectSchema, type WorkspaceProjectStatus, WorkspaceSchema, type WorkspaceStatusReport, adopt, applyManifestEdit, applyTags, approveQualityRecord, auditStyle, availableProviders, backoffMs, buildGallerySnapshot, buildManifest, buildPlan, buildWorkspaceGallerySnapshot, bundledRecipeRoot, cacheFileName, candidateCount, characterDirections, checkQualityBaseline, checkQualityRecord, clientFromEnv, colorDistance, countNumberedDescriptions, createArtifactBundleManifest, createGalleryEditHandler, createGalleryEditorHandlers, createGenerateHandlers, createProvider, currentEntryOutputPath, currentOutputPath, defaultOpenCommand, detachHandEdit, detectMediaType, doctor, editorBaseUrl, editorDir, editorRoute, editorStatus, editorToolsRoot, errorCode, evaluateAudit, exitCodeFor, expectedOutputPath, exportTileset, fallbackOutputRole, fetchAssets, fetchWithRetry, findOrphans, formatCost, frameSetFps, galleryMediaId, galleryMediaRoute, generationCost, groupOrphansByStyle, handEditBase, handEditBases, handEditCompanionPath, handEditMembers, handEditPath, handEditProjectPath, hex, historyAfterReplacing, historyLimit, idFromPrompt, imageMetadata, inspectCaches, inspectQualityProfile, inspectRevisionReadiness, installEditor, installRecipe, isFrameSetEntry, isMemberSetEntry, isSensitiveSourceUrl, listBundledRecipes, loadClaims, loadLock, loadManifest, loadSiblingManifests, loadWorkspace, lockKey, matchOrphanStyle, measureBalanceChange, measureDecodedImageQuality, measureImageQuality, mediaExtension, mediaTypeFromExtension, memberPath, mergePalettes, mountSprites, mountStyle, normalizeLockOutputPaths, normalizeRefinementPalette, normalizeTileRules, openExternal, openInEditor, openProject, outliers, outputId, packSprites, packStyle, paletteDistance, parentAssetId, parseLock, parseWorkspace, pickHistory, pngSize, poll, portableOutputPath, prepareReview, primaryOutput, providerCredentialEnvs, providerFactory, pushTags, qualityFrameOutputPath, qualityRecordPath, quantizeToPalette, readArtifactBundleManifest, readHandEditCompanion, readQualityBaseline, recipeDigest, referencedHashes, refineAsset, refineFrameSet, refineQualityProfiles, registerProvider, remove, renderAsepriteSheet, renderGallery, renderGodotSpriteFrames, renderSalvageSheet, renderSheet, renderSheetDocument, requireApprovedQualitySources, requireBalance, requireDelete, requireList, requireRevisionReady, requireSelectCandidate, resolveEntryOutputs, resolveOutputPath, resolvePackInputs, resolveProject, resolveQualityInputs, resolveRecipe, resolveSpecEntryOutputs, resolveSpecOutputs, resolveSpecs, resolveStyleImages, resolveStyleOutputs, resumeActions, resumeCommandForStatus, retireGeneration, retryAfterMs, revertGeneration, runPicker, runSalvage, saveHandEdit, saveLock, saveWorkspace, scanAssets, selectEntryOutput, serveGallery, sha256, sha256File, shouldPersistSourceUrl, shouldRetry, slugify, snapshotQualityBaseline, sourceIsStem, sourceOutputPath, specHash, spendByUnit, startHandEdit, styleImagesBase64, submit, summarize, tagAdopted, tileFeatureOutputCount, tileVariationCount, tilesCost, toPortablePath, totalSpend, upsert, validateCostEstimate, validateMedia, validateWorkspace, verifyArtifactBundle, verifyRecipe, withArtifactManifest, workspaceClaims, workspaceStatus, writeArtifactBundle, writeManagedArtifactBundle };
+export { type AdoptResult, type ApproveQualityOptions, type ApprovedQualityReview, type ArtifactBundleManifest, type ArtifactBundleOptions, type ArtifactBundleResult, type ArtifactFile, type ArtifactProvenance, type ArtifactSource, type ArtifactVerification, type Asset, type AssetAudit, AssetSchema, type AtlasSet, type AuditEvaluation, type AuditThresholds, type AuditViolation, type Balance, type BalanceChange, type BalanceInfo, BudgetError, type BuildGalleryOptions, type BuildWorkspaceGalleryOptions, CHARACTER_DIRECTIONS_4, CHARACTER_DIRECTIONS_8, type CacheHealthOptions, type CacheHealthReport, type CandidateSelection, type CharacterAnimation, type CharacterAnimationMode, CharacterAnimationModeSchema, CharacterAnimationSchema$1 as CharacterAnimationSchema, type CharacterDirection, CharacterDirectionSchema, type CharacterMode, CharacterModeSchema, type CharacterState, CharacterStateSchema, type ComfyUIBinding, type ComfyUIBindings, type ComfyUIFramesOptions, type ComfyUIImageInput, type ComfyUIOptions, ComfyUIProvider, type ContentCacheHealth, type ContentCacheIssue, type CostEstimate, type CostUnit, DEFAULT_HISTORY_LIMIT, DEFAULT_QUALITY_TOLERANCES, DEFAULT_RATE_LIMIT, DEFAULT_TIMEOUT_MS, type DoctorCheck, type DoctorLevel, type DoctorOptions, type DoctorReport, EDITOR_PIN, EDITOR_RELEASE_BASE, EXIT_CODES, EditorInstallError, type EditorInstallOptions, type EditorInstallProgress, type EditorInstallResult, type EditorInstallStatus, type EditorPin, type ErrorCode, FAKE_PNG, type FakeOptions, FakeProvider, type FetchResult, type GalleryBuild, type GalleryEditHandlerOptions, type GalleryEditMeta, type GalleryEditorHandlers, type GalleryEditorOptions, type GalleryEditorStatus, type GalleryGenerateHandlers, type GalleryGeneration, type GalleryItem, type GalleryMedia, type GalleryOutput, type GalleryProject, type GalleryProjectContext, type GalleryQuality, type GalleryServer, type GalleryServerOptions, type GallerySnapshot, type GalleryState, type GalleryStyle, type GenerateHandlerOptions, type GenerateJob, type GeneratePhase, GenerateRequestError, GenerateRequestSchema, type GenerateStatus, type Generator, GeneratorSchema, type GenericTileset, type GridConfidence, GridConfidenceSchema, HAND_EDIT_DIR, HISTORY_ENV, type HandEditCompanion, HandEditCompanionSchema, type HandEditMember, type HandEditSave, type HandEditSaveInput, type HandEditStart, type HandEditStatus, type HistoryPick, type ImageQualityMetrics, ImageQualityMetricsSchema, InheritedStyleSchema, type InstallRecipeOptions, type InstallRecipeResult, type JobState, type LoadedManifest, type LoadedRecipe, type Lock, type LockEntry, LockEntrySchema, type LockHistoryEntry, LockHistoryEntrySchema, type LockOutput, LockSchema, MAX_DOWNLOAD_BYTES, MAX_HAND_EDIT_BYTES, MAX_RETRIES, type ManagedArtifactBundleOptions, type Manifest, ManifestDriftError, type ManifestEdit, ManifestEditError, type ManifestEditResult, ManifestEditSchema, ManifestInputSchema, ManifestSchema, type MapObject, MediaType, type MountPlacement, type MountedSheet, type NormalizedTileRules, type OpenProjectOptions, type Orphan, type OrphanGroups, type OutputSelection, type OutputSource, OverwriteRefusedError, PIXEL_ART_FIXER_REVISION, PIXEL_ART_FIXER_URL, type PackedFrame, type PackedSheet, type PackedSource, type PendingQualityReview, type PickResult, type PixelArtFixerDetection, PixelKilnError, type PixelKilnErrorOptions, type PixelLabCharacter, type PixelLabCharacterAnimation, PixelLabClient, PixelLabError, type PixelLabObject, PixelLabProvider, type PixelLabUsage, type Plan, type PlanItem, type PlanState, type PollContext, type PollOptions, type PollResult, type Postprocess, PostprocessSchema, type PrepareReviewOptions, type Project, ProjectError, type Provider, ProviderError, type ProviderFactory, type ProviderInputContext, type ProviderInputScalar, type ProviderInputValue, type ProviderMetadata, type ProviderMode, type ProviderOptionContext, type ProviderSubmission, type QualityBaseline, QualityBaselineSchema, type QualityCheck, type QualityProfile, type QualityProfileInspection, QualityProfileSchema, type QualityProfileState, type QualityRegressionCaseResult, type QualityRegressionReport, type QualitySnapshotResult, QualityToleranceSchema, type QualityTolerances, type RateLimit, type Recipe, type RecipeFileVerification, type RecipeModelVerification, RecipeSchema, type RecipeVerification, type RefineAudit, type RefineFrameSetOptions, type RefineFrameSetResult, type RefineOptions, type RefineQualityProfilesOptions, type RefineQualityProfilesResult, type RefineRecordOptions, type RefineResult, type RefreshContext, type RemoteAsset, type RemoteCharacter, type RemoteCharacterDetail, type RemoteHashCacheHealth, type RenderGalleryOptions, type RenderSheetOptions, type ResolvedCharacter, type ResolvedOutput, type ResolvedProviderInputs, type ResolvedProviderOptions, type ResolvedQualityInput, type ResolvedQualityProfile, type ResolvedRevision, type ResolvedSpec, type ResolvedStyleImage, type ResumeAction, type ResumeCommand, type RetroDiffusionOptions, RetroDiffusionProvider, type RetryInit, type RetryOptions, type RetryingFetch, type RevertOptions, type RevertResult, type ReviewReadyInfo, type ReviewSession, type Revision, type RevisionMode, RevisionModeSchema, type RevisionReadiness, RevisionSchema, SHEET_FORMATS, type SalvageAction, type SalvageResult, type ScannedAsset, type ScenarioOptions, ScenarioProvider, type SessionBudget, type SheetAtlas, type SheetFormat, type SheetFormatOptions, type SheetGroup, type SiblingManifest, type SpriteInput, type Style, type StyleAudit, type StyleInput, StyleInputSchema, StyleSchema, type SubmissionCheckpoint, type SubmitContext, type SubmitOptions, type SubmitResult, type TilesPro, type TilesetExport, type TilesetExportOptions, type TilesetFormat, UnsupportedCapabilityError, UsageError, type Workspace, type WorkspaceClaims, type WorkspaceDiagnostic, type WorkspaceProject, WorkspaceProjectSchema, type WorkspaceProjectStatus, WorkspaceSchema, type WorkspaceStatusReport, adopt, applyManifestEdit, applyTags, approveQualityRecord, auditStyle, availableProviders, backoffMs, buildGallerySnapshot, buildManifest, buildPlan, buildWorkspaceGallerySnapshot, bundledRecipeRoot, cacheFileName, candidateCount, characterDirections, checkQualityBaseline, checkQualityRecord, clientFromEnv, colorDistance, countNumberedDescriptions, createArtifactBundleManifest, createGalleryEditHandler, createGalleryEditorHandlers, createGenerateHandlers, createProvider, currentEntryOutputPath, currentOutputPath, defaultOpenCommand, detachHandEdit, detectMediaType, doctor, editorBaseUrl, editorDir, editorRoute, editorStatus, editorToolsRoot, errorCode, evaluateAudit, exitCodeFor, expectedOutputPath, exportTileset, fallbackOutputRole, fetchAssets, fetchWithRetry, findOrphans, formatCost, frameSetFps, galleryMediaId, galleryMediaRoute, generationCost, groupOrphansByStyle, handEditBase, handEditBases, handEditCompanionPath, handEditMembers, handEditPath, handEditProjectPath, hex, historyAfterReplacing, historyLimit, idFromPrompt, imageMetadata, inspectCaches, inspectQualityProfile, inspectRevisionReadiness, installEditor, installRecipe, isFrameSetEntry, isMemberSetEntry, isSensitiveSourceUrl, listBundledRecipes, loadClaims, loadLock, loadManifest, loadSiblingManifests, loadWorkspace, lockKey, matchOrphanStyle, measureBalanceChange, measureDecodedImageQuality, measureImageQuality, mediaExtension, mediaTypeFromExtension, memberPath, mergePalettes, mountSprites, mountStyle, normalizeLockOutputPaths, normalizeRefinementPalette, normalizeTileRules, openExternal, openInEditor, openProject, outliers, outputId, packSprites, packStyle, paletteDistance, parentAssetId, parseLock, parseWorkspace, pickHistory, pngSize, poll, portableOutputPath, prepareReview, primaryOutput, providerCredentialEnvs, providerFactory, pushTags, qualityFrameOutputPath, qualityRecordPath, quantizeToPalette, readArtifactBundleManifest, readHandEditCompanion, readQualityBaseline, recipeDigest, referencedHashes, refineAsset, refineFrameSet, refineQualityProfiles, registerProvider, remove, renderAsepriteSheet, renderGallery, renderGodotSpriteFrames, renderSalvageSheet, renderSheet, renderSheetDocument, requireApprovedQualitySources, requireBalance, requireDelete, requireList, requireRevisionReady, requireSelectCandidate, resolveEntryOutputs, resolveOutputPath, resolvePackInputs, resolveProject, resolveQualityInputs, resolveRecipe, resolveSpecEntryOutputs, resolveSpecOutputs, resolveSpecs, resolveStyleImages, resolveStyleOutputs, resumeActions, resumeCommandForStatus, retireGeneration, retryAfterMs, revertGeneration, runPicker, runSalvage, saveHandEdit, saveLock, saveWorkspace, scanAssets, selectEntryOutput, serveGallery, sha256, sha256File, shouldPersistSourceUrl, shouldRetry, slugify, snapshotQualityBaseline, sourceIsStem, sourceOutputPath, specHash, spendByUnit, startHandEdit, styleImagesBase64, submit, summarize, tagAdopted, tileFeatureOutputCount, tileVariationCount, tilesCost, toPortablePath, totalSpend, upsert, validateCostEstimate, validateMedia, validateWorkspace, verifyArtifactBundle, verifyRecipe, withArtifactManifest, workspaceClaims, workspaceStatus, writeArtifactBundle, writeManagedArtifactBundle };

package/dist/index.d.ts

@@ -346,6 +346,21 @@ interface Provider {
     listCharacters?(): AsyncGenerator<RemoteCharacter>;
     /** One character with its rotations and animations. */
     getCharacter?(id: string): Promise<RemoteCharacterDetail>;
+    /**
+     * The object's source URLs as the service hands them out now, for
+     * `fetch --refresh` when recorded URLs go stale (PixelLab stamps a
+     * character's rotation URLs with its last edit time, and a cache may keep
+     * serving an old stamp's bytes). Resolve `null` when the object is gone
+     * upstream and `undefined` for objects whose recorded URLs stay good.
+     */
+    refreshSources?(objectId: string, context: RefreshContext): Promise<OutputSource[] | null | undefined>;
+}
+interface RefreshContext {
+    generator: Generator;
+    /** What the adapter recorded for this entry, under its own namespace. */
+    metadata?: ProviderMetadata;
+    /** The URLs the lockfile holds, in output order. */
+    sources: OutputSource[];
 }
 declare class UnsupportedCapabilityError extends PixelKilnError {
     constructor(providerId: string, capability: string);
@@ -6744,6 +6759,12 @@ declare class PixelLabProvider implements Provider {
     delete(assetId: string): Promise<void>;
     listCharacters(): AsyncGenerator<RemoteCharacter>;
     getCharacter(id: string): Promise<RemoteCharacterDetail>;
+    /**
+     * A character's rotation and frame URLs carry its last edit time as a
+     * cache-buster, so the record's URLs can name bytes a cache still holds
+     * after an edit in PixelLab's editor. Objects keep stable URLs.
+     */
+    refreshSources(objectId: string, context: RefreshContext): Promise<OutputSource[] | null | undefined>;
 }
 
 interface RetroDiffusionOptions {
@@ -7057,6 +7078,8 @@ declare class FakeProvider implements Provider {
     private listImpl;
     listCharacters(): AsyncGenerator<RemoteCharacter>;
     getCharacter(id: string): Promise<RemoteCharacterDetail>;
+    /** Characters answer with whatever the store holds now; other objects keep their URLs. */
+    refreshSources(objectId: string, context: RefreshContext): Promise<OutputSource[] | null | undefined>;
     delete(assetId: string): Promise<void>;
     /** Seed a pre-existing remote asset, for adopt / salvage tests. */
     seed(asset: Partial<RemoteAsset> & {
@@ -10258,6 +10281,8 @@ interface GalleryItem {
     revision: LockEntry["revision"];
     /** Parent lock key for a revision, so the page can link lineage. */
     revisionParentKey: string | null;
+    /** A character family member: what it is, whose it is, and what PixelLab holds for it. */
+    character: GalleryCharacter | null;
     outputs: GalleryOutput[];
     quality: GalleryQuality | null;
     providerMetadata: Record<string, unknown>;
@@ -10297,6 +10322,17 @@ interface GalleryItem {
     tags: string[];
     category: string | null;
 }
+interface GalleryCharacter {
+    kind: "base" | "state" | "animation";
+    /** Lock key of the base or state this is drawn from; null for a base. */
+    parentKey: string | null;
+    mode: string;
+    directions: number;
+    /** Animations only. */
+    direction: string | null;
+    /** Provider-side character id (an animation's is its character's). */
+    characterId: string | null;
+}
 interface GalleryStyle {
     id: string;
     /** Workspace project id, or null for a single-project gallery. */
@@ -10315,6 +10351,12 @@ interface GalleryStyle {
     /** Strip the generated background (sent for pixflux and non-PixelLab providers). */
     noBackground: boolean;
     quality: boolean;
+    /** Family counts for a `character` style; null otherwise. */
+    characters: {
+        bases: number;
+        states: number;
+        animations: number;
+    } | null;
     tags: string[];
     /** Parent style id when this style `extends` one. */
     extends: string | null;
@@ -11738,4 +11780,4 @@ interface WorkspaceStatusReport {
  */
 declare function workspaceStatus(ws: Workspace, dir: string): Promise<WorkspaceStatusReport>;
 
-export { type AdoptResult, type ApproveQualityOptions, type ApprovedQualityReview, type ArtifactBundleManifest, type ArtifactBundleOptions, type ArtifactBundleResult, type ArtifactFile, type ArtifactProvenance, type ArtifactSource, type ArtifactVerification, type Asset, type AssetAudit, AssetSchema, type AtlasSet, type AuditEvaluation, type AuditThresholds, type AuditViolation, type Balance, type BalanceChange, type BalanceInfo, BudgetError, type BuildGalleryOptions, type BuildWorkspaceGalleryOptions, CHARACTER_DIRECTIONS_4, CHARACTER_DIRECTIONS_8, type CacheHealthOptions, type CacheHealthReport, type CandidateSelection, type CharacterAnimation, type CharacterAnimationMode, CharacterAnimationModeSchema, CharacterAnimationSchema$1 as CharacterAnimationSchema, type CharacterDirection, CharacterDirectionSchema, type CharacterMode, CharacterModeSchema, type CharacterState, CharacterStateSchema, type ComfyUIBinding, type ComfyUIBindings, type ComfyUIFramesOptions, type ComfyUIImageInput, type ComfyUIOptions, ComfyUIProvider, type ContentCacheHealth, type ContentCacheIssue, type CostEstimate, type CostUnit, DEFAULT_HISTORY_LIMIT, DEFAULT_QUALITY_TOLERANCES, DEFAULT_RATE_LIMIT, DEFAULT_TIMEOUT_MS, type DoctorCheck, type DoctorLevel, type DoctorOptions, type DoctorReport, EDITOR_PIN, EDITOR_RELEASE_BASE, EXIT_CODES, EditorInstallError, type EditorInstallOptions, type EditorInstallProgress, type EditorInstallResult, type EditorInstallStatus, type EditorPin, type ErrorCode, FAKE_PNG, type FakeOptions, FakeProvider, type FetchResult, type GalleryBuild, type GalleryEditHandlerOptions, type GalleryEditMeta, type GalleryEditorHandlers, type GalleryEditorOptions, type GalleryEditorStatus, type GalleryGenerateHandlers, type GalleryGeneration, type GalleryItem, type GalleryMedia, type GalleryOutput, type GalleryProject, type GalleryProjectContext, type GalleryQuality, type GalleryServer, type GalleryServerOptions, type GallerySnapshot, type GalleryState, type GalleryStyle, type GenerateHandlerOptions, type GenerateJob, type GeneratePhase, GenerateRequestError, GenerateRequestSchema, type GenerateStatus, type Generator, GeneratorSchema, type GenericTileset, type GridConfidence, GridConfidenceSchema, HAND_EDIT_DIR, HISTORY_ENV, type HandEditCompanion, HandEditCompanionSchema, type HandEditMember, type HandEditSave, type HandEditSaveInput, type HandEditStart, type HandEditStatus, type HistoryPick, type ImageQualityMetrics, ImageQualityMetricsSchema, InheritedStyleSchema, type InstallRecipeOptions, type InstallRecipeResult, type JobState, type LoadedManifest, type LoadedRecipe, type Lock, type LockEntry, LockEntrySchema, type LockHistoryEntry, LockHistoryEntrySchema, type LockOutput, LockSchema, MAX_DOWNLOAD_BYTES, MAX_HAND_EDIT_BYTES, MAX_RETRIES, type ManagedArtifactBundleOptions, type Manifest, ManifestDriftError, type ManifestEdit, ManifestEditError, type ManifestEditResult, ManifestEditSchema, ManifestInputSchema, ManifestSchema, type MapObject, MediaType, type MountPlacement, type MountedSheet, type NormalizedTileRules, type OpenProjectOptions, type Orphan, type OrphanGroups, type OutputSelection, type OutputSource, OverwriteRefusedError, PIXEL_ART_FIXER_REVISION, PIXEL_ART_FIXER_URL, type PackedFrame, type PackedSheet, type PackedSource, type PendingQualityReview, type PickResult, type PixelArtFixerDetection, PixelKilnError, type PixelKilnErrorOptions, type PixelLabCharacter, type PixelLabCharacterAnimation, PixelLabClient, PixelLabError, type PixelLabObject, PixelLabProvider, type PixelLabUsage, type Plan, type PlanItem, type PlanState, type PollContext, type PollOptions, type PollResult, type Postprocess, PostprocessSchema, type PrepareReviewOptions, type Project, ProjectError, type Provider, ProviderError, type ProviderFactory, type ProviderInputContext, type ProviderInputScalar, type ProviderInputValue, type ProviderMetadata, type ProviderMode, type ProviderOptionContext, type ProviderSubmission, type QualityBaseline, QualityBaselineSchema, type QualityCheck, type QualityProfile, type QualityProfileInspection, QualityProfileSchema, type QualityProfileState, type QualityRegressionCaseResult, type QualityRegressionReport, type QualitySnapshotResult, QualityToleranceSchema, type QualityTolerances, type RateLimit, type Recipe, type RecipeFileVerification, type RecipeModelVerification, RecipeSchema, type RecipeVerification, type RefineAudit, type RefineFrameSetOptions, type RefineFrameSetResult, type RefineOptions, type RefineQualityProfilesOptions, type RefineQualityProfilesResult, type RefineRecordOptions, type RefineResult, type RemoteAsset, type RemoteCharacter, type RemoteCharacterDetail, type RemoteHashCacheHealth, type RenderGalleryOptions, type RenderSheetOptions, type ResolvedCharacter, type ResolvedOutput, type ResolvedProviderInputs, type ResolvedProviderOptions, type ResolvedQualityInput, type ResolvedQualityProfile, type ResolvedRevision, type ResolvedSpec, type ResolvedStyleImage, type ResumeAction, type ResumeCommand, type RetroDiffusionOptions, RetroDiffusionProvider, type RetryInit, type RetryOptions, type RetryingFetch, type RevertOptions, type RevertResult, type ReviewReadyInfo, type ReviewSession, type Revision, type RevisionMode, RevisionModeSchema, type RevisionReadiness, RevisionSchema, SHEET_FORMATS, type SalvageAction, type SalvageResult, type ScannedAsset, type ScenarioOptions, ScenarioProvider, type SessionBudget, type SheetAtlas, type SheetFormat, type SheetFormatOptions, type SheetGroup, type SiblingManifest, type SpriteInput, type Style, type StyleAudit, type StyleInput, StyleInputSchema, StyleSchema, type SubmissionCheckpoint, type SubmitContext, type SubmitOptions, type SubmitResult, type TilesPro, type TilesetExport, type TilesetExportOptions, type TilesetFormat, UnsupportedCapabilityError, UsageError, type Workspace, type WorkspaceClaims, type WorkspaceDiagnostic, type WorkspaceProject, WorkspaceProjectSchema, type WorkspaceProjectStatus, WorkspaceSchema, type WorkspaceStatusReport, adopt, applyManifestEdit, applyTags, approveQualityRecord, auditStyle, availableProviders, backoffMs, buildGallerySnapshot, buildManifest, buildPlan, buildWorkspaceGallerySnapshot, bundledRecipeRoot, cacheFileName, candidateCount, characterDirections, checkQualityBaseline, checkQualityRecord, clientFromEnv, colorDistance, countNumberedDescriptions, createArtifactBundleManifest, createGalleryEditHandler, createGalleryEditorHandlers, createGenerateHandlers, createProvider, currentEntryOutputPath, currentOutputPath, defaultOpenCommand, detachHandEdit, detectMediaType, doctor, editorBaseUrl, editorDir, editorRoute, editorStatus, editorToolsRoot, errorCode, evaluateAudit, exitCodeFor, expectedOutputPath, exportTileset, fallbackOutputRole, fetchAssets, fetchWithRetry, findOrphans, formatCost, frameSetFps, galleryMediaId, galleryMediaRoute, generationCost, groupOrphansByStyle, handEditBase, handEditBases, handEditCompanionPath, handEditMembers, handEditPath, handEditProjectPath, hex, historyAfterReplacing, historyLimit, idFromPrompt, imageMetadata, inspectCaches, inspectQualityProfile, inspectRevisionReadiness, installEditor, installRecipe, isFrameSetEntry, isMemberSetEntry, isSensitiveSourceUrl, listBundledRecipes, loadClaims, loadLock, loadManifest, loadSiblingManifests, loadWorkspace, lockKey, matchOrphanStyle, measureBalanceChange, measureDecodedImageQuality, measureImageQuality, mediaExtension, mediaTypeFromExtension, memberPath, mergePalettes, mountSprites, mountStyle, normalizeLockOutputPaths, normalizeRefinementPalette, normalizeTileRules, openExternal, openInEditor, openProject, outliers, outputId, packSprites, packStyle, paletteDistance, parentAssetId, parseLock, parseWorkspace, pickHistory, pngSize, poll, portableOutputPath, prepareReview, primaryOutput, providerCredentialEnvs, providerFactory, pushTags, qualityFrameOutputPath, qualityRecordPath, quantizeToPalette, readArtifactBundleManifest, readHandEditCompanion, readQualityBaseline, recipeDigest, referencedHashes, refineAsset, refineFrameSet, refineQualityProfiles, registerProvider, remove, renderAsepriteSheet, renderGallery, renderGodotSpriteFrames, renderSalvageSheet, renderSheet, renderSheetDocument, requireApprovedQualitySources, requireBalance, requireDelete, requireList, requireRevisionReady, requireSelectCandidate, resolveEntryOutputs, resolveOutputPath, resolvePackInputs, resolveProject, resolveQualityInputs, resolveRecipe, resolveSpecEntryOutputs, resolveSpecOutputs, resolveSpecs, resolveStyleImages, resolveStyleOutputs, resumeActions, resumeCommandForStatus, retireGeneration, retryAfterMs, revertGeneration, runPicker, runSalvage, saveHandEdit, saveLock, saveWorkspace, scanAssets, selectEntryOutput, serveGallery, sha256, sha256File, shouldPersistSourceUrl, shouldRetry, slugify, snapshotQualityBaseline, sourceIsStem, sourceOutputPath, specHash, spendByUnit, startHandEdit, styleImagesBase64, submit, summarize, tagAdopted, tileFeatureOutputCount, tileVariationCount, tilesCost, toPortablePath, totalSpend, upsert, validateCostEstimate, validateMedia, validateWorkspace, verifyArtifactBundle, verifyRecipe, withArtifactManifest, workspaceClaims, workspaceStatus, writeArtifactBundle, writeManagedArtifactBundle };
+export { type AdoptResult, type ApproveQualityOptions, type ApprovedQualityReview, type ArtifactBundleManifest, type ArtifactBundleOptions, type ArtifactBundleResult, type ArtifactFile, type ArtifactProvenance, type ArtifactSource, type ArtifactVerification, type Asset, type AssetAudit, AssetSchema, type AtlasSet, type AuditEvaluation, type AuditThresholds, type AuditViolation, type Balance, type BalanceChange, type BalanceInfo, BudgetError, type BuildGalleryOptions, type BuildWorkspaceGalleryOptions, CHARACTER_DIRECTIONS_4, CHARACTER_DIRECTIONS_8, type CacheHealthOptions, type CacheHealthReport, type CandidateSelection, type CharacterAnimation, type CharacterAnimationMode, CharacterAnimationModeSchema, CharacterAnimationSchema$1 as CharacterAnimationSchema, type CharacterDirection, CharacterDirectionSchema, type CharacterMode, CharacterModeSchema, type CharacterState, CharacterStateSchema, type ComfyUIBinding, type ComfyUIBindings, type ComfyUIFramesOptions, type ComfyUIImageInput, type ComfyUIOptions, ComfyUIProvider, type ContentCacheHealth, type ContentCacheIssue, type CostEstimate, type CostUnit, DEFAULT_HISTORY_LIMIT, DEFAULT_QUALITY_TOLERANCES, DEFAULT_RATE_LIMIT, DEFAULT_TIMEOUT_MS, type DoctorCheck, type DoctorLevel, type DoctorOptions, type DoctorReport, EDITOR_PIN, EDITOR_RELEASE_BASE, EXIT_CODES, EditorInstallError, type EditorInstallOptions, type EditorInstallProgress, type EditorInstallResult, type EditorInstallStatus, type EditorPin, type ErrorCode, FAKE_PNG, type FakeOptions, FakeProvider, type FetchResult, type GalleryBuild, type GalleryEditHandlerOptions, type GalleryEditMeta, type GalleryEditorHandlers, type GalleryEditorOptions, type GalleryEditorStatus, type GalleryGenerateHandlers, type GalleryGeneration, type GalleryItem, type GalleryMedia, type GalleryOutput, type GalleryProject, type GalleryProjectContext, type GalleryQuality, type GalleryServer, type GalleryServerOptions, type GallerySnapshot, type GalleryState, type GalleryStyle, type GenerateHandlerOptions, type GenerateJob, type GeneratePhase, GenerateRequestError, GenerateRequestSchema, type GenerateStatus, type Generator, GeneratorSchema, type GenericTileset, type GridConfidence, GridConfidenceSchema, HAND_EDIT_DIR, HISTORY_ENV, type HandEditCompanion, HandEditCompanionSchema, type HandEditMember, type HandEditSave, type HandEditSaveInput, type HandEditStart, type HandEditStatus, type HistoryPick, type ImageQualityMetrics, ImageQualityMetricsSchema, InheritedStyleSchema, type InstallRecipeOptions, type InstallRecipeResult, type JobState, type LoadedManifest, type LoadedRecipe, type Lock, type LockEntry, LockEntrySchema, type LockHistoryEntry, LockHistoryEntrySchema, type LockOutput, LockSchema, MAX_DOWNLOAD_BYTES, MAX_HAND_EDIT_BYTES, MAX_RETRIES, type ManagedArtifactBundleOptions, type Manifest, ManifestDriftError, type ManifestEdit, ManifestEditError, type ManifestEditResult, ManifestEditSchema, ManifestInputSchema, ManifestSchema, type MapObject, MediaType, type MountPlacement, type MountedSheet, type NormalizedTileRules, type OpenProjectOptions, type Orphan, type OrphanGroups, type OutputSelection, type OutputSource, OverwriteRefusedError, PIXEL_ART_FIXER_REVISION, PIXEL_ART_FIXER_URL, type PackedFrame, type PackedSheet, type PackedSource, type PendingQualityReview, type PickResult, type PixelArtFixerDetection, PixelKilnError, type PixelKilnErrorOptions, type PixelLabCharacter, type PixelLabCharacterAnimation, PixelLabClient, PixelLabError, type PixelLabObject, PixelLabProvider, type PixelLabUsage, type Plan, type PlanItem, type PlanState, type PollContext, type PollOptions, type PollResult, type Postprocess, PostprocessSchema, type PrepareReviewOptions, type Project, ProjectError, type Provider, ProviderError, type ProviderFactory, type ProviderInputContext, type ProviderInputScalar, type ProviderInputValue, type ProviderMetadata, type ProviderMode, type ProviderOptionContext, type ProviderSubmission, type QualityBaseline, QualityBaselineSchema, type QualityCheck, type QualityProfile, type QualityProfileInspection, QualityProfileSchema, type QualityProfileState, type QualityRegressionCaseResult, type QualityRegressionReport, type QualitySnapshotResult, QualityToleranceSchema, type QualityTolerances, type RateLimit, type Recipe, type RecipeFileVerification, type RecipeModelVerification, RecipeSchema, type RecipeVerification, type RefineAudit, type RefineFrameSetOptions, type RefineFrameSetResult, type RefineOptions, type RefineQualityProfilesOptions, type RefineQualityProfilesResult, type RefineRecordOptions, type RefineResult, type RefreshContext, type RemoteAsset, type RemoteCharacter, type RemoteCharacterDetail, type RemoteHashCacheHealth, type RenderGalleryOptions, type RenderSheetOptions, type ResolvedCharacter, type ResolvedOutput, type ResolvedProviderInputs, type ResolvedProviderOptions, type ResolvedQualityInput, type ResolvedQualityProfile, type ResolvedRevision, type ResolvedSpec, type ResolvedStyleImage, type ResumeAction, type ResumeCommand, type RetroDiffusionOptions, RetroDiffusionProvider, type RetryInit, type RetryOptions, type RetryingFetch, type RevertOptions, type RevertResult, type ReviewReadyInfo, type ReviewSession, type Revision, type RevisionMode, RevisionModeSchema, type RevisionReadiness, RevisionSchema, SHEET_FORMATS, type SalvageAction, type SalvageResult, type ScannedAsset, type ScenarioOptions, ScenarioProvider, type SessionBudget, type SheetAtlas, type SheetFormat, type SheetFormatOptions, type SheetGroup, type SiblingManifest, type SpriteInput, type Style, type StyleAudit, type StyleInput, StyleInputSchema, StyleSchema, type SubmissionCheckpoint, type SubmitContext, type SubmitOptions, type SubmitResult, type TilesPro, type TilesetExport, type TilesetExportOptions, type TilesetFormat, UnsupportedCapabilityError, UsageError, type Workspace, type WorkspaceClaims, type WorkspaceDiagnostic, type WorkspaceProject, WorkspaceProjectSchema, type WorkspaceProjectStatus, WorkspaceSchema, type WorkspaceStatusReport, adopt, applyManifestEdit, applyTags, approveQualityRecord, auditStyle, availableProviders, backoffMs, buildGallerySnapshot, buildManifest, buildPlan, buildWorkspaceGallerySnapshot, bundledRecipeRoot, cacheFileName, candidateCount, characterDirections, checkQualityBaseline, checkQualityRecord, clientFromEnv, colorDistance, countNumberedDescriptions, createArtifactBundleManifest, createGalleryEditHandler, createGalleryEditorHandlers, createGenerateHandlers, createProvider, currentEntryOutputPath, currentOutputPath, defaultOpenCommand, detachHandEdit, detectMediaType, doctor, editorBaseUrl, editorDir, editorRoute, editorStatus, editorToolsRoot, errorCode, evaluateAudit, exitCodeFor, expectedOutputPath, exportTileset, fallbackOutputRole, fetchAssets, fetchWithRetry, findOrphans, formatCost, frameSetFps, galleryMediaId, galleryMediaRoute, generationCost, groupOrphansByStyle, handEditBase, handEditBases, handEditCompanionPath, handEditMembers, handEditPath, handEditProjectPath, hex, historyAfterReplacing, historyLimit, idFromPrompt, imageMetadata, inspectCaches, inspectQualityProfile, inspectRevisionReadiness, installEditor, installRecipe, isFrameSetEntry, isMemberSetEntry, isSensitiveSourceUrl, listBundledRecipes, loadClaims, loadLock, loadManifest, loadSiblingManifests, loadWorkspace, lockKey, matchOrphanStyle, measureBalanceChange, measureDecodedImageQuality, measureImageQuality, mediaExtension, mediaTypeFromExtension, memberPath, mergePalettes, mountSprites, mountStyle, normalizeLockOutputPaths, normalizeRefinementPalette, normalizeTileRules, openExternal, openInEditor, openProject, outliers, outputId, packSprites, packStyle, paletteDistance, parentAssetId, parseLock, parseWorkspace, pickHistory, pngSize, poll, portableOutputPath, prepareReview, primaryOutput, providerCredentialEnvs, providerFactory, pushTags, qualityFrameOutputPath, qualityRecordPath, quantizeToPalette, readArtifactBundleManifest, readHandEditCompanion, readQualityBaseline, recipeDigest, referencedHashes, refineAsset, refineFrameSet, refineQualityProfiles, registerProvider, remove, renderAsepriteSheet, renderGallery, renderGodotSpriteFrames, renderSalvageSheet, renderSheet, renderSheetDocument, requireApprovedQualitySources, requireBalance, requireDelete, requireList, requireRevisionReady, requireSelectCandidate, resolveEntryOutputs, resolveOutputPath, resolvePackInputs, resolveProject, resolveQualityInputs, resolveRecipe, resolveSpecEntryOutputs, resolveSpecOutputs, resolveSpecs, resolveStyleImages, resolveStyleOutputs, resumeActions, resumeCommandForStatus, retireGeneration, retryAfterMs, revertGeneration, runPicker, runSalvage, saveHandEdit, saveLock, saveWorkspace, scanAssets, selectEntryOutput, serveGallery, sha256, sha256File, shouldPersistSourceUrl, shouldRetry, slugify, snapshotQualityBaseline, sourceIsStem, sourceOutputPath, specHash, spendByUnit, startHandEdit, styleImagesBase64, submit, summarize, tagAdopted, tileFeatureOutputCount, tileVariationCount, tilesCost, toPortablePath, totalSpend, upsert, validateCostEstimate, validateMedia, validateWorkspace, verifyArtifactBundle, verifyRecipe, withArtifactManifest, workspaceClaims, workspaceStatus, writeArtifactBundle, writeManagedArtifactBundle };

package/dist/index.js

@@ -2002,12 +2002,7 @@ var PixelLabProvider = class _PixelLabProvider {
     const character = await this.client.getCharacter(jobId);
     if (character.status === "failed") return { status: "failed", error: "character generation failed upstream" };
     if (character.status !== "completed" || !character.rotation_urls) return { status: "processing" };
-    const order = character.directions === 4 ? CHARACTER_DIRECTIONS_4 : CHARACTER_DIRECTIONS_8;
-    const sources = [];
-    for (const direction of order) {
-      const url = character.rotation_urls[direction];
-      if (url) sources.push({ url, role: direction });
-    }
+    const sources = rotationSources(character);
     if (!sources.length) return { status: "failed", error: "character completed with no rotation images" };
     return {
       status: "ready",
@@ -2299,6 +2294,27 @@ var PixelLabProvider = class _PixelLabProvider {
       })))
     };
   }
+  /**
+   * A character's rotation and frame URLs carry its last edit time as a
+   * cache-buster, so the record's URLs can name bytes a cache still holds
+   * after an edit in PixelLab's editor. Objects keep stable URLs.
+   */
+  async refreshSources(objectId, context) {
+    if (context.generator !== "character") return void 0;
+    const [characterId, groupId] = objectId.split("#");
+    const character = await this.client.getCharacter(characterId).catch((err) => {
+      if (err instanceof PixelLabError && err.status === 404) return null;
+      throw err;
+    });
+    if (!character) return null;
+    if (!groupId) return character.status === "completed" ? rotationSources(character) : void 0;
+    const recorded = context.metadata?.character ?? {};
+    const direction = recorded.direction ?? "south";
+    const group = character.animations.find((g) => g.animation_group_id === groupId);
+    const frames = group?.directions.find((d) => d.direction === direction && d.frames.length)?.frames ?? (recorded.animationName ? findAnimation(character, recorded.animationName, direction, recorded.animationId ?? null)?.frames : void 0);
+    if (!frames) return null;
+    return frames.map((url, index) => ({ url, role: `frame-${String(index).padStart(2, "0")}` }));
+  }
 };
 function remoteCharacter(character) {
   return {
@@ -2329,6 +2345,15 @@ function firstUrl(urls) {
   if (!urls) return null;
   return Object.values(urls).find((u) => typeof u === "string") ?? null;
 }
+function rotationSources(character) {
+  const order = character.directions === 4 ? CHARACTER_DIRECTIONS_4 : CHARACTER_DIRECTIONS_8;
+  const sources = [];
+  for (const direction of order) {
+    const url = character.rotation_urls?.[direction];
+    if (url) sources.push({ url, role: direction });
+  }
+  return sources;
+}
 function findAnimation(character, name, direction, animationId) {
   for (const group of character.animations) {
     const match = group.directions.find((d) => d.direction === direction && d.frames.length > 0);
@@ -4259,6 +4284,18 @@ var FakeProvider = class {
     if (!character) throw new Error(`fake provider has no character ${id}`);
     return character;
   }
+  /** Characters answer with whatever the store holds now; other objects keep their URLs. */
+  async refreshSources(objectId, context) {
+    if (context.generator !== "character") return void 0;
+    const [characterId, groupId] = objectId.split("#");
+    const character = this.characters.get(characterId);
+    if (!character) return null;
+    if (!groupId) return character.rotations;
+    const direction = context.metadata?.character?.direction ?? "south";
+    const animation = character.animations.find((a) => a.groupId === groupId && a.direction === direction);
+    if (!animation) return null;
+    return animation.frames.map((url, index) => ({ url, role: `frame-${String(index).padStart(2, "0")}` }));
+  }
   async delete(assetId) {
     this.deleted.push(assetId);
     this.assets.delete(assetId);
@@ -7937,7 +7974,40 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
         result.skipped++;
         continue;
       }
-      const sources = entry.sourceUrls?.length ? entry.sourceUrls : entry.sourceUrl ? [{ url: entry.sourceUrl }] : opts.repair && entry.outputs.length ? entry.outputs.map((o) => ({ url: "", role: o.role, mediaType: o.mediaType })) : [];
+      const recordedSources = entry.sourceUrls?.length ? entry.sourceUrls : entry.sourceUrl ? [{ url: entry.sourceUrl }] : opts.repair && entry.outputs.length ? entry.outputs.map((o) => ({ url: "", role: o.role, mediaType: o.mediaType })) : [];
+      let sources = recordedSources;
+      let rotated = false;
+      if (opts.refresh && entry.status === "downloaded" && entry.objectId && provider.refreshSources) {
+        let current;
+        try {
+          current = await provider.refreshSources(entry.objectId, {
+            generator: entry.generator,
+            metadata: entry.providerMetadata?.[provider.id],
+            sources: recordedSources
+          });
+        } catch (err) {
+          const message6 = err instanceof Error ? err.message : String(err);
+          upsert(lock, key, { status: "download-failed", error: `download failed: ${message6}` });
+          result.failed++;
+          log(`  FAILED  ${key}: ${message6}`);
+          await saveLock(lockPath, lock);
+          continue;
+        }
+        if (current === null) {
+          upsert(lock, key, { status: "download-failed", error: `download failed: ${entry.objectId} no longer exists upstream` });
+          result.failed++;
+          log(`  FAILED  ${key}: ${entry.objectId} no longer exists upstream`);
+          await saveLock(lockPath, lock);
+          continue;
+        }
+        if (current) {
+          sources = current.map((source) => ({
+            ...source,
+            mediaType: source.mediaType ?? recordedSources.find((r) => r.role === source.role)?.mediaType
+          }));
+          rotated = sources.length !== recordedSources.length || sources.some((source, index) => source.url !== recordedSources[index]?.url || source.role !== recordedSources[index]?.role);
+        }
+      }
       if (!sources.length) {
         upsert(lock, key, {
           status: "download-failed",
@@ -8066,6 +8136,10 @@ async function fetchAssets(provider, specs, lock, lockPath, opts = {}) {
           log(`  wrote   ${path16.relative(process.cwd(), target)}`);
         }
         if (opts.refresh && !wrote) {
+          if (rotated) {
+            const persistent = sources.filter((source) => shouldPersistSourceUrl(source.url));
+            upsert(lock, key, { sourceUrl: persistent[0]?.url ?? null, sourceUrls: persistent });
+          }
           result.unchanged = (result.unchanged ?? 0) + 1;
           continue;
         }
@@ -11214,6 +11288,32 @@ async function samePixels(a, b) {
   }
 }
 var metadataFps = (entry) => entry ? frameSetFps(entry) : null;
+function describeCharacter(spec, entry) {
+  const recorded = entry?.providerMetadata?.[entry.provider]?.character;
+  if (spec?.character) {
+    const character = spec.character;
+    return {
+      kind: character.kind,
+      parentKey: character.parentAssetId ? lockKey(spec.styleId, character.parentAssetId) : null,
+      mode: character.kind === "animation" ? character.animation.mode : character.mode,
+      directions: character.directions,
+      direction: character.animation?.direction ?? null,
+      characterId: recorded?.characterId ?? entry?.objectId?.split("#")[0] ?? null
+    };
+  }
+  if (entry?.generator === "character") {
+    const kind = recorded?.kind === "animation" || entry.outputs.some((o) => o.role?.startsWith("frame-")) ? "animation" : "base";
+    return {
+      kind,
+      parentKey: null,
+      mode: recorded?.mode ?? "standard",
+      directions: recorded?.directions ?? entry.outputs.length,
+      direction: recorded?.direction ?? null,
+      characterId: recorded?.characterId ?? entry.objectId?.split("#")[0] ?? null
+    };
+  }
+  return null;
+}
 async function fileInfo(absolutePath) {
   try {
     const info = await stat3(absolutePath);
@@ -11422,6 +11522,7 @@ async function buildGallerySnapshot(opts) {
       currentSpecHash: spec.specHash,
       revision: entry?.revision ?? null,
       revisionParentKey: spec.revision ? lockKey(spec.styleId, spec.revision.sourceAssetId) : entry?.revision ? lockKey(spec.styleId, entry.revision.sourceAssetId) : null,
+      character: describeCharacter(spec, entry),
       outputs,
       quality,
       providerMetadata: entry?.providerMetadata ?? {},
@@ -11483,6 +11584,7 @@ async function buildGallerySnapshot(opts) {
       currentSpecHash: null,
       revision: entry.revision,
       revisionParentKey: entry.revision ? lockKey(entry.styleId, entry.revision.sourceAssetId) : null,
+      character: describeCharacter(void 0, entry),
       outputs,
       quality: null,
       providerMetadata: entry.providerMetadata ?? {},
@@ -11539,6 +11641,11 @@ async function buildGallerySnapshot(opts) {
       view: style?.view ?? null,
       noBackground: style?.noBackground ?? true,
       quality: Boolean(style?.quality),
+      characters: style?.generator === "character" ? {
+        bases: styleItems.filter((item) => item.character?.kind === "base").length,
+        states: styleItems.filter((item) => item.character?.kind === "state").length,
+        animations: styleItems.filter((item) => item.character?.kind === "animation").length
+      } : null,
       tags: style?.tags ?? [],
       extends: typeof rawStyle?.extends === "string" ? rawStyle.extends : null,
       ownFields: rawStyle ? Object.keys(rawStyle).filter((key) => key !== "extends") : [],