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
/**
* Shared scene-prompt composer + bible matchers. Pure ESM, no Node-only
* deps — mirrored to `client/src/lib/scenePrompt.js` for the client bundle.
*/
import { mapCanonDescriptorFragments, richCanonDescriptorFragments } from './canonPrompt.js';
import { escapeRegExp } from './textUtils.js';
const PROMPT_MAX = 1900;
// Normalize a screenplay slugline so case/punctuation/dash variants collapse:
// `INT. KITCHEN — NIGHT` and `INT KITCHEN - NIGHT` both become `INT KITCHEN NIGHT`.
export const normalizeSlugline = (s) => String(s || '')
.toUpperCase()
.replace(/[—–-]/g, ' ')
.replace(/[.,:;]/g, '')
.replace(/\s+/g, ' ')
.trim();
// LLM scenes name characters bare ("ARIA"); profiles may use full names
// ("Aria Reyes") or "the bartender". Strip leading "the " and lowercase.
export const normCharKey = (s) => String(s || '').trim().toLowerCase().replace(/^the\s+/, '');
export function buildCharByKey(allCharacters) {
const map = new Map();
for (const profile of allCharacters || []) {
map.set(normCharKey(profile.name), profile);
for (const alias of profile.aliases || []) map.set(normCharKey(alias), profile);
}
return map;
}
export function matchSceneCharacters(sceneCharacterNames = [], charByKey) {
if (!Array.isArray(sceneCharacterNames) || !sceneCharacterNames.length) return [];
const matched = [];
const seen = new Set();
for (const name of sceneCharacterNames) {
const profile = charByKey?.get(normCharKey(name));
if (profile && !seen.has(profile.id || profile.name)) {
matched.push(profile);
seen.add(profile.id || profile.name);
}
}
return matched;
}
/**
* Scan a free-form text blob (panel/scene description) for any character
* names or aliases from the bible. Word-boundary matching, case-insensitive.
* Used when the visual record doesn't carry a structured character list (e.g.
* storyboard scenes only have a free-text description). Keeps the prompt
* grounded in bible-canonical descriptions for everyone the LLM named.
*/
export function matchCharactersInText(text, allCharacters) {
return matchEntriesByCandidates(text, allCharacters, (c) => [c.name, ...(c.aliases || [])]);
}
export function buildPlaceByKey(allSettings) {
const map = new Map();
for (const setting of allSettings || []) {
const key = normalizeSlugline(setting.slugline || setting.name);
if (!key) continue;
map.set(key, setting);
}
return map;
}
export function matchScenePlace(sceneSlugline, placeByKey) {
if (!sceneSlugline) return null;
return placeByKey?.get(normalizeSlugline(sceneSlugline)) || null;
}
// Shared word-boundary scanner used by the *-InText helpers below. Returns
// the entries whose `candidates(entry)` strings appear in the haystack.
function matchEntriesByCandidates(text, entries, candidatesFn) {
if (!text || !Array.isArray(entries) || !entries.length) return [];
const haystack = String(text);
const matched = [];
const seen = new Set();
const wordBoundary = (needle) => {
if (!needle) return false;
const escaped = escapeRegExp(needle);
// Unicode-aware boundary instead of ASCII `\b`: a name starting/ending with a
// non-ASCII letter (José, Élodie, Zoë) has no `\b` adjacent to the accented
// char, so `\b…\b` would silently miss it. Lookarounds over `[\p{L}\p{N}_]`
// with the `u` flag reproduce word-boundary semantics for all scripts
// (still won't match "Mira" inside "Miranda").
return new RegExp(`(?<![\\p{L}\\p{N}_])${escaped}(?![\\p{L}\\p{N}_])`, 'iu').test(haystack);
};
for (const entry of entries) {
const key = entry.id || entry.name;
if (!key || seen.has(key)) continue;
const candidates = candidatesFn(entry).filter(Boolean);
if (candidates.some(wordBoundary)) {
matched.push(entry);
seen.add(key);
}
}
return matched;
}
// Scan free-form prose for bible-canonical places. Mirrors
// `matchCharactersInText` but tests against `name` (places have no aliases
// in the canonical schema — slugline is for screenplay matching, not prose).
export function matchPlacesInText(text, allPlaces) {
return matchEntriesByCandidates(text, allPlaces, (p) => [p.name]);
}
// Scan free-form prose for bible-canonical objects. Mirrors
// `matchCharactersInText` — objects carry `name` + `aliases[]` per
// `server/lib/storyBible.js:PROMPT_FIELDS`.
export function matchObjectsInText(text, allObjects) {
return matchEntriesByCandidates(text, allObjects, (o) => [o.name, ...(o.aliases || [])]);
}
// Append a user-selected wardrobe description AFTER the character's physical
// description without clobbering it — wardrobe is a deliberate per-scene
// overlay, never a substitute for the canonical body fields. The "Wearing: …"
// label matches the existing "Palette: …" / "Era: …" fragment vocabulary, and
// the sentence separator keeps the two clauses from running together once the
// budget-truncation join collapses fragments with a single space.
function appendWardrobe(base, wardrobeDesc) {
if (!wardrobeDesc) return base;
const wearing = `Wearing: ${wardrobeDesc}`;
if (!base) return wearing;
const sep = /[.!?]$/.test(base) ? ' ' : '. ';
return `${base}${sep}${wearing}`;
}
/**
* Compose the final image-gen prompt with priority order (diffusion models
* weight earlier tokens heaviest):
* 1. worldStyle preset (cinematic / film-noir / etc.) — broadest aesthetic
* 2. workTitle — gives the model story-context cues
* 3. setting baseline (description / palette / era / weather / recurring) — the place
* 4. Featuring — char1: desc, char2: desc — the subjects
* 5. scene.visualPrompt — what's NEW this beat
*
* Truncation priority is the inverse: visualPrompt survives unconditionally,
* then setting baseline, then characters. Style + title are short so they're
* always kept. Featuring drops characters one-by-one to fit; setting drops
* trailing fragments first (recurringDetails → weather → era → palette →
* description) so the most identity-defining field — description — survives
* longest under budget pressure.
*
* Positional API kept for parity with the long-running Writers Room caller
* (`SceneCard.jsx`) — adding new optional kwargs at the tail is fine.
*/
export function buildScenePrompt(workTitle, scene, matchedCharacters, worldStyle = '', matchedPlace = null) {
const stylePart = worldStyle && worldStyle.trim() ? `${worldStyle.trim()}. ` : '';
const titlePart = workTitle ? `${workTitle}. ` : '';
const visual = scene?.visualPrompt || scene?.description || '';
// INT/EXT + time-of-day claim the first setting slot — they're cheap
// (≤30 chars combined) and load-bearing for lighting/composition cues
// diffusion models actually weight.
const intExtPart = matchedPlace?.intExt === 'INT'
? 'Interior'
: matchedPlace?.intExt === 'EXT'
? 'Exterior'
: '';
const todPart = typeof matchedPlace?.timeOfDay === 'string' && matchedPlace.timeOfDay
? matchedPlace.timeOfDay
: '';
const placeMetaFrag = [intExtPart, todPart].filter(Boolean).join(', ');
// RICH spec (description / Palette / Era / Weather / recurringDetails) —
// era + weather are continuity-critical visual cues that diffusion models
// weight for lighting / atmosphere / period dress. UI card summaries use the
// narrower SHORT spec via `KINDS[].descFor`; both stay coherent through the
// shared helper but are not byte-equivalent. Per-frag trailing period
// preserves "Palette: X." sentence boundaries when the budget-truncation
// join collapses fragments with a single space.
const baselineFrags = matchedPlace
? mapCanonDescriptorFragments(richCanonDescriptorFragments('place', matchedPlace), { trailingPeriod: true })
: [];
const placeFrags = matchedPlace ? [
placeMetaFrag ? `${placeMetaFrag}.` : '',
...baselineFrags,
].filter(Boolean) : [];
// Per-scene wardrobe picks: `scene.characterAppearances` is
// [{ characterId, wardrobeId? }]. When a matched character has a selected
// wardrobe, its description is appended after physicalDescription. The user
// picks these explicitly (no extractor guess); an absent or empty list
// leaves every character on their canonical body description.
const appearanceByCharId = new Map(
(Array.isArray(scene?.characterAppearances) ? scene.characterAppearances : [])
.filter((a) => a && a.characterId)
.map((a) => [a.characterId, a]),
);
// Accept either `physicalDescription` (writers-room shape) or
// `description` (pipeline shape) — the composer doesn't care which
// field carries the visual descriptor.
const featuringFragments = (matchedCharacters || [])
.map((c) => {
const base = (c.physicalDescription || c.description || '').trim();
const appearance = appearanceByCharId.get(c.id);
const wardrobe = appearance?.wardrobeId
? (c.wardrobes || []).find((w) => w && w.id === appearance.wardrobeId)
: null;
return { name: c.name, desc: appendWardrobe(base, (wardrobe?.description || '').trim()) };
})
.filter((c) => c.desc)
.map((c) => `${c.name}: ${c.desc}`);
const PREFIX = 'Featuring — ';
const reserveCore = stylePart.length + titlePart.length + visual.length + 4;
let budget = PROMPT_MAX - reserveCore;
// Setting first claim on remaining budget (place baseline > characters
// for visual continuity across scenes).
const placeFit = [];
for (const frag of placeFrags) {
const cost = (placeFit.length === 0 ? 0 : 1) + frag.length;
if (cost > budget) break;
placeFit.push(frag);
budget -= cost;
}
// Then characters fill what's left, prefix included.
budget -= PREFIX.length;
const charFit = [];
for (const frag of featuringFragments) {
const cost = (charFit.length === 0 ? 0 : 1) + frag.length;
if (cost > budget) break;
charFit.push(frag);
budget -= cost;
}
const segs = [];
if (stylePart) segs.push(stylePart.trim());
if (titlePart) segs.push(titlePart.trim());
if (placeFit.length > 0) segs.push(placeFit.join(' '));
if (charFit.length > 0) segs.push(`${PREFIX}${charFit.join(' ')}`);
if (visual) segs.push(visual);
return segs.filter(Boolean).join(' ').slice(0, PROMPT_MAX);
}
export const __testing = { PROMPT_MAX };