Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

37.2 KB
Raw Blame
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import useMounted from './useMounted';
import toast from '../components/ui/Toast';
import {
  addUniverseStyleReference,
  adoptUniverseStyleGuide,
  createUniverse,
  deleteUniverse,
  getProviders,
  getSettings,
  getUniverse,
  listImageModels,
  listLorasFull,
  listUniverses,
  listWorldRuns,
  removeUniverseStyleReference,
  updateUniverse,
  WORLD_LOCKABLE_FIELDS,
  ensureInfluences,
} from '../services/api';
import {
  deriveAvailableBackends, renderPinLadder, renderTargetPin,
  IMAGE_GEN_MODE, RENDER_TARGET,
} from '../lib/imageGenBackends';
import { resolveRenderCfg } from '../lib/pipelineImageDefaults';
import { sameJsonShape } from '../lib/sameJsonShape';
import { upsertByIdPrepend } from '../lib/upsertByIdPrepend';
import { mergeCanonByName } from '../lib/universeBuilderExpand';
import {
  TRUNK_BY_KIND,
  adoptServerCategoryIds,
  adoptServerEntryIds,
  ensureDraftCategories,
  humanizeCategory,
  normalizeCategoryKey,
} from '../lib/universeBuilderShared';

// Distinguishes "this request failed" from "this request returned nothing". A unique
// object is used rather than null/undefined so it can never collide with a legitimate
// empty payload from any of the endpoints refresh() fans out to.
const FETCH_FAILED = Symbol('fetch-failed');

export const createEmptyUniverseDraft = () => ({
  name: '',
  starterPrompt: '',
  logline: '',
  premise: '',
  styleNotes: '',
  // Factual/fiction axis (#7616) — true marks a real-world universe.
  factual: false,
  moodBoardId: null,
  categories: ensureDraftCategories(),
  compositeSheets: [],
  influences: { embrace: [], avoid: [] },
  styleReferences: [],
  locked: {},
  llm: { provider: null, model: null },
});

// Stable serialization of the fields the general Save action owns. Canon and
// styleReferences are excluded because targeted editors persist those
// arrays independently.
export const universeDraftSnapshot = (draft = {}) => JSON.stringify({
  name: (draft.name || '').trim(),
  starterPrompt: draft.starterPrompt || '',
  logline: draft.logline || '',
  premise: draft.premise || '',
  styleNotes: draft.styleNotes || '',
  factual: draft.factual === true,
  moodBoardId: draft.moodBoardId || null,
  categories: draft.categories || {},
  compositeSheets: draft.compositeSheets || [],
  influences: ensureInfluences(draft.influences),
  locked: draft.locked || {},
  llm: draft.llm || { provider: null, model: null },
});

const emptyPendingCanon = () => ({ characters: [], places: [], objects: [] });

/**
 * Owns the Universe Builder's editable draft and persistence contract.
 *
 * The hook deliberately centralizes the concurrency-sensitive pieces that
 * used to be interleaved with the route markup: the saved-draft baseline,
 * pending canon-addition ledger, selection hydration, keyed category writes,
 * and create/update/delete flows. LLM expansion/refinement and rendering stay
 * separate consumers of this contract.
 */
export const RUNS_STATUS = { LOADING: 'loading', READY: 'ready', ERROR: 'error' };

