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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { StrictMode } from 'react';
import { act, renderHook, waitFor } from '@testing-library/react';
import { beforeEach, describe, expect, it, vi } from 'vitest';
// These constant stand-ins mirror the REAL values exported from
// services/apiUniverseBuilder.js (WORLD_CATEGORIES, WORLD_LOCKABLE_FIELDS,
// WORLD_CATEGORY_KEY_MAX). Because the suite mocks the whole api module, a
// convenience list here that drifts from the shipped one would let a body the
// server's `.strict()` Zod schemas reject pass green — the exact failure mode
// this suite's wire-shape assertions exist to catch.
const apiMocks = vi.hoisted(() => ({
addUniverseStyleReference: vi.fn(),
createUniverse: vi.fn(),
deleteUniverse: vi.fn(),
getProviders: vi.fn(),
getSettings: vi.fn(),
getUniverse: vi.fn(),
listImageModels: vi.fn(),
listLorasFull: vi.fn(),
listUniverses: vi.fn(),
listWorldRuns: vi.fn(),
removeUniverseStyleReference: vi.fn(),
updateUniverse: vi.fn(),
WORLD_CATEGORY_KEY_MAX: 64,
WORLD_CATEGORIES: ['landscapes', 'environments', 'structures', 'vehicles'],
WORLD_LOCKABLE_FIELDS: [
'starterPrompt', 'logline', 'premise', 'styleNotes', 'influencesEmbrace', 'influencesAvoid',
],
ensureInfluences: (value) => ({
embrace: Array.isArray(value?.embrace) ? value.embrace : [],
avoid: Array.isArray(value?.avoid) ? value.avoid : [],
}),
}));
const toastMock = vi.hoisted(() => ({ success: vi.fn(), error: vi.fn() }));
vi.mock('../services/api', () => apiMocks);
vi.mock('../components/ui/Toast', () => ({ default: toastMock }));
import useUniverseDraft from './useUniverseDraft.js';
const universe = {
id: 'u1',
name: 'Example Universe',
starterPrompt: 'A test world',
logline: 'Original logline',
premise: 'Original premise',
styleNotes: '',
categories: { heroes: { kind: 'characters', variations: [] } },
compositeSheets: [],
influences: { embrace: ['ink'], avoid: [] },
styleReferences: [],
locked: {},
llm: { provider: null, model: null },
characters: [{ name: 'Stale Draft Character' }],
places: [],
objects: [],
updatedAt: '2026-01-01T00:00:00.000Z',
};
// Stand-in for the server's authoritative styleReferences list, keyed by
// universe id. The delta endpoints append/filter THIS — not a client-held base
// array — which is the whole point of #3109: the client sends only the change,
// so two mutations compose no matter what order their responses arrive in.
let serverReferences;
const serverRefsFor = (id) => serverReferences.get(id) ?? [];
// The server's `updatedAt` clock. Every write bumps it, and the hook keys its
// "is this GET body older than a write I already saw?" watermark on it — so the
// mock has to advance it or the ordering under test isn't modelled at all.
let serverClock;
const tickServerClock = () => {
serverClock += 1;
return `2026-01-01T00:00:${String(serverClock).padStart(2, '0')}.000Z`;
};
beforeEach(() => {
vi.clearAllMocks();
serverReferences = new Map();
serverClock = 0;
apiMocks.listUniverses.mockResolvedValue([universe]);
apiMocks.getProviders.mockResolvedValue({ providers: [], activeProvider: null });
apiMocks.listImageModels.mockResolvedValue([]);
apiMocks.listLorasFull.mockResolvedValue([]);
apiMocks.getSettings.mockResolvedValue({ imageGen: {} });
apiMocks.getUniverse.mockResolvedValue(universe);
apiMocks.listWorldRuns.mockResolvedValue([{ id: 'run-1' }]);
apiMocks.updateUniverse.mockImplementation(async (id, payload) => ({
...universe, id, ...payload, updatedAt: tickServerClock(),
}));
apiMocks.createUniverse.mockImplementation(async (payload) => ({
...universe, ...payload, id: 'u-new', updatedAt: tickServerClock(),
}));
apiMocks.deleteUniverse.mockResolvedValue({ ok: true });
apiMocks.addUniverseStyleReference.mockImplementation(async (id, { reference, adopt } = {}) => {
const next = [...serverRefsFor(id), reference];
serverReferences.set(id, next);
return {
...universe, id, styleReferences: next, ...(adopt || {}), updatedAt: tickServerClock(),
};
});
apiMocks.removeUniverseStyleReference.mockImplementation(async (id, referenceId) => {
const next = serverRefsFor(id).filter((ref) => ref.id !== referenceId);
serverReferences.set(id, next);
return { ...universe, id, styleReferences: next, updatedAt: tickServerClock() };
});
});
const renderDraft = (options) => {
const goToWorld = vi.fn();
const hook = renderHook(() => useUniverseDraft({ selectedId: 'u1', goToWorld }), options);
return { ...hook, goToWorld };
};
// An unsaved universe: no `selectedId`, so the draft starts from
// createEmptyUniverseDraft() and every mutator takes its "nothing to PATCH
// yet, defer to the next Save" branch.
const renderUnsaved = () => {
const goToWorld = vi.fn();
const hook = renderHook(() => useUniverseDraft({ selectedId: null, goToWorld }));
return { ...hook, goToWorld };
};
// The seeded bucket map every draft starts from — the four WORLD_CATEGORIES
// with no `kind` yet. Spelled out (rather than derived from
// ensureDraftCategories) so a create payload assertion pins the literal wire
// shape instead of restating the implementation.
const seededCategories = () => ({
landscapes: { variations: [] },
environments: { variations: [] },
structures: { variations: [] },
vehicles: { variations: [] },
});
// A second universe to navigate to, for the tests that exercise a selection
// switch. Overridden per-test where the switch target needs its own references.
const universeTwo = { ...universe, id: 'u2', name: 'Second Universe', styleReferences: [] };
// Same as renderDraft, but with `selectedId` driven by rerender props so a test
// can switch universes mid-flight.
const renderSelectable = () => {
const goToWorld = vi.fn();
const hook = renderHook(
({ selectedId }) => useUniverseDraft({ selectedId, goToWorld }),
{ initialProps: { selectedId: 'u1' } },
);
return { ...hook, goToWorld };
};
describe('useUniverseDraft', () => {
it('refuses saving an outgoing draft while the selected universe is loading or failed, then retries', async () => {
const { result, rerender } = renderSelectable();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
let failRead;
apiMocks.getUniverse.mockImplementationOnce(() => new Promise((_resolve, reject) => { failRead = reject; }));
rerender({ selectedId: 'u2' });
await act(async () => { await result.current.handleSave(); });
expect(apiMocks.updateUniverse).not.toHaveBeenCalled();
await act(async () => failRead(new Error('World unavailable')));
expect(result.current.draftReadError).toBe('World unavailable');
await act(async () => { await result.current.handleSave(); });
expect(apiMocks.updateUniverse).not.toHaveBeenCalled();
apiMocks.getUniverse.mockResolvedValueOnce(universeTwo);
act(() => result.current.retryDraft());
await waitFor(() => expect(result.current.draftReady).toBe(true));
await act(async () => { await result.current.handleSave(); });
expect(apiMocks.updateUniverse).toHaveBeenCalledWith('u2', expect.objectContaining({ name: 'Second Universe' }), { silent: true });
});
it('does not rebaseline the new universe when an earlier save completes', async () => {
const { result, rerender } = renderSelectable();
await waitFor(() => expect(result.current.draftReady).toBe(true));
let finishSave;
apiMocks.updateUniverse.mockImplementationOnce(() => new Promise(resolve => { finishSave = resolve; }));
let pendingSave;
act(() => { pendingSave = result.current.handleSave(); });
apiMocks.getUniverse.mockResolvedValueOnce(universeTwo);
rerender({ selectedId: 'u2' });
await waitFor(() => expect(result.current.draft.id).toBe('u2'));
await act(async () => { finishSave({ ...universe, updatedAt: tickServerClock() }); await pendingSave; });
expect(result.current.draft.name).toBe('Second Universe');
expect(result.current.isDraftDirty()).toBe(false);
});
it('hydrates the selected universe and its run history', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.loading).toBe(false));
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
expect(result.current.draft.name).toBe('Example Universe');
expect(result.current.runs).toEqual([{ id: 'run-1' }]);
expect(result.current.isDraftDirty()).toBe(false);
});
describe('run history load state', () => {
it('reports a failed history read as an error, not an empty history, and retries without touching the draft', async () => {
apiMocks.listWorldRuns.mockRejectedValueOnce(new Error('boom'));
const { result } = renderDraft();
await waitFor(() => expect(result.current.runsStatus).toBe('error'));
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
expect(result.current.runs).toEqual([]);
act(() => result.current.updateDraft({ premise: 'Unsaved premise' }));
const getCalls = apiMocks.getUniverse.mock.calls.length;
await act(async () => { result.current.retryRuns(); });
await waitFor(() => expect(result.current.runsStatus).toBe('ready'));
expect(result.current.runs).toEqual([{ id: 'run-1' }]);
expect(result.current.draft.premise).toBe('Unsaved premise');
expect(apiMocks.getUniverse.mock.calls.length).toBe(getCalls);
});
it('keeps same-record rows when a refresh fails', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.runsStatus).toBe('ready'));
apiMocks.listWorldRuns.mockRejectedValueOnce(new Error('boom'));
await act(async () => { result.current.retryRuns(); });
await waitFor(() => expect(result.current.runsStatus).toBe('error'));
expect(result.current.runs).toEqual([{ id: 'run-1' }]);
});
it('drops a late history response for a universe that is no longer selected', async () => {
let resolveOld;
apiMocks.listWorldRuns.mockImplementation((id) => (id === 'u1'
? new Promise((resolve) => { resolveOld = resolve; })
: Promise.reject(new Error('boom'))));
const goToWorld = vi.fn();
const { result, rerender } = renderHook(
({ selectedId }) => useUniverseDraft({ selectedId, goToWorld }),
{ initialProps: { selectedId: 'u1' } },
);
rerender({ selectedId: 'u2' });
await waitFor(() => expect(result.current.runsStatus).toBe('error'));
await act(async () => { resolveOld([{ id: 'stale-run' }]); });
expect(result.current.runs).toEqual([]);
expect(result.current.runsStatus).toBe('error');
});
});
// A failed fetch and an empty response must not land in the same state. The refresh()
// fan-out used to `.catch(() => [])` / `.catch(() => ({}))` every call, so a transient
// failure was indistinguishable from a real empty answer — and for settings it was
// actively destructive, since deriving from a `{}` stand-in reset the user's saved
// image-gen mode and pipeline image config to defaults.
describe('refresh() failure handling', () => {
// NOTE: refresh() runs from a mount-only effect, so a rerender() does NOT re-run it.
// These tests invoke result.current.refresh() directly — otherwise the second load
// never happens and the assertions pass vacuously against untouched initial state.
it('keeps the last-known image-gen mode and config when the settings fetch fails', async () => {
apiMocks.getSettings.mockResolvedValue({ imageGen: { mode: 'local' }, localImageGen: {} });
const { result } = renderDraft();
await waitFor(() => expect(result.current.loading).toBe(false));
const modeBefore = result.current.defaultMode;
const cfgBefore = result.current.imageCfg;
const backendsBefore = result.current.availableBackends;
expect(modeBefore).toBeTruthy();
// Second load fails. Nothing derived from settings may change.
apiMocks.getSettings.mockRejectedValueOnce(new Error('network blip'));
await act(async () => { await result.current.refresh(); });
expect(result.current.defaultMode).toBe(modeBefore);
expect(result.current.imageCfg).toEqual(cfgBefore);
expect(result.current.availableBackends).toEqual(backendsBefore);
});
it('keeps the previously loaded providers and image models when their fetches fail', async () => {
apiMocks.getProviders.mockResolvedValue({
providers: [{ id: 'p1', name: 'Provider One' }], activeProvider: 'p1',
});
apiMocks.listImageModels.mockResolvedValue([{ id: 'm1' }]);
apiMocks.listLorasFull.mockResolvedValue([{ id: 'l1' }]);
const { result } = renderDraft();
await waitFor(() => expect(result.current.providers).toHaveLength(1));
apiMocks.getProviders.mockRejectedValueOnce(new Error('down'));
apiMocks.listImageModels.mockRejectedValueOnce(new Error('down'));
apiMocks.listLorasFull.mockRejectedValueOnce(new Error('down'));
await act(async () => { await result.current.refresh(); });
// Not wiped to [] — a failed read is not evidence that nothing is configured.
expect(result.current.providers).toEqual([{ id: 'p1', name: 'Provider One' }]);
expect(result.current.activeProviderId).toBe('p1');
expect(result.current.imageModels).toEqual([{ id: 'm1' }]);
expect(result.current.availableLoras).toEqual([{ id: 'l1' }]);
});
it('still applies a genuinely empty response (empty is not treated as failure)', async () => {
apiMocks.getProviders.mockResolvedValue({
providers: [{ id: 'p1', name: 'Provider One' }], activeProvider: 'p1',
});
apiMocks.listImageModels.mockResolvedValue([{ id: 'm1' }]);
const { result } = renderDraft();
await waitFor(() => expect(result.current.providers).toHaveLength(1));
apiMocks.getProviders.mockResolvedValueOnce({ providers: [], activeProvider: null });
apiMocks.listImageModels.mockResolvedValueOnce([]);
await act(async () => { await result.current.refresh(); });
expect(result.current.providers).toEqual([]);
expect(result.current.activeProviderId).toBe(null);
expect(result.current.imageModels).toEqual([]);
});
});
it('saves general draft edits without replacing canon when canon is clean', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
act(() => result.current.updateDraft({ premise: 'Changed premise' }));
expect(result.current.isDraftDirty()).toBe(true);
await act(async () => { await result.current.handleSave(); });
const payload = apiMocks.updateUniverse.mock.calls.at(-1)[1];
expect(payload.premise).toBe('Changed premise');
expect(payload).not.toHaveProperty('characters');
expect(result.current.isDraftDirty()).toBe(false);
});
it('marks the draft dirty when the factual toggle flips and ships it with Save', async () => {
// The regression: omitting `factual` from universeDraftSnapshot leaves the
// draft looking clean after the toggle, so Save is a no-op and the world
// silently stays fiction.
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
expect(result.current.draft.factual).toBe(false);
act(() => result.current.updateDraft({ factual: true }));
expect(result.current.isDraftDirty()).toBe(true);
await act(async () => { await result.current.handleSave(); });
expect(apiMocks.updateUniverse.mock.calls.at(-1)[1].factual).toBe(true);
act(() => result.current.updateDraft({ factual: false }));
await act(async () => { await result.current.handleSave(); });
expect(apiMocks.updateUniverse.mock.calls.at(-1)[1].factual).toBe(false);
});
// The render flow keys its per-row pending-job map on the id the SERVER
// stamped onto `entryJobs`. A board or variation created in this session has
// no id until a save mints one, so without adopting it the row can never match
// its own job — no spinner, no thumbnail until reload, and a pending entry
// with no consumer to clear it.
describe('adopting server-minted entry ids on save', () => {
it('backfills ids onto sheets and variations the save created', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
act(() => {
result.current.updateCompositeSheets([{ kind: 'reference_sheet', label: 'New board', prompt: 'p', locked: true }]);
result.current.updateCategory('heroes', [{ label: 'New hero', prompt: 'p' }]);
});
// The server sanitizer mints ids for both id-less entries.
apiMocks.updateUniverse.mockImplementationOnce(async (id, payload) => ({
...universe,
id,
compositeSheets: payload.compositeSheets.map((s) => ({ ...s, id: 'sheet-minted' })),
categories: {
heroes: { ...payload.categories.heroes, variations: [{ ...payload.categories.heroes.variations[0], id: 'var-minted' }] },
},
updatedAt: tickServerClock(),
}));
await act(async () => { await result.current.handleSave(); });
expect(result.current.draft.compositeSheets[0].id).toBe('sheet-minted');
expect(result.current.draft.categories.heroes.variations[0].id).toBe('var-minted');
// Adopting the ids is not a user edit — the page must not read as dirty.
expect(result.current.isDraftDirty()).toBe(false);
});
// The sanitizer echoes back any id the payload carried, so a row whose id the
// server confirms must keep it — re-keying it would strand an in-flight job.
it('keeps an id the saved record confirms', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
act(() => {
result.current.updateCompositeSheets([{ id: 'mine', kind: 'reference_sheet', label: 'Board', prompt: 'p', locked: true }]);
});
await act(async () => { await result.current.handleSave(); });
expect(result.current.draft.compositeSheets[0].id).toBe('mine');
expect(result.current.isDraftDirty()).toBe(false);
});
// The legacy shape: entries written before ids were persisted get a fresh
// uuid minted on every read, so this draft's copy is transient. POST /render
// persists a real set before queueing jobs against it — syncEntryIdsFromServer
// is what re-points the rows at those ids.
it('replaces transient ids with the persisted ones after a render migration', async () => {
apiMocks.getUniverse.mockResolvedValue({
...universe,
compositeSheets: [{ id: 'transient-1', kind: 'reference_sheet', label: 'Legacy board', prompt: 'p', locked: true }],
});
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.compositeSheets[0]?.id).toBe('transient-1'));
expect(result.current.isDraftDirty()).toBe(false);
apiMocks.getUniverse.mockResolvedValueOnce({
...universe,
compositeSheets: [{ id: 'persisted-1', kind: 'reference_sheet', label: 'Legacy board', prompt: 'p', locked: true }],
});
await act(async () => { await result.current.syncEntryIdsFromServer(); });
expect(result.current.draft.compositeSheets[0].id).toBe('persisted-1');
// Re-pointing an id is not a user edit.
expect(result.current.isDraftDirty()).toBe(false);
});
});
it('merges only pending canon additions onto a fresh server snapshot', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
apiMocks.getUniverse.mockResolvedValueOnce({
...universe,
characters: [{ name: 'Server Character' }],
});
act(() => {
result.current.setCanonDirty(true);
result.current.pendingCanonAdditionsRef.current.characters = [{ name: 'New Character' }];
});
await act(async () => { await result.current.handleSave(); });
const payload = apiMocks.updateUniverse.mock.calls.at(-1)[1];
expect(payload.characters.map((entry) => entry.name)).toEqual([
'Server Character',
'New Character',
]);
expect(payload.characters).not.toContainEqual({ name: 'Stale Draft Character' });
});
// ---- Art style references (#3109) ----
//
// These now assert the DELTA contract: each mutation sends only the change
// and the server applies it to the freshest persisted list inside the
// universe record's write queue. That removes the client-side base array
// whose staleness the previous six review-driven fixes were guarding —
// sequential-remove ordering, add/remove interleaving, cross-universe
// corruption, and the A→B→A round trip are all structurally impossible when
// the client never holds the array. What remains worth pinning is the
// request SHAPE, the display-side reconciliation (which universe's draft a
// response is allowed to touch), and the one race the server can't see: a
// hydration GET that raced a mutation and may carry a pre-write body.
it('adds a reference and adopted guidance in one request, without clearing unrelated dirty edits', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
act(() => result.current.updateDraft({ premise: 'Unsaved concurrent premise' }));
const reference = {
id: 'style-ref-1',
title: 'Ink wash',
prompt: 'Granular ink wash',
imageRefs: ['reference.png'],
};
await act(async () => {
await result.current.persistStyleReference({
reference,
proposed: {
styleNotes: 'Tactile and muted',
influences: { embrace: ['ink wash'], avoid: ['gloss'] },
},
adopt: true,
});
});
// The request carries the ADDITION plus the guidance the same write
// adopts — never a whole-array replace.
expect(apiMocks.addUniverseStyleReference).toHaveBeenCalledWith('u1', {
reference,
adopt: {
styleNotes: 'Tactile and muted',
influences: { embrace: ['ink wash'], avoid: ['gloss'] },
},
}, { silent: true });
expect(result.current.draft).toMatchObject({
premise: 'Unsaved concurrent premise',
styleNotes: 'Tactile and muted',
styleReferences: [reference],
});
expect(result.current.isDraftDirty()).toBe(true);
});
it('adds a reference without adopting guidance when the user declines the style guide', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
const reference = { id: 'style-ref-1', title: 'Ink wash', prompt: 'wash', imageRefs: ['a.png'] };
await act(async () => {
await result.current.persistStyleReference({
reference,
proposed: { styleNotes: 'Ignored', influences: { embrace: ['ignored'], avoid: [] } },
adopt: false,
});
});
// No `adopt` key at all — a reference-only add must not carry style
// guidance the user explicitly declined.
expect(apiMocks.addUniverseStyleReference).toHaveBeenCalledWith(
'u1',
{ reference, adopt: undefined },
{ silent: true },
);
expect(result.current.draft.styleNotes).toBe('');
});
it('removes one reference by id rather than patching the surviving list', async () => {
const reference = { id: 'style-ref-1', title: 'Ink wash', prompt: 'wash', imageRefs: ['a.png'] };
serverReferences.set('u1', [reference]);
apiMocks.getUniverse.mockResolvedValueOnce({ ...universe, styleReferences: [reference] });
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.styleReferences).toEqual([reference]));
await act(async () => { await result.current.removeStyleReference(reference.id); });
expect(apiMocks.removeUniverseStyleReference).toHaveBeenCalledWith('u1', reference.id, { silent: true });
expect(result.current.draft.styleReferences).toEqual([]);
});
it('removes both references when two removals fire before either request resolves', async () => {
const refA = { id: 'style-ref-a', title: 'Ref A', prompt: 'moody', imageRefs: ['a.png'] };
const refB = { id: 'style-ref-b', title: 'Ref B', prompt: 'bright', imageRefs: ['b.png'] };
serverReferences.set('u1', [refA, refB]);
apiMocks.getUniverse.mockResolvedValueOnce({ ...universe, styleReferences: [refA, refB] });
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.styleReferences).toEqual([refA, refB]));
// No client-side queue serializes these anymore — each request names only
// the id it removes, so whichever order the server applies them in, both
// removals survive. (Previously each had to carry the surviving array,
// which is what made ordering load-bearing.)
await act(async () => {
await Promise.all([
result.current.removeStyleReference(refA.id),
result.current.removeStyleReference(refB.id),
]);
});
expect(apiMocks.removeUniverseStyleReference.mock.calls.map((call) => call[1]))
.toEqual([refA.id, refB.id]);
expect(serverRefsFor('u1')).toEqual([]);
expect(result.current.draft.styleReferences).toEqual([]);
});
it('does not let an in-flight mutation for one universe touch a different, now-selected universe', async () => {
const refB2 = { id: 'style-ref-b2', title: 'Ref B2', prompt: 'b2', imageRefs: ['b2.png'] };
const universeTwoWithRef = { ...universeTwo, styleReferences: [refB2] };
apiMocks.getUniverse.mockImplementation(async (id) => (id === 'u2' ? universeTwoWithRef : universe));
const { result, rerender } = renderSelectable();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
// Start an add for u1 and hold its response open — simulates the user
// switching universes before it resolves.
let resolveU1Add;
apiMocks.addUniverseStyleReference.mockImplementationOnce(
() => new Promise((resolve) => { resolveU1Add = resolve; }),
);
const referenceForU1 = { id: 'style-ref-stale', title: 'Stale', prompt: 'stale', imageRefs: ['stale.png'] };
const staleSave = result.current.persistStyleReference({ reference: referenceForU1, adopt: false });
await act(async () => { rerender({ selectedId: 'u2' }); });
await waitFor(() => expect(result.current.draft.id).toBe('u2'));
expect(result.current.draft.styleReferences).toEqual([refB2]);
await act(async () => {
resolveU1Add({ ...universe, styleReferences: [referenceForU1] });
await staleSave;
});
// u2's displayed draft is untouched by u1's now-resolved response.
expect(result.current.draft.id).toBe('u2');
expect(result.current.draft.styleReferences).toEqual([refB2]);
// And a removal on u2 targets u2's own reference — no cross-universe leak.
await act(async () => { await result.current.removeStyleReference(refB2.id); });
expect(apiMocks.removeUniverseStyleReference).toHaveBeenLastCalledWith('u2', refB2.id, { silent: true });
});
it('re-reads instead of applying a hydration GET that raced a mutation (would blank the new reference)', async () => {
const refA = { id: 'style-ref-a', title: 'Ref A', prompt: 'a', imageRefs: ['a.png'] };
const refX = { id: 'style-ref-x', title: 'Ref X', prompt: 'x', imageRefs: ['x.png'] };
serverReferences.set('u1', [refA]);
// The re-hydration fetch on the return to u1 is held open so it can resolve
// AFTER the mutation, carrying the PRE-mutation body the server would have
// returned had it read before the add landed. The client can't tell that
// from the response alone — hence the re-read.
let serverStyleNotes = '';
let serverUpdatedAt = universe.updatedAt;
let u1Fetches = 0;
let resolveU1Hydration;
apiMocks.getUniverse.mockImplementation(async (id) => {
if (id === 'u2') return universeTwo;
u1Fetches += 1;
if (u1Fetches === 2) return new Promise((resolve) => { resolveU1Hydration = resolve; });
return {
...universe,
styleReferences: serverRefsFor('u1'),
styleNotes: serverStyleNotes,
updatedAt: serverUpdatedAt,
};
});
const { result, rerender } = renderSelectable();
await waitFor(() => expect(result.current.draft.styleReferences).toEqual([refA]));
let resolveU1Add;
apiMocks.addUniverseStyleReference.mockImplementationOnce(
() => new Promise((resolve) => { resolveU1Add = resolve; }),
);
const pendingAdd = result.current.persistStyleReference({
reference: refX,
proposed: { styleNotes: 'Adopted notes', influences: { embrace: ['ink'], avoid: [] } },
adopt: true,
});
// u1 -> u2 -> u1; the return issues re-hydration GET G, held pending.
await act(async () => { rerender({ selectedId: 'u2' }); });
await waitFor(() => expect(result.current.draft.id).toBe('u2'));
await act(async () => { rerender({ selectedId: 'u1' }); });
await waitFor(() => expect(resolveU1Hydration).toBeTypeOf('function'));
// The add resolves first — the reordering this guard exists for. It advances
// the server clock, which is what makes G's older body detectable.
const addUpdatedAt = tickServerClock();
await act(async () => {
serverReferences.set('u1', [refA, refX]);
serverStyleNotes = 'Adopted notes';
serverUpdatedAt = addUpdatedAt;
resolveU1Add({
...universe,
styleReferences: [refA, refX],
styleNotes: 'Adopted notes',
influences: { embrace: ['ink'], avoid: [] },
updatedAt: addUpdatedAt,
});
await pendingAdd;
});
// ...then G resolves carrying the stale, pre-mutation body. The hook
// re-reads (fetch 3, which sees the committed write) rather than applying
// it, so both the reference AND the guidance the same write adopted stand.
await act(async () => {
resolveU1Hydration({
...universe, styleReferences: [refA], styleNotes: '', updatedAt: universe.updatedAt,
});
await Promise.resolve();
});
await waitFor(() => expect(result.current.draft.styleReferences).toEqual([refA, refX]));
expect(result.current.draft.styleNotes).toBe('Adopted notes');
// markDraftSaved banked the re-read values, so the adopted guidance is not
// silently re-saved as the stale '' on the next general Save.
expect(result.current.isDraftDirty()).toBe(false);
});
it('does not re-read when the hydration GET already contains the mutation', async () => {
// The other half of the gate: it compares the BODY's clock against the newest
// write seen, not merely "did a write happen" — so the common overlap, where
// the GET was served after the write committed, costs no extra round-trip.
const refX = { id: 'style-ref-x', title: 'Ref X', prompt: 'x', imageRefs: ['x.png'] };
let serverUpdatedAt = universe.updatedAt;
apiMocks.getUniverse.mockImplementation(async (id) => (id === 'u2'
? universeTwo
: { ...universe, styleReferences: serverRefsFor('u1'), updatedAt: serverUpdatedAt }));
const { result, rerender } = renderSelectable();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
apiMocks.addUniverseStyleReference.mockImplementationOnce(async (id, { reference }) => {
serverReferences.set(id, [...serverRefsFor(id), reference]);
serverUpdatedAt = tickServerClock();
return { ...universe, id, styleReferences: serverRefsFor(id), updatedAt: serverUpdatedAt };
});
await act(async () => {
await result.current.persistStyleReference({ reference: refX, adopt: false });
});
const fetchesBefore = apiMocks.getUniverse.mock.calls.length;
await act(async () => { rerender({ selectedId: 'u2' }); });
await waitFor(() => expect(result.current.draft.id).toBe('u2'));
await act(async () => { rerender({ selectedId: 'u1' }); });
await waitFor(() => expect(result.current.draft.styleReferences).toEqual([refX]));
// One GET for u2, one for u1 — no third (re-read) call.
expect(apiMocks.getUniverse.mock.calls.length).toBe(fetchesBefore + 2);
});
it('re-reads after a general Save that a hydration GET raced, not just a reference mutation', async () => {
// The stale-GET guard keys on the server's clock rather than on anything
// style-reference-specific, so every writer that stamps its response is
// covered — including handleSave. Without that, a save → navigate away →
// back round trip could show the pre-save record.
let serverPremise = 'Original premise';
let serverUpdatedAt = universe.updatedAt;
let u1Fetches = 0;
let resolveU1Hydration;
apiMocks.getUniverse.mockImplementation(async (id) => {
if (id === 'u2') return universeTwo;
u1Fetches += 1;
if (u1Fetches === 2) return new Promise((resolve) => { resolveU1Hydration = resolve; });
return { ...universe, premise: serverPremise, updatedAt: serverUpdatedAt };
});
const { result, rerender } = renderSelectable();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
act(() => result.current.updateDraft({ premise: 'Saved premise' }));
// handleSave sets `saving` synchronously before its first await, so the call
// itself has to be inside act() (unlike the reference mutators).
let resolveSave;
let pendingSave;
apiMocks.updateUniverse.mockImplementationOnce(() => new Promise((resolve) => { resolveSave = resolve; }));
await act(async () => { pendingSave = result.current.handleSave(); });
await act(async () => { rerender({ selectedId: 'u2' }); });
await waitFor(() => expect(result.current.draft.id).toBe('u2'));
await act(async () => { rerender({ selectedId: 'u1' }); });
await waitFor(() => expect(resolveU1Hydration).toBeTypeOf('function'));
const savedAt = tickServerClock();
await act(async () => {
serverPremise = 'Saved premise';
serverUpdatedAt = savedAt;
resolveSave({ ...universe, premise: 'Saved premise', updatedAt: savedAt });
await pendingSave;
});
await act(async () => {
resolveU1Hydration({ ...universe, premise: 'Original premise', updatedAt: universe.updatedAt });
await Promise.resolve();
});
await waitFor(() => expect(result.current.draft.premise).toBe('Saved premise'));
});
it('tracks a directly marked import response before a hydration GET can overwrite it', async () => {
let serverUpdatedAt = universe.updatedAt;
let u1Fetches = 0;
let resolveStaleHydration;
apiMocks.getUniverse.mockImplementation(async (id) => {
if (id === 'u2') return universeTwo;
u1Fetches += 1;
if (u1Fetches === 2) return new Promise((resolve) => { resolveStaleHydration = resolve; });
return { ...universe, premise: 'Imported premise', updatedAt: serverUpdatedAt };
});
const { result, rerender } = renderSelectable();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
const importedAt = tickServerClock();
const imported = { ...universe, premise: 'Imported premise', updatedAt: importedAt };
await act(async () => {
serverUpdatedAt = importedAt;
result.current.setDraft(imported);
result.current.markDraftSaved(imported);
});
await act(async () => { rerender({ selectedId: 'u2' }); });
await waitFor(() => expect(result.current.draft.id).toBe('u2'));
await act(async () => { rerender({ selectedId: 'u1' }); });
await waitFor(() => expect(resolveStaleHydration).toBeTypeOf('function'));
await act(async () => {
resolveStaleHydration({ ...universe, premise: 'Original premise', updatedAt: universe.updatedAt });
await Promise.resolve();
});
await waitFor(() => expect(result.current.draft.premise).toBe('Imported premise'));
expect(u1Fetches).toBe(3);
});
it('lets an un-raced hydration carry a peer edit the client never wrote', async () => {
// The mirror of the test above: with no mutation in flight, the GET is
// authoritative — including for writers the client can't see (peer sync,
// the image-delete purge). The old design cached a base array here and
// needed an epoch to avoid shadowing them; now there is nothing to shadow.
const refPeer = { id: 'style-ref-peer', title: 'Peer', prompt: 'peer', imageRefs: ['peer.png'] };
let u1Fetches = 0;
apiMocks.getUniverse.mockImplementation(async (id) => {
if (id === 'u2') return universeTwo;
u1Fetches += 1;
return u1Fetches === 1
? { ...universe, styleReferences: [], styleNotes: '' }
: { ...universe, styleReferences: [refPeer], styleNotes: 'Peer notes' };
});
const { result, rerender } = renderSelectable();
await waitFor(() => expect(result.current.draft.styleReferences).toEqual([]));
await act(async () => { rerender({ selectedId: 'u2' }); });
await waitFor(() => expect(result.current.draft.id).toBe('u2'));
await act(async () => { rerender({ selectedId: 'u1' }); });
await waitFor(() => expect(result.current.draft.styleReferences).toEqual([refPeer]));
expect(result.current.draft.styleNotes).toBe('Peer notes');
});
it('surfaces a failed add without touching the draft', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
apiMocks.addUniverseStyleReference.mockRejectedValueOnce(new Error('at capacity'));
let ok;
await act(async () => {
ok = await result.current.persistStyleReference({
reference: { id: 'style-ref-1', title: 'T', prompt: 'p', imageRefs: ['a.png'] },
adopt: false,
});
});
expect(ok).toBe(false);
expect(toastMock.error).toHaveBeenCalledWith('Reference save failed: at capacity');
expect(result.current.draft.styleReferences).toEqual([]);
});
// ---- Destructive: delete (#3290) ----
describe('handleDelete', () => {
it('drops the universe from the list, clears the draft, and navigates away', async () => {
const { result, goToWorld } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
act(() => result.current.setPendingDeleteId('u1'));
await act(async () => { await result.current.handleDelete(); });
expect(apiMocks.deleteUniverse).toHaveBeenCalledWith('u1', { silent: true });
expect(result.current.universes).toEqual([]);
expect(result.current.draft.id).toBeUndefined();
expect(result.current.draft.name).toBe('');
expect(result.current.pendingDeleteId).toBe(null);
expect(goToWorld).toHaveBeenCalledWith(null);
expect(toastMock.success).toHaveBeenCalledWith('World deleted');
});
// The failure path is the one that matters: a delete that 500s must leave
// the user exactly where they were, still looking at the record. Navigating
// away (or filtering the list) on a failed delete would make a live
// universe look gone until the next reload.
it('keeps the universe and stays put when the delete fails', async () => {
const { result, goToWorld } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
apiMocks.deleteUniverse.mockRejectedValueOnce(new Error('record is locked'));
await act(async () => { await result.current.handleDelete(); });
expect(toastMock.error).toHaveBeenCalledWith('Delete failed: record is locked');
expect(result.current.universes).toEqual([universe]);
expect(result.current.draft.id).toBe('u1');
expect(goToWorld).not.toHaveBeenCalled();
expect(toastMock.success).not.toHaveBeenCalledWith('World deleted');
});
it('is a no-op on an unsaved universe', async () => {
const { result, goToWorld } = renderUnsaved();
await waitFor(() => expect(result.current.loading).toBe(false));
await act(async () => { await result.current.handleDelete(); });
expect(apiMocks.deleteUniverse).not.toHaveBeenCalled();
expect(goToWorld).not.toHaveBeenCalled();
});
});
// ---- Fire-and-forget PATCHes: exact wire bodies (#3290) ----
//
// Each of these sends a targeted PATCH whose body the mocked api module can
// never validate. The server's patchSchema is built from `.strict()` pieces
// (lockedSchema, influencesSchema) and refuses an empty patch outright, so a
// body that drifts here 400s in production behind a green suite. These
// assertions therefore pin the EXACT object handed to updateUniverse, not
// just "some call happened".
describe('toggleLock', () => {
it('PATCHes only the lock map when a field is locked, and again when it is cleared', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
await act(async () => { result.current.toggleLock('logline'); });
expect(apiMocks.updateUniverse).toHaveBeenLastCalledWith(
'u1',
{ locked: { logline: true } },
{ silent: true },
);
expect(result.current.draft.locked).toEqual({ logline: true });
// Unlocking DELETES the key rather than writing `false` — the stored map
// is sparse, and lockedSchema is strict about nothing else riding along.
await act(async () => { result.current.toggleLock('logline'); });
expect(apiMocks.updateUniverse).toHaveBeenLastCalledWith(
'u1',
{ locked: {} },
{ silent: true },
);
expect(result.current.draft.locked).toEqual({});
});
// Two clicks inside one tick: the lock map has to compose across them.
// `draftRef` is normally refreshed by a passive effect that runs a commit
// later, so a naive read of it would let the second toggle re-send the
// first's write and leave the field locked forever.
it('composes back-to-back toggles that land before a re-render', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
await act(async () => {
result.current.toggleLock('logline');
result.current.toggleLock('logline');
});
expect(apiMocks.updateUniverse.mock.calls.map((call) => call[1]))
.toEqual([{ locked: { logline: true } }, { locked: {} }]);
expect(result.current.draft.locked).toEqual({});
});
// The server replaces `locked` wholesale per PATCH, so if those two writes
// reached it reversed the record would persist the lock the user just
// cleared. Holding the first request open proves the second is not even
// issued until it settles.
it('holds the second lock write until the first has settled', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
let releaseFirst;
apiMocks.updateUniverse.mockImplementationOnce(
() => new Promise((resolve) => { releaseFirst = resolve; }),
);
await act(async () => {
result.current.toggleLock('logline');
result.current.toggleLock('logline');
});
expect(apiMocks.updateUniverse).toHaveBeenCalledTimes(1);
await act(async () => { releaseFirst({ ...universe, locked: { logline: true } }); });
expect(apiMocks.updateUniverse).toHaveBeenCalledTimes(2);
expect(apiMocks.updateUniverse).toHaveBeenLastCalledWith(
'u1',
{ locked: {} },
{ silent: true },
);
});
// The tail is per universe, not per hook. A request has no timeout, so one
// stalled write for the universe the user just left must not block every
// lock on the one they navigated to — silently, since the draft still
// updates optimistically either way.
it('does not let a stalled lock write for one universe block another', async () => {
apiMocks.getUniverse.mockImplementation(async (id) => (id === 'u2' ? universeTwo : universe));
const { result, rerender } = renderSelectable();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
// u1's lock write never settles.
apiMocks.updateUniverse.mockImplementationOnce(() => new Promise(() => {}));
await act(async () => { result.current.toggleLock('logline'); });
expect(apiMocks.updateUniverse).toHaveBeenCalledTimes(1);
await act(async () => { rerender({ selectedId: 'u2' }); });
await waitFor(() => expect(result.current.draft.id).toBe('u2'));
await act(async () => { result.current.toggleLock('premise'); });
expect(apiMocks.updateUniverse).toHaveBeenCalledTimes(2);
expect(apiMocks.updateUniverse).toHaveBeenLastCalledWith(
'u2',
{ locked: { premise: true } },
{ silent: true },
);
});
it('accepts the per-influence-list lock keys, not just the bible scalars', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
await act(async () => { result.current.toggleLock('influencesEmbrace'); });
// `influencesEmbrace` / `influencesAvoid` are real LOCKABLE_FIELDS keys;
// the legacy whole-block `influences` key is not what the UI writes.
expect(apiMocks.updateUniverse).toHaveBeenLastCalledWith(
'u1',
{ locked: { influencesEmbrace: true } },
{ silent: true },
);
});
it('ignores a field that is not lockable', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
await act(async () => { result.current.toggleLock('categories'); });
expect(apiMocks.updateUniverse).not.toHaveBeenCalled();
expect(result.current.draft.locked).toEqual({});
});
it('updates the draft without PATCHing an unsaved universe', async () => {
const { result } = renderUnsaved();
await waitFor(() => expect(result.current.loading).toBe(false));
await act(async () => { result.current.toggleLock('premise'); });
expect(result.current.draft.locked).toEqual({ premise: true });
expect(apiMocks.updateUniverse).not.toHaveBeenCalled();
});
// Regression (#3290): the PATCH used to be issued from inside the setDraft
// updater. React may invoke an updater more than once per setState — under
// StrictMode it always does — so a single lock click sent two identical
// PATCHes. State updaters must be pure; the request belongs beside
// setRenderPin's, outside the updater.
it('sends exactly one PATCH per toggle under StrictMode', async () => {
const { result } = renderDraft({ wrapper: StrictMode });
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
await act(async () => { result.current.toggleLock('logline'); });
expect(apiMocks.updateUniverse).toHaveBeenCalledTimes(1);
expect(result.current.draft.locked).toEqual({ logline: true });
});
it('surfaces a failed lock save', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
apiMocks.updateUniverse.mockRejectedValueOnce(new Error('write queue busy'));
await act(async () => { result.current.toggleLock('premise'); });
expect(toastMock.error).toHaveBeenCalledWith('Lock save failed: write queue busy');
});
});
describe('setRenderPin', () => {
it('PATCHes both pin fields together and mirrors them onto the draft', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
await act(async () => {
result.current.setRenderPin({ imageMode: 'local', imageModelId: null });
});
expect(apiMocks.updateUniverse).toHaveBeenLastCalledWith(
'u1',
{ imageMode: 'local', imageModelId: null },
{ silent: true },
);
expect(result.current.draft).toMatchObject({ imageMode: 'local', imageModelId: null });
});
// Clearing the pin must send explicit nulls, never omit the keys: an
// all-undefined body JSON.stringifies to `{}`, which the server's
// "patch must include at least one field" refinement rejects — and
// key-absent means "preserve" there, so the pin would never clear.
it('clears the pin with explicit nulls rather than an empty patch', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
await act(async () => {
result.current.setRenderPin({ imageMode: null, imageModelId: null });
});
const body = apiMocks.updateUniverse.mock.calls.at(-1)[1];
expect(body).toEqual({ imageMode: null, imageModelId: null });
expect(Object.keys(JSON.parse(JSON.stringify(body)))).toEqual(['imageMode', 'imageModelId']);
});
it('updates the draft without PATCHing an unsaved universe', async () => {
const { result } = renderUnsaved();
await waitFor(() => expect(result.current.loading).toBe(false));
await act(async () => {
result.current.setRenderPin({ imageMode: 'agy', imageModelId: 'imagen-3' });
});
expect(result.current.draft).toMatchObject({ imageMode: 'agy', imageModelId: 'imagen-3' });
expect(apiMocks.updateUniverse).not.toHaveBeenCalled();
});
it('surfaces a failed pin save', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
apiMocks.updateUniverse.mockRejectedValueOnce(new Error('unknown model'));
await act(async () => {
result.current.setRenderPin({ imageMode: 'agy', imageModelId: 'nope' });
});
expect(toastMock.error).toHaveBeenCalledWith('Render pin save failed: unknown model');
});
});
describe('assignBucketKind', () => {
it('PATCHes only the moved bucket, keyed by bucket name', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
await act(async () => { await result.current.assignBucketKind('heroes', 'places'); });
// A single-key `categories` map: the server merges per bucket key, so
// sending the whole map would be both wasteful and a clobber risk.
expect(apiMocks.updateUniverse).toHaveBeenLastCalledWith(
'u1',
{ categories: { heroes: { kind: 'places', variations: [] } } },
{ silent: true },
);
expect(result.current.draft.categories.heroes.kind).toBe('places');
expect(result.current.universes[0].categories.heroes.kind).toBe('places');
expect(toastMock.success).toHaveBeenCalledWith('Moved "Heroes" to Places');
});
it('tags the bucket locally and defers to Save on an unsaved universe', async () => {
const { result } = renderUnsaved();
await waitFor(() => expect(result.current.loading).toBe(false));
await act(async () => { await result.current.assignBucketKind('landscapes', 'places'); });
expect(apiMocks.updateUniverse).not.toHaveBeenCalled();
expect(result.current.draft.categories.landscapes).toEqual({ kind: 'places', variations: [] });
expect(toastMock.success).toHaveBeenCalledWith('Tagged "Landscapes" as Places — save to persist');
});
it('ignores an unknown trunk kind or an unknown bucket', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
await act(async () => {
await result.current.assignBucketKind('heroes', 'sidekicks');
await result.current.assignBucketKind('no-such-bucket', 'places');
});
expect(apiMocks.updateUniverse).not.toHaveBeenCalled();
expect(result.current.draft.categories.heroes.kind).toBe('characters');
});
it('surfaces a failed move and leaves the list untouched', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
apiMocks.updateUniverse.mockRejectedValueOnce(new Error('bucket cap reached'));
await act(async () => { await result.current.assignBucketKind('heroes', 'objects'); });
expect(toastMock.error).toHaveBeenCalledWith('Move failed: bucket cap reached');
// The optimistic local move stands (same contract as toggleLock /
// setRenderPin); only the shared list is left alone.
expect(result.current.universes[0].categories.heroes.kind).toBe('characters');
});
});
// ---- Local category + draft editors (#3290) ----
describe('addCategory', () => {
it('normalizes the typed name into a bucket key and clears the input', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
act(() => result.current.setNewCategoryName('Ancient Ruins & Relics'));
act(() => result.current.addCategory());
expect(result.current.draft.categories.ancient_ruins_and_relics).toEqual({ variations: [] });
expect(result.current.newCategoryName).toBe('');
expect(toastMock.error).not.toHaveBeenCalled();
});
it('rejects a name that normalizes onto an existing bucket', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
// 'Heroes' normalizes to the `heroes` key the universe already has.
act(() => result.current.setNewCategoryName('Heroes'));
act(() => result.current.addCategory());
expect(toastMock.error).toHaveBeenCalledWith('Category already exists');
// Untouched — including the input, so the user can correct it in place.
expect(result.current.draft.categories.heroes).toEqual({ kind: 'characters', variations: [] });
expect(result.current.newCategoryName).toBe('Heroes');
});
it('rejects a name with no usable characters', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
const before = result.current.draft.categories;
act(() => result.current.setNewCategoryName('!!! ???'));
act(() => result.current.addCategory());
expect(toastMock.error).toHaveBeenCalledWith('Use letters or numbers for the category name');
expect(result.current.draft.categories).toEqual(before);
});
});
describe('removeCategory', () => {
it('removes a custom bucket outright', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
act(() => result.current.removeCategory('heroes'));
expect(result.current.draft.categories).not.toHaveProperty('heroes');
expect(result.current.draft.categories).toEqual(seededCategories());
});
// A built-in bucket can't actually be removed — the server re-seeds all
// four WORLD_CATEGORIES on every read, so removing one empties it instead.
// Mirroring that here keeps the draft from showing a bucket-shaped hole the
// next hydration would fill back in.
it('empties rather than deletes a built-in bucket', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
const variation = { id: 'v1', label: 'Salt flats', prompt: 'a cracked white plain' };
act(() => result.current.updateCategory('landscapes', [variation]));
expect(result.current.draft.categories.landscapes.variations).toEqual([variation]);
act(() => result.current.removeCategory('landscapes'));
expect(result.current.draft.categories.landscapes).toEqual({ variations: [] });
});
});
it('updateCategory replaces one bucket\'s variations while preserving its kind', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
const variation = { id: 'v1', label: 'Scout', prompt: 'a wiry outrider' };
act(() => result.current.updateCategory('heroes', [variation]));
expect(result.current.draft.categories.heroes).toEqual({
kind: 'characters',
variations: [variation],
});
expect(result.current.isDraftDirty()).toBe(true);
// Local edit only — it rides along on the next general Save.
expect(apiMocks.updateUniverse).not.toHaveBeenCalled();
});
it('updateCompositeSheets replaces the sheet list on the draft', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
const sheets = [{ id: 's1', kind: 'reference_sheet', label: 'Cast board', prompt: 'six figures' }];
act(() => result.current.updateCompositeSheets(sheets));
expect(result.current.draft.compositeSheets).toEqual(sheets);
expect(result.current.isDraftDirty()).toBe(true);
expect(apiMocks.updateUniverse).not.toHaveBeenCalled();
});
// ---- Save preflight + canon reconciliation (#3290) ----
describe('flushDraftIfDirty', () => {
it('reports success without saving when the draft is clean', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
let flushed;
await act(async () => { flushed = await result.current.flushDraftIfDirty(); });
expect(flushed).toBe(true);
expect(apiMocks.updateUniverse).not.toHaveBeenCalled();
});
it('saves a dirty draft first so the server acts on what the user sees', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
act(() => result.current.updateDraft({ premise: 'Pre-flight premise' }));
let flushed;
await act(async () => { flushed = await result.current.flushDraftIfDirty(); });
expect(flushed).toBe(true);
expect(apiMocks.updateUniverse.mock.calls.at(-1)[1].premise).toBe('Pre-flight premise');
expect(result.current.isDraftDirty()).toBe(false);
});
it('reports failure when the preflight save fails, so the caller aborts', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
act(() => result.current.updateDraft({ premise: 'Doomed premise' }));
apiMocks.updateUniverse.mockRejectedValueOnce(new Error('disk full'));
let flushed;
await act(async () => { flushed = await result.current.flushDraftIfDirty(); });
expect(flushed).toBe(false);
expect(toastMock.error).toHaveBeenCalledWith('Save failed: disk full');
});
});
describe('handleCanonChange', () => {
it('adopts the canon editor\'s arrays wholesale when nothing is pending', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
act(() => result.current.handleCanonChange({
characters: [{ name: 'Editor Character' }],
places: [{ name: 'Editor Place' }],
objects: [],
updatedAt: '2026-02-02T00:00:00.000Z',
}));
expect(result.current.draft.characters).toEqual([{ name: 'Editor Character' }]);
expect(result.current.draft.places).toEqual([{ name: 'Editor Place' }]);
expect(result.current.draft.objects).toEqual([]);
expect(result.current.draft.updatedAt).toBe('2026-02-02T00:00:00.000Z');
});
it('preserves unsaved additions when canon is dirty', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
act(() => {
result.current.setCanonDirty(true);
result.current.pendingCanonAdditionsRef.current.characters = [{ name: 'Pending Character' }];
});
act(() => result.current.handleCanonChange({
characters: [{ name: 'Editor Character' }],
places: [],
objects: [],
updatedAt: '2026-02-02T00:00:00.000Z',
}));
// The editor's list wins on collision; the not-yet-saved addition is
// appended rather than dropped on the floor.
expect(result.current.draft.characters.map((entry) => entry.name))
.toEqual(['Editor Character', 'Pending Character']);
});
it('ignores a null payload', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
act(() => result.current.handleCanonChange(null));
expect(result.current.draft.characters).toEqual([{ name: 'Stale Draft Character' }]);
});
});
// ---- Create-a-second-universe from the name field (#3290) ----
describe('handleCreateNamed', () => {
it('creates a blank universe alongside the selected one and navigates to it', async () => {
const { result, goToWorld } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
await act(async () => { await result.current.handleCreateNamed(' Spin-off World '); });
// A named-create is deliberately EMPTY apart from the name — it must not
// carry the currently open universe's bible over to the new record.
expect(apiMocks.createUniverse).toHaveBeenCalledWith({
name: 'Spin-off World',
starterPrompt: '',
logline: '',
premise: '',
styleNotes: '',
factual: false,
moodBoardId: null,
categories: seededCategories(),
compositeSheets: [],
influences: { embrace: [], avoid: [] },
styleReferences: [],
locked: {},
llm: { provider: null, model: null },
}, { silent: true });
expect(apiMocks.updateUniverse).not.toHaveBeenCalled();
expect(result.current.universes[0].id).toBe('u-new');
expect(goToWorld).toHaveBeenCalledWith('u-new');
expect(toastMock.success).toHaveBeenCalledWith('World created');
});
it('rejects an all-whitespace name before touching the server', async () => {
const { result } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
await act(async () => { await result.current.handleCreateNamed(' '); });
expect(toastMock.error).toHaveBeenCalledWith('Name is required');
expect(apiMocks.createUniverse).not.toHaveBeenCalled();
});
it('falls through to the normal Save on an unsaved universe', async () => {
const { result, goToWorld } = renderUnsaved();
await waitFor(() => expect(result.current.loading).toBe(false));
act(() => result.current.updateDraft({ name: 'Fresh World', premise: 'Typed premise' }));
await act(async () => { await result.current.handleCreateNamed('Fresh World'); });
// handleSave's payload, not the blank-draft one — the premise the user
// already typed has to survive the create.
const payload = apiMocks.createUniverse.mock.calls.at(-1)[0];
expect(payload).toMatchObject({ name: 'Fresh World', premise: 'Typed premise' });
expect(payload.characters).toEqual([]);
expect(goToWorld).toHaveBeenCalledWith('u-new');
});
it('surfaces a failed create and stays on the current universe', async () => {
const { result, goToWorld } = renderDraft();
await waitFor(() => expect(result.current.draft.id).toBe('u1'));
apiMocks.createUniverse.mockRejectedValueOnce(new Error('name taken'));
await act(async () => { await result.current.handleCreateNamed('Spin-off World'); });
expect(toastMock.error).toHaveBeenCalledWith('Create failed: name taken');
expect(result.current.universes).toEqual([universe]);
expect(result.current.saving).toBe(false);
expect(goToWorld).not.toHaveBeenCalled();
});
});
});
// The universe's own backend pin (Render tab → "This universe's default") has to
// reach the per-entry render config, not just the batch form: the cast / places /
// objects rows POST `/api/image-gen/generate` with an EXPLICIT `mode` taken from
// `imageCfg`, and an explicit mode outranks the record pin on the server ladder.
// Before this, an agy-pinned universe rendered its cast on the install default.
describe('imageCfg — universe render pin', () => {
const CLOUD_ON = { codex: { enabled: true }, agy: { enabled: true } };
it('folds the universe pin over the install-wide settings default', async () => {
apiMocks.getSettings.mockResolvedValue({ imageGen: CLOUD_ON });
apiMocks.listUniverses.mockResolvedValue([{ ...universe, imageMode: 'agy' }]);
apiMocks.getUniverse.mockResolvedValue({ ...universe, imageMode: 'agy' });
const { result } = renderDraft();
// readPipelineImageSettings prefers codex when it's enabled, so 'agy' can
// only come from the record pin.
await waitFor(() => expect(result.current.imageCfg.mode).toBe('agy'));
});
it('keeps the install-wide default for an unpinned universe', async () => {
apiMocks.getSettings.mockResolvedValue({ imageGen: CLOUD_ON });
const { result } = renderDraft();
await waitFor(() => expect(result.current.loading).toBe(false));
expect(result.current.imageCfg.mode).toBe('codex');
});
// The batch form's default mode and the per-entry cfg must agree — they are
// the same ladder, and a page that renders its cast on agy while its batch
// form says codex is the inconsistency this whole change is about.
it('resolves the batch form default mode through the same ladder', async () => {
apiMocks.getSettings.mockResolvedValue({ imageGen: { mode: 'codex', ...CLOUD_ON } });
apiMocks.listUniverses.mockResolvedValue([{ ...universe, imageMode: 'agy' }]);
apiMocks.getUniverse.mockResolvedValue({ ...universe, imageMode: 'agy' });
const { result } = renderDraft();
await waitFor(() => expect(result.current.effectiveDefaultMode).toBe('agy'));
expect(result.current.imageCfg.mode).toBe('agy');
});
it('ignores a pin whose backend this install no longer has enabled', async () => {
apiMocks.getSettings.mockResolvedValue({ imageGen: { codex: { enabled: true } } });
apiMocks.listUniverses.mockResolvedValue([{ ...universe, imageMode: 'agy' }]);
apiMocks.getUniverse.mockResolvedValue({ ...universe, imageMode: 'agy' });
const { result } = renderDraft();
await waitFor(() => expect(result.current.loading).toBe(false));
expect(result.current.imageCfg.mode).toBe('codex');
});
// The rung between the record pin and the install default. Batch renders and
// character sheets already resolved it server-side, so omitting it here made
// two surfaces on one page disagree about the backend.
it("falls through an unpinned universe to the Universe Bible renderDefaults pin", async () => {
apiMocks.getSettings.mockResolvedValue({
imageGen: CLOUD_ON,
renderDefaults: { 'universe-bible': { imageMode: 'agy', imageModel: 'gemini-3.5-pro' } },
});
const { result } = renderDraft();
await waitFor(() => expect(result.current.imageCfg.mode).toBe('agy'));
expect(result.current.imageCfg.cloudModel).toBe('gemini-3.5-pro');
// The batch form's default mode runs the same ladder.
expect(result.current.effectiveDefaultMode).toBe('agy');
});
});