Generation Families — Frontend

Generation Families — Frontend

The shared FacetedCreateForm assembles product and example forms from workflow contracts. One adapter binds engine descriptors to visual controls, one registry renders them, and FacetedFormLayout supplies the responsive geometry. Product definitions supply copy and policies rather than separate form implementations.

flowchart LR
    A["Catalog item: axes, variants, union contract"] --> B["useWorkflowForm: state and descriptors"]
    B --> C["bindFormControls: resolved inputs and callbacks"]
    C --> D["FormControl: visual types"]
    D --> E["FacetedFormControl registry"]
    E --> F["FacetedCreateForm and DS layout"]
    B --> G["buildPayload: axes and pruned inputs"]
    G --> H["useFacetedGenerate: gates, upload, dispatch"]

Contracts and resolved inputs

A CatalogItem carries axes, variants, and a contract. The server’s unionVariantContract deduplicates family input definitions into a union; a singleton has its own contract. The union supplies the engine’s field inventory, but it is not a promise that every input stays visible in the shared production form.

useWorkflowForm resolves the selected variant for availability, price, required fields, workflow-specific overrides, and input definitions such as enum values and numeric ranges. bindFormControls keeps axes and only inputs in useFacetedSurface.resolvedInputKeys, excluding hidden initial-source controls. Changing a variant can therefore change the shared form’s visible fields. At submission, buildPayload sends axes as generationAxes and prunes input buckets to the resolved variant’s accepted keys. The server remains authoritative for workflow resolution and rating.

Hidden and locked example inputs use overrides for the workflow actually selected. Hidden fields do not render; locked fields reject edits. Neither requires the user to supply the authored value. The server re-fetches the example and overlays those values at dispatch.

Engine descriptors and visual controls

The engine retains ControlDescriptor with axis/field kinds and separate state buckets. bindFormControl is the adapter that understands those origins and produces a bound FormControl with its value, change callback, lock state, and region. Visual renderers do not inspect engine buckets or axis/field tags.

Visual type	Engine inputs	Renderer responsibility
select	Axis select or scalar enum/format	Selected value and options
toggle	Boolean axis	Checked, disabled, and locked state
text	Text field	Composer value and required state
number	Numeric scalar	Value, range, and step
duration	Duration field	Numeric duration choices
character	Character IDs	Eligible characters and selection
media	Image/video input	Bound files, uploads, and input capacity

FacetedFormControl has a typed component registry covering every visual type. Text and media default to the composer; other controls default to settings. FACETED_CREATE_FORMS supplies product titles, prompt tips, media behavior, output/quantity policy, and optional placement/omission policies. An omitted required editable input produces an unavailable state only when its supplied or seeded value does not satisfy the resolved contract. Authored hidden or locked inputs remain server-owned.

The WorkflowControls renderer and descriptor exports remain compatibility interfaces for the developer workflow tester. Production forms use the bound visual registry. The tester source is unchanged.

Form composition and layout ownership

FacetedCreateForm combines the surface hook, bound controls, character selection, preview, settings, and generation actions. Hosts supply source context, preview/supporting content, and navigation callbacks. Product pages, example pages, and overlays always use this form.

The DS FacetedFormLayout exposes page and overlay variants with optional heading, preview, composer, settings, actions, and supportingContent slots. Missing regions are omitted. CSS changes the layout without replacing the mounted input subtree, preserving drafts and focus across resizing. Brisket owns data, gating, recommendations, and dialog lifecycle; DS owns geometry and styling.

Ordered selection and initial state

Initial selection and interactive changes have distinct rules:

• resolveOrderedTuple chooses initial or repaired tuples from available variants. It handles the requested/permitted 18+ mode first, then preserves valid preferences and uses authored option order. There is no remembered model across opens.
• workflowSeedAxes restores an available source workflow’s complete tuple only when its rating and access are compatible. Invalid provenance cannot bypass availability or rating checks.
• resolveAxisChange preserves axes before the changed axis, pins the new value, and re-defaults every later axis in authored order. If that prefix cannot resolve, it chooses the first valid tuple; no available tuple yields an unavailable form.
• Aspect ratio remains a contract input. Seeded values must fit the resolved input’s accepted values.

FacetedFormInitialState separates selection (workflowName, axes) from inputs.media (ID, media type, optional input key and presentation hints). Edit, image-to-video, and Kack Me bind their source media without adopting the source generation’s workflow. bindInitialMedia requires a unique compatible target in the resolved contract unless an explicit key identifies it, rejects duplicate IDs and capacity violations, and preserves hidden sources in the payload.

Form state reseeds when the item changes; a background refetch of the same item ID does not erase the draft. Per-variant definitions and overrides still update as selection changes.

Resolution, generation, and recovery

useFacetedSurface composes family/example resolution, initial binding, the form, and useFacetedGenerate. Its result is explicitly loading, ready, or unavailable. Missing families, malformed contracts, unavailable tuples, incompatible sources/ratings, and prompt conflicts reach the shared error UI. Opener attempt ownership prevents stale resolution from changing a newer open; resolution retries start new attempts.

useFacetedGenerate retains current-character, subscription, 18+, KYC, credits, required-field, and upload checks. It prevents overlapping submissions and validates the final payload before calling generationCatalog.generate. A successful queued result drives the host callback. Uncertain submission failure is not automatically retried: the user is directed to check Gallery. Frontend incident reports are deduplicated per attempt and use allowlisted metadata; ordinary user-action gates are not incidents.

Extension rules

There is one production form implementation, with no faceted presentation or product rollout flags. Workflow eligibility and entitlement checks still apply. See Create Form Routing and Recovery for endpoint refusal and batch/content-dump safeguards.

A new visual control needs an engine descriptor mapping, a FormControl binding, and a registry renderer. A new product normally needs a family mapping and a FACETED_CREATE_FORMS definition. Keep domain behavior out of the DS layout, preserve the compatibility interfaces needed by the tester, and reject contracts the form cannot safely complete.

See also

• Generation Families — family and variant concepts.
• Create Form Routing and Recovery — opening, failures, and server boundaries.

Gallery rating constraint

Before resolving a Gallery Re-create seed, useFacetedSurface applies restrictCatalogRating when preserveNsfw and the saved isNsfw value are present. The form can select only variants at that rating, including after a model or character change. Ordinary product and Explore seeds keep their existing selection behavior. See Gallery Re-create rules and QA.