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 { useCallback, useEffect, useRef, useState } from 'react';
import socket from '../services/socket';
import { getMediaJob } from '../services/apiMediaJobs';
import { evictOldest, ORPHAN_BUFFER_MAX } from '../lib/boundedMap';
import { pluralize } from '../lib/textUtils';
import toast from '../components/ui/Toast';
// Failures landing within this window of each other are one batch.
const FAILURE_BATCH_WINDOW_MS = 600;
const MAX_NAMED_SCENES = 3;
// One toast for however many scenes failed in the window: names the scene (or
// the first few, with a count) and the first reported reason.
function failureToastMessage(failMessage, failures) {
const reason = failures.find((f) => f.error)?.error;
const labels = [...new Set(failures.map((f) => f.label).filter(Boolean))];
if (failures.length === 1) {
return `${failMessage}${labels[0] ? `: ${labels[0]}` : ''}${reason ? ` — ${reason}` : ''}`;
}
const named = labels.slice(0, MAX_NAMED_SCENES).join(', ');
const more = labels.length > MAX_NAMED_SCENES ? `, +${labels.length - MAX_NAMED_SCENES} more` : '';
return `${failMessage} for ${pluralize(failures.length, 'scene')}${named ? ` (${named}${more})` : ''}${reason ? ` — ${reason}` : ''}`;
}
/**
* Per-scene async-render lifecycle for a Music Video board lane (reference
* frame OR i2v clip — #1798). One call owns everything one lane needs to drive
* its "Rendering…" spinners from media-job socket events:
*
* - `genScenes` — sceneId → true while that scene's render is in flight (the
* spinner source).
* - a pending-jobs map (jobId → sceneId) so a queued render's terminal event
* clears the RIGHT scene's spinner.
* - an orphan-terminals map (jobId → failed) for the terminal event that
* raced ahead of the kickoff's `trackJob` registration (the HTTP response
* and the WebSocket terminal event arrive on separate channels, so a
* fast-failing queued job's event can land first).
* - the socket subscription: a durable `attachEvent` that folds the finished
* asset onto the matching scene without a refetch (does NOT touch the
* spinner — an older render's attach can arrive while a newer one is still
* in flight, so the spinner is owned solely by the job-id-correlated
* terminal events), plus the `completedEvent` / `failedEvent` /
* `canceledEvent` terminal events that clear the spinner.
*
* The image and video lanes were near-verbatim copies of this before the
* extraction; the server-side image/video duplication was already unified in
* #1791 behind `createMediaJobImageHook`, so this is the client-side analog.
*
* Config:
* - `attachEvent` — durable broadcast that lands the finished asset
* (e.g. `music-video:scene-image`). Handler receives the
* raw event payload and calls `apply(data)`.
* - `completedEvent` — job terminal success (e.g. `image-gen:completed`).
* - `failedEvent` — job terminal failure (e.g. `image-gen:failed`).
* - `canceledEvent` — job cancel (e.g. `image-gen:canceled`). A queued-cancel
* emits only this (no `failedEvent`), so without it the
* spinner would stick — every queue-backed lane has one.
* - `startedEvent` / `progressEvent` — optional `*-gen:started` / `*-gen:progress`
* events; they feed `sceneProgress` (queued → running +
* a 0..1 fraction) for the scene whose job they name.
* - `onSettled({ jobId, sceneId, outcome })` — optional; called once per
* tracked job with `'completed' | 'failed' | 'canceled'`
* (the batch counter in `useSceneBatch` listens here).
* - `apply(data)` — fold the finished asset onto the matching scene
* (functional setProjects update); called on `attachEvent`.
* - `failMessage` — the toast headline for a confirmed render failure
* (e.g. 'Frame render failed').
* - `sceneLabel(sceneId)` — OPTIONAL display name of a scene, so the failure
* toast says WHICH scene failed. Failure toasts also
* carry the failed event's `error`, and failures that
* land within a short window (a batch) collapse into ONE
* summary toast instead of one identical toast per scene.
*
* Returns `{ genScenes, sceneProgress, failedScenes, startScene, clearScene, trackJob, restoreJobs }`
* (`sceneProgress`: sceneId → `{ progress }` once a job reports running; a scene
* in `genScenes` with no entry is still queued;
* `failedScenes` — sceneId → true after a confirmed render failure this session, until that scene renders again):
* - `startScene(sceneId)` — light the spinner before the kickoff request.
* - `clearScene(sceneId)` — drop the spinner (sync-lane finish, or a kickoff
* that returns no trackable job id).
* - `trackJob(jobId, sceneId)` — register a queued render so its terminal
* event clears the right scene's spinner; reconciles an already-arrived
* orphan terminal inline (clears the spinner, toasts on failure) instead of
* registering a job that's already done.
* - `restoreJobs([{ jobId, sceneId }])` — after a reload, re-light the
* spinners for renders the server's queue still has in flight (#10154) and
* correlate their jobs so the terminal events clear them as usual.
*/
export default function useSceneRenderLifecycle({
attachEvent,
completedEvent,
failedEvent,
canceledEvent,
startedEvent,
progressEvent,
onSettled,
apply,
failMessage,
sceneLabel,
}) {
const [genScenes, setGenScenes] = useState({});
const [sceneProgress, setSceneProgress] = useState({});
// sceneId → true once a render for it failed this session (cleared when the scene renders again or succeeds).
const [failedScenes, setFailedScenes] = useState({});
const markFailed = useCallback((sceneId, failed) => setFailedScenes((prev) => {
if (!!prev[sceneId] === failed) return prev;
const next = { ...prev };
if (failed) next[sceneId] = true; else delete next[sceneId];
return next;
}), []);
// jobId → sceneId for renders this lane is awaiting.
const pendingRef = useRef(new Map());
// jobId → outcome ('completed' | 'failed' | 'canceled') for terminal events that beat their kickoff's
// trackJob registration. Capped so unrelated jobs across the app can't grow
// it unbounded; the kickoff reconciles its own entry on arrival.
const orphanRef = useRef(new Map());
// Latest `apply` / `failMessage` without re-subscribing the socket every
// render — the effect keys on the (static) event names and reads the mutable
// callbacks through this ref, mirroring the original `[]`-deps effects.
const cfgRef = useRef({ apply, failMessage, onSettled, sceneLabel });
cfgRef.current = { apply, failMessage, onSettled, sceneLabel };
// Failures waiting for the batch window to close, and that window's timer.
const failuresRef = useRef([]);
const flushTimerRef = useRef(null);
// Queue one confirmed failure; the toast fires once the window closes so a
// batch of failures reads as one summary rather than N identical toasts.
const reportFailure = useCallback((sceneId, error) => {
failuresRef.current.push({ label: cfgRef.current.sceneLabel?.(sceneId) || '', error: typeof error === 'string' ? error.trim() : '' });
if (flushTimerRef.current) return;
flushTimerRef.current = setTimeout(() => {
flushTimerRef.current = null;
const failures = failuresRef.current;
failuresRef.current = [];
if (failures.length) toast.error(failureToastMessage(cfgRef.current.failMessage, failures));
}, FAILURE_BATCH_WINDOW_MS);
}, []);
// A navigated-away page must not pop a late failure toast onto another view.
useEffect(() => () => {
clearTimeout(flushTimerRef.current);
flushTimerRef.current = null;
failuresRef.current = [];
}, []);
const startScene = useCallback(
(sceneId) => { markFailed(sceneId, false); setGenScenes((prev) => ({ ...prev, [sceneId]: true })); },
[markFailed],
);
const clearScene = useCallback(
(sceneId) => setGenScenes((prev) => {
const next = { ...prev };
delete next[sceneId];
return next;
}),
[],
);
const clearProgress = useCallback((sceneId) => setSceneProgress((prev) => {
if (!(sceneId in prev)) return prev;
const next = { ...prev };
delete next[sceneId];
return next;
}), []);
// The orphan-reconcile helper used by the kickoff `.then`: if the terminal
// event already raced ahead, settle it now; otherwise register the pending job.
const trackJob = useCallback((jobId, sceneId) => {
if (orphanRef.current.has(jobId)) {
const orphan = orphanRef.current.get(jobId);
orphanRef.current.delete(jobId);
clearScene(sceneId);
clearProgress(sceneId);
const failed = typeof orphan === 'object' ? orphan.failed : orphan === 'failed';
const outcome = (typeof orphan === 'object' ? orphan.outcome : orphan) || (failed ? 'failed' : 'completed');
const error = typeof orphan === 'object' ? orphan.error : undefined;
if (failed || outcome === 'failed') {
markFailed(sceneId, true);
reportFailure(sceneId, error);
}
cfgRef.current.onSettled?.({ jobId, sceneId, outcome });
return;
}
pendingRef.current.set(jobId, sceneId);
}, [clearScene, clearProgress, markFailed, reportFailure]);
const restoreJobs = useCallback((entries) => {
const list = (Array.isArray(entries) ? entries : []).filter((e) => e?.jobId && e?.sceneId);
if (list.length === 0) return;
setGenScenes((prev) => {
const next = { ...prev };
for (const { sceneId } of list) next[sceneId] = true;
return next;
});
for (const { jobId, sceneId } of list) trackJob(jobId, sceneId);
}, [trackJob]);
useEffect(() => {
const onAttach = (data) => cfgRef.current.apply(data);
// jobId → pending error-toast timer (running-cancel deferral; see onFailed).
const failTimers = new Map();
// Unmount/re-run guard for the deferred fail-toast fetch below: cleared in
// cleanup so a `getMediaJob` promise still in flight (or a re-arm) can't pop
// a "render failed" toast onto whatever page the user navigated to.
let mounted = true;
// `failed` is the toast bit (an orphan failure still owes its kickoff a
// toast); `outcome` is what actually happened, for the batch counter.
const settle = (data, failed, outcome) => {
const jobId = data?.generationId || data?.jobId;
if (!jobId) return;
const sceneId = pendingRef.current.get(jobId);
if (!sceneId) {
// Not yet correlated (the kickoff `trackJob` hasn't run, or it's an
// unrelated job). Stash it so a slightly-late registration can
// reconcile; cap so other pages' renders can't grow this unbounded.
const orphans = orphanRef.current;
orphans.set(jobId, { failed: !!failed, outcome, error: data?.error });
evictOldest(orphans, ORPHAN_BUFFER_MAX);
return;
}
pendingRef.current.delete(jobId);
clearScene(sceneId);
clearProgress(sceneId);
if (failed) {
markFailed(sceneId, true);
reportFailure(sceneId, data?.error);
}
cfgRef.current.onSettled?.({ jobId, sceneId, outcome });
};
const onCompleted = (data) => settle(data, false, 'completed');
// started / progress: a tracked job is running; keep the fraction for its card.
const onRunning = (data) => {
const jobId = data?.generationId || data?.jobId;
const sceneId = jobId && pendingRef.current.get(jobId);
if (!sceneId) return;
const progress = typeof data.progress === 'number' && Number.isFinite(data.progress)
? Math.min(1, Math.max(0, data.progress)) : null;
setSceneProgress((prev) => (prev[sceneId]?.progress === progress && sceneId in prev
? prev
: { ...prev, [sceneId]: { progress: progress ?? prev[sceneId]?.progress ?? null } }));
};
// Deferred failure toast for an owned render. A render canceled WHILE RUNNING
// reaches us as `failedEvent` (SIGTERM) just before `canceledEvent` — and
// before the queue flips the job to 'canceled' — so neither the failed event
// nor an immediate status fetch can tell a cancel from a real failure
// (#1791/#1796). `canceledEvent` cancels this timer in the common case; if
// the timer fires first it re-polls the job and only toasts on a CONFIRMED
// terminal failure — a still-'running'/'queued' status means the cancel (or
// the failure transition) hasn't landed yet, so it re-polls a bounded number
// of times rather than toasting prematurely (the spinner is already cleared,
// so giving up silently never strands the UI).
const armFailToast = (jobId, sceneId, error, attempt = 0) => {
failTimers.set(jobId, setTimeout(() => {
failTimers.delete(jobId);
if (!mounted) return; // navigated away before the timer fired
getMediaJob(jobId)
.then((job) => {
if (!mounted) return; // unmounted while the status fetch was in flight
const status = job?.status;
if (status === 'canceled') return; // user cancel — never a failure toast
if (status === 'failed' || status === 'error') {
markFailed(sceneId, true);
reportFailure(sceneId, error || job?.error);
return;
}
if (attempt < 2) armFailToast(jobId, sceneId, error, attempt + 1); // non-terminal: wait, don't toast yet
})
.catch(() => {
if (mounted) {
markFailed(sceneId, true);
reportFailure(sceneId, error);
}
});
}, 800));
};
const onFailed = (data) => {
const jobId = data?.generationId || data?.jobId;
if (!jobId) return;
// Only THIS lane's renders surface a failure toast. An OWNED job clears the
// spinner silently (settle with failed=false) and defers the toast above so
// a running-cancel can retract it. A not-yet-owned job is stashed as an
// orphan WITH the failure bit so a fast-fail that raced ahead of its own
// kickoff registration is toasted by the kickoff reconciliation; an
// unrelated job is simply capped/evicted from the orphan map unseen.
const ownedSceneId = pendingRef.current.get(jobId);
const owned = !!ownedSceneId;
settle(data, !owned, 'failed');
if (owned && !failTimers.has(jobId)) armFailToast(jobId, ownedSceneId, data?.error);
};
// Queued-cancel emits no `failedEvent`; running-cancel emits failed then this.
// Either way clear the spinner and cancel any pending failure toast.
const onCanceled = (data) => {
const jobId = data?.generationId || data?.jobId;
if (jobId) {
const t = failTimers.get(jobId);
if (t) { clearTimeout(t); failTimers.delete(jobId); }
}
settle(data, false, 'canceled');
};
socket.on(attachEvent, onAttach);
if (startedEvent) socket.on(startedEvent, onRunning);
if (progressEvent) socket.on(progressEvent, onRunning);
socket.on(completedEvent, onCompleted);
socket.on(failedEvent, onFailed);
socket.on(canceledEvent, onCanceled);
return () => {
socket.off(attachEvent, onAttach);
if (startedEvent) socket.off(startedEvent, onRunning);
if (progressEvent) socket.off(progressEvent, onRunning);
socket.off(completedEvent, onCompleted);
socket.off(failedEvent, onFailed);
socket.off(canceledEvent, onCanceled);
mounted = false;
for (const t of failTimers.values()) clearTimeout(t);
failTimers.clear();
};
}, [attachEvent, completedEvent, failedEvent, canceledEvent, startedEvent, progressEvent, clearScene, clearProgress, markFailed, reportFailure]);
return { genScenes, sceneProgress, failedScenes, startScene, clearScene, trackJob, restoreJobs };
}