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 per-kind field-precedence rules for canon entries. Pure ESM, no
* Node-only deps — `client/src/lib/canonPrompt.js` re-exports it for the client
* bundle, so nothing here may import outside `server/lib`.
*
* Source of truth for "which fields describe a canon entry of this kind,
* in what order". Consumers:
* - `synthesizeCanonPrompt` (server/services/universeBuilder.js) →
* render-prompt body (RICH fields)
* - `canonEntryHasContent` (client/src/pages/UniverseBuilder.jsx) →
* "is there any descriptive content?" gate (RICH fields)
* - `KINDS[].descFor` (client/src/components/universe/UniverseCanonSection.jsx) →
* UI summary + handleRenderRef button-enable predicate (SHORT fields)
* - `settingFrags` (server/lib/scenePrompt.js) → scene-prompt framing
* for places (SHORT fields)
* - `CanonReviewSection` (client/src/pages/Importer.jsx) → importer
* pre-commit per-card preview (PREVIEW fields)
*
* SHORT vs PREVIEW vs RICH:
* - SHORT = the visual descriptor subset shown in UI cards. For
* chars/objects: single primary field with a single fallback (mirrors
* the legacy `descFor` `||` chain). For places: description +
* palette + recurringDetails (the "place baseline" from scenePrompt).
* - PREVIEW = narrative + identity-disambiguation fields surfaced in the
* importer's pre-commit review cards. Includes prose-only fields
* (`personality`, `background`, `slugline`) that have no visual role.
* - RICH = every descriptive field that contributes to a render prompt.
* Adds `role` (chars), `era`+`weather` (places), additive
* `significance` (objects).
*/
const trim = (s) => (typeof s === 'string' ? s.trim() : '');
// SHORT spec: chars/objects use single-with-fallback; places uses a
// sequence so palette can carry its prefix.
const SHORT_SPEC = Object.freeze({
characters: Object.freeze({ primary: 'physicalDescription', fallback: 'description' }),
places: Object.freeze({
sequence: Object.freeze([
{ field: 'description' },
{ field: 'palette', prefix: 'Palette' },
{ field: 'recurringDetails' },
]),
}),
objects: Object.freeze({ primary: 'description', fallback: 'significance' }),
});
// PREVIEW spec: importer pre-commit review surface. Wider than SHORT (the
// user needs to see narrative-only fields like `personality` / `background`
// to judge "include this character?") and intentionally distinct from RICH
// (RICH drives render prompts; preview is about identity disambiguation).
// `subtitleField` is the single-line tagline; `bodyFields` uses the same
// `[{ field }]` sequence shape as RICH_SPEC so `fragmentsFromSequence` can
// be reused (no prefixes — importer cards render values verbatim).
const PREVIEW_SPEC = Object.freeze({
characters: Object.freeze({
subtitleField: 'role',
bodyFields: Object.freeze([
{ field: 'physicalDescription' },
{ field: 'personality' },
{ field: 'background' },
]),
}),
places: Object.freeze({
subtitleField: 'slugline',
bodyFields: Object.freeze([{ field: 'description' }]),
}),
objects: Object.freeze({
subtitleField: null,
bodyFields: Object.freeze([
{ field: 'description' },
{ field: 'significance' },
]),
}),
});
// RICH spec: ordered list of all descriptor fields. Prefixes capitalized
// uniformly so flattened output reads as natural sentence fragments.
const RICH_SPEC = Object.freeze({
characters: Object.freeze([
{ field: 'physicalDescription' },
{ field: 'role' },
// Extended visual descriptors — flow into per-page render prompts so the
// model has continuity beyond the bare physicalDescription. Structured
// fields (colorPalette, props, expressions) are flattened by the
// reference-sheet builder, not here, to keep this spec field-keyed.
{ field: 'visualNotes' },
{ field: 'silhouetteNotes' },
{ field: 'postureNotes' },
{ field: 'specialTraits' },
{ field: 'visualIdentity' },
]),
places: Object.freeze([
{ field: 'description' },
{ field: 'palette', prefix: 'Palette' },
{ field: 'era', prefix: 'Era' },
{ field: 'weather', prefix: 'Weather' },
{ field: 'recurringDetails' },
]),
objects: Object.freeze([
{ field: 'description' },
{ field: 'significance', prefix: 'Significance' },
]),
});
function normalizeKind(kind) {
const k = String(kind || '').toLowerCase();
if (k === 'character' || k === 'characters') return 'characters';
if (k === 'place' || k === 'places') return 'places';
if (k === 'object' || k === 'objects') return 'objects';
return null;
}
function fragmentsFromSequence(sequence, entry) {
const out = [];
for (const spec of sequence) {
const value = trim(entry[spec.field]);
if (!value) continue;
out.push(spec.prefix ? { field: spec.field, value, prefix: spec.prefix } : { field: spec.field, value });
}
return out;
}
// Short-circuit "any non-blank field in this sequence" — used by
// `hasCanonDescriptorContent` so per-entry render-count filters don't
// allocate a full fragments array just to read `.length > 0`.
function sequenceHasAnyField(sequence, entry) {
for (const spec of sequence) {
if (trim(entry[spec.field])) return true;
}
return false;
}
/**
* SHORT descriptor fragments — the visual subset used in canon UI cards
* and the render-ref button-enable predicate.
*
* Returns `[{ field, value, prefix? }]` in display order. Empty/missing
* fields produce no fragment. For chars/objects this is at most a single
* fragment (primary with single-field fallback).
*/
export function shortCanonDescriptorFragments(kind, entry) {
if (!entry || typeof entry !== 'object') return [];
const spec = SHORT_SPEC[normalizeKind(kind)];
if (!spec) return [];
if (spec.sequence) return fragmentsFromSequence(spec.sequence, entry);
const primary = trim(entry[spec.primary]);
if (primary) return [{ field: spec.primary, value: primary }];
const fallback = trim(entry[spec.fallback]);
if (fallback) return [{ field: spec.fallback, value: fallback }];
return [];
}
/**
* The single primary descriptor field for a kind — the field a SHORT card
* leads with (chars: `physicalDescription`, objects: `description`, places:
* the first `sequence` field, `description`). Single source of truth so
* callers that need "which field is the headline descriptor for this kind"
* (e.g. the reveal-gated surface substitution in storyBible.js, #2178) don't
* hand-maintain a parallel map. Returns null for an unknown kind.
*/
export function shortCanonPrimaryField(kind) {
const spec = SHORT_SPEC[normalizeKind(kind)];
if (!spec) return null;
return spec.primary || spec.sequence?.[0]?.field || null;
}
/**
* RICH descriptor fragments — every descriptive field that contributes to
* a render prompt body. Used by render-synthesis and the
* "has any content?" gate.
*/
export function richCanonDescriptorFragments(kind, entry) {
if (!entry || typeof entry !== 'object') return [];
const sequence = RICH_SPEC[normalizeKind(kind)];
if (!sequence) return [];
return fragmentsFromSequence(sequence, entry);
}
/**
* Render `[{ prefix?, value }]` fragments as an array of display strings.
*
* When `trailingPeriod` is true, each prefixed fragment is rendered as
* `${prefix}: ${value}.` so that a downstream caller can later join the array
* with a single space and still preserve "Palette: red. Era: Victorian."
* sentence boundaries (see `buildScenePrompt`'s budget-truncation join).
* Bare-value fragments never get a trailing period — the caller controls
* sentence punctuation when no prefix is involved.
*/
export function mapCanonDescriptorFragments(fragments, { trailingPeriod = false } = {}) {
if (!Array.isArray(fragments)) return [];
return fragments.map((f) => {
if (!f) return '';
const body = f.prefix ? `${f.prefix}: ${f.value}` : (f.value ?? '');
return f.prefix && trailingPeriod ? `${body}.` : body;
});
}
/**
* Flatten `[{ prefix?, value }]` fragments to a single sentence-style string.
*
* Shared by `descriptorForCanonEntry` (SHORT spec, `. ` separator),
* `composeComicPagePrompt` (RICH spec, `. ` separator), and
* `synthesizeCanonPrompt` (RICH spec, `. ` separator). The 4-arg
* `mapCanonDescriptorFragments` companion supports the scene-prompt budget
* truncator that needs the array form (`buildScenePrompt`).
*/
export function flattenCanonDescriptorFragments(fragments, { separator = '. ', trailingPeriod = false } = {}) {
return mapCanonDescriptorFragments(fragments, { trailingPeriod }).join(separator);
}
/**
* Flatten SHORT fragments into a sentence-style descriptor string.
* Matches the legacy `KINDS[].descFor` output:
* characters: "physicalDescription" else "description"
* places: "description. Palette: <palette>. recurringDetails"
* objects: "description" else "significance"
*/
export function descriptorForCanonEntry(kind, entry) {
return flattenCanonDescriptorFragments(shortCanonDescriptorFragments(kind, entry));
}
/**
* PREVIEW fragments — importer pre-commit review surface.
*
* Returns `{ subtitle, body }` where `subtitle` is a single trimmed string
* (empty when the kind has no subtitle field or the value is blank) and
* `body` is an ordered `[{ field, value }]` array of non-blank fields,
* intended for ` • `-joined rendering in importer cards. Unknown kinds and
* non-object entries return the empty shape so callers can render
* unconditionally.
*
* This is intentionally wider than `shortCanonDescriptorFragments` (which
* is scoped to the visual subset that drives render-prompts and ref-image
* gating). PREVIEW exists so the user can disambiguate which character /
* place / object to commit, so it surfaces narrative-only fields
* (`personality`, `background`, `slugline`) that have no visual role.
*/
export function previewCanonFragments(kind, entry) {
if (!entry || typeof entry !== 'object') return { subtitle: '', body: [] };
const spec = PREVIEW_SPEC[normalizeKind(kind)];
if (!spec) return { subtitle: '', body: [] };
const subtitle = spec.subtitleField ? trim(entry[spec.subtitleField]) : '';
return { subtitle, body: fragmentsFromSequence(spec.bodyFields, entry) };
}
/**
* True when the entry has any non-blank value across the RICH field set.
* Mirrors `canonEntryHasContent`'s per-kind union check (UniverseBuilder.jsx)
* and is the read-side mirror of `synthesizeCanonPrompt`'s skip-empty-seed
* rule.
*/
export function hasCanonDescriptorContent(kind, entry) {
if (!entry || typeof entry !== 'object') return false;
const sequence = RICH_SPEC[normalizeKind(kind)];
if (!sequence) return false;
return sequenceHasAnyField(sequence, entry);
}
// Flatteners for character bible list fields — used by the reference-sheet
// builder and future per-page render prompts so the join logic stays in one
// place. Each returns `''` when the input is missing/empty.
//
// Server-only: `client/src/lib/canonPrompt.js` re-exports this module by NAME,
// and deliberately leaves these out — they would bloat the bundle for code that
// only runs in image-gen / prompt-building paths.
export function flattenStats(stats) {
if (!Array.isArray(stats) || stats.length === 0) return '';
return stats
.map((s) => (s?.label && s?.value ? `${s.label}: ${s.value}` : s?.label || ''))
.filter(Boolean)
.join(' | ');
}
export function flattenPalette(palette) {
if (!Array.isArray(palette) || palette.length === 0) return '';
return palette
.map((c, i) => {
const name = trim(c?.name);
const hex = trim(c?.hex);
const role = trim(c?.role);
if (!name) return '';
const hexBit = hex ? ` ${hex}` : '';
const roleBit = role ? ` — ${role}` : '';
return `Swatch ${i + 1}: ${name}${hexBit}${roleBit}`;
})
.filter(Boolean)
.join(', ');
}
export function flattenWardrobes(wardrobes) {
if (!Array.isArray(wardrobes) || wardrobes.length === 0) return '';
return wardrobes
.map((w) => (w?.name && w?.description ? `"${w.name}": ${w.description}` : w?.name || ''))
.filter(Boolean)
.join(' | ');
}
export function flattenProps(props) {
if (!Array.isArray(props) || props.length === 0) return '';
return props
.map((p) => {
const name = trim(p?.name);
const purpose = trim(p?.purpose);
const materials = trim(p?.materials);
if (!name) return '';
const bits = [purpose ? `(${purpose})` : '', materials ? `[${materials}]` : '']
.filter(Boolean)
.join(' ');
return bits ? `${name} ${bits}` : name;
})
.filter(Boolean)
.join(' | ');
}
// `defaults` is consulted when the entry has no items at all — keeps the
// reference-sheet prompt's expression / hand-gesture panels populated even
// when the bible omitted them. Caps at 7 entries so the rendered sheet
// stays legible across providers (codex/local both honor the cap).
export function flattenNamedList(items, defaults) {
const list = Array.isArray(items) && items.length > 0
? items.map((e) => (e?.name && e?.description ? `${e.name} (${e.description})` : trim(e?.name))).filter(Boolean)
: [...defaults];
return list.slice(0, 7).join(', ');
}