export default function useUniverseDraft({ selectedId, goToWorld }) {
  const visitRef = useRef({ id: selectedId });
  if (visitRef.current.id !== selectedId) visitRef.current = { id: selectedId };
  const [universes, setWorlds] = useState([]);
  const [loading, setLoading] = useState(true);
  const [saving, setSaving] = useState(false);
  const [providers, setProviders] = useState([]);
  const [activeProviderId, setActiveProviderId] = useState(null);
  const [imageModels, setImageModels] = useState([]);
  const [availableLoras, setAvailableLoras] = useState([]);
  const [availableBackends, setAvailableBackends] = useState([]);
  const [defaultMode, setDefaultMode] = useState(null);
  // The raw settings blob, held so the render config below can be re-resolved
  // whenever this universe s own pin changes rather than only at fetch time.
  // Null until the first successful read (and after a failed one).
  const [renderSettings, setRenderSettings] = useState(null);
  // The Universe Bible target's own `settings.renderDefaults` pin — the rung
  // between this universe's pin and the install default. Held as the normalized
  // pin rather than the whole settings blob so the memo below has a stable dep.
  const [targetPin, setTargetPin] = useState(null);
  const [draft, setDraft] = useState(createEmptyUniverseDraft);
  const [draftRead, setDraftRead] = useState({ id: null, status: 'idle', error: null });
  const [draftReadAttempt, setDraftReadAttempt] = useState(0);
  const draftReady = selectedId ? (draftRead.id === selectedId
    && draftRead.status === 'ready' && draft.id === selectedId) : !draft.id;
  const draftReadError = draftRead.id === selectedId ? draftRead.error : null;
  const retryDraft = useCallback(() => setDraftReadAttempt(attempt => attempt + 1), []);
  const [runs, setRuns] = useState([]);
  // History read state, bound to the universe it was requested for. A failed
  // read must not look like an empty history, so it is tracked apart from `runs`.
  const [runsStatus, setRunsStatus] = useState(RUNS_STATUS.READY);
  const [pendingDeleteId, setPendingDeleteId] = useState(null);
  const [newCategoryName, setNewCategoryName] = useState('');
  const [canonDirty, setCanonDirty] = useState(false);

  const mountedRef = useMounted();
  const draftRef = useRef(null);
  const savedDraftSnapshotRef = useRef(universeDraftSnapshot(createEmptyUniverseDraft()));
  const savedStyleSnapshotRef = useRef(ensureInfluences(createEmptyUniverseDraft().influences));
  const pendingCanonAdditionsRef = useRef(emptyPendingCanon());
  // Mirrors `selectedId` synchronously during render (not via a passive
  // effect, which runs one tick later and would leave a window where a resolving
  // request still sees the OLD selection as current). Mutators compare against
  // this — not the `selectedId` closure — to decide whether their result should
  // still touch the currently DISPLAYED draft, so a response for a universe the
  // user has navigated away from is dropped instead of poisoning a different
  // universe's draft. Dropping it loses nothing: the write is already persisted
  // and returning re-reads it.
  const selectedIdRef = useRef(selectedId);
  selectedIdRef.current = selectedId;
  // The freshest `updatedAt` this hook has seen CONFIRMED for each universe —
  // stamped from every mutation response, whatever field it wrote. The hydration
  // GET compares its own body against it and re-reads when the body is older,
  // because a GET issued before a write's response landed can still carry the
  // pre-write record: applying it would visibly revert the change the user just
  // made (client-side only — the server has it).
  //
  // Keyed on the server's own clock rather than a per-feature counter so it
  // covers every writer that stamps through `noteUniverseUpdated`, not just
  // style references — a mutation added to this hook is protected by recording
  // its response, with no separate marker to remember. And because it decides
  // only "re-ask the server", never "use my cached value", it also covers
  // writers the client cannot see at all (peer sync, the image-delete purge) —
  // which is exactly what the per-universe value cache it replaced could not
  // do (#3109).
  const lastSeenUpdatedAtRef = useRef(new Map());
  const universeIsStale = useCallback((id, updatedAt) => {
    const seen = lastSeenUpdatedAtRef.current.get(id);
    if (!seen) return false;
    // A body with no `updatedAt` is unorderable — treat it as stale so the
    // re-read decides, rather than letting it silently win.
    if (!updatedAt) return true;
    return Date.parse(updatedAt) < Date.parse(seen);
  }, []);
  const noteUniverseUpdated = useCallback((id, updatedAt) => {
    if (!id || !updatedAt) return;
    const seen = lastSeenUpdatedAtRef.current.get(id);
    // Monotonic — a slow response that resolves after a newer one must not roll
    // the watermark backwards.
    if (seen && Date.parse(seen) >= Date.parse(updatedAt)) return;
    lastSeenUpdatedAtRef.current.set(id, updatedAt);
  }, []);

  useEffect(() => { draftRef.current = draft; }, [draft]);

  const clearPendingCanonAdditions = useCallback(() => {
    pendingCanonAdditionsRef.current = emptyPendingCanon();
  }, []);

  const markDraftSaved = useCallback((snapshotSource) => {
    savedDraftSnapshotRef.current = universeDraftSnapshot(snapshotSource);
    savedStyleSnapshotRef.current = ensureInfluences(snapshotSource?.influences);
    noteUniverseUpdated(snapshotSource?.id, snapshotSource?.updatedAt);
  }, [noteUniverseUpdated]);

  // Mark only the style-guide fields as saved after an atomic reference-adopt
  // PATCH. Replacing the entire baseline here would incorrectly clear dirty
  // state for unrelated edits made while the vision request was in flight.
  const markStyleGuidanceSaved = useCallback((snapshotSource) => {
    const saved = JSON.parse(savedDraftSnapshotRef.current);
    saved.styleNotes = snapshotSource?.styleNotes || '';
    saved.influences = ensureInfluences(snapshotSource?.influences);
    savedDraftSnapshotRef.current = JSON.stringify(saved);
    savedStyleSnapshotRef.current = ensureInfluences(snapshotSource?.influences);
  }, []);

  const isDraftDirty = useCallback(
    () => savedDraftSnapshotRef.current !== universeDraftSnapshot(draftRef.current || draft),
    [draft],
  );

  const refresh = async () => {
    setLoading(true);
    // FETCH_FAILED is a sentinel, not a value: it keeps "the request failed" distinct
    // from "the request succeeded and the answer is empty". Collapsing both to `[]`/`{}`
    // is what made a transient blip look identical to an unconfigured install — and, for
    // settings, silently rewrote the user's saved image-gen mode (see below).
    const [list, providerData, models, loras, settings] = await Promise.all([
      listUniverses().catch(() => FETCH_FAILED),
      getProviders().catch(() => FETCH_FAILED),
      listImageModels().catch(() => FETCH_FAILED),
      listLorasFull().catch(() => FETCH_FAILED),
      getSettings().catch(() => FETCH_FAILED),
    ]);
    if (list !== FETCH_FAILED) setWorlds(list);
    if (providerData !== FETCH_FAILED) {
      setProviders(providerData.providers || []);
      setActiveProviderId(providerData.activeProvider || null);
    }
    if (models !== FETCH_FAILED) setImageModels(models || []);
    if (loras !== FETCH_FAILED) setAvailableLoras(Array.isArray(loras) ? loras : []);
    // Deriving the backend list / default mode / image config from a `{}` stand-in on a
    // failed settings read reset the picker to IMAGE_GEN_MODE.LOCAL and the pipeline
    // image config to defaults — overwriting the user's real configuration because a
    // request happened to fail. Leave all three at their last-known-good values instead.
    if (settings !== FETCH_FAILED) {
      const backends = deriveAvailableBackends(settings, { excludeExternal: true });
      setAvailableBackends(backends);
      const saved = settings?.imageGen?.mode;
      setDefaultMode(backends.find((backend) => backend.id === saved)?.id || backends[0]?.id || IMAGE_GEN_MODE.LOCAL);
      setRenderSettings(settings);
      setTargetPin(renderTargetPin(settings, RENDER_TARGET.UNIVERSE_BIBLE));
    }
    setLoading(false);
  };

  useEffect(() => { refresh(); }, []);

  useEffect(() => {
    setPendingDeleteId(null);
    setSaving(false);
    setCanonDirty(false);
    clearPendingCanonAdditions();
    if (!selectedId) {
      const empty = createEmptyUniverseDraft();
      setDraft(empty);
      markDraftSaved(empty);
      return undefined;
    }
    let cancelled = false;
    let readError = null;
    const failedRead = error => { readError = error.message || 'Unable to load universe'; return null; };
    setDraftRead({ id: selectedId, status: 'loading', error: null });
    getUniverse(selectedId, { silent: true }).catch(failedRead).then(async (fetched) => {
      if (cancelled) return;
      // This body predates a mutation we already have confirmed — re-read rather
      // than apply it. The second read is issued after that mutation's response,
      // so it necessarily reflects the committed write. Comparing the body's own
      // clock (not merely "did a write happen") means the common case where the
      // GET already contains the write costs no extra request. On a re-read
      // failure, keep the draft as the mutation left it rather than applying the
      // body we just judged stale.
      const universe = (fetched && universeIsStale(selectedId, fetched.updatedAt))
        ? await getUniverse(selectedId, { silent: true }).catch(failedRead)
        : fetched;
      if (cancelled) return;
      if (universe) {
        noteUniverseUpdated(selectedId, universe.updatedAt);
        const hydrated = {
          ...universe,
          categories: ensureDraftCategories(universe.categories),
          compositeSheets: universe.compositeSheets || [],
          logline: universe.logline || '',
          premise: universe.premise || '',
          styleNotes: universe.styleNotes || '',
          // Absent on the wire means fiction — normalize so the toggle is
          // always a controlled boolean rather than undefined.
          factual: universe.factual === true,
          moodBoardId: universe.moodBoardId || null,
          influences: ensureInfluences(universe.influences),
          styleReferences: universe.styleReferences || [],
          locked: universe.locked || {},
          llm: universe.llm || { provider: null, model: null },
        };
        setDraft(hydrated);
        markDraftSaved(hydrated);
        setDraftRead({ id: selectedId, status: 'ready', error: null });
      } else {
        setDraftRead({ id: selectedId, status: 'error', error: readError || 'Universe not found' });
      }
    });
    return () => { cancelled = true; };
  }, [selectedId, universeIsStale, noteUniverseUpdated, draftReadAttempt]);

  // Run history loads independently of the draft so Retry never re-hydrates
  // (and so never clobbers) unsaved edits. Results are dropped unless they
  // still belong to the current selection and the latest request.
  const runsRequestRef = useRef(0);
  const loadRuns = useCallback(async (id) => {
    const request = ++runsRequestRef.current;
    setRunsStatus(RUNS_STATUS.LOADING);
    const fetched = await listWorldRuns(id).catch(() => null);
    if (!mountedRef.current || request !== runsRequestRef.current || selectedIdRef.current !== id) return;
    if (fetched) setRuns(fetched);
    setRunsStatus(fetched ? RUNS_STATUS.READY : RUNS_STATUS.ERROR);
  }, [mountedRef]);
  const retryRuns = useCallback(() => {
    if (selectedIdRef.current) loadRuns(selectedIdRef.current);
  }, [loadRuns]);

  useEffect(() => {
    // Rows from the previous universe must never show under the new one.
    setRuns([]);
    if (!selectedId) {
      runsRequestRef.current += 1;
      setRunsStatus(RUNS_STATUS.READY);
      return;
    }
    loadRuns(selectedId);
  }, [selectedId, loadRuns]);

  const handleSave = async () => {
    if (!draftReady || saving || selectedIdRef.current !== selectedId) return null;
    const visit = visitRef.current;
    const isCurrentVisit = () => mountedRef.current && visitRef.current === visit;
    if (!draft.name?.trim()) {
      toast.error('Name is required');
      return null;
    }
    setSaving(true);
    const basePayload = {
      name: draft.name.trim(),
      starterPrompt: draft.starterPrompt || '',
      logline: draft.logline || '',
      premise: draft.premise || '',
      styleNotes: draft.styleNotes || '',
      // Factual/fiction axis (#7616). Always shipped, like the other scalars:
      // the server drops a literal `false` back to absent, which is the clear.
      factual: draft.factual === true,
      // Linked mood board (#4188) — null clears server-side; the field always
      // ships so Save carries the full intended state like other scalars.
      moodBoardId: draft.moodBoardId || null,
      categories: draft.categories,
      compositeSheets: draft.compositeSheets || [],
      influences: ensureInfluences(draft.influences),
      locked: draft.locked || {},
      llm: draft.llm || {},
      // Per-record render pin (#3231 Phase 3) — included only when set so a
      // pin chosen on a not-yet-saved universe survives the create (the
      // update path is a no-op re-send; setRenderPin already PATCHed it).
      ...(draft.imageMode ? { imageMode: draft.imageMode } : {}),
      ...(draft.imageModelId ? { imageModelId: draft.imageModelId } : {}),
    };
    const needsCanonInPayload = !selectedId || canonDirty;
    let payload = basePayload;
    if (needsCanonInPayload) {
      if (selectedId) {
        const fresh = await getUniverse(selectedId, { silent: true }).catch(() => null);
        if (!isCurrentVisit()) return null;
        if (!fresh) {
          setSaving(false);
          toast.error('Save failed: could not fetch latest canon — please try again');
          return null;
        }
        const additions = pendingCanonAdditionsRef.current;
        payload = {
          ...basePayload,
          characters: mergeCanonByName(fresh.characters || [], additions.characters, 'character'),
          places: mergeCanonByName(fresh.places || [], additions.places, 'place'),
          objects: mergeCanonByName(fresh.objects || [], additions.objects, 'object'),
        };
      } else {
        payload = {
          ...basePayload,
          characters: draft.characters || [],
          places: draft.places || [],
          objects: draft.objects || [],
        };
      }
    }
    const result = selectedId
      ? await updateUniverse(selectedId, payload, { silent: true }).catch((error) => { toast.error(`Save failed: ${error.message}`); return null; })
      : await createUniverse(payload, { silent: true }).catch((error) => { toast.error(`Save failed: ${error.message}`); return null; });
    // Persisted writes still update the list/watermark, but only their original
    // visit may settle its draft or navigate after a create (including A→B→A).
    if (result) {
      noteUniverseUpdated(result.id, result.updatedAt);
      setWorlds(previous => upsertByIdPrepend(previous, result));
    }
    if (!isCurrentVisit()) return result;
    setSaving(false);
    if (!result) return null;
    if (needsCanonInPayload) {
      setCanonDirty(false);
      clearPendingCanonAdditions();
    }
    // Adopt the ids the server sanitizer minted for entries this save created,
    // so per-entry client state keyed by id (the render queue's pending-job map)
    // can match a board or variation added and used in the same session. Both
    // the draft AND the saved baseline take the ids — backfilling only the draft
    // would read as an unsaved edit and leave the page permanently dirty.
    const savedSheets = adoptServerEntryIds(payload.compositeSheets, result.compositeSheets);
    const savedCategories = adoptServerCategoryIds(payload.categories, result.categories);
    markDraftSaved({ ...payload, compositeSheets: savedSheets, categories: savedCategories });
    if (savedSheets !== payload.compositeSheets || savedCategories !== payload.categories) {
      // Re-derive from the CURRENT draft rather than assigning `savedSheets`
      // wholesale — edits made while the save was in flight must survive, and
      // adopting an id is additive to whatever the row looks like now.
      setDraft((d) => ({
        ...d,
        compositeSheets: adoptServerEntryIds(d.compositeSheets, result.compositeSheets),
        categories: adoptServerCategoryIds(d.categories, result.categories),
      }));
    }
    toast.success(selectedId ? 'World updated' : 'World created');
    if (result.id !== selectedId) goToWorld(result.id);
    return result;
  };

  // Reconcile the draft's entry ids with the persisted record. `POST /render`
  // migrates a universe whose entries predate persisted ids — before that write,
  // `ensureEntryId` mints a fresh uuid on every read, so this draft is holding
  // transient ids while the queued jobs are keyed by the ones the migration just
  // wrote. Without this the pending-job map and the rows it drives use different
  // keys, and no row picks up its own render.
  //
  // Only the ids move: `adoptServerEntryIds` keeps every local id the server also
  // has, so a row is never re-keyed out from under an in-flight job, and nothing
  // else from the fetched record is merged in (it would clobber edits made since).
  // The saved baseline takes the same ids, or adopting them reads as a user edit
  // and the page stays permanently dirty.
  const syncEntryIdsFromServer = useCallback(async () => {
    const id = selectedIdRef.current;
    if (!id) return;
    const fresh = await getUniverse(id, { silent: true }).catch(() => null);
    // Dropping a response for a universe the user has navigated away from —
    // same rule every other mutator here follows.
    if (!fresh || !mountedRef.current || selectedIdRef.current !== id) return;
    const current = draftRef.current || {};
    if (adoptServerEntryIds(current.compositeSheets, fresh.compositeSheets) === current.compositeSheets
      && adoptServerCategoryIds(current.categories, fresh.categories) === current.categories) return;
    const saved = JSON.parse(savedDraftSnapshotRef.current);
    saved.compositeSheets = adoptServerEntryIds(saved.compositeSheets, fresh.compositeSheets);
    saved.categories = adoptServerCategoryIds(saved.categories, fresh.categories);
    savedDraftSnapshotRef.current = JSON.stringify(saved);
    setDraft((d) => ({
      ...d,
      compositeSheets: adoptServerEntryIds(d.compositeSheets, fresh.compositeSheets),
      categories: adoptServerCategoryIds(d.categories, fresh.categories),
    }));
  }, [mountedRef]);

  // Preflight for any server action that reads the PERSISTED universe (the LLM
  // actions, batch render): persist a dirty draft first, so the server operates
  // on what the user is looking at rather than the last-saved snapshot. Lives
  // here — beside the `isDraftDirty` / `handleSave` pair it is derived from —
  // so every consumer shares one definition of the contract.
  // Returns true when the draft is clean or the save succeeded; false (with
  // handleSave's own error toast already raised) when the save failed.
  const flushDraftIfDirty = async () => {
    if (!isDraftDirty()) return true;
    return !!(await handleSave());
  };

  const handleCreateNamed = async (rawName) => {
    const name = (rawName || '').trim();
    if (!name) {
      toast.error('Name is required');
      return;
    }
    if (!selectedId) {
      await handleSave();
      return;
    }
    setSaving(true);
    const result = await createUniverse({ ...createEmptyUniverseDraft(), name }, { silent: true })
      .catch((error) => { toast.error(`Create failed: ${error.message}`); return null; });
    setSaving(false);
    if (!result) return;
    toast.success('World created');
    setWorlds((previous) => upsertByIdPrepend(previous, result));
    goToWorld(result.id);
  };

  const handleDelete = async () => {
    if (!selectedId) return;
    const deleted = await deleteUniverse(selectedId, { silent: true })
      .then(() => true)
      .catch((error) => { toast.error(`Delete failed: ${error.message}`); return false; });
    if (!deleted) return;
    setWorlds((previous) => previous.filter((universe) => universe.id !== selectedId));
    goToWorld(null);
    setDraft(createEmptyUniverseDraft());
    setPendingDeleteId(null);
    toast.success('World deleted');
  };

  const updateDraft = useCallback((patch) => setDraft((current) => ({ ...current, ...patch })), []);

  // Fold one style-reference mutation's response (the full updated universe)
  // into the DISPLAYED draft — but only when the user is still on the universe
  // that was mutated; otherwise applying it would poison a different,
  // now-selected universe's draft. Nothing is lost by dropping it: the change
  // is already persisted, and the server owns the array now.
  //
  // `capturedStyle` is the style guide as it read when an ADOPT request was
  // issued; passing it is what marks the response as an adopt, so the guide
  // fields are folded in too (and banked as saved) — unless the user edited them
  // while the request was in flight. A plain add or remove passes nothing,
  // because it wrote no guidance to fold in.
  const applyStyleReferenceResult = useCallback((targetId, updated, capturedStyle = null) => {
    noteUniverseUpdated(targetId, updated.updatedAt);
    if (selectedIdRef.current === targetId) {
      if (capturedStyle) markStyleGuidanceSaved(updated);
      setDraft((latest) => {
        const styleUnchangedDuringSave = capturedStyle
          && latest.styleNotes === capturedStyle.styleNotes
          && sameJsonShape(ensureInfluences(latest.influences), capturedStyle.influences);
        return {
          ...latest,
          styleReferences: updated.styleReferences || [],
          updatedAt: updated.updatedAt,
          ...(styleUnchangedDuringSave ? {
            styleNotes: updated.styleNotes || '',
            influences: ensureInfluences(updated.influences),
          } : {}),
        };
      });
    }
    setWorlds((previous) => upsertByIdPrepend(previous, updated));
  }, [noteUniverseUpdated, markStyleGuidanceSaved]);

  // Add one art reference. Sends ONLY the addition — see `addStyleReference` in
  // server/services/universeBuilder/crud.js for why (#3109). The cap is enforced
  // there too, against persisted state rather than a client cache.
  const persistStyleReference = useCallback(async ({ reference, proposed, adopt }) => {
    if (!selectedId || !reference) return false;
    const targetId = selectedId;
    const current = draftRef.current || draft;
    const capturedStyle = {
      styleNotes: current.styleNotes || '',
      influences: ensureInfluences(current.influences),
    };
    const updated = await addUniverseStyleReference(targetId, {
      reference,
      adopt: adopt ? {
        styleNotes: proposed?.styleNotes || '',
        influences: ensureInfluences(proposed?.influences),
      } : undefined,
    }, { silent: true }).catch((error) => {
      toast.error(`Reference save failed: ${error.message}`);
      return null;
    });
    if (!updated) return false;
    applyStyleReferenceResult(targetId, updated, adopt ? capturedStyle : null);
    toast.success(adopt ? 'Art reference added and style guide updated' : 'Art reference added');
    return true;
  }, [applyStyleReferenceResult, draft, selectedId]);

  // Adopt a board-synthesized style guide (#4188 Phase 4) — the reference-less
  // sibling of the persistStyleReference adopt path. Routes through the same
  // applyStyleReferenceResult bookkeeping so the saved snapshot + update
  // watermark advance and styleProbeDirty clears, exactly as an art-reference
  // adopt does; the server re-checks field locks in its queued write.
  const adoptStyleGuideFromBoard = useCallback(async (proposed) => {
    if (!selectedId) return false;
    const targetId = selectedId;
    const current = draftRef.current || draft;
    const capturedStyle = {
      styleNotes: current.styleNotes || '',
      influences: ensureInfluences(current.influences),
    };
    const updated = await adoptUniverseStyleGuide(targetId, {
      styleNotes: proposed?.styleNotes || '',
      influences: ensureInfluences(proposed?.influences),
    }, { silent: true }).catch((error) => {
      toast.error(`Adopting the style guide failed: ${error.message}`);
      return null;
    });
    if (!updated) return false;
    applyStyleReferenceResult(targetId, updated, capturedStyle);
    toast.success('Style guide adopted from mood board');
    return true;
  }, [applyStyleReferenceResult, draft, selectedId]);

  // Remove one art reference by id. Also a delta, so back-to-back removals need
  // no client-side queue — the server's record write queue serializes them.
  const removeStyleReference = useCallback(async (referenceId) => {
    if (!selectedId) return false;
    const targetId = selectedId;
    const updated = await removeUniverseStyleReference(targetId, referenceId, { silent: true })
      .catch((error) => {
        toast.error(`Reference removal failed: ${error.message}`);
        return null;
      });
    if (!updated) return false;
    applyStyleReferenceResult(targetId, updated);
    toast.success('Art reference removed');
    return true;
  }, [applyStyleReferenceResult, selectedId]);

  const handleCanonChange = useCallback((updated) => {
    if (!updated) return;
    setDraft((current) => {
      if (canonDirty) {
        const additions = pendingCanonAdditionsRef.current;
        return {
          ...current,
          characters: mergeCanonByName(updated.characters || [], additions.characters, 'character'),
          places: mergeCanonByName(updated.places || [], additions.places, 'place'),
          objects: mergeCanonByName(updated.objects || [], additions.objects, 'object'),
          updatedAt: updated.updatedAt,
        };
      }
      return {
        ...current,
        characters: updated.characters,
        places: updated.places,
        objects: updated.objects,
        updatedAt: updated.updatedAt,
      };
    });
  }, [canonDirty]);

  // Serializes lock PATCHes, PER UNIVERSE. The server replaces the stored
  // `locked` map wholesale on every arrival, so ORDER is load-bearing: two
  // toggles fired back-to-back that land reversed persist the older map,
  // leaving a field locked on disk while the UI shows it unlocked. Chaining
  // them means the second is not even sent until the first settles. The
  // style-reference mutators need no such tail — they send deltas the server
  // applies in any order (#3109) — which is exactly the difference that makes
  // one necessary here.
  //
  // Keyed by id rather than held as one tail for the hook, because a request
  // has no timeout: a stalled write for the universe the user just left would
  // otherwise block every lock on the one they navigated to, indefinitely and
  // silently (the draft still updates optimistically, so nothing surfaces it).
  const lockWriteTailsRef = useRef(new Map());

  const toggleLock = useCallback((field) => {
    if (!WORLD_LOCKABLE_FIELDS.includes(field)) return;
    // The next lock map is derived from the freshest draft OUTSIDE the state
    // updater, and the PATCH fires from here rather than from inside it. A
    // state updater must be pure: React is free to invoke it more than once
    // for a single setState (StrictMode double-invocation, an interrupted
    // concurrent render), and a request issued from within one is sent once
    // per invocation — one lock click produced two identical PATCHes. Mirrors
    // setRenderPin / assignBucketKind, which already patch outside the updater.
    const current = draftRef.current || draft;
    const nextLocked = { ...(current.locked || {}) };
    if (nextLocked[field]) delete nextLocked[field];
    else nextLocked[field] = true;
    // Advance the mirror synchronously. The effect that syncs `draftRef` runs a
    // commit later, so two toggles inside one tick would otherwise both read the
    // pre-toggle map — the second re-sending the first's write instead of
    // composing on top of it. The functional updater still owns the draft
    // itself, so a concurrent edit to another field is not clobbered.
    draftRef.current = { ...current, locked: nextLocked };
    setDraft((value) => ({ ...value, locked: nextLocked }));
    if (selectedId && current.name?.trim()) {
      const tail = lockWriteTailsRef.current.get(selectedId) || Promise.resolve();
      lockWriteTailsRef.current.set(selectedId, tail
        .then(() => updateUniverse(selectedId, { locked: nextLocked }, { silent: true }))
        .catch((error) => toast.error(`Lock save failed: ${error.message}`)));
    }
  }, [draft, selectedId]);

  // Per-record render pin (#3231 Phase 3) — this universe's default image
  // backend + cloud model. Mirrors toggleLock: reactive local update plus an
  // immediate targeted PATCH (the pin is not part of the autosaved draft
  // payload, so a stale draft flush can't resurrect a cleared pin).
  const setRenderPin = useCallback(({ imageMode, imageModelId }) => {
    setDraft((current) => ({ ...current, imageMode, imageModelId }));
    if (selectedId) {
      updateUniverse(selectedId, { imageMode, imageModelId }, { silent: true })
        .catch((error) => toast.error(`Render pin save failed: ${error.message}`));
    }
  }, [selectedId]);

  const updateCategory = useCallback((category, variations) => setDraft((current) => ({
    ...current,
    categories: {
      ...current.categories,
      [category]: { ...(current.categories?.[category] || {}), variations },
    },
  })), []);

  const assignBucketKind = async (bucket, targetKind) => {
    if (!TRUNK_BY_KIND[targetKind]) return;
    const latestDraft = draftRef.current || draft;
    const current = latestDraft.categories?.[bucket];
    if (!current) return;
    const nextBucket = { ...current, kind: targetKind };
    setDraft((value) => ({
      ...value,
      categories: {
        ...value.categories,
        [bucket]: { ...(value.categories?.[bucket] || current), kind: targetKind },
      },
    }));
    const trunk = TRUNK_BY_KIND[targetKind];
    if (!selectedId) {
      toast.success(`Tagged "${humanizeCategory(bucket)}" as ${trunk.label} — save to persist`);
      return;
    }
    const updated = await updateUniverse(
      selectedId,
      { categories: { [bucket]: nextBucket } },
      { silent: true },
    ).catch((error) => { toast.error(`Move failed: ${error.message}`); return null; });
    if (updated) {
      setWorlds((previous) => upsertByIdPrepend(previous, updated));
      toast.success(`Moved "${humanizeCategory(bucket)}" to ${trunk.label}`);
    }
  };

  const updateCompositeSheets = useCallback((sheets) => {
    setDraft((current) => ({ ...current, compositeSheets: sheets }));
  }, []);

  const addCategory = useCallback(() => {
    const key = normalizeCategoryKey(newCategoryName);
    if (!key) {
      toast.error('Use letters or numbers for the category name');
      return;
    }
    if (draft.categories?.[key]) {
      toast.error('Category already exists');
      return;
    }
    setDraft((current) => ({
      ...current,
      categories: { ...current.categories, [key]: { variations: [] } },
    }));
    setNewCategoryName('');
  }, [draft.categories, newCategoryName]);

  const removeCategory = useCallback((category) => setDraft((current) => {
    const categories = { ...current.categories };
    delete categories[category];
    return { ...current, categories: ensureDraftCategories(categories) };
  }), []);

  const providerLabel = useCallback(
    (id) => providers.find((provider) => provider.id === id)?.name || id || '—',
    [providers],
  );
  const providerModels = useMemo(() => {
    const provider = providers.find((item) => item.id === draft.llm?.provider)
      || providers.find((item) => item.id === activeProviderId);
    return provider?.models || [];
  }, [providers, activeProviderId, draft.llm?.provider]);
  const styleProbeDirty = !sameJsonShape(
    savedStyleSnapshotRef.current,
    ensureInfluences(draft.influences),
  );
  // The render-pin ladder's inputs (see `renderPinLadder`), resolved here at the
  // source — this hook owns every rung — rather than at each consumer, so a new
  // render affordance on this page inherits the pin instead of re-introducing
  // the bug. `targetPin` doubles as the "settings loaded" sentinel: it is only
  // ever set from a successful read, and the backend list must be passed as
  // `null` (not the initial `[]`, which reads as "loaded, nothing enabled" and
  // would suppress every pin) until then.
  const pinSources = [draft, targetPin];
  const pinBackends = targetPin ? availableBackends : null;
  // What every SINGLE-image render on this page uses: cast / places / objects
  // reference renders and clean plates.
  const imageCfg = useMemo(
    () => resolveRenderCfg(renderSettings, {
      record: draft, target: RENDER_TARGET.UNIVERSE_BIBLE, backends: pinBackends,
    }),
    [renderSettings, targetPin, draft.imageMode, draft.imageModelId, availableBackends],
  );
  // The same ladder for the BATCH form's default mode. The client always sends
  // an explicit body.mode once settings load, so without resolving it here the
  // pins would only ever apply to mode-less API callers.
  const effectiveDefaultMode = renderPinLadder(pinSources, pinBackends).mode || defaultMode;

  return {
    activeProviderId,
    addCategory,
    assignBucketKind,
    availableBackends,
    availableLoras,
    canonDirty,
    clearPendingCanonAdditions,
    defaultMode,
    draft,
    draftRef,
    draftReady,
    draftReadError,
    retryDraft,
    effectiveDefaultMode,
    flushDraftIfDirty,
    handleCanonChange,
    handleCreateNamed,
    handleDelete,
    handleSave,
    imageCfg,
    imageModels,
    isDraftDirty,
    loading,
    markDraftSaved,
    mountedRef,
    newCategoryName,
    pendingCanonAdditionsRef,
    pendingDeleteId,
    providerLabel,
    providerModels,
    providers,
    // Exposed so a consumer can retry the catalog/settings load after a failed
    // refresh instead of forcing a full page reload.
    refresh,
    adoptStyleGuideFromBoard,
    persistStyleReference,
    removeCategory,
    removeStyleReference,
    runs,
    runsStatus,
    retryRuns,
    saving,
    setRenderPin,
    setCanonDirty,
    setDraft,
    setNewCategoryName,
    setPendingDeleteId,
    setRuns,
    setSaving,
    setWorlds,
    styleProbeDirty,
    syncEntryIdsFromServer,
    toggleLock,
    universes,
    updateCategory,
    updateCompositeSheets,
    updateDraft,
  };
}