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

fix(create): offer contextual unlock before reference rendering

Adam Eivy3ad4230eabdd
diff --git a/client/src/components/catalog/CatalogUnlockNotice.jsx b/client/src/components/catalog/CatalogUnlockNotice.jsx
new file mode 100644
index 0000000000..4c8737d547
--- /dev/null
+++ b/client/src/components/catalog/CatalogUnlockNotice.jsx
@@ -0,0 +1,76 @@
+import { useRef, useState } from 'react';
+import { Loader2, Unlock } from 'lucide-react';
+import useMounted from '../../hooks/useMounted';
+import { getCatalogIngredientDetails, updateCatalogIngredient } from '../../services/apiCatalog';
+import { getUniverse, setUniverseCanonLock } from '../../services/apiUniverseBuilder';
+
+/** Resolve a render's lock in place without saving the editor's draft or rendering. */
+export default function CatalogUnlockNotice({ record, disabled = false, onUnlocked, onPendingChange }) {
+ const mounted = useMounted();
+ const inFlight = useRef(false);
+ const [pending, setPending] = useState(false);
+ const [error, setError] = useState(null);
+ const [unlocked, setUnlocked] = useState(false);
+ const locked = record.payload?.locked === true;
+
+ const unlock = async () => {
+ if (inFlight.current || disabled || !locked) return;
+ inFlight.current = true;
+ setPending(true);
+ onPendingChange(true);
+ setError(null);
+ try {
+ const details = await getCatalogIngredientDetails(record.id, { silent: true });
+ if (!mounted.current) return;
+ const current = details?.ingredient;
+ if (!current) throw new Error('This record is no longer available.');
+ const field = { character: 'characters', place: 'places', object: 'objects' }[current.type];
+ let canonTarget = null;
+ for (const ref of details.refs || []) {
+ if (!field || ref.refKind !== 'universe') continue;
+ const universe = await getUniverse(ref.refId, { silent: true }).catch((err) => {
+ if (err?.status === 404 || err?.code === 'NOT_FOUND') return null;
+ throw err;
+ });
+ if (!mounted.current) return;
+ const entry = universe?.[field]?.find((item) => item.ingredientId === record.id);
+ if (entry) { canonTarget = { universeId: ref.refId, entryId: entry.id }; break; }
+ }
+ if (canonTarget) {
+ await setUniverseCanonLock(canonTarget.universeId, current.type, canonTarget.entryId, false, { silent: true });
+ } else if (current.payload?.locked === true) {
+ await updateCatalogIngredient(record.id, { payload: { ...current.payload, locked: false } }, { silent: true });
+ }
+ if (!mounted.current) return;
+ // Canon projection can fail independently; only clear the UI lock after readback.
+ const confirmed = await getCatalogIngredientDetails(record.id, { silent: true });
+ if (!mounted.current) return;
+ if (!confirmed?.ingredient || confirmed.ingredient.payload?.locked === true) {
+ throw new Error('The record is still locked. Try unlocking again.');
+ }
+ onUnlocked(confirmed.ingredient);
+ setUnlocked(true);
+ } catch (err) {
+ if (mounted.current) setError(err?.message || 'Could not unlock this record.');
+ } finally {
+ inFlight.current = false;
+ if (mounted.current) { setPending(false); onPendingChange(false); }
+ }
+ };
+
+ if (!locked && !unlocked) return null;
+ return (
+ <div className="rounded-lg border border-port-border bg-port-card p-3 space-y-2">
+ <p role="status" className="text-sm text-port-warning">
+ {locked ? `${record.name} is locked. Unlock it to render a reference sheet or look. Unlocking also allows AI edits to this record.`
+ : 'Unlocked. Choose Generate when you are ready; unsaved profile edits still need saving.'}
+ </p>
+ {locked && <button type="button" onClick={unlock} disabled={disabled || pending} aria-busy={pending}
+ className="inline-flex items-center gap-1.5 rounded border border-port-border px-3 py-2 text-sm text-white disabled:opacity-50">
+ {pending ? <Loader2 size={14} aria-hidden="true" className="animate-spin" /> : <Unlock size={14} aria-hidden="true" />}
+ {pending ? 'Unlocking…' : 'Unlock for rendering'}
+ </button>}
+ {error && <p role="alert" className="text-sm text-port-error">{error}</p>}
+ </div>
+ );
+}
diff --git a/client/src/components/catalog/CatalogUnlockNotice.test.jsx b/client/src/components/catalog/CatalogUnlockNotice.test.jsx
new file mode 100644
index 0000000000..5ff6e4b1c1
--- /dev/null
+++ b/client/src/components/catalog/CatalogUnlockNotice.test.jsx
@@ -0,0 +1,114 @@
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import CatalogUnlockNotice from './CatalogUnlockNotice';
+import { getCatalogIngredientDetails, updateCatalogIngredient } from '../../services/apiCatalog';
+import { getUniverse, setUniverseCanonLock } from '../../services/apiUniverseBuilder';
+
+vi.mock('../../services/apiCatalog', () => ({ getCatalogIngredientDetails: vi.fn(), updateCatalogIngredient: vi.fn() }));
+vi.mock('../../services/apiUniverseBuilder', () => ({ getUniverse: vi.fn(), setUniverseCanonLock: vi.fn() }));
+const record = { id: 'example-object', type: 'object', name: 'Example object', payload: { locked: true, description: 'Saved description' } };
+const confirmed = { ...record, payload: { ...record.payload, locked: false } };
+const details = { ingredient: record, refs: [] };
+const onUnlocked = vi.fn();
+const onPendingChange = vi.fn();
+const show = (props = {}) => render(<CatalogUnlockNotice record={record} onUnlocked={onUnlocked} onPendingChange={onPendingChange} {...props} />);
+beforeEach(() => {
+ vi.resetAllMocks();
+ getCatalogIngredientDetails.mockResolvedValueOnce(details).mockResolvedValue({ ingredient: confirmed, refs: [] });
+ updateCatalogIngredient.mockResolvedValue(confirmed);
+});
+
+describe('contextual catalog unlock', () => {
+ it('coalesces repeated clicks and confirms the saved lock without rendering', async () => {
+ let finish;
+ updateCatalogIngredient.mockImplementation(() => new Promise((resolve) => { finish = resolve; }));
+ const view = show();
+ const button = screen.getByRole('button', { name: 'Unlock for rendering' });
+ fireEvent.click(button);
+ fireEvent.click(button);
+ await waitFor(() => expect(updateCatalogIngredient).toHaveBeenCalledTimes(1));
+ expect(button).toBeDisabled();
+ expect(button).toHaveAttribute('aria-busy', 'true');
+ expect(updateCatalogIngredient).toHaveBeenCalledWith(record.id, { payload: confirmed.payload }, { silent: true });
+ await act(async () => finish(confirmed));
+ expect(onUnlocked).toHaveBeenCalledWith(confirmed);
+ view.rerender(<CatalogUnlockNotice record={confirmed} onUnlocked={onUnlocked} onPendingChange={onPendingChange} />);
+ expect(screen.getByRole('status')).toHaveTextContent('Unlocked. Choose Generate');
+ });
+
+ it.each(['character', 'place', 'object'])('uses the supported canon lock mutation for %s', async (type) => {
+ getCatalogIngredientDetails.mockReset().mockResolvedValueOnce({ ingredient: { ...record, type }, refs: [{ refKind: 'universe', refId: 'example-universe' }] })
+ .mockResolvedValue({ ingredient: confirmed });
+ const field = { character: 'characters', place: 'places', object: 'objects' }[type];
+ getUniverse.mockResolvedValue({ [field]: [{ id: 'example-entry', ingredientId: record.id }] });
+ show({ record: { ...record, type } });
+ fireEvent.click(screen.getByRole('button', { name: 'Unlock for rendering' }));
+ await waitFor(() => expect(onUnlocked).toHaveBeenCalled());
+ expect(setUniverseCanonLock).toHaveBeenCalledWith('example-universe', type, 'example-entry', false, { silent: true });
+ expect(updateCatalogIngredient).not.toHaveBeenCalled();
+ });
+
+ it('skips deleted universe refs when resolving a standalone record', async () => {
+ getCatalogIngredientDetails.mockReset().mockResolvedValueOnce({ ...details, refs: [{ refKind: 'universe', refId: 'deleted-universe' }] })
+ .mockResolvedValue({ ingredient: confirmed });
+ getUniverse.mockRejectedValue(Object.assign(new Error('Not found'), { status: 404 }));
+ show();
+ fireEvent.click(screen.getByRole('button', { name: 'Unlock for rendering' }));
+ await waitFor(() => expect(onUnlocked).toHaveBeenCalledWith(confirmed));
+ expect(updateCatalogIngredient).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not fall back to a catalog write when universe access is forbidden', async () => {
+ getCatalogIngredientDetails.mockReset().mockResolvedValue({ ...details, refs: [{ refKind: 'universe', refId: 'private-universe' }] });
+ getUniverse.mockRejectedValue(Object.assign(new Error('Access forbidden'), { status: 403 }));
+ show();
+ fireEvent.click(screen.getByRole('button', { name: 'Unlock for rendering' }));
+ expect(await screen.findByRole('alert')).toHaveTextContent('Access forbidden');
+ expect(updateCatalogIngredient).not.toHaveBeenCalled();
+ });
+
+ it('keeps a rejected permission visible and permits retry without clearing the lock', async () => {
+ updateCatalogIngredient.mockRejectedValue(new Error('Read-only access: unlocking is not permitted'));
+ show();
+ fireEvent.click(screen.getByRole('button', { name: 'Unlock for rendering' }));
+ expect(await screen.findByRole('alert')).toHaveTextContent('Read-only access');
+ expect(onUnlocked).not.toHaveBeenCalled();
+ expect(screen.getByRole('button', { name: 'Unlock for rendering' })).toBeEnabled();
+ });
+
+ it('does not offer an enabled mutation while the parent is read-only or saving', () => {
+ show({ disabled: true });
+ fireEvent.click(screen.getByRole('button', { name: 'Unlock for rendering' }));
+ expect(getCatalogIngredientDetails).not.toHaveBeenCalled();
+ });
+
+ it('does not mutate after navigation while resolving the target', async () => {
+ let finish;
+ getCatalogIngredientDetails.mockReset().mockImplementation(() => new Promise((resolve) => { finish = resolve; }));
+ const view = show();
+ fireEvent.click(screen.getByRole('button', { name: 'Unlock for rendering' }));
+ view.unmount();
+ await act(async () => finish(details));
+ expect(updateCatalogIngredient).not.toHaveBeenCalled();
+ expect(onUnlocked).not.toHaveBeenCalled();
+ });
+
+ it('ignores a completed mutation after the selected record is left', async () => {
+ let finish;
+ updateCatalogIngredient.mockImplementation(() => new Promise((resolve) => { finish = resolve; }));
+ const view = show();
+ fireEvent.click(screen.getByRole('button', { name: 'Unlock for rendering' }));
+ await waitFor(() => expect(updateCatalogIngredient).toHaveBeenCalled());
+ view.unmount();
+ await act(async () => finish(confirmed));
+ expect(onUnlocked).not.toHaveBeenCalled();
+ });
+
+ it('retains the lock when canon projection did not persist it', async () => {
+ getCatalogIngredientDetails.mockReset().mockResolvedValue(details);
+ show();
+ fireEvent.click(screen.getByRole('button', { name: 'Unlock for rendering' }));
+ expect(await screen.findByRole('alert')).toHaveTextContent('still locked');
+ expect(onUnlocked).not.toHaveBeenCalled();
+ });
+});
diff --git a/client/src/pages/CatalogIngredient.jsx b/client/src/pages/CatalogIngredient.jsx
index 71755af2e6..4c0db728cc 100644
--- a/client/src/pages/CatalogIngredient.jsx
+++ b/client/src/pages/CatalogIngredient.jsx
@@ -53,6 +53,7 @@ import IngredientPicker from '../components/IngredientPicker';
import MediaImage from '../components/MediaImage';
import CatalogMediaTile from '../components/catalog/CatalogMediaTile';
import CatalogSheetsPanel, { ReferenceSheetPanel } from '../components/catalog/CatalogSheetsPanel';
+import CatalogUnlockNotice from '../components/catalog/CatalogUnlockNotice';
import CatalogPlatesPanel from '../components/catalog/CatalogPlatesPanel';
import CatalogLooksPanel from '../components/catalog/CatalogLooksPanel';
import CharacterLoraChip from '../components/loraTraining/CharacterLoraChip';
@@ -174,6 +175,7 @@ export default function CatalogIngredient() {
const [tags, setTags] = useState([]);
const [payload, setPayload] = useState({});
const [saving, setSaving] = useState(false);
+ const [unlocking, setUnlocking] = useState(false);
// A Looks-tab wardrobe save in flight; the profile Save waits for it so its
// draft payload can't write back the previous wardrobes.
const [lookSaving, setLookSaving] = useState(false);
@@ -204,6 +206,7 @@ export default function CatalogIngredient() {
let cancelled = false;
setLoading(true);
setSaving(false);
+ setUnlocking(false);
getCatalogIngredientDetails(id, { silent: true })
.then((d) => {
if (cancelled) return;
@@ -446,7 +449,7 @@ export default function CatalogIngredient() {
}, [id]);
const handleSave = async () => {
- if (!record) return;
+ if (!record || unlocking) return;
const submittedId = record.id;
const submittedGeneration = activeVisitRef.current.generation;
const submittedName = name;
@@ -598,7 +601,9 @@ export default function CatalogIngredient() {
: [];
const liveLookIds = new Set(wardrobes.map((w) => w?.id).filter(Boolean));
const isReferenceTabRow = (m) => isReferenceTabMedia(m, liveLookIds);
- const renderBlockedReason = (subject) => (saving
+ const renderBlockedReason = (subject) => (record.payload?.locked === true
+ ? 'Unlock this record above before rendering.'
+ : saving
? `Saving — the ${subject} renders from the saved record.`
: isDirty ? `Save your profile edits first — the ${subject} renders from the saved record.` : null);
@@ -634,7 +639,7 @@ export default function CatalogIngredient() {
<Link to={backPath} className="inline-flex items-center gap-1.5 px-3 py-2 rounded-lg text-sm text-gray-400 hover:text-white">
<ArrowLeft size={14} aria-hidden="true" /> Back
</Link>
- <button type="button" onClick={handleSave} disabled={saving || lookSaving}
+ <button type="button" onClick={handleSave} disabled={saving || lookSaving || unlocking}
className="inline-flex items-center gap-1.5 px-3 py-2 rounded-lg bg-port-accent hover:bg-port-accent/90 disabled:opacity-50 text-white text-sm font-medium">
{saving ? <Loader2 size={14} className="animate-spin" /> : <Save size={14} />} Save
</button>
@@ -745,6 +750,15 @@ export default function CatalogIngredient() {
</>
)}
+ <div hidden={activeTab !== 'sheets' && activeTab !== 'looks'}>
+ <CatalogUnlockNotice key={record.id} record={record} disabled={saving || lookSaving} onPendingChange={setUnlocking}
+ onUnlocked={(updated) => {
+ setRecord((current) => current?.id === updated.id
+ ? { ...current, updatedAt: updated.updatedAt, payload: { ...current.payload, locked: false } } : current);
+ setPayload((current) => ({ ...current, locked: false }));
+ }} />
+ </div>
+
{activeTab === 'sheets' && (
<CatalogSheetsPanel
ingredientId={record.id}
@@ -767,7 +781,7 @@ export default function CatalogIngredient() {
lookMedia={media.filter((m) => liveLookIds.has(lookIdOf(m)))}
candidates={media.filter((m) => m.kind === 'reference' && isReferenceTabRow(m))}
missingMedia={missingMedia}
- editLocked={saving}
+ editLocked={saving || unlocking}
blockedReason={renderBlockedReason('look')}
savedStamp={record.updatedAt || null}
onSaveWardrobes={handleSaveWardrobes}
diff --git a/client/src/pages/CatalogIngredient.test.jsx b/client/src/pages/CatalogIngredient.test.jsx
index 306c6b67aa..1372fa7418 100644
--- a/client/src/pages/CatalogIngredient.test.jsx
+++ b/client/src/pages/CatalogIngredient.test.jsx
@@ -143,6 +143,7 @@ const renderPage = async (path = '/catalog/character/cat-chr-1') => {
{ path: '/catalog/:type/:id', element: <CatalogIngredient /> },
{ path: '/casting', element: <div>Casting index</div> },
{ path: '/casting/:id/:tab?', element: <CatalogIngredient /> },
+ { path: '/objects/:id/:tab?', element: <CatalogIngredient /> },
{ path: '/environments/:id/:tab?', element: <CatalogIngredient /> },
], { initialEntries: [path] });
const result = render(<RouterProvider router={router} />);
@@ -1036,3 +1037,42 @@ describe('buildGenerationPromptSeed', () => {
expect(seed.endsWith('…')).toBe(true);
});
});
+
+
+describe('contextual unlock in Create libraries', () => {
+ it.each([['objects', 'object'], ['environments', 'place'], ['casting', 'character']])(
+ 'preserves draft edits and sheet selection in %s and renders only on request', async (library, type) => {
+ const api = await import('../services/apiCatalog');
+ const locked = { id: 'example-locked', type, name: 'Example locked record', tags: [], payload: { locked: true, description: 'Saved description' }, refs: [] };
+ let persisted = locked;
+ getCatalogIngredientDetails.mockImplementation(async () => detailsOf(persisted));
+ updateCatalogIngredient.mockImplementation(async (_id, patch) => {
+ persisted = { ...persisted, ...patch, updatedAt: '2026-01-01T00:00:01Z' };
+ return persisted;
+ });
+ api.listCatalogSheetVariants.mockResolvedValue({ variants: [{ id: 'standard', label: 'Standard' }, { id: 'alternate', label: 'Alternate' }] });
+ api.renderCatalogSheet.mockReset().mockResolvedValue({ jobId: 'example-sheet-job', variant: 'alternate' });
+ api.attachCatalogIngredientMedia.mockResolvedValue({});
+ const { router } = await renderPage(`/${library}/example-locked/profile`);
+ fireEvent.change(screen.getByLabelText('Name'), { target: { value: 'Unsaved draft name' } });
+ await act(async () => router.navigate(`/${library}/example-locked/sheets`));
+ const picker = await screen.findByLabelText('Sheet kind');
+ fireEvent.change(picker, { target: { value: 'alternate' } });
+ expect(screen.getByRole('button', { name: /Generate sheet/ })).toBeDisabled();
+ fireEvent.click(screen.getByRole('button', { name: 'Unlock for rendering' }));
+ await screen.findByText(/Unlocked. Choose Generate/);
+ expect(picker).toHaveValue('alternate');
+ expect(api.renderCatalogSheet).not.toHaveBeenCalled();
+ expect(screen.getByRole('button', { name: /Generate sheet/ })).toBeDisabled();
+ expect(updateCatalogIngredient).toHaveBeenCalledWith('example-locked', { payload: { ...locked.payload, locked: false } }, { silent: true });
+ await act(async () => router.navigate(`/${library}/example-locked/profile`));
+ expect(screen.getByLabelText('Name')).toHaveValue('Unsaved draft name');
+ fireEvent.click(screen.getByRole('button', { name: /^Save$/ }));
+ await waitFor(() => expect(persisted.name).toBe('Unsaved draft name'));
+ await act(async () => router.navigate(`/${library}/example-locked/sheets`));
+ await waitFor(() => expect(screen.getByRole('button', { name: /Generate sheet/ })).toBeEnabled());
+ fireEvent.click(screen.getByRole('button', { name: /Generate sheet/ }));
+ await waitFor(() => expect(api.renderCatalogSheet).toHaveBeenCalledTimes(1));
+ },
+ );
+});