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
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.jsxnew file mode 100644index 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.jsxnew file mode 100644index 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.jsxindex 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' && (<CatalogSheetsPanelingredientId={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.jsxindex 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));+ },+ );+});